{"_id":"@agent-mcp-tools/mcp-slim-guard","_rev":"2-51b8dbb532bd9c083995e936c9ad0877","name":"@agent-mcp-tools/mcp-slim-guard","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@agent-mcp-tools/mcp-slim-guard","version":"0.1.0","keywords":["mcp","model-context-protocol","security","proxy","ssrf","mcp-compression","schema-compression","token-optimization","context-window","mcp-proxy","tool-filtering","claude-code","cursor","codex","ai-security","llm"],"license":"MIT","_id":"@agent-mcp-tools/mcp-slim-guard@0.1.0","maintainers":[{"name":"lennney","email":"a13168336807@gmail.com"}],"homepage":"https://github.com/lennney/mcp-slim-guard","bugs":{"url":"https://github.com/lennney/mcp-slim-guard/issues"},"bin":{"mcp-slim-guard":"dist/cli.js"},"dist":{"shasum":"b58265454cf4d8ac5895dbfd9235d2f9cb8fe839","tarball":"https://registry.npmjs.org/@agent-mcp-tools/mcp-slim-guard/-/mcp-slim-guard-0.1.0.tgz","fileCount":71,"integrity":"sha512-QSppnlt84/8K/8cnFbMzkMxxHmPbUIE1IgsPIzLUMoI59b4xk4hJy93szgzyJ2NhTvn0xBe5Q/JXIq7fsG9mkQ==","signatures":[{"sig":"MEYCIQDbjpLZNTYAr9IAl6Uy7nf+Qy8gc5kkh0NyeAkGaucnawIhALBggVsnU42sON0xTOVkeP++UxQxmdDCzpEMd/2iG21t","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":304659},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18"},"exports":{".":"./dist/index.js","./cli":"./dist/cli.js"},"gitHead":"0d34b14053b577c9b72279134eb00c2e1166d5bd","mcpName":"io.github.lennney/mcp-slim-guard","scripts":{"dev":"tsc --watch","lint":"eslint src/","test":"vitest run","bench":"node scripts/benchmark/bench.mjs","build":"tsc","check":"npm run typecheck && npm run lint && npm run test","start":"node dist/cli.js","format":"prettier --write 'src/**/*.ts' 'tests/**/*.ts' '*.{json,md,yml,yaml}'","prepare":"husky","lint:fix":"eslint src/ --fix","typecheck":"tsc --noEmit","test:watch":"vitest","bench:schema":"node scripts/benchmark/schema.mjs","bench:tokens":"node scripts/benchmark/tokens.mjs","format:check":"prettier --check 'src/**/*.ts' 'tests/**/*.ts' '*.{json,md,yml,yaml}'","bench:latency":"node scripts/benchmark/latency.mjs","test:coverage":"vitest run --coverage","bench:accuracy":"node scripts/benchmark/accuracy.mjs","prepublishOnly":"npm run build && npm run check"},"_npmUser":{"name":"lennney","email":"a13168336807@gmail.com"},"repository":{"url":"git+https://github.com/lennney/mcp-slim-guard.git","type":"git"},"_npmVersion":"10.9.8","description":"MCP proxy for schema compression, tool access control, SSRF protection, injection detection, rate limiting and audit logging","directories":{},"_nodeVersion":"22.23.1","dependencies":{"pino":"^9.6.0","js-yaml":"^4.1.0","commander":"^13.1.0","micromatch":"^4.0.8","@modelcontextprotocol/sdk":"^1.9.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"husky":"^9.1.7","eslint":"^10.0.0","vitest":"^3.0.0","prettier":"^3.9.6","tiktoken":"^1.0.22","@eslint/js":"^10.0.1","typescript":"^5.7.0","@types/node":"^22.0.0","lint-staged":"^15.5.2","@types/js-yaml":"^4.0.9","@types/micromatch":"^4.0.10","typescript-eslint":"^8.65.0","@vitest/coverage-v8":"^3.2.7"},"_npmOperationalInternal":{"tmp":"tmp/mcp-slim-guard_0.1.0_1784793930350_0.5019868662587283","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Renamed to mcp-slim-guard (unscoped). Use `npm install -g mcp-slim-guard` instead."}},"time":{"created":"2026-07-23T08:05:30.224Z","modified":"2026-07-23T08:37:53.550Z","0.1.0":"2026-07-23T08:05:30.487Z"},"bugs":{"url":"https://github.com/lennney/mcp-slim-guard/issues"},"license":"MIT","homepage":"https://github.com/lennney/mcp-slim-guard","keywords":["mcp","model-context-protocol","security","proxy","ssrf","mcp-compression","schema-compression","token-optimization","context-window","mcp-proxy","tool-filtering","claude-code","cursor","codex","ai-security","llm"],"repository":{"url":"git+https://github.com/lennney/mcp-slim-guard.git","type":"git"},"description":"MCP proxy for schema compression, tool access control, SSRF protection, injection detection, rate limiting and audit logging","maintainers":[{"name":"lennney","email":"a13168336807@gmail.com"}],"readme":"---\ntype: Readme\ntitle: mcp-slim-guard\ntimestamp: \"2026-07-23T18:00:00+08:00\"\ndescription: Lightweight MCP security proxy — compression (up to 86%) + SSRF protection + allow/deny + audit + rate limiting + injection detection\ntags:\n - mcp-slim-guard\n - readme\n - mcp\n - security\n - compression\n---\n\n

\n 中文文档 · English\n

\n\n

🛡️ mcp-slim-guard

\n\n

\n One proxy. Two superpowers: compression + security.\n

\n\n

\n \"npm\n \"Node=18\">\n \"402\n \"86%\n \"5\n \"MIT\"\n

\n\n
\n\nmcp-slim-guard sits between your AI agent and MCP servers, transparently adding **schema compression** (5 levels, up to 86% token reduction) and **security policies** (SSRF protection, tool allow/deny, injection detection, rate limiting, audit logging).\n\n```mermaid\ngraph LR\n A[AI Agent] --> B[mcp-slim-guard]\n B --> C[Compression Pipeline]\n B --> D[Security Pipeline]\n C --> E[MCP Server 1]\n C --> F[MCP Server N]\n D --> E\n D --> F\n style B fill:#4a90d9,color:#fff\n style C fill:#e6f3ff\n style D fill:#ffe6e6\n```\n\n---\n\n## Why mcp-slim-guard?\n\n| Problem | Impact | How mcp-slim-guard solves it |\n| --------------------- | ---------------------------------------------- | ------------------------------------------------- |\n| **Context wasted** | Tool schemas eat 60-86% of your context window | 5 compression levels, lazy loading, request cache |\n| **No access control** | Any agent calls any tool with any args | Glob-based allow/deny, fail-closed by default |\n| **SSRF** | Tool params inject internal network requests | IP blacklist + domain whitelist |\n| **Prompt injection** | Malicious params execute shell/SQL | 17 heuristic patterns, 3 sensitivity levels |\n| **Abuse** | Unthrottled tool calls flood upstream | Token bucket rate limiter (per-tool configurable) |\n| **No audit trail** | No record of who called what | Structured JSON audit log with rotation + gzip |\n\n**Only mcp-slim-guard combines compression AND security in a single proxy.** \nOther tools compress schemas but don't protect you. Security proxies don't save you tokens.\n\n---\n\n## Quick Start\n\n```bash\n# Install\nnpm install -g mcp-slim-guard\n\n# Auto-discover MCP servers from your .mcp.json\ncd your-project/\nmcp-slim-guard init\n\n# Dry-run policies to check for false positives\nmcp-slim-guard validate\n\n# Start the proxy\nmcp-slim-guard start\n```\n\nYour agent now connects to mcp-slim-guard instead of the original servers. That's it.\n\n> MCP servers are auto-discovered from `.mcp.json`, `mcp.json`, or `claude_desktop_config.json`.\n\n### Generated `mcp-slim-guard.yml`\n\n```yaml\ntools:\n allow: [\"search_*\", \"read_*\"] # only allow search/read tools\n deny: [\"*_delete_*\", \"*_admin_*\"] # block dangerous ops\nssrf:\n mode: block\n block_private_ips: true\n allow_domains: [\"*.github.com\"]\nrate_limit:\n default: 60/min # per-tool rate limit\ninjection_detection:\n enabled: true\n mode: block\n sensitivity: medium\ncompressor:\n enabled: true\n level: light # 5 levels: off/light/normal/extreme/maximum\ncache:\n enabled: false # TTL+LRU read-only response cache\naudit:\n output: file # structured JSON audit log\n maxSize: 10MB\n maxFiles: 5\n```\n\n---\n\n## Features\n\n### 🗜️ Schema Compression — Reclaim Your Context Window\n\n| Level | Strategy | Tokens (14 tools) | Savings | When to use |\n| ----------- | ------------------------------------------ | ----------------- | -------- | ------------------------------------------- |\n| `off` | Passthrough | 1,736 | — | < 5 tools, or testing |\n| **`light`** | **3 wrapper tools (on-demand schema)** | **300** | **-83%** | **⭐ Default. Best balance for most users** |\n| `normal` | 2 wrapper tools (no list_tools) | 245 | -86% | 30+ tools, strong LLMs |\n| `extreme` | In-place: strip property descriptions | 1,361 | -22% | Few tools with complex schemas (10+ params) |\n| `maximum` | In-place: signature only, empty properties | 1,294 | -25% | Very large individual schemas |\n| `lazy` | Budget preload + on-demand schema | 1,644 | -5% | 30+ tools, most used only occasionally |\n\n> **Why the big gap?** `light`/`normal` replace all tools with 2-3 wrapper tools (`mcp__invoke_tool`, `mcp__get_tool_schema`). The LLM fetches schemas on demand. `extreme`/`maximum` keep all tools and only compress each schema in place — savings depend on schema complexity.\n\n#### Real-world cost impact\n\n| Setup | Tokens/call | Monthly cost (DeepSeek V4) |\n| ------------------- | ----------- | -------------------------- |\n| Without compression | 1,736 | ~$52 (10K calls) |\n| **With `light`** | **300** | **~$9 (-83%)** |\n\n#### Accuracy verified\n\nBenchmarked against DeepSeek V4 Flash across 12 scenarios × 5 levels × 3 runs = 180 API calls. \n[Run it yourself →](#benchmarks)\n\n### 🛡️ Security Pipeline — Defense in Depth\n\nEvery tool call runs through a serial pipeline. First rejection stops execution:\n\n```\nAgent Request\n │\n ▼\n┌─────────────────┐\n│ 1. Allow/Deny │ ← Glob pattern matching. Fail-closed.\n│ (Whitelist) │\n└────────┬────────┘\n ▼\n┌─────────────────┐\n│ 2. SSRF Shield │ ← IP blacklist + domain whitelist.\n│ │ Blocks 10.*, 192.168.*, 169.254.*\n└────────┬────────┘\n ▼\n┌─────────────────┐\n│ 3. Injection │ ← 17 heuristic patterns:\n│ Detection │ Shell/SQL/NoSQL/Prompt injection\n└────────┬────────┘\n ▼\n┌─────────────────┐\n│ 4. Rate Limit │ ← Token bucket. Per-tool or global.\n│ │ Default: 60 req/min/tool\n└────────┬────────┘\n ▼\n┌─────────────────┐\n│ 5. Audit Log │ ← Structured JSON. Rotate + compress.\n│ │ Every decision recorded.\n└────────┬────────┘\n ▼\n Upstream MCP Server\n```\n\n### 🔄 Additional Capabilities\n\n| Feature | Description |\n| ------------------------ | ------------------------------------------------------------------------------------------------------------ |\n| **Multi-server routing** | One proxy, multiple upstream MCP servers. Tool names are prefixed (`{server}_{tool}`) for automatic routing. |\n| **Hot reload** | `kill -HUP ` — zero-downtime config reload. All fields hot-swappable. |\n| **Request cache** | TTL+LRU in-memory cache for read-only tool results. Per-tool stats. |\n| **Streamable HTTP** | `mcp-slim-guard start --http --port 3000` — works as a remote MCP endpoint. |\n| **STDIO mode** | Default. Transparent drop-in for local agents. |\n\n---\n\n## How It Works\n\n```mermaid\nsequenceDiagram\n participant LLM as AI Agent\n participant MM as mcp-slim-guard\n participant US as Upstream MCP Server\n\n LLM->>MM: tools/list\n Note over MM: Compression pipeline
filters + transforms tools\n MM-->>LLM: compressed tool list (light: 3 wrappers)\n\n LLM->>MM: mcp__get_tool_schema(\"search\")\n MM-->>LLM: full schema for \"search\"\n\n LLM->>MM: mcp__invoke_tool(\"search\", {q: \"...\"})\n Note over MM: Security pipeline
whitelist → ssrf → injection → ratelimit\n MM->>US: forward call\n US-->>MM: result\n Note over MM: Audit log entry\n MM-->>LLM: result\n```\n\n### CLI Reference\n\n| Command | Description |\n| ----------------------------------------- | -------------------------------------------------------- |\n| `mcp-slim-guard init` | Auto-discover `.mcp.json`, generate `mcp-slim-guard.yml` |\n| `mcp-slim-guard validate` | Dry-run policies, show allow/deny for each tool |\n| `mcp-slim-guard start` | Start proxy (STDIO mode) |\n| `mcp-slim-guard start --http --port 3000` | Start proxy (HTTP mode) |\n| `mcp-slim-guard status` | Show config summary + policy overview |\n| `mcp-slim-guard doctor` | Diagnose upstream server connectivity |\n| `mcp-slim-guard audit` | View audit log |\n| `mcp-slim-guard uninit` | Remove mcp-slim-guard.yml and roll back |\n\n---\n\n## Benchmarks\n\nAll benchmarks use real MCP server tool schemas (`filesystem` server, 14 tools) with `tiktoken` (gpt-4o encoding). \nRun them yourself: `npm run bench`\n\n### Token Savings\n\n| Level | Tokens | Reduction |\n| ---------- | ------- | --------- |\n| off | 1,736 | baseline |\n| **light** | **300** | **-83%** |\n| **normal** | **245** | **-86%** |\n| extreme | 1,361 | -22% |\n| maximum | 1,294 | -25% |\n| lazy | 1,644 | -5% |\n\n### Latency Overhead\n\n```\nPolicy pipeline: ~2ms/call (whitelist → ssrf → injection → ratelimit)\nCompression (light): <0.05ms\nCache hit: 0.01ms\n```\n\n### Accuracy (DeepSeek V4 Flash)\n\n12 scenarios × 5 levels × 3 runs = 180 API calls. Scenarios include 4 fuzzy-name tests (read vs search, list vs tree).\n\n| Level | Accuracy | Notes |\n| ------ | -------------- | ---------------------------------- |\n| off | 100% | Baseline |\n| light | ✅ (on-demand) | Wrapper mode uses extra round-trip |\n| normal | ✅ (on-demand) | Same as light |\n\n---\n\n## Comparison\n\n| Feature | mcp-slim-guard | slim-mcp | mcp-compressor | mcp-guardian |\n| -------------------------- | -------------------- | ------------------- | ------------------- | ---------------- |\n| Schema compression | ✅ 5 levels, -86% | ✅ 5 levels, -77% | ✅ | ❌ |\n| Accuracy validation | ✅ 180 API calls | ✅ 120 API calls | ❌ | — |\n| Request cache | ✅ TTL+LRU | ❌ | ❌ | ❌ |\n| Tool allow/deny | ✅ Glob-based | ❌ | ❌ | ✅ |\n| SSRF protection | ✅ IP + domain | ❌ | ❌ | ✅ |\n| Injection detection | ✅ 17 patterns | ❌ | ❌ | ✅ |\n| Rate limiting | ✅ Token bucket | ❌ | ❌ | ✅ |\n| Audit log | ✅ JSON, rotation | ❌ | ❌ | ✅ |\n| Hot reload | ✅ SIGHUP | ❌ | ❌ | ❌ |\n| Multi-server routing | ✅ Prefix auto-route | ❌ | ❌ | ❌ |\n| HTTP transport | ✅ Streamable HTTP | ❌ | ✅ | ❌ |\n| **Compression + Security** | **✅ One proxy** | ❌ Compression only | ❌ Compression only | ❌ Security only |\n\n---\n\n## Requirements\n\n- **Node.js** >= 18\n- **Only 5 production dependencies** (MCP SDK, commander, js-yaml, micromatch, pino)\n\n---\n\n## Docker\n\n```bash\ndocker build -t mcp-slim-guard .\ndocker run -i --rm -v $(pwd)/mcp-slim-guard.yml:/app/mcp-slim-guard.yml mcp-slim-guard start\n```\n\n---\n\n## License\n\nMIT\n","readmeFilename":"README.md"}