Documentation
¶
Overview ¶
Package proxy implements a transparent MCP STDIO proxy.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func MakeErrorResponse ¶
func MakeErrorResponse(id json.RawMessage, code int, message string) []byte
MakeErrorResponse creates a JSON-RPC error response for the given request ID.
func MakeErrorResponseWithData ¶ added in v0.3.9
func MakeErrorResponseWithData(id json.RawMessage, code int, message string, data map[string]any) []byte
MakeErrorResponseWithData creates a JSON-RPC error response with optional structured error data for the given request ID.
func StripMCPPrefix ¶ added in v0.3.1
StripMCPPrefix removes the MCP server prefix from a tool name. Tool names from MCP clients arrive as "mcp__<server>__<tool>" but downstream classification and receipts should use the bare tool name.
Types ¶
type Handler ¶
type Handler func(direction string, raw []byte, msg *Message) *HandlerResult
Handler is called for each message flowing through the proxy. direction is "client_to_server" or "server_to_client". Return nil to forward normally.
type HandlerResult ¶
type HandlerResult struct {
// Block suppresses forwarding and sends ClientResponse to the client instead.
Block bool
// ClientResponse is sent to the client when Block is true.
ClientResponse []byte
}
HandlerResult tells the proxy what to do with a message.
type Message ¶
type Message struct {
JSONRPC string `json:"jsonrpc"`
ID json.RawMessage `json:"id,omitempty"`
Method string `json:"method,omitempty"`
Params json.RawMessage `json:"params,omitempty"`
Result json.RawMessage `json:"result,omitempty"`
Error json.RawMessage `json:"error,omitempty"`
}
Message represents a parsed JSON-RPC 2.0 message.
func ParseMessage ¶
ParseMessage attempts to parse a JSON-RPC message from a line. Returns nil if the line is not valid JSON-RPC.
func (*Message) IDString ¶
IDString returns the message ID as a normalized string for matching purposes. Strips surrounding quotes from JSON string IDs so "1" and 1 both work as map keys.
func (*Message) IsNotification ¶
IsNotification returns true if the message is a notification (method but no id).
func (*Message) IsResponse ¶
IsResponse returns true if the message is a response (has result or error).
func (*Message) IsToolCall ¶
IsToolCall returns true if this is a tools/call request.
func (*Message) ParseToolCallParams ¶
func (m *Message) ParseToolCallParams() (*ToolCallParams, error)
ParseToolCallParams extracts tool name and arguments from a tools/call request. Returns a zero-value ToolCallParams (empty name) if params are nil or missing, so callers always get a non-nil result for tool calls.
type Proxy ¶
type Proxy struct {
// contains filtered or unexported fields
}
Proxy is a transparent STDIO MCP proxy.
func (*Proxy) Run ¶
Run starts the child MCP server and proxies stdin/stdout bidirectionally. It blocks until the child process exits, either of the STDIO pumps closes (stdin EOF ends a normal STDIO session), or ctx is cancelled. Cancellation kills the upstream child so both pumps unblock and Run returns promptly.
type ToolCallParams ¶
type ToolCallParams struct {
Name string `json:"name"`
Arguments map[string]any `json:"arguments,omitempty"`
// Meta holds the MCP _meta field. Claude Code populates
// _meta["claudecode/toolUseId"] with the tool_use_id from the hook payload,
// enabling correlation between hook pre-check receipts and proxy post-action
// receipts for the same logical tool invocation.
// Typed as map[string]any (not map[string]string) so that non-string values
// in _meta do not cause json.Unmarshal to fail and silently bypass policy.
Meta map[string]any `json:"_meta,omitempty"`
}
ToolCallParams holds parsed params for a tools/call request.
func (*ToolCallParams) ToolUseID ¶ added in v0.14.0
func (p *ToolCallParams) ToolUseID() string
ToolUseID returns the Claude Code tool_use_id from _meta, or empty string if absent or not a string. This is the correlation key linking a hook receipt to its paired proxy receipt.
Source Files