Documentation
¶
Overview ¶
Package mcp provides MCP (Model Context Protocol) client integration for squad agents. It connects to MCP servers, discovers their tools, and bridges them into squad's tool handler system.
Index ¶
Constants ¶
const ToolPrefix = "mcp__"
ToolPrefix is the namespace prefix for MCP tools: mcp__<server>__<tool>.
Variables ¶
This section is empty.
Functions ¶
func PrefixedName ¶
PrefixedName returns the squad-namespaced tool name.
func PreflightServer ¶
func PreflightServer(ctx context.Context, cfg ServerConfig)
PreflightServer runs server-specific readiness checks before the MCP subprocess is spawned. It never returns an error — the goal is to surface an actionable hint when a known fragile setup looks misconfigured, while still letting the MCP attempt its own connection (Chrome's 144+ permission API may succeed even when the legacy CDP port is closed).
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client wraps an MCP server connection with its configuration.
func Connect ¶
func Connect(ctx context.Context, cfg ServerConfig) (*Client, error)
Connect starts an MCP server connection and performs the protocol handshake. For stdio transport, it spawns a subprocess. For SSE transport, it connects to a running HTTP server. It then sends the initialize request and discovers available tools via tools/list.
func NewTestClient ¶
NewTestClient creates a Client for testing purposes. If inner is nil, only validation and cleanup paths work. If inner is provided, CallTool and Close will delegate to it.
func (*Client) CallTool ¶
func (c *Client) CallTool(ctx context.Context, name string, args map[string]any) (*mcptypes.CallToolResult, error)
CallTool invokes a tool on the MCP server by its original (un-prefixed) name.
func (*Client) Close ¶
Close shuts down the MCP server subprocess and releases resources. It applies a timeout because mcp-go's Close() blocks on cmd.Wait() after closing stdin — MCP servers with long-lived connections (e.g. WebSocket, HTTP) often don't exit on stdin EOF.
func (*Client) MaxResultBytes ¶
MaxResultBytes returns the effective per-tool-call output cap for this server. Resolution: explicit positive value wins, 0 maps to the package default, negative disables truncation entirely.
type ServerConfig ¶
type ServerConfig struct {
// Name is a short identifier used to namespace tools (e.g., "burpsuite").
// Tools are registered as "mcp__<name>__<tool_name>".
Name string `yaml:"name"`
// Transport selects the protocol: "stdio" (default), "sse", or
// "streamable_http". Stdio spawns a subprocess and communicates over
// stdin/stdout. SSE connects to a running HTTP server using legacy
// Server-Sent Events. streamable_http speaks the current MCP HTTP
// spec used by hosted endpoints like Google's MCP services.
Transport string `yaml:"transport,omitempty"`
// Command is the executable to spawn for stdio transport.
Command string `yaml:"command,omitempty"`
// Args are command-line arguments passed to the command.
Args []string `yaml:"args,omitempty"`
// Env are additional environment variables set for the subprocess.
// Format: KEY=VALUE strings.
Env []string `yaml:"env,omitempty"`
// URL is the endpoint for SSE / streamable_http transport
// (e.g., "http://localhost:9876" or
// "https://drivemcp.googleapis.com/mcp/v1").
URL string `yaml:"url,omitempty"`
// Headers are additional HTTP headers for SSE / streamable_http
// transport. Format: KEY=VALUE strings.
Headers []string `yaml:"headers,omitempty"`
// MaxResultBytes caps the bytes returned to the model from any
// single tool call on this server. 0 means use the package
// default (32 KiB). Negative means no cap — pass everything
// through (useful for document-reading servers like Google Docs
// where the HTML export of a multi-page table exceeds 32 KiB
// and a hard cap silently slices the document mid-row).
MaxResultBytes int `yaml:"max_result_bytes,omitempty"`
}
ServerConfig defines how to connect to an MCP server. Agents declare MCP dependencies in agent.yaml under mcp_servers.
func (ServerConfig) ConnectString ¶
func (c ServerConfig) ConnectString() string
ConnectString returns a human-readable description of the connection target, e.g. "stdio: /usr/bin/tool [--flag]" or "sse: http://localhost:9876".
func (ServerConfig) TransportType ¶
func (c ServerConfig) TransportType() string
TransportType returns the effective transport, defaulting to "stdio".
type ToolHandler ¶
type ToolHandler struct {
Def llms.Tool
Call func(ctx context.Context, rawArgs []byte) (string, error)
}
ToolHandler represents a bridged MCP tool with its definition and call function. This mirrors tools.Handler but avoids an import cycle (agent → mcp → tools → metrics → agent).
func BuildHandlers ¶
func BuildHandlers(clients []*Client) []ToolHandler
BuildHandlers converts all tools from a set of MCP clients into squad tool handlers. Each tool is namespaced as mcp__<server>__<tool>.