mcp

package
v0.4.41 Latest Latest
Warning

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

Go to latest
Published: Jul 28, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package mcp implements a minimal Model Context Protocol server.

The package is transport-agnostic: Server.HandleFrame takes a raw JSON-RPC byte slice in and returns the response bytes (or nil for notifications) — transports (stdio, HTTP) wrap it with their own I/O loop. This split lets the desktop client embed the same MCP surface inside a Wails process while the CLI keeps its stdio behaviour against Claude Desktop, Cursor, and Claude Code.

Protocol reference:

Supported methods:

  • initialize
  • notifications/initialized
  • tools/list
  • tools/call
  • ping

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type HTTPTransport

type HTTPTransport struct {

	// CORS allow-origin for the response header. Defaults to a wildcard;
	// the desktop client should override to the actual MCP-host origin
	// once embedded (avoids letting random web pages prompt the local
	// MCP endpoint).
	AllowOrigin string

	// ReadTimeout / WriteTimeout cap per-request I/O. Defaults are
	// loose because tools/call can run for minutes (install_module,
	// build_flow). Override per-deployment as needed.
	ReadTimeout  time.Duration
	WriteTimeout time.Duration
	// contains filtered or unexported fields
}

HTTPTransport serves MCP JSON-RPC over plain HTTP POST. Each POST to /mcp carries one JSON-RPC frame in the body and gets one frame back in the response (or 204 for notifications).

This is what the desktop client embeds — a localhost-only listener the local Claude Desktop / Cursor process connects to instead of spawning a separate mcp-server binary over stdio. Same Server underneath: same registry, same execution context, same tool dispatch.

Streaming-HTTP / SSE for server-initiated notifications is a future addition. Today's tool set is pure request/response so POST-only covers the spec's required transport.

func NewHTTPTransport

func NewHTTPTransport(server *Server, addr string) *HTTPTransport

NewHTTPTransport returns a transport that listens on addr (e.g. "127.0.0.1:9876") and dispatches MCP frames to server. Defaults to localhost-only — the embedded use case never wants to expose the endpoint beyond the host machine.

func (*HTTPTransport) Run

func (t *HTTPTransport) Run(ctx context.Context) error

Run starts the HTTP listener and blocks until ctx is cancelled or the server errors. On cancel the server shuts down gracefully with a 5-second drain window.

type Server

type Server struct {

	// OnActivity, if set, is called at the start of each tool call with the
	// tool name; it returns a function invoked when the call finishes, carrying
	// that call's outcome. Lets a host render live activity — a spinner per
	// call, and whether it actually worked. Optional.
	//
	// The outcome is passed because the host cannot infer it: a failing tool
	// still returns normally here, so a host given no result reports every
	// finished call identically. That is how the Activity feed came to paint
	// every completed call red.
	OnActivity func(tool string) (done func(success bool, errMsg string))
	// contains filtered or unexported fields
}

Server holds the tool registry + execution context and dispatches MCP JSON-RPC frames. Stateless across calls (no per-session state) — transports can share a single Server across many concurrent connections.

func NewServer

func NewServer(registry *sdktools.Registry, execCtx sdktools.ExecutionContext) *Server

NewServer returns a server bound to the given registry + execution context. Both are owned by the caller and assumed to live for the server's lifetime.

func (*Server) HandleFrame

func (s *Server) HandleFrame(ctx context.Context, frame []byte) ([]byte, error)

HandleFrame decodes one JSON-RPC frame, dispatches it, and returns the response bytes ready to write back to the client. Returns nil when the frame is a notification (no response expected). Returns an error only for malformed input the transport should care about — JSON-RPC errors are encoded into the returned bytes per spec.

func (*Server) SetInstructions

func (s *Server) SetInstructions(text string)

SetInstructions overrides the server-level instructions returned on `initialize` (the model's first steer about what this server is for).

func (*Server) SetServerInfo

func (s *Server) SetServerInfo(name, version string)

SetServerInfo overrides the name/version advertised on `initialize`. Useful when the same Server is embedded in another binary (desktop client) so the MCP client knows it isn't talking to the standalone mcp-server CLI.

type StdioTransport

type StdioTransport struct {
	// contains filtered or unexported fields
}

StdioTransport reads MCP JSON-RPC frames from stdin (newline-delimited) and writes responses to stdout. Each frame is dispatched to Server.HandleFrame.

This is the transport Claude Desktop uses today via the `claude_desktop_config.json` `command` field — the host spawns the binary and pipes JSON-RPC over its stdio.

func NewStdioServer deprecated

func NewStdioServer(registry *sdktools.Registry, execCtx sdktools.ExecutionContext) *StdioTransport

NewStdioServer is kept as a thin shim so existing callers in cmd/serve.go compile unchanged. New code should call NewServer + NewStdioTransport directly.

Deprecated: use NewServer + NewStdioTransport.

func NewStdioTransport

func NewStdioTransport(server *Server) *StdioTransport

NewStdioTransport returns a transport that reads from stdin and writes to stdout. The Server it wraps owns the tool registry and execution context.

func (*StdioTransport) Run

func (t *StdioTransport) Run(ctx context.Context) error

Run starts the read loop. It returns nil on clean EOF and error on anything else (I/O failure, context cancellation).

Jump to

Keyboard shortcuts

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