PR #40: feat: cancel-aware response filter (drops late responses for cancelled ids)

• Repository: shigechika/mcp-stdio
• Author: shigechika
• State: closed | merged: True
• Link: https://github.com/shigechika/mcp-stdio/pull/40

Description (problem / solution / changelog)

Summary

• Enforces the MCP cancellation spec's canceller-side SHOULD on the wire: notifications/cancelled ids seen on stdin are tracked (60 s TTL), and any late JSON-RPC response carrying one of those ids is dropped before reaching the downstream client.
• Also shields clients from the reciprocal receiver-side violation (cf. python-sdk#2480 — server still sends an ErrorData response on cancel).
• Works around claude-code#51073 where Claude Code drops the stdio transport on late responses instead of ignoring them.
• Enabled by default; --no-cancel-filter opt-out for debugging the raw upstream wire.
• Applies to both Streamable HTTP (run()) and legacy SSE (run_sse()) transports.

Closes #39.

Design

• _CancelTracker — thread-safe id→monotonic-timestamp dict, 60 s TTL, size-triggered GC at 256 entries. Shared between the main loop and the SSE reader thread.
• _extract_cancel_id(line) — regex fast path ("method":"notifications/cancelled") gates a full json.loads verify so the slow path runs only on actual cancels.
• _emit(line, tracker) — single gate replacing every response-bearing print in relay.py (5 call sites). Only proper JSON-RPC responses (object with id + result/error) are eligible for dropping; notifications, server-initiated requests, JSON-RPC batches, and anything that fails to parse pass through. mcp-stdio's own synthesized error responses (_error_response) intentionally bypass the gate.

Out of scope (future work)

• notifications/progress suppression (separate progressToken keyed map)
• Aborting paginated list fetches mid-merge on cancel
• JSON-RPC batch support (current MCP HTTP transport forbids batches)

Test plan

• pytest tests/ -v → 293 passed, 3 skipped (local, macOS/Python 3.12)
• TestCancelTracker covers add/contains/TTL/GC/thread-safety, plus id=0 and string ids
• TestExtractCancelId covers int/string requestId, malformed json, missing params, non-dict params, and substring false-positive guard
• TestEmit covers passthrough, drop, error response, uncancelled id, notification without id, server-initiated request, malformed json, json batch
• TestRunCancelFilter — Streamable HTTP end-to-end: cancel-then-late-response drop, cancel forwarded upstream, --no-cancel-filter disables filter
• TestRunSseCancelFilter — SSE end-to-end: async response via reader thread dropped when id is cancelled, passes through otherwise
• TestCli — --no-cancel-filter wires to both run() and run_sse()
• Manual smoke test against a real MCP server (optional — behavior is covered by the end-to-end tests)

Changed files

• CLAUDE.md (modified, +1/-0)
• README.ja.md (modified, +1/-0)
• README.md (modified, +1/-0)
• src/mcp_stdio/cli.py (modified, +18/-1)
• src/mcp_stdio/relay.py (modified, +164/-10)
• tests/test_cli.py (modified, +39/-0)
• tests/test_relay.py (modified, +421/-0)