mcp

package
v1.14.0 Latest Latest
Warning

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

 Go to latest Published: Jul 15, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

cmd/celeste/tools/mcp/adapter.go

cmd/celeste/tools/mcp/client.go

cmd/celeste/tools/mcp/config.go

cmd/celeste/tools/mcp/discovery.go

cmd/celeste/tools/mcp/jsonrpc.go

cmd/celeste/tools/mcp/manager.go

cmd/celeste/tools/mcp/sse.go

cmd/celeste/tools/mcp/stdio.go

cmd/celeste/tools/mcp/transport.go

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DefaultConfigPath 

func DefaultConfigPath() string

DefaultConfigPath returns the default path for the MCP configuration file.

func DiscoverAndRegister 

func DiscoverAndRegister(ctx context.Context, client *Client, registry *tools.Registry, serverName string) ([]string, error)

DiscoverAndRegister queries the MCP server for available tools via tools/list, creates an MCPTool adapter for each, and registers them in the registry. The serverName is recorded in each tool's metadata for debugging and display.

func DiscoverConfigPaths added in v1.13.0 

func DiscoverConfigPaths(cwd, home string) []string

DiscoverConfigPaths returns the MCP config files that exist on disk, ordered from lowest to highest precedence. Later paths override earlier ones on server-name collision (see LoadMerged). Non-existent candidates are skipped, so an empty slice means no MCP config anywhere.

func SetServerEnabled added in v1.13.0 

func SetServerEnabled(path, name string, enabled bool) error

SetServerEnabled flips the `enabled` flag of one server in the config file at path and writes it back, preserving all other fields. Errors if the file or the named server does not exist.

Types

type Client 

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

Client is a high-level MCP client that handles the protocol handshake, tool discovery, and tool execution over a Transport.

func NewClient 

func NewClient(transport Transport, clientName, clientVersion string) *Client

NewClient creates a new MCP client over the given transport.

func (*Client) CallTool 

func (c *Client) CallTool(ctx context.Context, name string, arguments map[string]any) (string, error)

CallTool executes a tool on the MCP server and returns the text result. Multiple text content blocks are joined with newlines.

func (*Client) Close 

func (c *Client) Close() error

Close shuts down the client and its transport.

func (*Client) Initialize 

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

Initialize performs the MCP initialize handshake. Sends initialize request, validates the server's protocol version, then sends notifications/initialized.

func (*Client) ListTools 

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

ListTools discovers available tools from the MCP server.

func (*Client) ProtocolVersion added in v1.13.0 

func (c *Client) ProtocolVersion() string

ProtocolVersion returns the MCP protocol version negotiated with the server during Initialize. Empty until Initialize succeeds.

func (*Client) ServerName 

func (c *Client) ServerName() string

ServerName returns the server's name after initialization.

type ContentBlock added in v1.8.0 

type ContentBlock struct {
	Type string `json:"type"`
	Text string `json:"text"`
}

ContentBlock is a single content item in a tool call response.

type ErrorObject 

type ErrorObject struct {
	Code    int             `json:"code"`
	Message string          `json:"message"`
	Data    json.RawMessage `json:"data,omitempty"`
}

ErrorObject is the error payload in a JSON-RPC 2.0 response.

func (*ErrorObject) Error 

func (e *ErrorObject) Error() string

Error implements the error interface.

type HTTPTransport added in v1.13.0 

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

HTTPTransport speaks MCP over Streamable HTTP: each outbound message is POSTed to the endpoint; the response is either a single JSON object or an SSE stream of JSON-RPC messages. Decoded responses are queued for Receive to drain.

func NewHTTPTransport added in v1.13.0 

func NewHTTPTransport(url string) (*HTTPTransport, error)

NewHTTPTransport creates a Streamable-HTTP transport for the given endpoint.

func (*HTTPTransport) Close added in v1.13.0 

func (t *HTTPTransport) Close() error

Close is a no-op for the stateless HTTP transport.

func (*HTTPTransport) Receive added in v1.13.0 

func (t *HTTPTransport) Receive() (*Response, error)

Receive drains the next queued response.

func (*HTTPTransport) Send added in v1.13.0 

func (t *HTTPTransport) Send(req *Request) error

Send POSTs a request and queues the resulting response(s).

func (*HTTPTransport) SendNotification added in v1.13.0 

func (t *HTTPTransport) SendNotification(notif *Notification) error

SendNotification POSTs a notification; no response is queued.

func (*HTTPTransport) SetProtocolVersion added in v1.13.0 

func (t *HTTPTransport) SetProtocolVersion(v string)

SetProtocolVersion sets the value sent as the MCP-Protocol-Version header.

type MCPConfig 

type MCPConfig struct {
	Servers map[string]ServerConfig `json:"mcpServers"`
}

MCPConfig is the top-level configuration for MCP servers. Loaded from ~/.celeste/mcp.json.

func LoadConfig 

func LoadConfig(path string) (*MCPConfig, error)

