Skip to main content
Glama
README.md
# mcp-diet (`@framy2/mcp-diet`)

<p align="center">
  <a href="https://www.npmjs.com/package/@framy2/mcp-diet"><img alt="npm version" src="https://img.shields.io/npm/v/@framy2/mcp-diet?style=flat&logo=npm&color=CB3837" /></a>
  <a href="https://glama.ai/mcp/servers/FramY2/mcp-diet"><img alt="Glama MCP Score" src="https://glama.ai/mcp/servers/FramY2/mcp-diet/badges/score.svg" /></a>
  <a href="https://github.com/FramY2/mcp-diet/stargazers"><img alt="GitHub Stars" src="https://img.shields.io/github/stars/FramY2/mcp-diet?style=flat&logo=github&color=F59E0B" /></a>
  <a href="https://github.com/FramY2/mcp-diet/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/FramY2/mcp-diet/actions/workflows/ci.yml/badge.svg" /></a>
  <img alt="Zero Dependencies" src="https://img.shields.io/badge/dependencies-0-brightgreen" />
  <img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-2DE2E6" />
</p>

**Zero-dependency stdio MCP proxy & runtime context firewall** for **Claude Code**, **OpenAI Codex CLI**, and **Cursor**.

Wrap any stdio MCP server in `.mcp.json`, `~/.claude.json`, or `.codex/config.toml` to tree-shake bloated `tools/list` schemas, prevent oversized `tools/call` stdio crashes (`anthropics/claude-code#105703`) and `>2000px` many-image session lockups, navigate `>=512 KiB` spilled responses via **Structured Spill Offset Maps** and sandboxed **`mcp_diet_read_spill`** paging, and redact leaked secrets before they enter the model's context window.

