Tool-result size governor for MCP

By TextForAgents LLC. MCP defines no limit on tool-result size, so one unbounded result from a third-party server you don't control can blow your agent's entire context window — or deadlock its stdio transport. Every published fix is server-side — useless across the third-party servers you cannot patch. This governor is a client-side proxy you point your agent at once, in front of any MCP server.

Quickstart

pip install tool-result-size-governor
# run your MCP client against the proxy instead of the server:
tool-result-governor-proxy -- python3 your_mcp_server.py

State (spill artifacts, your receipt-signing key, the denial registry) lives under $TRSG_HOME (default ~/.tool-result-size-governor).

Demo against the bundled fixture server (the CARD-051 failure population — an unpaginated list tool and a big log tool):

tool-result-governor-proxy -- python3 -m tool_result_governor.fixture_server

Call list_papers with {"count": 500}: the proxy returns a bounded 50-record window plus an in-band signed omission receipt; re-fetch a narrower slice byte-exact with the proxy's local governor_fetch_slice tool; re-firing the identical query is denied while the spill lives.

What it does

• Per-route ceilings in bytes / records / tokens; structure-aware windowing (array slices with total/returned/omitted counts, log head+tail, prose sectioning).
• The full payload spilled to a checksummed expiring artifact with a fetch-narrower-slice route.
• An HMAC-signed omission receipt on every shaped result proving what was held back — never silent truncation. Receipt expires_at is an upper bound: bounded-store eviction can retire an artifact earlier, in which case a fetch returns a clean unknown_artifact error and the identical query re-opens exactly once.
• A repeat-everything denial that lives exactly as long as its spill.
• Backpressure-safe forwarding so a 2 MB result cannot SIGPIPE the session (lab: 2,112,780-byte result, client bytes bounded at 24,469, no deadlock).

Hosted form

The same governor is available as a hosted per-result API ($0.001/result, x402; Operator $9/mo, Fleet $29/mo; first 100 shaped results free, one time per operator) at https://textforagents.com/products/tool-result-size-governor/ — support: support@textforagents.com.

License: MIT (see LICENSE). Copyright (c) 2026 TextForAgents LLC.