harness

type Factory func(ctx context.Context, opts Options) (Transport, error)

type Options struct {
	// MaxMessageSize, if >0, configures the transport's size cap and the
	// server's MaxMessageSize. Zero leaves both at their default (4 MiB).
	MaxMessageSize int64

	// BearerToken, if non-empty, enables static-bearer auth on transports
	// that require it (legacy HTTP, streamable HTTP, gRPC). stdio ignores
	// this field.
	BearerToken string

	// Tools lists the ToolDescriptors the mock server should expose. Nil
	// means the harness registers only the default mock_tool.
	Tools []mcp.ToolDescriptor

	// Enforcement, if non-nil, is installed on the mock server. Most harness
	// tests leave this nil; parity tests that exercise protocol-level
	// validation can opt in without rebuilding each transport fixture.
	Enforcement mcp.Enforcement
}

type RPCError struct {
	Code    int    `json:"code"`
	Message string `json:"message"`
	Data    any    `json:"data,omitempty"`
}

type Response struct {
	JSONRPC string          `json:"jsonrpc"`
	ID      int             `json:"id,omitempty"`
	Result  json.RawMessage `json:"result,omitempty"`
	Error   *RPCError       `json:"error,omitempty"`
	Method  string          `json:"method,omitempty"`
	Params  json.RawMessage `json:"params,omitempty"`
}

type ServerSharer interface {
	SharedServer() (*mcp.Server, bool)
}

type Transport interface {
	Name() string
	Initialize(ctx context.Context) (Response, error)
	ListTools(ctx context.Context) (Response, error)
	CallTool(ctx context.Context, name string, args map[string]any) (Response, error)
	CallToolAsync(ctx context.Context, name string, args map[string]any) (requestID int, done <-chan Response, err error)
	Cancel(ctx context.Context, requestID int) error
	// Notifications returns a channel of server→client frames (for
	// transports that support them: stdio, streamable HTTP, gRPC).
	// Legacy HTTP returns nil — callers must handle the nil case
	// explicitly rather than blocking forever on <-nil.
	Notifications() <-chan Response
	// SendRaw delivers arbitrary bytes through the transport's framing
	// layer without wrapping them in a JSON-RPC envelope and returns
	// the decoded server reply. Intended for malformed-JSON / parse-
	// error boundary tests; not for normal call flow.
	//
	// Line-delimited transports (stdio, gRPC) send the bytes verbatim
	// and read the next anonymous error frame. HTTP transports POST
	// the bytes as the request body and decode the HTTP response. Only
	// one SendRaw at a time per harness instance — serialisation is
	// enforced internally.
	SendRaw(ctx context.Context, frame []byte) (Response, error)
	MaxSupportedSize() int64
	Close() error
}