Documentation
¶
Overview ¶
Package mcp integrates Model Context Protocol (MCP) servers into BroCode.
MCP servers are spawned as stdio subprocesses (the standard convention used by opencode, Claude, Cursor, etc.). Every tool a server exposes becomes a native BroCode tool named `mcp__<server>__<tool>`, so the model can call it exactly like any built-in tool. Config is read from the standard locations, highest priority first:
.brocode/mcp.json (project, BroCode-specific)
.mcp.json (project, standard MCP convention)
~/.config/brocode/mcp.json (global, BroCode-specific)
~/.config/opencode/opencode.jsonc (the opencode "mcp" block, fallback only;
skipped when BROCODE_NO_OPENCODE=1)
Index ¶
- func AddServerToFile(path, name string, cfg ServerConfig) error
- func GlobalMCPPath() string
- func ProjectMCPPath() string
- func ProviderDefinitions(tools []*MCPTool) []provider.ToolDefinition
- func RemoveServerFromFile(path, name string) error
- type Client
- type ClientFactory
- type MCPTool
- func (t *MCPTool) Description() string
- func (t *MCPTool) Execute(ctx context.Context, argsJSON string) (string, error)
- func (t *MCPTool) FullName() string
- func (t *MCPTool) Name() string
- func (t *MCPTool) Parameters() map[string]any
- func (t *MCPTool) Server() string
- func (t *MCPTool) ToolName() string
- type Manager
- func (m *Manager) AddServer(name string, cfg ServerConfig)
- func (m *Manager) Close()
- func (m *Manager) Config(name string) (ServerConfig, bool)
- func (m *Manager) Errors() map[string]string
- func (m *Manager) LoadDefaults()
- func (m *Manager) ServerNames() []string
- func (m *Manager) SetClientFactory(f ClientFactory)
- func (m *Manager) Start(ctx context.Context)
- func (m *Manager) ToolNames(server string) []string
- func (m *Manager) Tools() []*MCPTool
- type ServerConfig
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AddServerToFile ¶ added in v0.1.1
func AddServerToFile(path, name string, cfg ServerConfig) error
AddServerToFile merges a server config into the mcpServers JSON file at path (creating the file when missing), preserving every other server and any fields BroCode does not model. A server with the same name is replaced.
func GlobalMCPPath ¶ added in v0.1.1
func GlobalMCPPath() string
GlobalMCPPath returns the per-user MCP config path.
func ProjectMCPPath ¶ added in v0.1.1
func ProjectMCPPath() string
ProjectMCPPath returns the standard project-scope MCP config path (the Claude/Cursor-compatible .mcp.json convention that BroCode already reads).
func ProviderDefinitions ¶
func ProviderDefinitions(tools []*MCPTool) []provider.ToolDefinition
ProviderDefinitions converts MCP tools into provider tool definitions for the LLM (used by the engine alongside built-in definitions).
func RemoveServerFromFile ¶ added in v0.1.1
RemoveServerFromFile deletes a server from the mcpServers file at path. A missing file or unknown name is not an error (idempotent delete).
Types ¶
type Client ¶
type Client interface {
Initialize(ctx context.Context, req mcp.InitializeRequest) (*mcp.InitializeResult, error)
ListTools(ctx context.Context, req mcp.ListToolsRequest) (*mcp.ListToolsResult, error)
CallTool(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error)
Close() error
}
Client is the minimal MCP client surface BroCode needs. *client.Client satisfies it; tests inject an in-process client instead of spawning a subprocess.
type ClientFactory ¶
type ClientFactory func(cfg ServerConfig) (Client, error)
ClientFactory creates a client for a server config. The default factory spawns the server as a stdio subprocess.
type MCPTool ¶
type MCPTool struct {
// contains filtered or unexported fields
}
MCPTool adapts a remote MCP tool to the native tool.Tool interface.
func (*MCPTool) Description ¶
Description implements tool.Tool.
func (*MCPTool) Execute ¶
Execute implements tool.Tool, forwarding the call to the MCP server and returning the text content of the result.
func (*MCPTool) Parameters ¶
Parameters implements tool.Tool, converting the MCP JSON schema.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager owns all configured MCP servers and the tools they expose.
func NewManager ¶
func NewManager() *Manager
NewManager creates an empty MCP manager. Call LoadDefaults then Start, or AddServer for programmatic config.
func (*Manager) AddServer ¶
func (m *Manager) AddServer(name string, cfg ServerConfig)
AddServer registers a server config under the given name (later adds override earlier ones with the same name).
func (*Manager) Config ¶ added in v0.1.1
func (m *Manager) Config(name string) (ServerConfig, bool)
Config returns the config registered for a server name (ok=false when unknown). Used by the CLI list command.
func (*Manager) Errors ¶
Errors returns per-server startup errors keyed by server name (empty value means the server started cleanly).
func (*Manager) LoadDefaults ¶
func (m *Manager) LoadDefaults()
LoadDefaults reads MCP servers from all standard locations. Precedence (highest wins): project BroCode → project .mcp.json → global BroCode → opencode.jsonc. BroCode's own configs are authoritative; the opencode block only contributes servers BroCode knows nothing about (and is skipped when BROCODE_NO_OPENCODE=1 for fully standalone operation). It never errors — missing files simply contribute nothing.
func (*Manager) ServerNames ¶
ServerNames returns the configured server names in stable (sorted) order.
func (*Manager) SetClientFactory ¶
func (m *Manager) SetClientFactory(f ClientFactory)
SetClientFactory overrides how clients are created (used by tests).
func (*Manager) Start ¶
Start connects to every configured server, runs the MCP handshake and discovers its tools concurrently. A failing server is recorded in Errors() but does not abort the others — one broken server must never kill the whole session.
type ServerConfig ¶
type ServerConfig struct {
Type string `json:"type,omitempty"` // "stdio" (default), "http"/"streamable-http", "sse"
Command string `json:"command,omitempty"` // stdio: executable to spawn
Args []string `json:"args,omitempty"` // stdio: command arguments
URL string `json:"url,omitempty"` // http/sse: endpoint
Env map[string]string `json:"env,omitempty"` // stdio: extra env vars
Headers map[string]string `json:"headers,omitempty"` // http/sse: static request headers
}
ServerConfig is a single MCP server definition. A server is either spawned as a stdio subprocess (Command set) or reached over the network as a Streamable HTTP / SSE endpoint (URL set). Environment overrides apply to stdio servers; Headers apply to HTTP/SSE servers.
func (ServerConfig) Transport ¶
func (c ServerConfig) Transport() string
Transport returns the wire transport for this server config.
Source Files