mcp-stdio copilot-instructions.md

Copilot code review instructions for mcp-stdio

Repository overview

mcp-stdio is a stdio-to-HTTP/SSE gateway/relay for the Model Context Protocol. It translates between the stdio JSON-RPC framing that MCP hosts (Claude Code, Claude Desktop, etc.) speak and the MCP HTTP transports that remote servers expose:

• Streamable HTTP — run() in src/mcp_stdio/relay.py, speaking two protocol eras: 2025-06-18 (legacy, the default) and 2026-07-28 (modern, opt-in via --protocol-era modern|auto; era detected by a server/discover probe). The modern era adds per-request _meta + Mcp-Method/Mcp-Name headers, no sessions, background subscriptions/listen streams (including resources/subscribe interception), an MRTR bridge translating input_required results into legacy elicitation/sampling/roots round-trips, and a stdin reader thread that aborts the in-flight POST on notifications/cancelled.
• Legacy SSE (2024-11-05) — run_sse() in src/mcp_stdio/relay.py (--protocol-era is ignored there, with a warning)

This repo implements zero MCP tools of its own. There is no FastMCP, no @mcp.tool() decorator, nothing that "wraps a tool return value" — do not review this code as if it were an MCP tool server. It works in two directions:

• relay (the original job, relay.py) — faithfully relays a stdio stream to/from a remote HTTP endpoint (client side: stdin/stdout in, HTTP out), plus a full OAuth 2.1 client (oauth.py) and on-disk token cache (token_store.py) to authenticate against that endpoint.
• serve (server.py, mcp-stdio serve) — the mirror image (server side: HTTP in, stdio out): spawns a local stdio MCP server as a child process and publishes it as a Streamable HTTP endpoint so clients that can't spawn the server locally can reach it over the network. Dual-era on one endpoint: _request_era() classifies each POST conservatively (modern only on positive evidence — params._meta carries the protocolVersion key, or the method is server/discover); legacy clients keep the sessioned per-child model unchanged, modern clients are served statelessly from a principal-keyed ModernBackendPool behind a request-validation ladder. Stdlib-only (http.server + subprocess); optional layered auth (open / static bearer / embedded OAuth 2.1 authorization server). See Review focus §5 and §6.