# mcp-context-budget

**Your MCP servers eat the context window before you type anything. This tells you how much, and which one to drop.**

Free, local, read-only. No account, no network call, no telemetry.

---

## The problem this solves

Every MCP server you install injects its full tool schema into every request. There is no lazy loading in the protocol. A dozen servers can consume tens of thousands of tokens before your first message, and nothing in the client tells you this is happening — the agent just gets quietly worse.

Known incidents from public reports:

- Cloudflare's standard MCP server consumed **1.17M tokens** in production, prompting a dedicated workaround.
- A practitioner measured **45K tokens for GitHub MCP alone** — 22.5% of a 200K window.
- A 12-server setup reported the system prompt at **18,000 tokens** before the user typed.

This tool measures your actual setup instead of quoting those numbers at you.

## Why measurement, not estimation

The config file only records *how to start* a server. The real cost lives in the `tools/list` payload, which changes with the server version and its runtime flags. Guessing from the config produces a confident wrong answer.

So this tool starts each stdio server, asks it for its tools, measures the payload, and shuts it down. That is the only honest method, and it takes a few seconds.

## Install

Requires Python 3.8+. No dependencies.

```bash
git clone <repo> mcp-context-budget
```

Add to your MCP client config (`claude_desktop_config.json`, `.cursor/mcp.json`, or `~/.workbuddy/mcp.json`):

```json
{
  "mcpServers": {
    "mcp-context-budget": {
      "command": "python",
      "args": ["/absolute/path/to/mcp-context-budget/run.py"]
    }
  }
}
```

## Tools

### `audit_context_budget`

Full report: cost per server, cost per tool, findings with quantified savings, and a fix order.

```
How much of my context window are my MCP servers eating?
```

Optional arguments: `window` (`200k` default, or `128k`/`32k`/`16k`), `config` (explicit path), `show_tools` (list the N most expensive tools per server).

### `rank_servers_by_cost`

Just the ranking. Answers "which server should I remove first" in one line per server.

### `explain_token_cost`

Measure an arbitrary schema or string before you publish a server of your own. Reports the CJK/ASCII split and shows how wrong the naive `len/4` heuristic would be.

## What it detects

| Finding | What it means |
|---|---|
| `single_tool_dominates` | One tool costs ≥2.5% of the window on its own |
| `repeated_boilerplate` | The same sentence appears in 4+ tool descriptions |
| `enum_listed_twice` | An enum is spelled out in prose *and* declared in the schema |
| `near_duplicate_tools` | 4+ tools with identical parameter shapes, differing only by verb |
| `param_desc_restates_name` | A parameter description that only repeats the field name |

Each finding carries an estimated token saving, so you can decide whether it is worth the edit.

## What it does not do

- **Does not edit anything.** It never writes to your configs and never removes a server.
- **Does not measure remote servers.** URL-based (SSE / streamable HTTP) servers are listed as *not probed* rather than silently scored zero. Their cost is real but cannot be measured locally.
- **Does not prove a bad agent is caused by schema cost.** It quantifies one specific tax. If your schemas are 2% of the window, the cause is elsewhere and the report says so.
- **Estimates, not exact tokenizer output.** No tokenizer dependency, by design — that would triple install size and pin you to one model family. The estimator is calibrated to *over*-count slightly, because under-counting a budget is the failure that hurts.

## Reading the verdict

| Verdict | Share of window |
|---|---|
| `healthy` | under 5% |
| `watch` | 5–10% |
| `over_budget` | 10–20% |
| `critical` | over 20% |

Ten percent is the line where trimming is worth the afternoon. Twenty percent is where the agent is measurably worse than it was before you installed things.

## Self-verification

Do not take the claims on faith:

```bash
python tests/selftest.py
```

28 checks, both directions: pathological schemas must be caught, and clean well-written servers must produce **zero** findings. The negative tests are the important half — a tool that cries wolf gets ignored, which is worse than no tool.

## License

MIT.