@permission-protocol/mcp-guard 0.1.0

package/README.md

@@ -0,0 +1,224 @@
+# MCP Guard
+
+**Stop your AI agents from doing dangerous things.**
+
+[MCP](https://modelcontextprotocol.io) (Model Context Protocol) is how AI agents call tools — like APIs, databases, or deployments. MCP has no built-in access control. MCP Guard adds that layer.
+
+Define what's allowed, blocked, or requires approval — in a single YAML file. MCP Guard sits between your MCP client and server, enforces the rules, and logs every decision as an audit receipt.
+
+Without MCP Guard, your agent can call any tool. With it, every action is checked. **MCP Guard does not just log — it blocks execution before it happens.**
+
+→ **Blocks** unsafe tool calls before they execute
+→ **Holds** sensitive actions for human approval
+→ **Logs** every decision as an immutable receipt
+→ **Observe mode** — audit what would be blocked before enforcing
+
+<p align="center">
+  <img src="assets/demo.gif" alt="MCP Guard Demo" width="700">
+</p>
+
+## Get Started (2 minutes)
+
+```bash
+# Install
+npm install @permissionprotocol/mcp-guard
+
+# Create a policy file
+cat > pp.config.yaml << 'EOF'
+default_action: allow
+rules:
+  - id: block-delete
+    tool: delete_user_data
+    action: block
+  - id: hold-deploy
+    tool: deploy_production
+    action: require_approval
+EOF
+
+# Run your MCP server through the guard
+mcp-guard --config pp.config.yaml -- node my-mcp-server.js
+```
+
+That's it. Your agent can no longer delete user data. Production deploys require approval. Everything is logged to `pp-receipts.jsonl`.
+
+## 60-Second Demo (no MCP server needed)
+
+```bash
+git clone https://github.com/permission-protocol/mcp-guard
+cd mcp-guard
+npm install
+npm run demo
+```
+
+Sends three tool calls through the guard and shows: one allowed, one blocked, one held. No setup required.
+
+## Architecture
+
+```
+┌────────────┐     stdio      ┌─────────────┐     stdio      ┌────────────┐
+│  MCP Client│ ──────────────▶│  MCP Guard   │──────────────▶ │ MCP Server │
+│  (Claude,  │                │  (proxy)     │                │ (your app) │
+│   Cursor)  │ ◀──────────────│              │◀────────────── │            │
+└────────────┘   responses    └─────────────┘   responses    └────────────┘
+                                    │
+                                    ▼
+                              pp-receipts.jsonl
+                              (audit trail)
+```
+
+MCP Guard intercepts JSON-RPC messages on stdin/stdout. When it sees a `tools/call` request:
+
+1. Looks up the tool name in the config rules
+2. If **allowed** → forwards to the real server
+3. If **blocked** → returns a JSON-RPC error (`-32001`) directly
+4. If **held for approval** → returns a JSON-RPC error (`-32002`) directly
+5. Emits a receipt for every decision (stderr + jsonl file)
+
+All other JSON-RPC methods pass through transparently.
+
+## Config Reference
+
+```yaml
+# pp.config.yaml
+default_action: allow  # "allow" or "block" — applies when no rule matches
+mode: enforce          # "enforce" (default) or "observe" (log only, never block)
+
+rules:
+  - id: unique-rule-id        # Human-readable identifier
+    tool: tool_name            # Exact match on MCP tool name
+    action: allow              # allow | block | require_approval
+```
+
+### Modes
+
+| Mode | Behavior |
+|------|----------|
+| `enforce` | Block/hold tool calls per rules (default) |
+| `observe` | Log decisions + emit receipts, but always forward (dry-run) |
+
+Use `observe` mode to audit what *would* be blocked before turning enforcement on. Switch via config or CLI: `--mode observe`.
+
+### Actions
+
+| Action | Behavior | JSON-RPC Error Code |
+|--------|----------|-------------------|
+| `allow` | Forward request to server | — |
+| `block` | Reject immediately | `-32001` |
+| `require_approval` | Reject with hold status | `-32002` |
+
+## Receipts
+
+Every `tools/call` decision generates an immutable receipt:
+
+```json
+{
+  "receipt_id": "550e8400-e29b-41d4-a716-446655440000",
+  "timestamp": "2026-03-20T15:30:00.000Z",
+  "agent_id": "my-agent",
+  "tool_name": "delete_user_data",
+  "decision": "blocked",
+  "reason": "Matched rule \"block-dangerous-delete\"",
+  "rule_id": "block-dangerous-delete",
+  "request_payload_hash": "sha256-hex-string",
+  "target_server": "node my-mcp-server.js",
+  "mode": "enforce"
+}
+```
+
+Receipts are written to:
+- **stderr** — for real-time monitoring
+- **pp-receipts.jsonl** — append-only audit file
+
+The `request_payload_hash` is a SHA-256 of the full request params, so you can verify what was sent without storing sensitive arguments.
+
+**[→ Visualize your receipts](https://permission-protocol.github.io/mcp-guard/)** — paste a receipt or upload `pp-receipts.jsonl` to see a visual summary.
+
+## CLI
+
+```
+mcp-guard [options] -- <server command>
+
+Options:
+  --config <path>     Path to config file (default: ./pp.config.yaml)
+  --agent-id <id>     Agent identifier for receipts (default: "unknown")
+  --mode <mode>           enforce or observe (overrides config file)
+  --approval-port <port>  Enable approval UI on this port (e.g. 3100)
+  -h, --help              Show help
+```
+
+### Example: Claude Desktop
+
+In your Claude Desktop MCP config, replace:
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "node",
+      "args": ["my-mcp-server.js"]
+    }
+  }
+}
+```
+
+With:
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "mcp-guard",
+      "args": ["--config", "pp.config.yaml", "--agent-id", "claude-desktop", "--", "node", "my-mcp-server.js"]
+    }
+  }
+}
+```
+
+## Approval Flow (v0.1)
+
+When a tool call matches a `require_approval` rule, MCP Guard can hold the request open and wait for human approval via a web UI — instead of rejecting immediately.
+
+```bash
+# Start with approval UI on port 3100
+mcp-guard --config pp.config.yaml --approval-port 3100 -- node my-mcp-server.js
+
+# Open http://localhost:3100 to see pending approvals
+```
+
+**How it works:**
+1. Agent calls a tool that requires approval
+2. MCP Guard holds the JSON-RPC response open (does NOT return an error)
+3. The tool call appears in the approval UI at `http://localhost:<port>`
+4. Human clicks **Approve** → request is forwarded to the server, response returned to the agent
+5. Human clicks **Deny** → JSON-RPC error (-32002) returned to the agent
+
+When `--approval-port` is **not** set, `require_approval` tools return an error immediately (original behavior, no change).
+
+The approval UI auto-refreshes every 3 seconds and shows:
+- Pending tool calls with collapsible arguments
+- Recent decision history (last 20)
+
+## Why not just use X?
+
+| Approach | Why MCP Guard is different |
+|----------|---------------------------|
+| API gateway | MCP operates at the tool-call layer, not HTTP. MCP Guard understands tool names and MCP's JSON-RPC protocol. |
+| RBAC / IAM | Those gate *users*. MCP Guard gates *agent actions* — the agent is already authenticated, the question is what it's allowed to *do*. |
+| "Just code it" | You could. MCP Guard gives you a declarative config, audit receipts, observe mode, and an approval UI — without changing your server code. |
+
+## What This Is NOT
+
+- **Not a dashboard.** It's a proxy. It sits in the data path and enforces rules.
+- **Not a scanner.** It doesn't analyze your code or model outputs. It gates tool calls.
+- **Not compliance theater.** Every decision has a cryptographic receipt.
+- **Not a replacement for good architecture.** It's one layer in a defense-in-depth strategy.
+
+Agents shouldn't be able to execute arbitrary actions without an explicit decision point.
+
+## Part of Permission Protocol
+
+MCP Guard is a building block of the [Permission Protocol](https://github.com/permission-protocol) — explicit authority for autonomous AI systems.
+
+## License
+
+MIT

package/bin/mcp-guard

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../dist/src/cli.js');

package/demo/_demo-scenario.sh

@@ -0,0 +1,43 @@
+#!/bin/bash
+set -euo pipefail
+
+GREEN='\033[0;32m'
+RED='\033[1;31m'
+BOLD='\033[1m'
+DIM='\033[2m'
+NC='\033[0m'
+BG_RED='\033[41m'
+BG_GREEN='\033[42m'
+BLACK='\033[30m'
+
+clear
+echo ""
+
+# ── BEFORE (red = danger) ──
+echo -e "  ${BG_RED}${BLACK}${BOLD} ✖ WITHOUT MCP GUARD ${NC}"
+echo ""
+sleep 0.6
+echo -e "  ${DIM}\$${NC} call ${BOLD}delete_user_data${NC}"
+sleep 0.4
+echo -e "  ${GREEN}✔ success${NC} — user data deleted"
+echo ""
+sleep 1.5
+
+# ── DIVIDER ──
+echo -e "  ${DIM}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo ""
+sleep 0.4
+
+# ── AFTER (green = safe) ──
+echo -e "  ${BG_GREEN}${BLACK}${BOLD} ✔ WITH MCP GUARD ${NC}"
+echo ""
+sleep 0.6
+echo -e "  ${DIM}\$${NC} call ${BOLD}delete_user_data${NC}"
+sleep 0.4
+echo -e "  ${RED}${BOLD}✖ BLOCKED${NC}"
+echo -e "  ${DIM}rule: block-delete-user-data${NC}"
+echo ""
+sleep 0.5
+echo -e "  ${DIM}{ \"decision\": \"blocked\" }${NC}"
+echo ""
+sleep 2.5

package/dist/example/server.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/example/server.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Tiny MCP server for testing mcp-guard.
+ * Responds to tools/call, tools/list, and initialize.
+ * Newline-delimited JSON-RPC over stdio.
+ */
+const node_readline_1 = require("node:readline");
+const TOOLS = [
+    { name: 'send_email', description: 'Send an email', inputSchema: { type: 'object', properties: { to: { type: 'string' }, body: { type: 'string' } } } },
+    { name: 'delete_user_data', description: 'Delete all user data', inputSchema: { type: 'object', properties: { user_id: { type: 'string' } } } },
+    { name: 'deploy_production', description: 'Deploy to production', inputSchema: { type: 'object', properties: { version: { type: 'string' } } } },
+];
+const rl = (0, node_readline_1.createInterface)({ input: process.stdin });
+rl.on('line', (line) => {
+    if (!line.trim())
+        return;
+    let msg;
+    try {
+        msg = JSON.parse(line);
+    }
+    catch {
+        return;
+    }
+    if (msg.method === 'initialize') {
+        respond(msg.id, {
+            protocolVersion: '2024-11-05',
+            capabilities: { tools: {} },
+            serverInfo: { name: 'example-server', version: '0.1.0' },
+        });
+    }
+    else if (msg.method === 'tools/list') {
+        respond(msg.id, { tools: TOOLS });
+    }
+    else if (msg.method === 'tools/call') {
+        const toolName = msg.params?.name ?? 'unknown';
+        respond(msg.id, {
+            content: [{ type: 'text', text: `Executed ${toolName} successfully` }],
+        });
+    }
+    else if (msg.method === 'notifications/initialized') {
+        // No response needed for notifications
+    }
+    else {
+        respondError(msg.id, -32601, `Method not found: ${msg.method}`);
+    }
+});
+function respond(id, result) {
+    process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id, result }) + '\n');
+}
+function respondError(id, code, message) {
+    process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id, error: { code, message } }) + '\n');
+}
+//# sourceMappingURL=server.js.map

