{"_id":"@agentic-security-mcp/mcp-guard","name":"@agentic-security-mcp/mcp-guard","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@agentic-security-mcp/mcp-guard","version":"0.1.0","description":"Policy-as-code for MCP servers: allow, deny, approve, rate-limit, and audit every AI tool call.","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./adapters":{"types":"./dist/adapters.d.ts","import":"./dist/adapters.js"},"./policy-check":{"types":"./dist/policy-check.d.ts","import":"./dist/policy-check.js"}},"bin":{"mcp-guard":"dist/cli.js"},"scripts":{"build":"tsc -p tsconfig.build.json","build:test":"tsc -p tsconfig.test.json","check":"tsc -p tsconfig.json --noEmit","test":"node --test dist-test/test/guard.test.js","pretest":"npm run build && npm run build:test"},"keywords":["mcp","model-context-protocol","security","policy","audit","rate-limit"],"license":"MIT","devDependencies":{"@types/node":"^22.0.0","typescript":"^5.6.0"},"peerDependencies":{"@modelcontextprotocol/server":">=2.0.0"},"peerDependenciesMeta":{"@modelcontextprotocol/server":{"optional":true}},"publishConfig":{"access":"public"},"_id":"@agentic-security-mcp/mcp-guard@0.1.0","_nodeVersion":"18.20.8","_npmVersion":"10.8.2","dist":{"integrity":"sha512-+/sZ0Xd/JSbTfpo+nwMGJp/VA41mz6EIY4Fzv+UVLPAAUmv5fT7Ka6NkndWxKigN+g4NTfvtS41V7kSEm4b9oQ==","shasum":"cfd2d0c14e83e6494aa865a28c8271cd87c73bc2","tarball":"https://registry.npmjs.org/@agentic-security-mcp/mcp-guard/-/mcp-guard-0.1.0.tgz","fileCount":26,"unpackedSize":31751,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIEDBqcARTKE1Q4Rgw0Ppef8VFHA049vRvWBLcX2IDmquAiBWoflOXgfx0EAfBO+xaJvloS1xG89Zimb/YD8aXo4WBA=="}]},"_npmUser":{"name":"shashank022","email":"shashank022@gmail.com"},"directories":{},"maintainers":[{"name":"shashank022","email":"shashank022@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-guard_0.1.0_1788673270364_0.16783833876657028"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-06T05:41:10.180Z","0.1.0":"2026-09-06T05:41:10.497Z","modified":"2026-09-06T05:41:10.765Z"},"maintainers":[{"name":"shashank022","email":"shashank022@gmail.com"}],"description":"Policy-as-code for MCP servers: allow, deny, approve, rate-limit, and audit every AI tool call.","keywords":["mcp","model-context-protocol","security","policy","audit","rate-limit"],"license":"MIT","readme":"# MCP Guard\n\nPolicy-as-code for MCP servers: allow, deny, approve, rate-limit, and audit every AI tool call.\n\n> MCP gives agents hands. MCP Guard decides what those hands can touch.\n\nMCP Guard is a small TypeScript runtime library for adding tool-level security rules around Model Context Protocol servers. It is designed for teams that want MCP adoption without letting every connected agent call every tool with every argument.\n\nIt does not try to be a dashboard, a hosted SaaS product, or an AI prompt-injection detector. It is a dependable open-source guardrail that runs in your server process.\n\n## Install\n\n```sh\nnpm install @agentic-security/mcp-guard\n```\n\nIf you are using the current MCP TypeScript SDK v2, install the server SDK too:\n\n```sh\nnpm install @modelcontextprotocol/server zod\n```\n\nMCP Guard is ESM-first and written in TypeScript.\n\n## Quick Start\n\nWrap a server-like object that exposes `callTool(tool, args, options)`.\n\n```ts\nimport { consoleAudit, guard, hasScope } from \"@agentic-security/mcp-guard\";\n\nconst guardedServer = guard(server, {\n  default: \"deny\",\n  tools: {\n    \"github.create_issue\": {\n      allow: hasScope(\"issues:write\")\n    },\n    \"payments.refund\": {\n      allow: hasScope(\"payments:write\"),\n      requireApproval: true\n    },\n    \"database.query\": {\n      allow: hasScope(\"db:read\"),\n      rateLimit: \"20/min\",\n      timeoutMs: 5000,\n      redact: [\"password\", \"connectionString\"]\n    }\n  },\n  approval: async (request) => request.actor === \"admin\",\n  audit: consoleAudit()\n});\n\nawait guardedServer.callTool(\n  \"github.create_issue\",\n  { repo: \"acme/api\", title: \"Bug in auth flow\" },\n  { actor: \"user_123\", scopes: [\"issues:write\"] }\n);\n```\n\nWith `default: \"deny\"`, any tool missing from `tools` is blocked.\n\n## Why Use It\n\nMCP servers expose real capabilities: creating issues, querying databases, sending emails, refunding payments, editing files, or calling internal APIs. Authentication answers who connected to the server. MCP Guard answers what that actor, agent, or session may do once connected.\n\nUse MCP Guard when you need to:\n\n- Deny unknown tools by default\n- Restrict tools by actor scope or custom predicates\n- Validate sensitive arguments before execution\n- Require approval for destructive actions\n- Rate-limit expensive or risky tools\n- Add timeout and retry boundaries around tool execution\n- Redact secrets and PII from audit events\n- Check policy files in CI\n\n## Core Concepts\n\n### Policy\n\nA policy has a default decision, a map of tool rules, and optional approval and audit hooks.\n\n```ts\nimport { type GuardPolicy, hasScope } from \"@agentic-security/mcp-guard\";\n\nexport const policy: GuardPolicy = {\n  default: \"deny\",\n  tools: {\n    \"github.create_issue\": { allow: hasScope(\"issues:write\") },\n    \"database.query\": {\n      allow: hasScope(\"db:read\"),\n      rateLimit: \"20/min\",\n      redact: [\"password\"]\n    }\n  }\n};\n```\n\n### Tool Rules\n\nEach tool can define:\n\n```ts\n{\n  allow: true,\n  deny: false,\n  requireApproval: true,\n  approveReason: \"This action changes customer billing state.\",\n  rateLimit: \"10/min\",\n  timeoutMs: 5000,\n  retry: { attempts: 2, delayMs: 100 },\n  redact: [\"password\", \"token\"],\n  args: {\n    amountCents: ({ args }) => Number(args.amountCents) < 10000\n  }\n}\n```\n\n`allow`, `deny`, `requireApproval`, and argument rules can be booleans or async predicates.\n\n### Context\n\nEvery guarded call receives context:\n\n```ts\n{\n  tool: \"payments.refund\",\n  args: { paymentId: \"pay_123\", amountCents: 5000 },\n  actor: \"user_123\",\n  scopes: [\"payments:write\"],\n  metadata: { requestId: \"req_abc\" }\n}\n```\n\nPredicates, approval hooks, and audit sinks all use this shape.\n\n## MCP SDK Usage\n\nFor the current MCP TypeScript SDK v2, wrap each registered tool handler with `mcpToolHandler`.\n\n```ts\nimport { McpServer } from \"@modelcontextprotocol/server\";\nimport { serveStdio } from \"@modelcontextprotocol/server/stdio\";\nimport * as z from \"zod/v4\";\nimport { hasScope, mcpToolHandler } from \"@agentic-security/mcp-guard\";\n\nconst policy = {\n  default: \"deny\" as const,\n  tools: {\n    \"github.create_issue\": { allow: hasScope(\"issues:write\") }\n  }\n};\n\nfunction createServer() {\n  const server = new McpServer({ name: \"guarded-github\", version: \"1.0.0\" });\n\n  server.registerTool(\n    \"github.create_issue\",\n    {\n      title: \"Create GitHub Issue\",\n      inputSchema: {\n        repo: z.string(),\n        title: z.string()\n      }\n    },\n    mcpToolHandler(\"github.create_issue\", policy, async ({ repo, title }) => ({\n      content: [{ type: \"text\", text: `Would create ${title} in ${repo}` }]\n    }))\n  );\n\n  return server;\n}\n\nvoid serveStdio(createServer);\n```\n\nSee [examples/mcp-sdk.ts](examples/mcp-sdk.ts) for a fuller example with approval, rate limiting, and redaction.\n\n## Approval\n\nApproval hooks let you pause destructive tool calls before execution.\n\n```ts\nconst policy = {\n  default: \"deny\" as const,\n  tools: {\n    \"payments.refund\": {\n      allow: hasScope(\"payments:write\"),\n      requireApproval: true,\n      approveReason: \"Refunds move money.\"\n    }\n  },\n  approval: async (request) => {\n    return request.actor === \"admin\";\n  }\n};\n```\n\nIf approval is required and no approval hook is configured, the call is denied.\n\n## Audit Logs\n\nUse `consoleAudit()` to emit JSON audit events.\n\n```ts\nimport { consoleAudit } from \"@agentic-security/mcp-guard\";\n\nconst policy = {\n  audit: consoleAudit(),\n  redact: [\"password\", \"token\"]\n};\n```\n\nAudit events include the tool name, actor, decision, redacted arguments, timestamp, duration, and error information when available.\n\nCommon secret keys such as `password`, `token`, `secret`, `apiKey`, `authorization`, and `cookie` are redacted automatically. Add custom fields with `redact`.\n\n## Rate Limits\n\nRate limits use a compact string format:\n\n```ts\n{\n  rateLimit: \"20/min\"\n}\n```\n\nSupported windows:\n\n- `10/s`\n- `20/min`\n- `100/hour`\n\nLimits are tracked in memory per actor and tool. For distributed deployments, use this first version as a local boundary and add a shared store adapter later.\n\n## CLI Policy Check\n\nValidate JSON policy files in CI:\n\n```sh\nnpx mcp-guard check mcp-guard.config.json\n```\n\nThe checker reports:\n\n- Invalid `default` values\n- Malformed rate limits\n- Non-positive timeouts\n- Tools with no allow rule when the default is deny\n\nUse JSON policy files for reviewable CI rules, and TypeScript policy files when you need custom predicates like `hasScope()`.\n\n## Framework Adapters\n\nMCP Guard includes lightweight helpers for common server shapes:\n\n```ts\nimport {\n  expressGuard,\n  fastifyGuard,\n  mcpToolHandler,\n  nestGuard\n} from \"@agentic-security/mcp-guard\";\n```\n\nThese adapters intentionally stay thin. The core enforcement engine is `createGuard(policy)`, which you can use directly in any runtime.\n\n## API\n\nPrimary exports:\n\n- `guard(server, policy)`\n- `createGuard(policy)`\n- `mcpToolHandler(tool, policy, handler)`\n- `hasScope(scope)`\n- `argEquals(name, value)`\n- `argMatches(name, pattern)`\n- `allOf(...rules)`\n- `anyOf(...rules)`\n- `consoleAudit()`\n- `redactArgs(args, fields)`\n- `checkPolicy(policy)`\n- `GuardError`\n\n## Development\n\n```sh\nnpm install\nnpm run build\nnpm test\nnpm run check\nnpm pack --dry-run\n```\n\nThe package publishes only compiled top-level `dist/*.js` and `dist/*.d.ts` files, examples, README, license, and package metadata.\n\n## Status\n\nMCP Guard is in early `0.1.x` development. The first goal is a tiny, dependable runtime policy layer with excellent examples. Dashboarding, hosted workflows, and prompt-injection detection are intentionally out of scope for the first version.\n","readmeFilename":"README.md","_rev":"1-2f60f1606cc94a9e612624fb1c1d3e37"}