LoadConfig reads and parses the MCP configuration from a JSON file. If the file does not exist, returns an empty config (not an error). This allows celeste to start without any MCP servers configured.

func LoadMerged added in v1.13.0 

func LoadMerged(paths []string) (*MCPConfig, error)

LoadMerged folds every config in paths into a single MCPConfig. paths must be ordered lowest-to-highest precedence (as DiscoverConfigPaths returns them): a server name present in a later path replaces the earlier definition wholesale. Each surviving server is stamped with the Origin path it came from. A missing file is skipped (LoadConfig already treats os.ErrNotExist as empty).

type MCPTool 

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

MCPTool wraps an MCP tool definition and implements the tools.Tool interface. It delegates execution to the MCP Client, bridging external MCP servers into celeste's unified tool system.

func NewMCPTool 

func NewMCPTool(def MCPToolDef, client *Client, serverName string) *MCPTool

NewMCPTool creates a new MCPTool adapter for the given MCP tool definition.

func (*MCPTool) Description 

func (m *MCPTool) Description() string

func (*MCPTool) Execute 

func (m *MCPTool) Execute(ctx context.Context, input map[string]any, progress chan<- tools.ProgressEvent) (tools.ToolResult, error)

Execute calls the MCP tool via the client and returns the result. Server-side errors are returned as ToolResult with Error=true so the LLM can see and react to the error message.

func (*MCPTool) InterruptBehavior 

func (m *MCPTool) InterruptBehavior() tools.InterruptBehavior

func (*MCPTool) IsConcurrencySafe 

func (m *MCPTool) IsConcurrencySafe(input map[string]any) bool

IsConcurrencySafe returns false because MCP tool calls go over a shared transport and we cannot guarantee the server handles concurrent calls safely.

func (*MCPTool) IsReadOnly 

func (m *MCPTool) IsReadOnly() bool

IsReadOnly returns false because we cannot know if an MCP tool mutates state.

func (*MCPTool) Name 

func (m *MCPTool) Name() string

func (*MCPTool) Parameters 

func (m *MCPTool) Parameters() json.RawMessage

func (*MCPTool) ValidateInput 

func (m *MCPTool) ValidateInput(input map[string]any) error

ValidateInput returns nil -- validation is delegated to the MCP server.

type MCPToolDef 

type MCPToolDef struct {
	Name        string          `json:"name"`
	Description string          `json:"description"`
	InputSchema json.RawMessage `json:"inputSchema"`
}

MCPToolDef is a tool definition returned by the MCP server.

type Manager 

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

Manager handles the lifecycle of all MCP server connections. It loads configuration, connects to servers, discovers tools, and registers them in the tool registry.

func NewManager 

func NewManager(configPath string, registry *tools.Registry) *Manager

NewManager creates a new MCP Manager. configPath is the path to the MCP configuration file (e.g., ~/.celeste/mcp.json). registry is the tool registry where discovered MCP tools will be registered.

func NewManagerMulti added in v1.13.0 

func NewManagerMulti(paths []string, registry *tools.Registry) *Manager

NewManagerMulti creates a Manager that merges MCP config from multiple discovered paths (see DiscoverConfigPaths / LoadMerged) instead of a single file. Lower-index paths are overridden by higher-index paths on name clash.

func (*Manager) Connect added in v1.13.0 

func (m *Manager) Connect(ctx context.Context, name string, cfg ServerConfig) error

Connect builds a transport from cfg, connects, and registers the server's tools at runtime. Safe to call after Start (lazy connect). A server that is already connected is a no-op.

func (*Manager) Disconnect added in v1.13.0 

func (m *Manager) Disconnect(name string) error

Disconnect closes a server's client and removes exactly the tools it added. No-op if the server is not connected.

func (*Manager) IsConnected added in v1.13.0 

func (m *Manager) IsConnected(name string) bool

IsConnected reports whether a server currently has a live client.

func (*Manager) ServerStatus 

func (m *Manager) ServerStatus() []ServerInfo

ServerStatus returns health information for all connected MCP servers.

func (*Manager) Start 

func (m *Manager) Start(ctx context.Context) error

Start loads the MCP configuration, connects to all configured servers, discovers their tools, and registers them in the tool registry. If the config file does not exist, it returns nil (no MCP configured). If a server fails to connect, it logs a warning and continues with others.

func (*Manager) Stop 

func (m *Manager) Stop() error

Stop gracefully disconnects from all MCP servers.

type Notification 

type Notification struct {
	JSONRPC string          `json:"jsonrpc"`
	Method  string          `json:"method"`
	Params  json.RawMessage `json:"params,omitempty"`
}

Notification is a JSON-RPC 2.0 notification (no ID, no response expected).

func NewNotification 

func NewNotification(method string) *Notification

NewNotification creates a JSON-RPC 2.0 notification (no ID).

type Request 