Companion runtime proxy to **[`FramY2/ctxwise`](https://github.com/FramY2/ctxwise)** (`@framy2/ctxwise`).

---

## ⚡ Why `mcp-diet`?

1. **Deterministic `tools/list` Tree-Shaking (`--allow`, `--deny`, `--read-only`, `--max-desc`)**:
   - Filters `tools/list` responses before the agent sees them and deterministically sorts tools by name so **prompt prefix caching never invalidates**.
   - `--read-only` keeps only tools with `annotations.readOnlyHint === true` or safe read-only names (`get_*`, `list_*`, `read_*`, `search_*`).
   - `--max-desc <chars>` compacts verbose tool and parameter descriptions without mutating JSON schema types.
2. **Oversized `tools/call` Crash Guard + Structured Spill Offset Maps (`--max-result-kb 512`, `--preview-chars 1200`)**:
   - Prevents Claude Code's `>= 8 MiB` stdio buffer disconnect crash (`anthropics/claude-code#105703`) and 100k-token single-turn blowouts by spilling oversized `tools/call` outputs to a local file.
   - Builds a deterministic **Structural Section & Offset Index** (`buildSpillStructureMap`) with `totalBytes`, `totalLines`, `sha256` digest, `headPreview` (default `1,200` chars, configurable per server wrapper via `--preview-chars <chars>`), `tailPreview` (default `400` chars or ~1/3 of `--preview-chars` when payloads exceed head + tail length), and `[L1-L42 | bytes 0..1820]` byte/line ranges across JSON top-level keys/array chunks, Markdown headings, and log blocks (`ERROR`, `WARN`, `FAIL`, timestamps).
3. **`>2000px` Image Dimension Firewall (`--max-image-dim 2000`)**:
   - Zero-dependency binary header inspection (`PNG`, `JPEG`, `GIF`, `WebP`) catches `image` content blocks exceeding `2000px` on either side **even when the raw file size is well below `--max-result-kb`** — preventing Claude Code's irreversible *"An image in the conversation exceeds the dimension limit for many-image requests (2000px)"* session rejection.
   - **Why `2000px` is the session-safe default**: Anthropic allows up to `8000px` only while a request carries `<=20` images, then rejects anything over `2000px` once image `#21` arrives; because earlier tool outputs remain immutable in `messages[]` (and a single stdio wrapper cannot see user-pasted screenshots or sibling MCP servers), keeping `2000px` prevents delayed turn-21 lockups. Short `<=20`-image sessions can explicitly pass `--max-image-dim 8000` (or `0` to disable).
   - Spills oversized images cleanly to native `.png` / `.jpg` / `.gif` / `.webp` files inside `spillDir`, leaving `<=2000px` images inline.
4. **Sandboxed Spill Paging (`mcp_diet_read_spill`) & Follow-Up Telemetry (`--report-stats`)**:
   - Automatically injected into `tools/list` (with `readOnlyHint: true`, compatible with `--read-only`; opt out with `--no-spill-reader`) and intercepted locally in the proxy without reaching the downstream child process.
   - Supports 1-based line slicing (`startLine`/`endLine`), UTF-8 byte paging (`offsetBytes`/`maxBytes`), and RFC 6901 `jsonPointer` extraction (`/results/0/title`).
   - Hard-sandboxed via `realpathSync` verification (`dirname(realTarget) === realSpillDir` and `^mcp-tool-output-\d+-[a-f0-9]{12}\.json$`), rejecting path traversal, symlinks escaping `spillDir`, or arbitrary filesystem paths, while capping returned bytes and redacting secrets by default.
   - Tracks `upstreamServer` (`{ name, version }` captured from `initialize`), global counters (`byteSpillsTriggered`, `imageDimensionSpillsTriggered`, `uniqueSpillsReadCount`, `previewOnlySpillsCount`, `spillReadFollowUpRate`), and a per-tool `byTool` breakdown via `getTelemetry()`, `mcp_diet_status`, or `--report-stats` on stderr at exit.
5. **Live `tools/call` Secret Redaction (`--redact-secrets`)**:
   - Masks leaked credentials (`sk-ant-*`, `sk-proj-*`, `ghp_*`, `AKIA*`, `://user:pass@`, `AccountKey=...`, `Bearer ...`, private keys) in tool call responses before they enter your LLM transcript.

---

## 🚀 Quickstart (Drop-In `.mcp.json` Wrapper)

Replace your MCP server command in `.mcp.json` or `~/.claude.json`:

```json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@framy2/mcp-diet@0.3.1",
        "--read-only",
        "--max-desc",
        "160",
        "--max-result-kb",
        "512",
        "--redact-secrets",
        "--",
        "npx",
        "-y",
        "@modelcontextprotocol/server-github"
      ]
    }
  }
}
```

### Paging Oversized Spills with `mcp_diet_read_spill`

When a tool response exceeds `--max-result-kb`, `mcp-diet` writes the full JSON payload to `spillDir` and returns an offset map plus concrete paging examples:

```text
[mcp-diet] Oversized tool output intercepted (742.4 KiB > 512 KiB limit).
Full output saved to local file: /tmp/mcp-diet-spills/mcp-tool-output-1763114400000-a1b2c3d4e5f6.json
totalBytes=760218 | totalLines=4820 | sha256=a1b2c3d4e5f6
Structural Section & Offset Index:
  [L1-L42 | bytes 0..1820] metadata (object)
  [L43-L4820 | bytes 1821..760218] results (array[420])
```

The agent can then inspect targeted slices without blowing its context budget:

- **By RFC 6901 JSON Pointer**: `mcp_diet_read_spill({ path: "...", jsonPointer: "/results/0" })`
- **By 1-based line range**: `mcp_diet_read_spill({ path: "...", startLine: 43, endLine: 120 })`
- **By UTF-8 byte offset**: `mcp_diet_read_spill({ path: "...", offsetBytes: 1821, maxBytes: 16384 })`

---

## 🛠️ CLI Options

```text
Usage:
  mcp-diet [options] -- <server-command> [server-args...]
  mcp-diet [options] --self-test-server

Options:
  --allow <t1,t2>         Allow only matching tool names or wildcard patterns (e.g. get_*,list_*)
  --deny <t1,t2>          Remove matching tool names or wildcard patterns (e.g. delete_*,drop_*)
  --read-only             Keep only read-only tools (annotations.readOnlyHint or read-only heuristic)
  --max-desc <chars>      Deterministically truncate tool and property descriptions
  --max-result-kb <kb>    Spill oversized tools/call results to a temp file (default: 512)
  --preview-chars <chars> Override spilled head preview length in chars (default: 1200)
  --max-image-dim <px>    Spill PNG/JPEG/GIF/WebP images wider/taller than <px> (default: 2000, 0 disables)
  --redact-secrets        Redact leaked API keys, PATs, and credentials in tools/call output
  --spill-dir <dir>       Custom directory for spilled oversized tool outputs
  --no-spill-reader       Disable the virtual mcp_diet_read_spill tool in tools/list and tools/call
  --report-stats          Emit session spill & follow-up telemetry JSON to stderr on exit
  --self-test-server      Run standalone diagnostic MCP server over stdio (for introspection/Glama)
  -v, --version           Print version
  -h, --help              Print help
```

---

## 📦 Programmatic API

```ts
import {
  buildSpillStructureMap,
  executeReadSpillTool,
  filterToolsList,
  guardToolCallResult,
  inspectImageDimensions,
  redactSecretsInText,
  startStandaloneMcpServer,
  startStdioMcpProxy,
  type ImageDimensions,
  type SpillSectionEntry,
  type SpillStructureMap,
  type SpillTelemetryStats,
  type ToolSpillTelemetryStats,
  type UpstreamServerInfo,
} from "@framy2/mcp-diet";
```

## 🧩 Companion Tools / Ecosystem

- **[`FramY2/ctxwise`](https://github.com/FramY2/ctxwise) (`@framy2/ctxwise`)**: Local-first AI Context Firewall, MCP Schema Tree-Shaker (`mcp-xray`, `mcp-prune`), multi-agent rule sync (`CLAUDE.md` ↔ `AGENTS.md` ↔ Cursor), Codex `32 KiB` doctor, and SARIF 2.1.0 Secret Shield.
- **[`FramY2/agent-wire-tap`](https://github.com/FramY2/agent-wire-tap) (`@framy2/agent-wire-tap`)**: Zero-cost local loopback HTTP interceptor & CI context contract tester for `codex` and `claude` — verifies outbound system prompt markers, tool counts, and byte budgets with **$0.00 API cost**.
- **[Interactive Context & MCP Token Tax Calculator](https://framy2.github.io/ctxwise/)**: 100% client-side web calculator for MCP schema token tax, 50-turn session costs, and secret scanning.

---

## License

MIT © [Christian Frascogna (@FramY2)](https://github.com/FramY2)

TDQS

A3.7/5.0

Scored across 4 tools

Disambiguation5/5

Each tool maps to a clearly different action: analysis of tool definitions, reading spill files, redacting secrets, and inspecting runtime status. There is no plausible overlap — an agent can pick the right tool from the name alone, and the descriptions reinforce distinct resource/action pairs.

Naming Consistency5/5

All four tools share the `mcp_diet_` server prefix followed by a snake_case verb_noun pattern (analyze_tools, read_spill, redact_text, status). The one slight deviation is `status` (noun-only), but it is unambiguous and predictable within the set.

Tool Count4/5

Four tools is well-scoped for a narrow utility server covering analysis, spill reading, redaction, and status. It is on the thin side — the surface could support a policy/configuration tool — but no tool feels redundant or out of place.

Completeness4/5

The lifecycle is largely covered: analyze computes savings, read_spill retrieves oversized output, redact_text handles secret leakage, and status reports runtime config. The main gap is the absence of a tool to set or apply mcp-diet policies/config, so agents can inspect and analyze but not mutate configuration.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues