# MCP Context Budget

[![CI](https://github.com/KaryawanSurga/mcp-context-budget/actions/workflows/ci.yml/badge.svg)](https://github.com/KaryawanSurga/mcp-context-budget/actions/workflows/ci.yml)
[![Node](https://img.shields.io/badge/node-%3E%3D20-339933)](package.json)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)

**Know what your MCP tools cost before they fill the window.**

MCP Context Budget connects to your MCP servers, reads their tool definitions, and ranks every tool by how many context tokens it consumes — name, description, and input schema. Use it before enabling a server, when an agent feels slow, or in CI to keep tool bloat out of your setup.

Sister project of [TokenSaver MCP](https://github.com/KaryawanSurga/TokenSaverMcp): TokenSaver cuts tokens on the way out, Context Budget cuts them on the way in.

> Product requirements: [PRD.md](PRD.md) · [PRD.id.md](PRD.id.md) (Bahasa Indonesia)

## Why

Every MCP tool ships its name, description, and JSON schema into the model's context on every request. A handful of verbose servers can quietly consume tens of thousands of tokens — and with many clients still paying per token, that is money and attention spent before the first user message. This tool makes the cost visible and rankable.

## Quick start

Audit a single server command with no config file:

```sh
npx -y mcp-context-budget probe -- npx -y @modelcontextprotocol/server-filesystem .
```

Audit every server in an MCP client config:

```sh
npx -y mcp-context-budget scan --config ./mcp.json
```

`mcp.json` uses the familiar Claude Desktop shape:

```json
{
  "mcpServers": {
    "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "."] },
    "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_TOKEN": "..." } }
  }
}
```

## Example output

```text
$ mcp-context-budget probe -- node tests/fixtures/echo-server.mjs

MCP Context Budget — 1 server(s) | 3 tools | ~1,383 tokens (0.7% of 200,000)

echo-fixture  3 tools  ~1,383 tokens (0.7%)
  ! big                          ~ 1,311 tokens  (name 1, description 808, schema 502)
    echo                         ~    48 tokens  (name 1, description 7, schema 40)
    tiny                         ~    24 tokens  (name 1, description 1, schema 22)

! tools above the 800 token threshold
token counts are estimated at four characters per token
```

One oversized description can cost more than 2% of a working context window on its own — this is what the tool surfaces.

## What counts

| Segment | Source |
| --- | --- |
| name | the tool name |
| description | `title` plus `description` as sent in `tools/list` |
| schema | the full JSON Schema of `inputSchema` |

Totals are compared against your context window (`--context`, default 200,000) and a per-tool threshold (`--threshold`, default 800). Token counts are estimated at four characters per token so the audit stays fully offline and deterministic.

## Commands

| Command | Purpose |
| --- | --- |
| `scan --config <path>` | Audit every stdio server in an MCP client config. |
| `probe -- <command> [args...]` | Audit one server launch command. |
| `serve` | Run as an MCP server exposing the `audit_context` tool. |

Options: `--context <tokens>`, `--threshold <n>`, `--timeout <ms>`, `--json`, `--soft`.

Exit codes: `0` ok, `1` a tool crossed the threshold or a server failed to connect, `2` usage error. Use `--soft` to always exit `0` — handy while exploring.

## Use it as an MCP tool

Agents can budget their own tools if you add the server:

```json
{
  "mcpServers": {
    "contextbudget": {
      "command": "npx",
      "args": ["-y", "mcp-context-budget", "serve"]
    }
  }
}
```

The `audit_context` tool accepts either `config` (a path) or `command` + `args` and returns the ranked report.

## CI usage

```yaml
- name: Audit MCP context budget
  run: npx -y mcp-context-budget scan --config ./mcp.json --threshold 1500
```

The job fails when any tool exceeds the threshold or a configured server cannot start.

## Supported configs

`scan` understands `mcpServers`, `servers`, or a bare map of server entries with `command`, `args`, `env`, and `cwd`. Only stdio servers are supported in v0.1.0; HTTP/SSE support is on the roadmap.

## Development

```sh
npm install
npm run typecheck
npm run build
npm test
```

The suite covers config parsing, costing math, stdio probing (including timeouts and missing binaries), CLI behavior, and exit codes.

## Roadmap

- Optional exact tokenizer mode per model family.
- HTTP/SSE server support.
- Baseline snapshots and diffing so budget regressions show up in review.
- Per-project budgets with allowlists.

## License

MIT — see [LICENSE](LICENSE).