Metadata-Version: 2.4
Name: tool-result-size-governor
Version: 1.0.0
Summary: Client-side tool-result size governor for MCP: per-route output budgets, structure-aware windowing, spill artifacts, signed omission receipts.
Author: TextForAgents LLC
License: MIT License
        
        Copyright (c) 2026 TextForAgents LLC
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://textforagents.com/products/tool-result-size-governor/
Keywords: mcp,model-context-protocol,proxy,context-window,tool-results
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 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

```sh
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):

```sh
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.