package/dist/example/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../example/server.ts"],"names":[],"mappings":"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"}

package/dist/src/approval-server.d.ts

@@ -0,0 +1,4 @@
+import type { Receipt } from './receipt.js';
+export declare function pushReceipt(receipt: Receipt): void;
+export declare function setOnApprove(cb: (id: string) => void): void;
+export declare function startApprovalServer(port: number): void;

package/dist/src/approval-server.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pushReceipt = pushReceipt;
+exports.setOnApprove = setOnApprove;
+exports.startApprovalServer = startApprovalServer;
+const node_http_1 = require("node:http");
+const pending_js_1 = require("./pending.js");
+const approval_ui_js_1 = require("./approval-ui.js");
+/** Recent receipts store (ring buffer) */
+const recentReceipts = [];
+const MAX_RECEIPTS = 50;
+function pushReceipt(receipt) {
+    recentReceipts.push(receipt);
+    if (recentReceipts.length > MAX_RECEIPTS)
+        recentReceipts.shift();
+}
+/** Callback invoked when an action is approved — proxy registers this */
+let onApproveCallback = null;
+function setOnApprove(cb) {
+    onApproveCallback = cb;
+}
+function parseBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on('data', (c) => chunks.push(c));
+        req.on('end', () => resolve(Buffer.concat(chunks).toString()));
+        req.on('error', reject);
+    });
+}
+function json(res, status, data) {
+    const body = JSON.stringify(data);
+    res.writeHead(status, {
+        'Content-Type': 'application/json',
+        'Access-Control-Allow-Origin': '*',
+    });
+    res.end(body);
+}
+function text(res, status, msg) {
+    res.writeHead(status, { 'Content-Type': 'text/plain' });
+    res.end(msg);
+}
+function startApprovalServer(port) {
+    const server = (0, node_http_1.createServer)(async (req, res) => {
+        const url = req.url ?? '/';
+        const method = req.method ?? 'GET';
+        // CORS preflight
+        if (method === 'OPTIONS') {
+            res.writeHead(204, {
+                'Access-Control-Allow-Origin': '*',
+                'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+                'Access-Control-Allow-Headers': 'Content-Type',
+            });
+            res.end();
+            return;
+        }
+        try {
+            // GET / — Approval UI
+            if (method === 'GET' && url === '/') {
+                res.writeHead(200, { 'Content-Type': 'text/html' });
+                res.end((0, approval_ui_js_1.getApprovalHTML)());
+                return;
+            }
+            // GET /api/pending
+            if (method === 'GET' && url === '/api/pending') {
+                const pending = (0, pending_js_1.getPending)().map(p => ({
+                    id: p.id,
+                    timestamp: p.timestamp,
+                    tool_name: p.tool_name,
+                    tool_args: p.tool_args,
+                    agent_id: p.agent_id,
+                    rule_id: p.rule_id,
+                    status: p.status,
+                }));
+                json(res, 200, pending);
+                return;
+            }
+            // POST /api/approve/:id
+            const approveMatch = url.match(/^\/api\/approve\/([a-f0-9-]+)$/);
+            if (method === 'POST' && approveMatch) {
+                const id = approveMatch[1];
+                const action = (0, pending_js_1.resolveAction)(id, 'approved');
+                if (!action) {
+                    json(res, 404, { error: 'Not found or already resolved' });
+                    return;
+                }
+                process.stderr.write(`[mcp-guard] Approved: ${action.tool_name} (${id})\n`);
+                // Notify proxy to forward the original request
+                if (onApproveCallback)
+                    onApproveCallback(id);
+                json(res, 200, { id, status: 'approved' });
+                return;
+            }
+            // POST /api/deny/:id
+            const denyMatch = url.match(/^\/api\/deny\/([a-f0-9-]+)$/);
+            if (method === 'POST' && denyMatch) {
+                const id = denyMatch[1];
+                const action = (0, pending_js_1.resolveAction)(id, 'denied');
+                if (!action) {
+                    json(res, 404, { error: 'Not found or already resolved' });
+                    return;
+                }
+                process.stderr.write(`[mcp-guard] Denied: ${action.tool_name} (${id})\n`);
+                // Return JSON-RPC error to the waiting caller
+                const errResp = JSON.stringify({
+                    jsonrpc: '2.0',
+                    id: action.jsonrpcId,
+                    error: { code: -32002, message: 'Denied by administrator' },
+                });
+                action.resolve(errResp);
+                json(res, 200, { id, status: 'denied' });
+                return;
+            }
+            // GET /api/receipts
+            if (method === 'GET' && url === '/api/receipts') {
+                json(res, 200, recentReceipts.slice(-50).reverse());
+                return;
+            }
+            text(res, 404, 'Not found');
+        }
+        catch (err) {
+            text(res, 500, err.message ?? 'Internal error');
+        }
+    });
+    server.listen(port, () => {
+        process.stderr.write(`[mcp-guard] Approval UI: http://localhost:${port}\n`);
+    });
+}
+//# sourceMappingURL=approval-server.js.map

