mcp-diet

零依賴的 stdio MCP 代理與執行階段上下文防火牆:tools/list 樹狀搖除、8 MiB 當機防護,以及機密資訊遮蔽。

文件

mcp-diet (@framy2/mcp-diet)

npm version Glama MCP Score GitHub Stars CI Zero Dependencies License: MIT

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), 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 (@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):
    • 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 (~1,200 chars), tailPreview (~400 chars for payloads > 1,600 chars), 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. Sandboxed Spill Paging (mcp_diet_read_spill):
    • 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.
  4. 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:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@framy2/mcp-diet@0.2.0",
        "--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:

[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

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)
  --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
  --self-test-server      Run standalone diagnostic MCP server over stdio (for introspection/Glama)
  -v, --version           Print version
  -h, --help              Print help

📦 Programmatic API

import {
  buildSpillStructureMap,
  executeReadSpillTool,
  filterToolsList,
  guardToolCallResult,
  redactSecretsInText,
  startStandaloneMcpServer,
  startStdioMcpProxy,
  type SpillSectionEntry,
  type SpillStructureMap,
} from "@framy2/mcp-diet";

🧩 Companion Tools / Ecosystem

  • 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 (@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: 100% client-side web calculator for MCP schema token tax, 50-turn session costs, and secret scanning.

License

MIT © Christian Frascogna (@FramY2)