Module

tools.handler

MCP JSON-RPC protocol handler.

Handles the Model Context Protocol's Streamable HTTP transport. Receives a chirpRequest, returns a chirp Response— this means it participates in the normal middleware pipeline (auth, CORS, rate limiting all apply).

Implements the minimal MCP surface for v1:

  • initialize— capability negotiation (tools only)
  • notifications/initialized— client acknowledgment (no-op)
  • tools/list— return registered tool schemas
  • tools/call— dispatch to tool handler, return result
4Classes8Functions

Classes

JsonRpcError 2 ▼
JSON-RPC error object (§5.1).

JSON-RPC error object (§5.1).

Attributes

Name Type Description
code int —
message str —
JsonRpcErrorResponse 3 ▼
JSON-RPC error response envelope.

JSON-RPC error response envelope.

Attributes

Name Type Description
jsonrpc str —
error JsonRpcError —
id str | int | float | None —
JsonRpcSuccessResponse 3 ▼
JSON-RPC success response envelope.

JSON-RPC success response envelope.

Attributes

Name Type Description
jsonrpc str —
result Any —
id str | int | float | None —
McpContentBlock 2 ▼
MCP text content block.

MCP text content block.

Attributes

Name Type Description
type str —
text str —

Functions

handle_mcp_request 2 Response ▼
Handle an MCP JSON-RPC request. Takes a chirp Request, returns a chirp Respons…
async
async def handle_mcp_request(request: Request, registry: ToolRegistry) -> Response

Handle an MCP JSON-RPC request.

Takes a chirp Request, returns a chirp Response. This function is called from within the middleware pipeline inhandle_request(), so all middleware (auth, CORS, rate limiting) applies.

Parameters
Name Type Description
request Request
registry ToolRegistry
Returns
Response
_handle_notification 1 Response ▼
Handle a JSON-RPC notification (no response expected). MCP clients send ``noti…
def _handle_notification(method: str) -> Response

Handle a JSON-RPC notification (no response expected).

MCP clients sendnotifications/initializedafter the initialize handshake completes. Per JSON-RPC spec, notifications have noid and the server MUST NOT reply. We return 204 No Content.

Parameters
Name Type Description
method str
Returns
Response
_dispatch 3 Any ▼
Route a JSON-RPC method to the appropriate handler.
async
async def _dispatch(method: str, params: dict[str, Any], *, registry: ToolRegistry) -> Any
Parameters
Name Type Description
method str
params dict[str, Any]
registry ToolRegistry
Returns
Any
_handle_initialize 1 dict[str, Any] ▼
Handle MCP ``initialize`` — capability negotiation.
def _handle_initialize(params: dict[str, Any]) -> dict[str, Any]
Parameters
Name Type Description
params dict[str, Any]
Returns
dict[str, Any]
_handle_tools_list 1 dict[str, Any] ▼
Handle MCP ``tools/list`` — return registered tool schemas.
def _handle_tools_list(registry: ToolRegistry) -> dict[str, Any]
Parameters
Name Type Description
registry ToolRegistry
Returns
dict[str, Any]
_handle_tools_call 2 dict[str, Any] ▼
Handle MCP ``tools/call`` — dispatch to tool handler.
async
async def _handle_tools_call(params: dict[str, Any], registry: ToolRegistry) -> dict[str, Any]
Parameters
Name Type Description
params dict[str, Any]
registry ToolRegistry
Returns
dict[str, Any]
_format_result 1 McpContentBlock ▼
Format a tool result as an MCP content block.
def _format_result(result: Any) -> McpContentBlock
Parameters
Name Type Description
result Any
Returns
McpContentBlock
_json_response 2 Response ▼
Build a chirp Response with JSON content.
def _json_response(status: int, body: JsonRpcErrorResponse | JsonRpcSuccessResponse) -> Response
Parameters
Name Type Description
status int
body JsonRpcErrorResponse | JsonRpcSuccessResponse
Returns
Response