package/dist/src/approval-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-server.js","sourceRoot":"","sources":["../../src/approval-server.ts"],"names":[],"mappings":";;AASA,kCAGC;AAKD,oCAEC;AAyBD,kDA2FC;AAvID,yCAAoF;AACpF,6CAAoF;AACpF,qDAAmD;AAGnD,0CAA0C;AAC1C,MAAM,cAAc,GAAc,EAAE,CAAC;AACrC,MAAM,YAAY,GAAG,EAAE,CAAC;AAExB,SAAgB,WAAW,CAAC,OAAgB;IAC1C,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC7B,IAAI,cAAc,CAAC,MAAM,GAAG,YAAY;QAAE,cAAc,CAAC,KAAK,EAAE,CAAC;AACnE,CAAC;AAED,yEAAyE;AACzE,IAAI,iBAAiB,GAAkC,IAAI,CAAC;AAE5D,SAAgB,YAAY,CAAC,EAAwB;IACnD,iBAAiB,GAAG,EAAE,CAAC;AACzB,CAAC;AAED,SAAS,SAAS,CAAC,GAAoB;IACrC,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,MAAM,GAAa,EAAE,CAAC;QAC5B,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAS,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QAC9C,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;QAC/D,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC1B,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,IAAI,CAAC,GAAmB,EAAE,MAAc,EAAE,IAAa;IAC9D,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IAClC,GAAG,CAAC,SAAS,CAAC,MAAM,EAAE;QACpB,cAAc,EAAE,kBAAkB;QAClC,6BAA6B,EAAE,GAAG;KACnC,CAAC,CAAC;IACH,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED,SAAS,IAAI,CAAC,GAAmB,EAAE,MAAc,EAAE,GAAW;IAC5D,GAAG,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,cAAc,EAAE,YAAY,EAAE,CAAC,CAAC;IACxD,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AACf,CAAC;AAED,SAAgB,mBAAmB,CAAC,IAAY;IAC9C,MAAM,MAAM,GAAG,IAAA,wBAAY,EAAC,KAAK,EAAE,GAAoB,EAAE,GAAmB,EAAE,EAAE;QAC9E,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC;QAC3B,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,IAAI,KAAK,CAAC;QAEnC,iBAAiB;QACjB,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE;gBACjB,6BAA6B,EAAE,GAAG;gBAClC,8BAA8B,EAAE,oBAAoB;gBACpD,8BAA8B,EAAE,cAAc;aAC/C,CAAC,CAAC;YACH,GAAG,CAAC,GAAG,EAAE,CAAC;YACV,OAAO;QACT,CAAC;QAED,IAAI,CAAC;YACH,sBAAsB;YACtB,IAAI,MAAM,KAAK,KAAK,IAAI,GAAG,KAAK,GAAG,EAAE,CAAC;gBACpC,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,WAAW,EAAE,CAAC,CAAC;gBACpD,GAAG,CAAC,GAAG,CAAC,IAAA,gCAAe,GAAE,CAAC,CAAC;gBAC3B,OAAO;YACT,CAAC;YAED,mBAAmB;YACnB,IAAI,MAAM,KAAK,KAAK,IAAI,GAAG,KAAK,cAAc,EAAE,CAAC;gBAC/C,MAAM,OAAO,GAAG,IAAA,uBAAU,GAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;oBACrC,EAAE,EAAE,CAAC,CAAC,EAAE;oBACR,SAAS,EAAE,CAAC,CAAC,SAAS;oBACtB,SAAS,EAAE,CAAC,CAAC,SAAS;oBACtB,SAAS,EAAE,CAAC,CAAC,SAAS;oBACtB,QAAQ,EAAE,CAAC,CAAC,QAAQ;oBACpB,OAAO,EAAE,CAAC,CAAC,OAAO;oBAClB,MAAM,EAAE,CAAC,CAAC,MAAM;iBACjB,CAAC,CAAC,CAAC;gBACJ,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;gBACxB,OAAO;YACT,CAAC;YAED,wBAAwB;YACxB,MAAM,YAAY,GAAG,GAAG,CAAC,KAAK,CAAC,gCAAgC,CAAC,CAAC;YACjE,IAAI,MAAM,KAAK,MAAM,IAAI,YAAY,EAAE,CAAC;gBACtC,MAAM,EAAE,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;gBAC3B,MAAM,MAAM,GAAG,IAAA,0BAAa,EAAC,EAAE,EAAE,UAAU,CAAC,CAAC;gBAC7C,IAAI,CAAC,MAAM,EAAE,CAAC;oBACZ,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,+BAA+B,EAAE,CAAC,CAAC;oBAC3D,OAAO;gBACT,CAAC;gBACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,yBAAyB,MAAM,CAAC,SAAS,KAAK,EAAE,KAAK,CAAC,CAAC;gBAC5E,+CAA+C;gBAC/C,IAAI,iBAAiB;oBAAE,iBAAiB,CAAC,EAAE,CAAC,CAAC;gBAC7C,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC;gBAC3C,OAAO;YACT,CAAC;YAED,qBAAqB;YACrB,MAAM,SAAS,GAAG,GAAG,CAAC,KAAK,CAAC,6BAA6B,CAAC,CAAC;YAC3D,IAAI,MAAM,KAAK,MAAM,IAAI,SAAS,EAAE,CAAC;gBACnC,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;gBACxB,MAAM,MAAM,GAAG,IAAA,0BAAa,EAAC,EAAE,EAAE,QAAQ,CAAC,CAAC;gBAC3C,IAAI,CAAC,MAAM,EAAE,CAAC;oBACZ,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,+BAA+B,EAAE,CAAC,CAAC;oBAC3D,OAAO;gBACT,CAAC;gBACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,uBAAuB,MAAM,CAAC,SAAS,KAAK,EAAE,KAAK,CAAC,CAAC;gBAC1E,8CAA8C;gBAC9C,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC;oBAC7B,OAAO,EAAE,KAAK;oBACd,EAAE,EAAE,MAAM,CAAC,SAAS;oBACpB,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,yBAAyB,EAAE;iBAC5D,CAAC,CAAC;gBACH,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;gBACxB,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;gBACzC,OAAO;YACT,CAAC;YAED,oBAAoB;YACpB,IAAI,MAAM,KAAK,KAAK,IAAI,GAAG,KAAK,eAAe,EAAE,CAAC;gBAChD,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,cAAc,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;gBACpD,OAAO;YACT,CAAC;YAED,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,WAAW,CAAC,CAAC;QAC9B,CAAC;QAAC,OAAO,GAAQ,EAAE,CAAC;YAClB,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,OAAO,IAAI,gBAAgB,CAAC,CAAC;QAClD,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,EAAE;QACvB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,6CAA6C,IAAI,IAAI,CAAC,CAAC;IAC9E,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/src/approval-ui.d.ts

