Documentation
¶
Overview ¶
Package mcp implements a JSON-RPC 2.0 client for MCP (Model Context Protocol) servers. It communicates with MCP servers via stdio (subprocess) or SSE transport.
Index ¶
Constants ¶
const DefaultCallTimeout = 120 * time.Second
DefaultCallTimeout is the default bound on one tools/call.
Variables ¶
This section is empty.
Functions ¶
func NewHTTPClient ¶
func NewHTTPClient(cfg ServerConfig) *httpClient
NewHTTPClient creates a Streamable HTTP MCP client from cfg but does not contact the server yet (Start performs initialize).
Types ¶
type Annotations ¶
type Annotations struct {
Title string `json:"title,omitempty"`
// ReadOnlyHint marks a tool the server claims has no side effects.
ReadOnlyHint *bool `json:"readOnlyHint,omitempty"`
// DestructiveHint marks a tool the server claims may destroy data.
DestructiveHint *bool `json:"destructiveHint,omitempty"`
// IdempotentHint marks a repeated call with the same arguments as harmless.
IdempotentHint *bool `json:"idempotentHint,omitempty"`
// OpenWorldHint marks interaction with an open world (the internet).
OpenWorldHint *bool `json:"openWorldHint,omitempty"`
}
Annotations is the optional "annotations" object of one tools/list entry (MCP spec: title, readOnlyHint, destructiveHint, idempotentHint, openWorldHint). Every hint is a pointer so "declared false" stays apart from "not declared": a server that says nothing is not read as "not destructive" and never as read-only.
func AnnotationsOf ¶
func AnnotationsOf(t api.Tool) (Annotations, bool)
AnnotationsOf returns the annotations an MCP tool's server declared, and whether the tool carries any at all. Non-MCP tools, nil tools and MCP tools whose server declared nothing report false, so callers keep their default classification.
func (Annotations) Declared ¶
func (a Annotations) Declared() bool
Declared reports whether the server declared at least one annotation field.
func (Annotations) Destructive ¶
func (a Annotations) Destructive() bool
Destructive reports the server's destructiveHint == true claim.
func (Annotations) ReadOnly ¶
func (a Annotations) ReadOnly() bool
ReadOnly reports the server's readOnlyHint == true claim. It is intent declared by an external server: a host may report it (ACP announces kind=read), but suga itself never approves a call because of it.
func (Annotations) SafeReadOnly ¶
func (a Annotations) SafeReadOnly() bool
SafeReadOnly reports a tool the server declares read-only and not destructive; a destructive read-only claim is contradictory and ignored.
type Annotator ¶
type Annotator interface {
MCPAnnotations() Annotations
}
Annotator is the optional interface of a tool that carries the annotations its MCP server declared in tools/list. Only MCP tool adapters implement it.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client connects to an MCP server via stdio and exposes its tools.
func NewClient ¶
func NewClient(cfg ServerConfig) *Client
NewClient creates an MCP client from cfg but does not start the server yet.
func (*Client) Start ¶
Start launches the MCP server subprocess and performs the JSON-RPC initialize handshake. ctx only bounds the handshake: the subprocess lifetime is owned by Stop, so a startup-scoped (timeout) ctx being released does not kill a healthy server. On any failure the subprocess is stopped and reaped before returning.
type Conflict ¶
type Conflict struct {
Server string `json:"server"`
Tool string `json:"tool"`
KeptBy string `json:"kept_by"`
}
Conflict records one tool name a later MCP server could not register because an earlier tool already owns it (first-wins, design D8). KeptBy names that owner so a runtime diagnostics view can explain the missing tool; it never carries an endpoint, argument, environment variable or header value.
type Provider ¶
type Provider struct {
// contains filtered or unexported fields
}
Provider exposes MCP tools as a runtime capability-governed tool source.
func NewProvider ¶
func NewProvider(ctx context.Context, settings ServerSettings) (*Provider, error)
func NewProviderForTools ¶
NewProviderForTools constructs a Provider from already-materialized MCP tools. It exists for higher-level wiring tests so app capability assembly can verify provider composition without starting a real MCP subprocess.
type ServerConfig ¶
type ServerConfig struct {
Name string // logical server name
Command string // executable
Args []string // command arguments
Env []string // extra environment variables (KEY=VALUE)
// URL is the Streamable HTTP endpoint of the server; when set, no
// subprocess is started and Headers are sent with every request.
URL string
// Headers are extra HTTP headers (for example Authorization). Values come
// from ${VAR} expansion in the config reader and must never be logged.
Headers map[string]string
// CallTimeout bounds one tools/call (mcp.call_timeout_sec); 0 means
// DefaultCallTimeout. A server that never answers must not hang the turn.
CallTimeout time.Duration
// RawBytes caps the text of one tool result (head and tail kept); 0 means
// tools.DefaultRawOutputBytes. MCP servers have no output limit of their
// own, so this is what bounds the output layer's saved copy.
RawBytes int
}
ServerConfig describes an MCP server to connect to. It is either a stdio subprocess (Command, Args, Env) or a Streamable HTTP endpoint (URL, Headers); a non-empty URL selects the HTTP transport.
type ServerSettings ¶
type ServerSettings struct {
ID string
Command string
Args []string
Env map[string]string
// URL, Headers and Transport configure the Streamable HTTP transport.
URL string
Headers map[string]string
Transport Transport
// StartupTimeout bounds initialize + tools/list for this server;
// 0 means the package default (mcp.startup_timeout_sec).
StartupTimeout time.Duration
// CallTimeout bounds one tools/call; 0 means DefaultCallTimeout.
CallTimeout time.Duration
// RawBytes caps one tool result (tools.max_spill_bytes); 0 means
// tools.DefaultRawOutputBytes.
RawBytes int
}
ServerSettings describes one MCP server. A server is either stdio (Command/Args/Env) or Streamable HTTP (URL/Headers). The host fills it from its own configuration; this package never reads global config.
type Transport ¶
type Transport string
Transport names the wire protocol of one MCP server.
func ParseTransport ¶
ParseTransport normalizes a configured transport name. An empty value is derived from the settings shape (url -> streamable_http, command -> stdio). Legacy SSE is rejected explicitly so a typo cannot silently become stdio.