mcp-diet
Proxy MCP stdio sem dependências e firewall de contexto em tempo de execução: tree-shaking de tools/list, proteção contra falhas de 8 MiB e ocultação de segredos.
Documentação
mcp-diet (@framy2/mcp-diet)
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?
- Deterministic
tools/listTree-Shaking (--allow,--deny,--read-only,--max-desc):- Filters
tools/listresponses before the agent sees them and deterministically sorts tools by name so prompt prefix caching never invalidates. --read-onlykeeps only tools withannotations.readOnlyHint === trueor safe read-only names (get_*,list_*,read_*,search_*).--max-desc <chars>compacts verbose tool and parameter descriptions without mutating JSON schema types.
- Filters
- Oversized
tools/callCrash Guard + Structured Spill Offset Maps (--max-result-kb 512):- Prevents Claude Code's
>= 8 MiBstdio buffer disconnect crash (anthropics/claude-code#105703) and 100k-token single-turn blowouts by spilling oversizedtools/calloutputs to a local file. - Builds a deterministic Structural Section & Offset Index (
buildSpillStructureMap) withtotalBytes,totalLines,sha256digest,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).
- Prevents Claude Code's
- Sandboxed Spill Paging (
mcp_diet_read_spill):- Automatically injected into
tools/list(withreadOnlyHint: 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 6901jsonPointerextraction (/results/0/title). - Hard-sandboxed via
realpathSyncverification (dirname(realTarget) === realSpillDirand^mcp-tool-output-\d+-[a-f0-9]{12}\.json$), rejecting path traversal, symlinks escapingspillDir, or arbitrary filesystem paths, while capping returned bytes and redacting secrets by default.
- Automatically injected into
- Live
tools/callSecret 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.
- Masks leaked credentials (
🚀 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), Codex32 KiBdoctor, 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 forcodexandclaude— 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.