# mcp-diet: MCP Context Optimizer

Build `mcp-diet` — a CLI tool that analyzes MCP servers and shows developers exactly how much of their AI agent's context window each tool consumes, then suggests how to slim it down.

## Why this exists

MCP (Model Context Protocol) hit 6M PyPI downloads/day and is growing 13%+ daily. Every MCP server injects tool definitions into the LLM's context window — descriptions, JSON schemas, parameter docs. Developers have zero visibility into this cost. A server with 20 tools can silently eat 30-40% of your context before a single user message. Nobody is solving this yet.

## What to build

A Python CLI (`mcp-diet`) published to PyPI, installable via `pip install mcp-diet` or `uvx mcp-diet`.

### Core commands

```bash
# Analyze a running MCP server via stdio
mcp-diet analyze -- npx @modelcontextprotocol/server-filesystem /tmp

# Analyze a running MCP server via SSE
mcp-diet analyze --sse http://localhost:3000/sse

# Analyze a Claude Code config (reads ~/.claude/settings.json or .mcp.json)
mcp-diet auto

# Output formats
mcp-diet analyze --format table    # default: rich terminal table
mcp-diet analyze --format json     # machine-readable
mcp-diet analyze --format markdown # for docs/PRs
```

### What `analyze` shows

For each tool in the MCP server:

| Column | Description |
|--------|-------------|
| Tool name | The tool's registered name |
| Tokens | Estimated token count of the full tool definition (name + description + input schema) |
| % of budget | Percentage of a configurable context budget (default: 200k) |
| Schema depth | Max nesting depth of the JSON schema |
| Desc length | Character count of the description field |
| Grade | A-F rating based on token efficiency |

Plus a summary footer:
- Total tokens consumed by all tools
- % of context budget used before any conversation
- Top 3 bloat offenders
- Estimated $/1000 calls at current API pricing (use Anthropic Claude pricing)

### What `auto` does

1. Reads `~/.claude/settings.json` or `.mcp.json` from cwd
2. Spins up each configured MCP server
3. Runs `analyze` on each
4. Produces a combined report showing total context cost across all servers

### Grading rubric

| Grade | Tokens per tool |
|-------|----------------|
| A | < 200 |
| B | 200-500 |
| C | 500-1000 |
| D | 1000-2000 |
| F | > 2000 |

### Stretch: `suggest` subcommand

```bash
mcp-diet suggest -- npx @modelcontextprotocol/server-filesystem /tmp
```

For each tool graded C or worse, output concrete suggestions:
- Trim redundant description text (show before/after with diff)
- Flatten unnecessarily nested schemas
- Flag optional parameters that could be removed
- Identify tools with duplicate/overlapping functionality

## Technical approach

### Token counting

Use `tiktoken` with `cl100k_base` encoding (GPT-4/Claude-compatible). Count the full tool definition as it would appear in an API call:
- Tool name
- Tool description
- Full JSON schema serialized as the API would send it

### MCP client

Use the official `mcp` Python package to connect to servers:
```python
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
```

Connect via stdio or SSE, call `list_tools()`, then analyze the returned tool definitions.

### Project structure

```
mcp-diet/
├── pyproject.toml          # uv/pip, entry point: mcp-diet
├── src/
│   └── mcp_diet/
│       ├── __init__.py
│       ├── cli.py          # click/typer CLI
│       ├── analyzer.py     # token counting + grading logic
│       ├── client.py       # MCP server connection (stdio + SSE)
│       ├── config.py       # read Claude/MCP config files
│       ├── report.py       # output formatting (table/json/md)
│       └── suggest.py      # optimization suggestions (stretch)
├── tests/
│   ├── test_analyzer.py
│   ├── test_config.py
│   └── fixtures/           # sample tool definitions for testing
└── README.md
```

### Dependencies

Keep it minimal:
- `mcp` — official MCP client
- `tiktoken` — token counting
- `click` or `typer` — CLI framework
- `rich` — terminal tables and formatting

No ML, no GPU, no database, no API keys needed.

## Steps

1. **Scaffold the project** — `pyproject.toml` with uv, src layout, entry point
2. **Build the analyzer** — token counting for tool definitions, grading logic
3. **Build the MCP client** — connect to stdio and SSE servers, fetch tool lists
4. **Build the CLI** — `analyze` command with format options
5. **Build config reader** — parse `.mcp.json` and Claude settings for `auto` command
6. **Build the reporter** — rich table, JSON, markdown outputs
7. **Write tests** — unit tests with fixture tool definitions
8. **Add suggest command** — optimization recommendations (stretch)
9. **Publish** — pyproject.toml metadata for PyPI, write README

## Design principles

- Zero config by default — just point at a server and go
- Fast — analyze should complete in <2 seconds
- No API keys — everything runs locally
- Opinionated grading — developers want to be told "this is bad", not given raw numbers
- Machine-readable output — `--format json` for CI/CD integration (fail builds if context budget exceeded)
