package mcp import ( "context" "encoding/json" "fmt" "sync" "sync/atomic" "github.com/samcharles93/archie-core/internal/tools" ) // protocolVersion is the MCP protocol version this client speaks. const protocolVersion = "2024-11-05" // Transport sends requests and notifications to an MCP server. type Transport interface { Send(ctx context.Context, body []byte) ([]byte, error) Notify(ctx context.Context, body []byte) error } // Client speaks the MCP JSON-RPC protocol (initialize, tools/list, // tools/call) over a [Transport]. It does not manage the transport's // lifecycle (Start/Stop) -- callers start the transport first, then // build a Client on top of it. type Client struct { transport Transport serverName string nextID atomic.Int64 // callMu serializes tools/call to this server. Nil allows concurrent calls. callMu *sync.Mutex // samplingHandler answers server-initiated sampling/createMessage // requests. Set once at construction, so reading it from a transport // reader goroutine needs no lock. Nil means the method is refused. samplingHandler SamplingHandler } // ClientOption adjusts a Client at construction. type ClientOption func(*Client) // WithSamplingHandler answers server-initiated sampling/createMessage // requests from the supplied handler. Without it the client answers the // method with a JSON-RPC method-not-found error, per the MCP spec -- never // a silent drop. func WithSamplingHandler(handler SamplingHandler) ClientOption { return func(c *Client) { c.samplingHandler = handler } } // NewClient builds a Client over transport. parallelToolCalls allows // concurrent tools/call. The client handles server-initiated requests when // the transport supports them. func NewClient(transport Transport, serverName string, parallelToolCalls bool, opts ...ClientOption) *Client { c := &Client{transport: transport, serverName: serverName} if !parallelToolCalls { c.callMu = &sync.Mutex{} } for _, opt := range opts { opt(c) } if router, ok := transport.(serverRequestRouter); ok { router.SetServerRequestHandler(c.handleServerRequest) } return c } // handleServerRequest answers sampling/createMessage and returns // method-not-found for anything else. func (c *Client) handleServerRequest(ctx context.Context, method string, params json.RawMessage) (json.RawMessage, *ErrorData) { if method != "sampling/createMessage" { return nil, &ErrorData{Code: ErrCodeMethodNotFound, Message: "method not found: " + method} } if c.samplingHandler == nil { return nil, &ErrorData{ Code: ErrCodeMethodNotFound, Message: "sampling/createMessage is not supported: no sampling handler is configured", } } var req SamplingRequest if err := json.Unmarshal(params, &req); err != nil { return nil, &ErrorData{Code: ErrCodeInvalidParams, Message: "invalid sampling/createMessage params: " + err.Error()} } result, err := c.samplingHandler(ctx, req) if err != nil { return nil, &ErrorData{Code: ErrCodeInternal, Message: err.Error()} } body, err := json.Marshal(result) if err != nil { return nil, &ErrorData{Code: ErrCodeInternal, Message: "marshal sampling result: " + err.Error()} } return body, nil } // InitializeResult is the server's response to initialize. type InitializeResult struct { ProtocolVersion string `json:"protocolVersion"` ServerInfo ServerInfo `json:"serverInfo"` Capabilities Capabilities `json:"capabilities"` } // ServerInfo identifies the MCP server implementation. type ServerInfo struct { Name string `json:"name"` Version string `json:"version"` } // Capabilities describes what the server supports. Fields are omitted // (left as raw presence checks) rather than fully modeled -- archie-core // only needs tool discovery today. type Capabilities struct { Tools json.RawMessage `json:"tools,omitempty"` } // ToolSchema is one tool as advertised by tools/list. type ToolSchema struct { Name string `json:"name"` Description string `json:"description,omitempty"` InputSchema tools.JSONSchema `json:"inputSchema"` Annotations struct { ReadOnlyHint bool `json:"readOnlyHint"` } `json:"annotations"` } // ContentBlock is one block of a tools/call result. Per the MCP spec a // block is one of: text (Text set), image/audio (Data+MimeType set), or // resource (Resource set, itself either inline text or a base64 blob). type ContentBlock struct { Type string `json:"type"` Text string `json:"text,omitempty"` Data string `json:"data,omitempty"` // base64, for type "image"/"audio" MimeType string `json:"mimeType,omitempty"` Resource *ResourceContent `json:"resource,omitempty"` } // ResourceContent is an embedded resource, for a ContentBlock of type // "resource". Exactly one of Text or Blob is set: Text for inline // textual resources (treated as plain text, not media), Blob // (base64-encoded) for binary resources (treated as media). type ResourceContent struct { URI string `json:"uri"` MimeType string `json:"mimeType,omitempty"` Text string `json:"text,omitempty"` Blob string `json:"blob,omitempty"` } // CallToolResult is a tools/call result. IsError reports a tool-level // failure. type CallToolResult struct { Content []ContentBlock `json:"content"` IsError bool `json:"isError,omitempty"` } // Initialize performs the MCP handshake: sends initialize, then the // notifications/initialized notification the spec requires after a // successful initialize response. Must be called once before ListTools // or CallTool. func (c *Client) Initialize(ctx context.Context) (InitializeResult, error) { params := map[string]any{ "protocolVersion": protocolVersion, "capabilities": map[string]any{}, "clientInfo": map[string]any{"name": "archie-core", "version": "1.0.0"}, } var result InitializeResult if err := c.call(ctx, "initialize", params, &result); err != nil { return InitializeResult{}, fmt.Errorf("mcp: initialize %s: %w", c.serverName, err) } if err := c.notify(ctx, "notifications/initialized", nil); err != nil { return InitializeResult{}, fmt.Errorf("mcp: notifications/initialized %s: %w", c.serverName, err) } return result, nil } // ListTools returns every tool the server advertises, following the // cursor-based pagination the spec defines until the server stops // returning nextCursor. func (c *Client) ListTools(ctx context.Context) ([]ToolSchema, error) { var all []ToolSchema cursor := "" for { params := map[string]any{} if cursor != "" { params["cursor"] = cursor } var page struct { Tools []ToolSchema `json:"tools"` NextCursor string `json:"nextCursor,omitempty"` } if err := c.call(ctx, "tools/list", params, &page); err != nil { return nil, fmt.Errorf("mcp: tools/list %s: %w", c.serverName, err) } all = append(all, page.Tools...) if page.NextCursor == "" { return all, nil } cursor = page.NextCursor } } // CallTool calls a tool. A Go error means the call failed; a tool failure is // CallToolResult.IsError. func (c *Client) CallTool(ctx context.Context, name string, arguments map[string]any) (CallToolResult, error) { if c.callMu != nil { c.callMu.Lock() defer c.callMu.Unlock() } params := map[string]any{"name": name, "arguments": arguments} var result CallToolResult if err := c.call(ctx, "tools/call", params, &result); err != nil { return CallToolResult{}, fmt.Errorf("mcp: tools/call %s.%s: %w", c.serverName, name, err) } return result, nil } // call sends a JSON-RPC request and decodes its result into out. It // returns an error for a transport failure, a JSON-RPC error response, // or a malformed result payload. func (c *Client) call(ctx context.Context, method string, params, out any) error { id := c.nextID.Add(1) req := struct { JSONRPC string `json:"jsonrpc"` ID int64 `json:"id"` Method string `json:"method"` Params any `json:"params,omitempty"` }{JSONRPC: "2.0", ID: id, Method: method, Params: params} body, err := json.Marshal(req) if err != nil { return fmt.Errorf("marshal request: %w", err) } respBody, err := c.transport.Send(ctx, body) if err != nil { return err } var resp Message if err := json.Unmarshal(respBody, &resp); err != nil { return fmt.Errorf("unmarshal response: %w", err) } if resp.Error != nil { return fmt.Errorf("rpc error %d: %s", resp.Error.Code, resp.Error.Message) } if out == nil || len(resp.Result) == 0 { return nil } if err := json.Unmarshal(resp.Result, out); err != nil { return fmt.Errorf("unmarshal result: %w", err) } return nil } // notify sends a JSON-RPC notification (no id, no response expected). func (c *Client) notify(ctx context.Context, method string, params any) error { req := struct { JSONRPC string `json:"jsonrpc"` Method string `json:"method"` Params any `json:"params,omitempty"` }{JSONRPC: "2.0", Method: method, Params: params} body, err := json.Marshal(req) if err != nil { return fmt.Errorf("marshal notification: %w", err) } return c.transport.Notify(ctx, body) }