{"_id":"@aporthq/mcp-policy-gate-example","name":"@aporthq/mcp-policy-gate-example","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@aporthq/mcp-policy-gate-example","version":"1.0.0","type":"module","description":"Example MCP server with APort policy enforcement","main":"dist/index.js","scripts":{"build":"tsc","start":"node dist/index.js","dev":"tsx src/index.ts"},"dependencies":{"@modelcontextprotocol/sdk":"^1.0.0","@aporthq/sdk-node":"^0.1.0"},"devDependencies":{"typescript":"^5.0.0","@types/node":"^20.0.0","tsx":"^4.0.0"},"license":"MIT*","_id":"@aporthq/mcp-policy-gate-example@1.0.0","dist":{"shasum":"63f3e7abf92873783f4bbda95fb921010f71c16f","integrity":"sha512-6ZV4CViA0Q4hWT7BLg6/oViKLORwFcLDOET4uMZgw/PEfmR5QtmZAOCKhRsjOULcjsMjTlKX8p2h2Z1YqLa7GA==","tarball":"https://registry.npmjs.org/@aporthq/mcp-policy-gate-example/-/mcp-policy-gate-example-1.0.0.tgz","fileCount":8,"unpackedSize":17494,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQD7nS/OOr8iT9d3NCFeI8p2b0xMTdTTqSIIxGzGeEfdwAIhAOFkimYBCx+T+Lbsklzb4LZVH/OvK+mPiGzIBmtZoXQC"}]},"_npmUser":{"name":"uchi4jah","email":"uchi.uchibeke@gmail.com"},"directories":{},"maintainers":[{"name":"uchi4jah","email":"uchi.uchibeke@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-policy-gate-example_1.0.0_1763553215614_0.7168985910564418"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-19T11:53:35.535Z","1.0.0":"2025-11-19T11:53:35.812Z","modified":"2025-11-19T11:53:36.110Z"},"maintainers":[{"name":"uchi4jah","email":"uchi.uchibeke@gmail.com"}],"description":"Example MCP server with APort policy enforcement","license":"MIT*","readme":"# APort Policy Gate Example - MCP Server\n\nExample MCP server that demonstrates APort policy enforcement for AI agent tool calls using **Simple Mode** (passport check + policy verification).\n\n**Note**: This example uses Simple Mode, suitable for internal tools and dev environments. Secure Mode (with SCA requirements) will be added in Month 2 for enterprise/external tools.\n\n## Features\n\n- 🔐 Policy enforcement using APort before tool execution (Simple Mode)\n- 🛠️ Two example tools: `merge_pull_request` and `process_refund`\n- ✅ Real-time authorization with <100ms latency\n- 📝 Immutable audit trail with decision IDs\n- 🔌 Compatible with Claude Desktop, VS Code, and any MCP client\n\n## Quick Start\n\n### 1. Install\n\n```bash\nnpm install -g @aporthq/mcp-policy-gate-example\n```\n\n### 2. Configure Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"aport-protected-tools\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"@aporthq/mcp-policy-gate-example\"\n      ],\n      \"env\": {\n        \"APORT_BASE_URL\": \"https://api.aport.io\"\n      }\n    }\n  }\n}\n```\n\n### 3. Register Agent Passport\n\nGet an agent passport from [aport.io](https://aport.io):\n\n```bash\ncurl -X POST https://api.aport.io/api/passports \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"owner_id\": \"your_org_id\",\n    \"capabilities\": [\"code.repository.merge\", \"finance.payment.refund\"],\n    \"assurance_level\": \"L2\"\n  }'\n```\n\n### 4. Use in Claude\n\n```\nUser: Merge PR #123 in my-org/my-repo to main branch\n\nClaude: I'll use the merge_pull_request tool...\n[Policy check happens automatically]\n✅ Pull request #123 merged to main in my-org/my-repo\nDecision ID: dec_1234567890\n```\n\n## Architecture (Simple Mode)\n\n**Security Model**: Passport-based verification with policy enforcement.\n\n```mermaid\nsequenceDiagram\n    participant Claude\n    participant MCP Server\n    participant APort\n    participant Tool (GitHub API)\n\n    Claude->>MCP Server: merge_pull_request(agent_id, repo, pr_number)\n    Note over MCP Server: Extract agent_id from request\n    MCP Server->>APort: POST /api/verify/policy/code.repository.merge.v1\n    Note over APort: 1. Verify passport exists\n    Note over APort: 2. Evaluate policy locally\n    APort-->>MCP Server: { allow: true, decision_id: \"dec_...\" }\n    MCP Server->>Tool: Execute merge (policy approved)\n    Tool-->>MCP Server: Success\n    MCP Server-->>Claude: ✅ PR merged (decision_id: dec_...)\n```\n\n## Policy Enforcement (Simple Mode)\n\nEvery tool call is protected by APort policies using Simple Mode:\n\n**Endpoint**: `/api/verify/policy/{pack_id}`\n\n**Security Flow**:\n1. Extract `agent_id` from request context\n2. Verify passport exists and is active\n3. Evaluate policy locally (<20ms)\n4. Return allow/deny decision\n\n**Use Case**: Internal tools, dev environments, CI/CD pipelines, trusted agents\n\n### `merge_pull_request` → `code.repository.merge.v1`\n- Requires capability: `code.repository.merge` or `repo.pr.create` + `repo.merge`\n- Minimum assurance level: L2\n- Validates: repository access, branch protection, PR size limits\n\n### `process_refund` → `finance.payment.refund.v1`\n- Requires capability: `finance.payment.refund`\n- Minimum assurance level: L2\n- Validates: amount limits, currency support, daily caps, reason codes\n\n**When to Upgrade to Secure Mode** (Month 2):\n- External MCP servers (tools from outside your organization)\n- Payment processors requiring cryptographic proof\n- Data exports with PII/sensitive data\n- Enterprise APIs with regulatory requirements\n\n## Example: Policy Denial\n\n```\nUser: Process a $100,000 refund for order 123\n\nClaude: I'll process that refund...\n[Policy check fails]\n❌ Policy denied: Amount exceeds daily cap of $50,000\nDecision ID: dec_0987654321\n```\n\n## Environment Variables\n\n- `APORT_BASE_URL`: APort registry URL (default: `https://api.aport.io`)\n- `APORT_TIMEOUT_MS`: Request timeout in milliseconds (default: `5000`)\n\n## Local Development\n\n```bash\n# Clone repo\ngit clone https://github.com/aporthq/mcp-policy-gate-example.git\ncd mcp-policy-gate-example\n\n# Install dependencies\nnpm install\n\n# Build TypeScript\nnpm run build\n\n# Run locally\nnpm start\n\n# Or run in dev mode with auto-reload\nnpm run dev\n```\n\n## Integration with Other MCP Clients\n\n### VS Code (Cline Extension)\n\nAdd to settings.json:\n\n```json\n{\n  \"cline.mcpServers\": {\n    \"aport-protected-tools\": {\n      \"command\": \"npx\",\n      \"args\": [\"@aporthq/mcp-policy-gate-example\"]\n    }\n  }\n}\n```\n\n### Custom MCP Client\n\n```typescript\nimport { Client } from '@modelcontextprotocol/sdk/client/index.js';\nimport { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';\n\nconst transport = new StdioClientTransport({\n  command: 'npx',\n  args: ['@aporthq/mcp-policy-gate-example'],\n});\n\nconst client = new Client({\n  name: 'my-client',\n  version: '1.0.0',\n}, {\n  capabilities: {},\n});\n\nawait client.connect(transport);\n\n// Call tool (agent_id required)\nconst result = await client.request({\n  method: 'tools/call',\n  params: {\n    name: 'merge_pull_request',\n    arguments: {\n      agent_id: 'ap_a2d10232c6534523812423eec8a1425c',\n      repository: 'my-org/my-repo',\n      pr_number: 123,\n      base_branch: 'main',\n    },\n  },\n});\n\nconsole.log(result);\n```\n\n## License\n\nMIT","readmeFilename":"README.md","_rev":"1-d00941eefbd49ba18181fcadeef57e71"}