MingaClaudeBridge.MCP (minga_claude_bridge v0.1.0)

Copy Markdown View Source

Routes the JSON-RPC messages of the in-process MCP server named "minga".

Claude Code hosts the bridge's tools as an SDK MCP server. It sends each JSON-RPC message to the bridge inside an mcp_message control request (see MingaClaudeBridge.Wire.ControlRequest) and waits for a control_response. route/2 decides what to do with one message, given the tool declarations of the current turn. It is pure: it performs no I/O and holds no state.

Outcomes

  • {:reply, jsonrpc_id, result} - answer with a JSON-RPC result. Used for initialize, ping, and tools/list.
  • :acknowledge - the message is not a request (a notification such as notifications/initialized, or a JSON-RPC response). Claude Code still waits for the control response, so the session answers with the acknowledgement the Agent SDK sends: {"jsonrpc": "2.0", "result": {}, "id": 0}.
  • {:tool_call, call} - a valid tools/call. Minga runs the tool, so the session does not answer yet. It holds the control request in MingaClaudeBridge.ToolCalls until the next Minga request carries the result.
  • {:reply_error, jsonrpc_id, code, message} - answer with a JSON-RPC error. jsonrpc_id is nil when the request id is not a string or integer.

reply_line/2 encodes every outcome except {:tool_call, _} as the control_response line to write.

Error codes

Standard JSON-RPC 2.0 codes:

  • -32600 (invalid request) - the message has an id and a method, but one of them has the wrong JSON type.
  • -32601 (method not found) - any method other than initialize, ping, tools/list, and tools/call.
  • -32602 (invalid params) - a tools/call for a tool not offered this turn, without params._meta["claudecode/toolUseId"], or with arguments that fail the minimal schema check. The MCP specification uses this code for unknown tools.

Classifying messages

A message is a request when it has a method key and a non-null id key, which is the test the Agent SDK applies. Everything else is acknowledged.

tools/list

The list is built from the declarations passed to route/2, so it always matches the current turn and is never cached. Each schema goes through MingaClaudeBridge.MCP.Schema.flatten/1, and the constraint that flattening removes is prepended to the description.

Argument check (limited)

tools/call arguments must be a JSON object (an absent arguments counts as an empty object) and must contain every key in the flattened schema's top-level required list. Nothing else is checked: not property types, nested schemas, enums, formats, or the anyOf/oneOf constraints that flattening drops. The bridge does not include a JSON Schema validator. Minga validates the arguments against the full schema before it runs the tool, and reports a failure to the model as a tool error.

Protocol version

initialize answers with the client's requested protocolVersion when it is one the Agent SDK 0.3.330 supports, and otherwise with the latest one, "2025-11-25". This matches the MCP TypeScript SDK server.

Error messages name tools and argument keys but never contain argument values.

Summary

Types

A decoded JSON-RPC 2.0 message from an mcp_message control request.

A tool Minga offers for the current turn. input_schema is a string-keyed JSON Schema.

Functions

Encodes a reply outcome as the control_response line that answers control request request_id.

Routes one JSON-RPC message, given the tools offered for the current turn.

Returns the MCP server name the bridge registers with Claude Code.

Types

message()

@type message() :: %{optional(String.t()) => term()}

A decoded JSON-RPC 2.0 message from an mcp_message control request.

outcome()

@type outcome() :: reply() | {:tool_call, MingaClaudeBridge.MCP.CallRequest.t()}

reply()

@type reply() ::
  {:reply, MingaClaudeBridge.Wire.jsonrpc_id(), map()}
  | :acknowledge
  | {:reply_error, MingaClaudeBridge.Wire.error_id(), integer(), String.t()}

tool()

@type tool() :: %{name: String.t(), description: String.t(), input_schema: map()}

A tool Minga offers for the current turn. input_schema is a string-keyed JSON Schema.

Functions

reply_line(request_id, arg2)

@spec reply_line(String.t(), reply()) :: MingaClaudeBridge.Wire.line()

Encodes a reply outcome as the control_response line that answers control request request_id.

route(message, tools)

@spec route(message(), [tool()]) :: outcome()

Routes one JSON-RPC message, given the tools offered for the current turn.

server_name()

@spec server_name() :: String.t()

Returns the MCP server name the bridge registers with Claude Code.