type Request struct {
	JSONRPC string          `json:"jsonrpc"`
	ID      int64           `json:"id"`
	Method  string          `json:"method"`
	Params  json.RawMessage `json:"params,omitempty"`
}

Request is a JSON-RPC 2.0 request.

func NewRequest 

func NewRequest(method string, params any) (*Request, error)

NewRequest creates a new JSON-RPC 2.0 request with an auto-incremented ID. params is marshaled to JSON. Pass nil for no params.

type Response 

type Response struct {
	JSONRPC string          `json:"jsonrpc"`
	ID      json.Number     `json:"id,omitempty"`
	Result  json.RawMessage `json:"result,omitempty"`
	Error   *ErrorObject    `json:"error,omitempty"`
}

Response is a JSON-RPC 2.0 response.

type SSETransport 

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

SSETransport communicates with an MCP server over HTTP Server-Sent Events. Requests are sent via POST to the server's endpoint URL. Responses are received via an SSE event stream from a GET connection.

func NewSSETransport 

func NewSSETransport(url string) (*SSETransport, error)

NewSSETransport connects to an MCP server's SSE endpoint. url is the base URL of the MCP server (e.g., "http://localhost:3000/sse").

func (*SSETransport) Close 

func (t *SSETransport) Close() error

Close shuts down the SSE connection.

func (*SSETransport) Receive 

func (t *SSETransport) Receive() (*Response, error)

Receive reads the next JSON-RPC response from the SSE event stream.

func (*SSETransport) Send 

func (t *SSETransport) Send(req *Request) error

Send sends a JSON-RPC request via HTTP POST to the server's endpoint.

func (*SSETransport) SendNotification 

func (t *SSETransport) SendNotification(notif *Notification) error

SendNotification sends a JSON-RPC notification via HTTP POST.

type ServerConfig 

type ServerConfig struct {
	// Enabled opts the server into auto-connection at startup. It is false by
	// default: a server is only connected if it explicitly sets
	// "enabled": true. This keeps configured-but-unused servers (e.g. an X
	// bridge awaiting its first OAuth login) from delaying startup.
	Enabled bool `json:"enabled,omitempty"`

	// Transport is "stdio" or "sse". Defaults to "stdio" if not set.
	Transport string `json:"transport"`

	// Command is the executable to spawn (stdio transport only).
	Command string `json:"command,omitempty"`

	// Args are command-line arguments (stdio transport only).
	Args []string `json:"args,omitempty"`

	// URL is the SSE endpoint URL (sse transport only).
	URL string `json:"url,omitempty"`

	// Env is a map of environment variables passed to the child process.
	// Values support ${VAR} expansion from the host environment.
	Env map[string]string `json:"env,omitempty"`

	// Origin is the absolute path of the config file this server was loaded
	// from. Set by the discovery/merge layer, never parsed from JSON. Used by
	// the /mcp panel to show provenance.
	Origin string `json:"-"`
}

ServerConfig defines how to connect to a single MCP server.

type ServerInfo 

type ServerInfo struct {
	Name      string
	Transport string
	Connected bool
	ToolCount int
}

ServerInfo contains health/status information for a connected MCP server.

type StdioTransport 

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

StdioTransport communicates with an MCP server via a child process's stdin and stdout. Each JSON-RPC message is a single line of JSON.

func NewStdioTransport 

func NewStdioTransport(command string, args []string, env map[string]string) (*StdioTransport, error)

NewStdioTransport spawns a child process and connects to its stdin/stdout. command is the executable to run (e.g., "npx", "python3"). args are the command-line arguments. env is an optional map of environment variables (supports ${VAR} expansion).

func (*StdioTransport) Close 

func (t *StdioTransport) Close() error

Close shuts down the child process and closes pipes.

func (*StdioTransport) Receive 

func (t *StdioTransport) Receive() (*Response, error)

Receive reads the next JSON line from stdout and parses it as a Response.

func (*StdioTransport) Send 

func (t *StdioTransport) Send(req *Request) error

Send sends a JSON-RPC request as a single JSON line to the child process stdin.

func (*StdioTransport) SendNotification 

func (t *StdioTransport) SendNotification(notif *Notification) error

SendNotification sends a JSON-RPC notification as a single JSON line.

type ToolCallResult added in v1.8.0 

type ToolCallResult struct {
	Content []ContentBlock `json:"content"`
}

ToolCallResult is the server's response to tools/call.

type Transport 

type Transport interface {
	// Send sends a JSON-RPC request to the server.
	// For requests, the caller should subsequently call Receive to get the response.
	Send(req *Request) error

	// SendNotification sends a JSON-RPC notification (no response expected).
	SendNotification(notif *Notification) error

	// Receive reads the next JSON-RPC response from the server.
	// Blocks until a response is available or the transport is closed.
	Receive() (*Response, error)

	// Close shuts down the transport, releasing all resources.
	Close() error
}

Transport is the abstraction over MCP communication channels. Implementations handle the physical sending and receiving of JSON-RPC messages over stdio (child process) or SSE (HTTP).

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.