Skip to content

github.com/ricardo/anthrogo/internal/mcp

package mcp // import "github.com/ricardo/anthrogo/internal/mcp"


CONSTANTS

const DefaultInitTimeout = 10 * time.Second
    DefaultInitTimeout is applied when MCPServerConfig.Timeout == 0.


TYPES

type ElicitFn func(serverName string, message string, schema map[string]any) (action string, formData map[string]any, err error)
    ElicitFn is a callback invoked when an MCP server requests elicitation.
    Returns action ("accept"|"decline"|"cancel"), optional form data, and error.
    When nil the server falls back to returning "decline".

type LogSink func(serverName, message string)
    LogSink receives notifications/message lines from any Server in the Manager.
    nil-safe: the Manager treats a nil LogSink as a no-op.

type MCPServerConfig struct {
    // Type selects the transport. Defaults to "stdio".
    Type string `yaml:"type,omitempty"`

    // stdio fields
    Command string            `yaml:"command,omitempty"`
    Args    []string          `yaml:"args,omitempty"`
    Env     map[string]string `yaml:"env,omitempty"`
    Cwd     string            `yaml:"cwd,omitempty"`

    // HTTP transport fields (sse / streamable / websocket)
    Endpoint   string `yaml:"endpoint,omitempty"`
    MaxRetries int    `yaml:"max_retries,omitempty"`

    // Timeout for the initial handshake (initialize + tools/list). Defaults to 10s.
    Timeout time.Duration `yaml:"timeout,omitempty"`

    // ElicitationMode controls how elicitation requests from this server are handled.
    //   - "" or "decline" (default): handler is registered (capability advertised);
    //     all requests are declined with Action="decline".
    //   - "disabled": handler is not registered (capability not advertised).
    // Any other value is treated as "decline" with a log warning.
    ElicitationMode string `yaml:"elicitation_mode,omitempty"`

    // Subprotocols is the list of WebSocket subprotocols to advertise during the
    // handshake (websocket transport only). The server's selected subprotocol is
    // returned in the Sec-WebSocket-Protocol response header.
    Subprotocols []string `yaml:"subprotocols,omitempty"`

    // Headers are additional HTTP headers injected on every outgoing request.
    // Applies to websocket (via DialOptions.HTTPHeader), sse, and streamable
    // transports (via a headerInjector RoundTripper). Takes no effect on stdio.
    Headers map[string]string `yaml:"headers,omitempty"`

    // OAuth, when non-nil, enables the OAuth 2.1 PKCE authorization-code flow for
    // sse / streamable / websocket transports. The fetched token is injected as
    // "Authorization: Bearer <token>" on every outgoing HTTP request.
    OAuth *OAuthConfig `yaml:"oauth,omitempty"`
}
    MCPServerConfig describes one MCP server. Type selects the transport:
      - "" or "stdio": spawn a subprocess via Command/Args (default)
      - "sse": connect to a remote 2024-11-05 SSE endpoint
      - "streamable": connect to a remote streamable HTTP endpoint
      - "websocket": connect via WebSocket (ws:// or wss://)

func (c *MCPServerConfig) Expand()
    Expand resolves any env: prefixed values in Headers to their actual
    environment variable values. This mirrors the env:VARNAME expansion used for
    APIKey (M5.3 subagent loader, M6.5 OAuth).

type Manager struct {
    // Has unexported fields.
}
    Manager owns N MCP Servers and exposes their tools through tool.Tool
    adapters. Construct with NewManager; call Start before AllTools.

func NewManager(logSink LogSink) *Manager
    NewManager constructs a Manager with an optional LogSink.

func (m *Manager) AddServer(name string, cfg MCPServerConfig)
    AddServer registers a server config. Server is not started until Start().

func (m *Manager) AllResources(ctx context.Context) map[string][]*sdk.Resource
    AllResources lists resources from every Ready server. Per-server errors are
    logged via LogSink and omitted from the result map.

func (m *Manager) AllTools() []tool.Tool
    AllTools returns one MCPAdapter per (ready server, advertised tool).

func (m *Manager) Close() error
    Close terminates every server.

func (m *Manager) Err(name string) error
    Err returns the last error for one server.

func (m *Manager) Names() []string
    Names returns server names in deterministic (sorted) order.

func (m *Manager) ReadResource(ctx context.Context, server, uri string) (*sdk.ReadResourceResult, error)
    ReadResource reads a resource by URI from a named server.

func (m *Manager) ServerConfig(name string) (MCPServerConfig, bool)
    ServerConfig returns the MCPServerConfig for the named server, and whether
    the server exists. Used by status display to show (redacted) headers.

func (m *Manager) SetElicitationHandler(fn ElicitFn)
    SetElicitationHandler installs fn as the elicitation callback for
    all current and future servers. Call before Start for best effect;
    any already- started servers update their elicitFn immediately (affects next
    elicitation).

func (m *Manager) Start(ctx context.Context) error
    Start spawns every server in parallel and waits for all of them to settle
    (ready or failed). Returns nil even if some servers failed — inspect with
    State(name).

func (m *Manager) State(name string) State
    State returns the state of one server, or "" if no such name.

type OAuthConfig struct {
    AuthorizationURL string   `yaml:"authorization_url"`
    TokenURL         string   `yaml:"token_url"`
    ClientID         string   `yaml:"client_id"`
    ClientSecret     string   `yaml:"client_secret,omitempty"` // optional (PKCE-only public clients)
    Scopes           []string `yaml:"scopes,omitempty"`
    RedirectPort     int      `yaml:"redirect_port,omitempty"` // local loopback port; default 8765
}
    OAuthConfig holds the OAuth 2.1 parameters needed to obtain an access token.

type Server struct {
    Name string

    // Has unexported fields.
}
    Server wraps one MCP stdio subprocess + its SDK ClientSession.

func NewServer(name string, cfg MCPServerConfig, notifyLog func(string, string), elicit ElicitFn) *Server
    NewServer constructs (but does not start) a Server. elicit may be nil;
    when non-nil it is called instead of auto-declining elicitation requests.

func (s *Server) CallTool(ctx context.Context, name string, args map[string]any) (*sdk.CallToolResult, error)
    CallTool invokes a tool on this server by name.

func (s *Server) Close() error
    Close gracefully terminates the server. The SDK's CommandTransport owns the
    cmd lifecycle (SIGTERM → wait → SIGKILL) via TerminateDuration, so we only
    need to call sess.Close().

func (s *Server) Err() error
    Err returns the last error if state is Failed.

func (s *Server) ListResources(ctx context.Context) ([]*sdk.Resource, error)
    ListResources returns the server's currently-advertised resources. Follows
    pagination via NextCursor. Returns an error if the server is not Ready.

func (s *Server) ReadResource(ctx context.Context, uri string) (*sdk.ReadResourceResult, error)
    ReadResource reads a resource by URI. Returns an error if the server is not
    Ready.

func (s *Server) Start(parent context.Context) error
    Start spawns or connects the server, performs the initialize handshake,
    and calls tools/list. State is StateReady on success or StateFailed on any
    error. It may be called again after Close to reload.

func (s *Server) State() State
    State returns the current state. Concurrent-safe.

func (s *Server) Tools() []*sdk.Tool
    Tools returns a copy of the most recent tools/list snapshot.

type State string
    State is the public lifecycle phase of one MCP server.

const (
    StateInit   State = "init"
    StateReady  State = "ready"
    StateFailed State = "failed"
    StateClosed State = "closed"
)
type WebSocketClientTransport struct {
    Endpoint     string
    HTTPHeader   http.Header
    Subprotocols []string
}
    WebSocketClientTransport opens a websocket to Endpoint and frames each
    JSON-RPC message as one text-mode websocket message. Endpoint must use the
    ws:// or wss:// scheme. HTTPHeader is optional; use it for auth tokens or
    custom headers. Subprotocols is optional; when non-empty the values are
    advertised in the Sec-WebSocket-Protocol handshake header.

func (t *WebSocketClientTransport) Connect(ctx context.Context) (sdk.Connection, error)
    Connect dials the WebSocket endpoint and returns a Connection. Implements
    sdk.Transport.