@@ -0,0 +1 @@
+export declare function getApprovalHTML(): string;

package/dist/src/approval-ui.js

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getApprovalHTML = getApprovalHTML;
+function getApprovalHTML() {
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>MCP Guard — Approval Queue</title>
+<style>
+  *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+  body {
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif;
+    background: #0d1117; color: #c9d1d9; line-height: 1.5;
+    padding: 24px; max-width: 900px; margin: 0 auto;
+  }
+  h1 { color: #58a6ff; font-size: 24px; margin-bottom: 4px; }
+  .subtitle { color: #8b949e; font-size: 14px; margin-bottom: 24px; }
+  .badge {
+    display: inline-block; padding: 2px 8px; border-radius: 12px;
+    font-size: 12px; font-weight: 600; text-transform: uppercase;
+  }
+  .badge-pending { background: #d29922; color: #0d1117; }
+  .badge-approved { background: #238636; color: #fff; }
+  .badge-denied { background: #da3633; color: #fff; }
+  .badge-allowed { background: #238636; color: #fff; }
+  .badge-blocked { background: #da3633; color: #fff; }
+  .badge-held_for_approval { background: #d29922; color: #0d1117; }
+  .card {
+    border: 1px solid #30363d; border-radius: 8px; padding: 16px;
+    margin-bottom: 12px; background: #161b22;
+  }
+  .card-header { display: flex; justify-content: space-between; align-items: center; margin-bottom: 8px; }
+  .tool-name { font-size: 18px; font-weight: 700; color: #f0f6fc; }
+  .meta { font-size: 13px; color: #8b949e; margin-bottom: 8px; }
+  .meta span { margin-right: 16px; }
+  .args-toggle {
+    background: none; border: 1px solid #30363d; color: #58a6ff;
+    padding: 4px 10px; border-radius: 4px; cursor: pointer; font-size: 12px;
+    margin-bottom: 8px;
+  }
+  .args-toggle:hover { border-color: #58a6ff; }
+  .args-content {
+    display: none; background: #0d1117; border: 1px solid #30363d;
+    border-radius: 4px; padding: 12px; margin-bottom: 12px;
+    font-family: 'SF Mono', Consolas, monospace; font-size: 13px;
+    overflow-x: auto; white-space: pre-wrap; word-break: break-all;
+  }
+  .args-content.open { display: block; }
+  .actions { display: flex; gap: 8px; }
+  .btn {
+    padding: 6px 16px; border-radius: 6px; border: none;
+    font-size: 14px; font-weight: 600; cursor: pointer; transition: opacity 0.15s;
+  }
+  .btn:hover { opacity: 0.85; }
+  .btn:disabled { opacity: 0.4; cursor: not-allowed; }
+  .btn-approve { background: #238636; color: #fff; }
+  .btn-deny { background: #da3633; color: #fff; }
+  .empty {
+    text-align: center; padding: 40px; color: #8b949e;
+    border: 1px dashed #30363d; border-radius: 8px; margin-bottom: 24px;
+  }
+  h2 { color: #c9d1d9; font-size: 18px; margin: 24px 0 12px; }
+  table { width: 100%; border-collapse: collapse; font-size: 13px; }
+  th { text-align: left; padding: 8px; border-bottom: 2px solid #30363d; color: #8b949e; font-weight: 600; }
+  td { padding: 8px; border-bottom: 1px solid #21262d; }
+  .pulse { display: inline-block; width: 8px; height: 8px; border-radius: 50%; background: #3fb950; margin-right: 8px; animation: pulse 2s infinite; }
+  @keyframes pulse { 0%,100% { opacity: 1; } 50% { opacity: 0.3; } }
+  .status-bar { display: flex; align-items: center; font-size: 12px; color: #8b949e; margin-bottom: 16px; }
+</style>
+</head>
+<body>
+<h1>MCP Guard — Approval Queue</h1>
+<p class="subtitle">Human-in-the-loop approval for AI tool calls</p>
+<div class="status-bar"><span class="pulse"></span> Polling every 3s</div>
+
+<div id="pending"></div>
+<h2>Recent Decisions</h2>
+<div id="receipts"></div>
+
+<script>
+function esc(s) { const d = document.createElement('div'); d.textContent = s; return d.innerHTML; }
+
+function toggleArgs(btn) {
+  const c = btn.nextElementSibling;
+  c.classList.toggle('open');
+  btn.textContent = c.classList.contains('open') ? '▾ Hide arguments' : '▸ Show arguments';
+}
+
+async function act(id, action) {
+  const btns = document.querySelectorAll('[data-id="'+id+'"]');
+  btns.forEach(b => b.disabled = true);
+  try {
+    const r = await fetch('/api/' + action + '/' + id, { method: 'POST' });
+    if (!r.ok) { const e = await r.text(); alert('Error: ' + e); }
+  } catch(e) { alert('Network error'); }
+  refresh();
+}
+
+async function refresh() {
+  try {
+    const [pRes, rRes] = await Promise.all([
+      fetch('/api/pending'), fetch('/api/receipts')
+    ]);
+    const pending = await pRes.json();
+    const receipts = await rRes.json();
+
+    const pEl = document.getElementById('pending');
+    if (pending.length === 0) {
+      pEl.innerHTML = '<div class="empty">No pending approvals</div>';
+    } else {
+      pEl.innerHTML = pending.map(p => \`
+        <div class="card">
+          <div class="card-header">
+            <span class="tool-name">\${esc(p.tool_name)}</span>
+            <span class="badge badge-pending">pending</span>
+          </div>
+          <div class="meta">
+            <span>Agent: <strong>\${esc(p.agent_id)}</strong></span>
+            <span>Rule: <strong>\${esc(p.rule_id)}</strong></span>
+            <span>\${esc(new Date(p.timestamp).toLocaleTimeString())}</span>
+          </div>
+          <button class="args-toggle" onclick="toggleArgs(this)">▸ Show arguments</button>
+          <div class="args-content">\${esc(JSON.stringify(p.tool_args, null, 2))}</div>
+          <div class="actions">
+            <button class="btn btn-approve" data-id="\${p.id}" onclick="act('\${p.id}','approve')">✅ Approve</button>
+            <button class="btn btn-deny" data-id="\${p.id}" onclick="act('\${p.id}','deny')">❌ Deny</button>
+          </div>
+        </div>
+      \`).join('');
+    }
+
+    const rEl = document.getElementById('receipts');
+    if (receipts.length === 0) {
+      rEl.innerHTML = '<div class="empty">No recent decisions</div>';
+    } else {
+      rEl.innerHTML = \`<table>
+        <thead><tr><th>Time</th><th>Tool</th><th>Decision</th><th>Agent</th><th>Rule</th></tr></thead>
+        <tbody>\${receipts.map(r => \`<tr>
+          <td>\${esc(new Date(r.timestamp).toLocaleTimeString())}</td>
+          <td><strong>\${esc(r.tool_name)}</strong></td>
+          <td><span class="badge badge-\${r.decision}">\${esc(r.decision)}</span></td>
+          <td>\${esc(r.agent_id)}</td>
+          <td>\${esc(r.rule_id || '—')}</td>
+        </tr>\`).join('')}</tbody>
+      </table>\`;
+    }
+  } catch(e) { /* retry next cycle */ }
+}
+
+refresh();
+setInterval(refresh, 3000);
+</script>
+</body>
+</html>`;
+}
+//# sourceMappingURL=approval-ui.js.map

package/dist/src/approval-ui.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-ui.js","sourceRoot":"","sources":["../../src/approval-ui.ts"],"names":[],"mappings":";;AAAA,0CAyJC;AAzJD,SAAgB,eAAe;IAC7B,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAuJD,CAAC;AACT,CAAC"}

package/dist/src/cli.d.ts

@@ -0,0 +1 @@
+export declare function main(): void;