mcp

package
v0.50.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 27, 2026 License: MIT Imports: 18 Imported by: 0

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

View Source
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) AsTool

func (c *Client) AsTool(t mcpTool) api.Tool

AsTool wraps an MCP tool definition as a api.Tool for the registry.

func (*Client) ListTools

func (c *Client) ListTools(ctx context.Context) ([]mcpTool, error)

ListTools queries the MCP server for its available tools.

func (*Client) Start

func (c *Client) Start(ctx context.Context) error

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.

func (*Client) Stop

func (c *Client) Stop()

Stop terminates the MCP server subprocess and reaps it. It is idempotent and never blocks longer than stopWaitTimeout, even if Wait is stuck (for example a grandchild keeps the stdout pipe open).

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

func NewProviderForTools(id string, toolsList []api.Tool, client toolClient) *Provider

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.

func (*Provider) Close

func (p *Provider) Close() error

func (*Provider) Conflicts

func (p *Provider) Conflicts() []Conflict

Conflicts reports the tool-name collisions this provider hit while registering; it is empty when every tool registered. The list is a copy, so callers can render it without locking the provider.

func (*Provider) ID

func (p *Provider) ID() string

func (*Provider) RegisterTools

func (p *Provider) RegisterTools(registry *tools.Registry) error

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.

const (
	// TransportStdio runs a local subprocess and speaks JSON-RPC on its stdio.
	TransportStdio Transport = "stdio"
	// TransportStreamableHTTP talks to an HTTP endpoint (MCP Streamable HTTP).
	TransportStreamableHTTP Transport = "streamable_http"
)

func ParseTransport

func ParseTransport(raw string, hasURL bool) (Transport, error)

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL