{"_id":"@daino/mcp-shield","name":"@daino/mcp-shield","dist-tags":{"latest":"1.1.0"},"versions":{"1.1.0":{"name":"@daino/mcp-shield","version":"1.1.0","description":"Production-grade resilience middleware for MCP servers — timeout, retry, circuit breaker.","bin":{"mcp-shield":"dist/cli.mjs"},"main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"scripts":{"build":"tsup","dev":"tsup --watch","test":"vitest run","test:watch":"vitest","typecheck":"tsc --noEmit","lint":"tsc --noEmit","prepublishOnly":"npm run build"},"keywords":["mcp","model-context-protocol","middleware","resilience","timeout","retry","circuit-breaker","proxy","claude","ai-agent","agentic-ai"],"repository":{"type":"git","url":"git+https://github.com/DainoJung/mcp-shield.git"},"homepage":"https://github.com/DainoJung/mcp-shield","author":{"name":"DainoJung"},"license":"MIT","engines":{"node":">=20"},"dependencies":{"commander":"^12.1.0","pino":"^9.6.0","yaml":"^2.7.0","zod":"^3.24.0"},"devDependencies":{"tsup":"^8.4.0","typescript":"^5.7.0","vitest":"^3.0.0","@types/node":"^22.0.0","pino-pretty":"^13.0.0"},"_id":"@daino/mcp-shield@1.1.0","gitHead":"e902a5939e4ecc015f498159b1e8aa6202371671","bugs":{"url":"https://github.com/DainoJung/mcp-shield/issues"},"_nodeVersion":"23.9.0","_npmVersion":"11.3.0","dist":{"integrity":"sha512-rn/hFOeg/wL4CAIsjkVxqO85Szm1eqHegCX3tJxAct6GZJPV1vLkIh2tVhfTRGyWhzfxN8UdYKlDzU1SQA2BXQ==","shasum":"9a486990e03710bd5c1f522071eb455ec586d7d8","tarball":"https://registry.npmjs.org/@daino/mcp-shield/-/mcp-shield-1.1.0.tgz","fileCount":10,"unpackedSize":347571,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCeFShvgkaGHs2caJ0xQZzbmkxKkrBvlY+bAQRGT9gPmQIgFQL8fe1HWLXi50ERvi42MZ+MtT3fH0+dl/urYEj31Bk="}]},"_npmUser":{"name":"daino","email":"wjdekdls3693@gmail.com"},"directories":{},"maintainers":[{"name":"daino","email":"wjdekdls3693@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-shield_1.1.0_1775806694802_0.41230568796484235"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-10T07:38:14.709Z","1.1.0":"2026-04-10T07:38:14.973Z","modified":"2026-04-10T07:38:15.220Z"},"maintainers":[{"name":"daino","email":"wjdekdls3693@gmail.com"}],"description":"Production-grade resilience middleware for MCP servers — timeout, retry, circuit breaker.","homepage":"https://github.com/DainoJung/mcp-shield","keywords":["mcp","model-context-protocol","middleware","resilience","timeout","retry","circuit-breaker","proxy","claude","ai-agent","agentic-ai"],"repository":{"type":"git","url":"git+https://github.com/DainoJung/mcp-shield.git"},"author":{"name":"DainoJung"},"bugs":{"url":"https://github.com/DainoJung/mcp-shield/issues"},"license":"MIT","readme":"# 🛡️ mcp-shield\n\n> Production-grade resilience middleware for MCP servers. Timeout, retry, circuit breaker — in one command.\n\n[![npm version](https://img.shields.io/npm/v/mcp-shield)](https://www.npmjs.com/package/mcp-shield)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nYour MCP servers are running naked in production. mcp-shield wraps any MCP server with resilience middleware — so a slow GitHub API or a flaky database tool doesn't crash your entire agent chain.\n\n## The Problem\n\nMCP servers have **zero built-in resilience**:\n\n- ⏰ **No timeout** — agent waits 600 seconds for a hung tool call\n- 🔄 **No retry** — transient network errors crash the chain\n- 💥 **No circuit breaker** — a dead server keeps getting hammered\n- 📊 **No logging** — \"something failed somewhere\" is your only signal\n\n## The Solution\n\nmcp-shield is a transparent stdio proxy. It sits between your agent and MCP server, adding production-grade middleware with zero code changes:\n\n```\nAgent ←→ mcp-shield ←→ MCP Server\n            │\n            ├── ⏰ Timeout (kill hung calls)\n            ├── 🔄 Retry (exponential backoff)\n            ├── 💥 Circuit Breaker (fail fast)\n            └── 📊 Structured Logging\n```\n\n## Quick Start\n\n```bash\n# Wrap any MCP server with sensible defaults (30s timeout, 2 retries)\nnpx @daino/mcp-shield wrap -- npx @modelcontextprotocol/server-github\n\n# Custom timeout and retries\nnpx @daino/mcp-shield wrap --timeout 60s --retries 5 -- npx server-github\n\n# Using a config file\nnpx @daino/mcp-shield wrap --config mcp-shield.yaml --server github\n```\n\n## Claude Desktop Integration\n\nAdd mcp-shield to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"github\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"@daino/mcp-shield\", \"wrap\",\n        \"--timeout\", \"30s\",\n        \"--retries\", \"3\",\n        \"--\",\n        \"npx\", \"@modelcontextprotocol/server-github\"\n      ],\n      \"env\": {\n        \"GITHUB_TOKEN\": \"your-token-here\"\n      }\n    }\n  }\n}\n```\n\nThat's it. Your GitHub MCP server now has timeout, retry, and circuit breaker protection.\n\n## Config File\n\nFor multi-server setups, use a YAML config:\n\n```yaml\n# mcp-shield.yaml\ndefaults:\n  timeout: 30s\n  retries:\n    max: 3\n    backoff: exponential\n    jitter: true\n  circuit_breaker:\n    threshold: 5\n    reset_after: 60s\n\nservers:\n  github:\n    command: \"npx @modelcontextprotocol/server-github\"\n    env:\n      GITHUB_TOKEN: \"${GITHUB_TOKEN}\"\n    tools:\n      get_file_contents:\n        timeout: 60s          # slow tool gets more time\n      search_repositories:\n        retries:\n          max: 5              # flaky tool gets more retries\n\n  filesystem:\n    command: \"npx @modelcontextprotocol/server-filesystem /home/user\"\n    timeout: 10s\n    retries:\n      max: 1                  # local filesystem rarely needs retry\n```\n\n## How It Works\n\n### Timeout\n\nKills tool calls that exceed the configured duration. No more 600-second hangs.\n\n```yaml\ntimeout: 30s   # Per-tool override available\n```\n\nWhen a timeout fires, the agent gets a clear error:\n```\nTool 'get_file_contents' timed out after 30000ms\n```\n\n### Retry\n\nAutomatically retries failed tool calls with exponential backoff + jitter.\n\n```yaml\nretries:\n  max: 3              # Up to 3 retries (4 total attempts)\n  backoff: exponential  # 1s → 2s → 4s\n  jitter: true         # Randomize ±50% to avoid thundering herd\n```\n\nSmart retry: deterministic errors (invalid params, method not found) are never retried.\n\n### Circuit Breaker\n\nAfter repeated failures, stop calling the dead server. Fail fast instead of burning tokens.\n\n```yaml\ncircuit_breaker:\n  threshold: 5       # Open after 5 consecutive failures\n  reset_after: 60s   # Try again after 60 seconds\n```\n\nStates: **Closed** (normal) → **Open** (rejecting) → **Half-Open** (testing one request).\n\n### Structured Logging\n\nEvery tool call logged as structured JSON to stderr:\n\n```json\n{\n  \"level\": \"info\",\n  \"msg\": \"tool_call_end\",\n  \"server\": \"github\",\n  \"tool\": \"get_file_contents\",\n  \"duration_ms\": 245,\n  \"status\": \"success\",\n  \"attempt\": 1\n}\n```\n\nUse `--log-format pretty` for human-readable output during development.\n\n## Programmatic Usage\n\n```typescript\nimport { shield } from '@daino/mcp-shield';\n\nconst proxy = shield({\n  command: 'npx',\n  args: ['@modelcontextprotocol/server-github'],\n  timeout: 30_000,\n  retries: { max: 3, backoff: 'exponential', jitter: true },\n  circuitBreaker: { threshold: 5, resetAfter: 60_000 },\n});\n\nproxy.start(); // starts the proxy and child MCP server\n```\n\n## Why mcp-shield?\n\n| Feature | mcp-shield | No protection | General retry libs |\n|---------|:----------:|:-------------:|:-----------------:|\n| MCP-native (understands JSON-RPC) | ✅ | — | ❌ |\n| Per-tool config | ✅ | — | ❌ |\n| Zero agent code changes | ✅ | — | ❌ |\n| Circuit breaker | ✅ | ❌ | ✅ |\n| Structured MCP logging | ✅ | ❌ | ❌ |\n| Drop-in Claude Desktop support | ✅ | — | ❌ |\n\n## Roadmap\n\n- [x] **v0.1** — Timeout + Retry + Circuit Breaker + Logging\n- [x] **v0.2** — Response Validation (schema check on tool responses)\n- [x] **v0.3** — Tool Filtering (expose only specific tools)\n- [x] **v0.4** — Rate Limiting (per-tool call caps)\n- [x] **v0.5** — Metrics Export (Prometheus-compatible `/metrics` endpoint)\n- [x] **v0.6** — Multi-server Composition\n\n## Contributing\n\nContributions welcome! Please open an issue first to discuss what you'd like to change.\n\n## License\n\n[MIT](LICENSE)\n","readmeFilename":"README.md","_rev":"1-93c0c8b7e11cf5764613aa8b29b2e77d"}