mcp

Documentation

Overview

Package mcp is the MCP frontend, built on the official Model Context Protocol Go SDK (github.com/modelcontextprotocol/go-sdk). It exposes every registered command as an MCP tool through the three transports (stdio / SSE / streamable HTTP) and lets the caller pin which protocol versions the server negotiates.

Output contract: every successful call returns the human-readable text (the same rendering the CLI frontend uses) in Content plus the raw value as JSON in StructuredContent; failures are reported as isError=true results carrying the classified error message.

Index

• Constants
• Variables
• func HTTPHandler(reg *registry.Registry, opts Options) (http.Handler, error)
• func Run(reg *registry.Registry, args []string) int
• func RunContext(ctx context.Context, reg *registry.Registry, args []string) int
• func RunContextWithOptions(ctx context.Context, reg *registry.Registry, args []string, base Options) int
• func RunWithOptions(reg *registry.Registry, args []string, base Options) int
• func Server(reg *registry.Registry, opts Options) (*sdkmcp.Server, error)
• type Options

Constants

const (
	ProtocolV2024_11_05 = "2024-11-05"
	ProtocolV2025_03_26 = "2025-03-26"
	ProtocolV2025_06_18 = "2025-06-18"
	ProtocolV2025_11_25 = "2025-11-25"
	ProtocolV2026_07_28 = "2026-07-28" // latest
)

Protocol versions known to the official Go SDK at v1.7.0. Negotiation prefers the client's requested version when the server supports it; 2026-07-28 is the latest revision and deprecates the legacy initialize handshake in favor of mutually-negotiated version lists.

Variables

var DefaultVersions = []string{
	ProtocolV2026_07_28,
	ProtocolV2025_11_25,
	ProtocolV2025_06_18,
	ProtocolV2025_03_26,
	ProtocolV2024_11_05,
}

DefaultVersions is the full set the SDK can serve, in negotiation preference order (newest first).

Functions

func HTTPHandler

func HTTPHandler(reg *registry.Registry, opts Options) (http.Handler, error)

func Run

func Run(reg *registry.Registry, args []string) int

Run parses the transport and flags from args and serves until the transport ends:

mcp stdio [flags]
mcp sse   [flags]     # flags: --addr, --versions v1,v2, --name, --server-version
mcp http  [flags]     # streamable HTTP; adds --json-response, --stateless

It returns the process exit code.

func RunContext

func RunContext(ctx context.Context, reg *registry.Registry, args []string) int

RunContext is Run with an explicit context (graceful shutdown), both for the stdio server and the http/sse listeners.

func RunContextWithOptions

func RunContextWithOptions(ctx context.Context, reg *registry.Registry, args []string, base Options) int

RunContextWithOptions combines RunContext and RunWithOptions.

func RunWithOptions

func RunWithOptions(reg *registry.Registry, args []string, base Options) int

RunWithOptions is Run with preset options (e.g. bearer tokens injected by the dispatcher's --xyz.bearer). Command-line flags still win over presets.

func Server

func Server(reg *registry.Registry, opts Options) (*sdkmcp.Server, error)

Server builds a ready sdkmcp.Server with one tool per registered command. Tool input schemas come straight from the registry's JSON Schema generation; the shared Invoke pipeline does all decoding and validation.

Types

type Options

type Options struct {
	// Name and Version identify this server implementation to clients.
	// Defaults: binary base name and "0.0.0".
	Name    string
	Version string

	// Versions restricts which protocol versions this server stands behind,
	// subset of DefaultVersions. Order is the preference order used during
	// negotiation. Empty means "all of them".
	Versions []string

	// Instructions is shown to clients after initialization.
	Instructions string

	// Addr is the listen address for the sse and http transports.
	// Default ":8080".
	Addr string

	// JSONResponse makes streamable HTTP answer with application/json
	// instead of text/event-stream (handy for debugging).
	JSONResponse bool

	// Stateless enables the streamable HTTP stateless mode (SEP-2567).
	Stateless bool

	// BearerTokens turns on Bearer-token verification for the http and sse
	// transports (stdio is local and unaffected). Empty means no auth.
	BearerTokens []string

	// SessionTimeout configures idle-session expiry for streamable HTTP
	// (the SDK's StreamableHTTPOptions.SessionTimeout). 0 keeps sessions.
	SessionTimeout time.Duration

	// CORSOrigins enables CORS for the http/sse transports ("*" = any origin).
	CORSOrigins []string

	// Defaults 是通道级默认参数（--default k=v）：调用未显式提供时补上。
	Defaults map[string]string
}

Options configures the MCP frontend. The zero value serves every protocol version the SDK knows.