@scopeblind/protect-mcp 0.1.0

package/README.md

@@ -0,0 +1,141 @@
+# @scopeblind/protect-mcp
+
+Security gateway for MCP servers. Tool-level policies, rate limiting, and structured decision logging.
+
+**Observe by default.** Wraps any MCP server as a transparent proxy. Logs every tool call. Optionally enforces policies.
+
+## Quick Start
+
+```bash
+# Observe mode — log all tool calls, allow everything through
+npx @scopeblind/protect-mcp -- node my-server.js
+
+# Enforce mode with a policy file
+npx @scopeblind/protect-mcp --policy policy.json --enforce -- node my-server.js
+```
+
+## How It Works
+
+protect-mcp sits between your MCP client and server as a stdio proxy:
+
+```
+MCP Client <--stdin/stdout--> protect-mcp <--stdin/stdout--> your MCP server
+```
+
+It intercepts `tools/call` JSON-RPC requests and:
+- **Observe mode** (default): logs every tool call to stderr, allows everything through
+- **Enforce mode**: applies policy rules, blocks denied tools, rate-limits others
+
+All other MCP messages (`initialize`, `tools/list`, notifications) pass through transparently.
+
+## Policy File
+
+Create a `policy.json`:
+
+```json
+{
+  "tools": {
+    "dangerous_tool": { "require": "gateway", "rate_limit": "5/hour" },
+    "read_only_tool": { "require": "any" },
+    "destructive_tool": { "block": true },
+    "*": { "require": "any", "rate_limit": "100/hour" }
+  }
+}
+```
+
+### Policy Rules
+
+| Field | Values | Description |
+|-------|--------|-------------|
+| `require` | `"gateway"`, `"any"`, `"none"` | Identity requirement (metadata only in v1 — not enforced until v2 SSE transport) |
+| `rate_limit` | `"N/unit"` | Rate limit (e.g. `"5/hour"`, `"100/day"`, `"10/minute"`) |
+| `block` | `true` | Explicitly block this tool |
+
+> **v1 enforcement:** `block` and `rate_limit` are enforced in `--enforce` mode. `require` is recorded in decision logs for policy documentation but not enforced — per-request identity verification requires the SSE gateway mode planned for v2.
+
+Tool names match exactly, with `"*"` as a wildcard fallback.
+
+## MCP Client Configuration
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "my-protected-server": {
+      "command": "npx",
+      "args": [
+        "-y", "@scopeblind/protect-mcp",
+        "--policy", "/path/to/policy.json",
+        "--enforce",
+        "--", "node", "my-server.js"
+      ]
+    }
+  }
+}
+```
+
+### Cursor / VS Code
+
+Same pattern — replace the server command with protect-mcp wrapping it.
+
+## Decision Logs
+
+Every tool call emits a structured JSON log to stderr:
+
+```
+[PROTECT_MCP] {"v":1,"tool":"dangerous_tool","decision":"deny","reason_code":"rate_limit_exceeded","policy_digest":"a1b2c3d4","request_id":"req_abc123","timestamp":1710000000,"mode":"enforce","rate_limit_remaining":0}
+```
+
+### Log Fields
+
+| Field | Description |
+|-------|-------------|
+| `v` | Schema version (always `1`) |
+| `tool` | Tool name that was called |
+| `decision` | `"allow"` or `"deny"` |
+| `reason_code` | `"policy_allow"`, `"policy_block"`, `"rate_limit_exceeded"`, `"observe_mode"`, `"default_allow"` |
+| `policy_digest` | SHA-256 prefix of the policy file |
+| `request_id` | Unique request identifier |
+| `timestamp` | Unix timestamp (ms) |
+| `mode` | `"observe"` or `"enforce"` |
+| `rate_limit_remaining` | Remaining rate limit budget (if applicable) |
+
+These are **decision logs**, not signed receipts. Cryptographically signed receipts require the ScopeBlind API (v2).
+
+## CLI Options
+
+```
+protect-mcp [options] -- <command> [args...]
+
+Options:
+  --policy <path>   Policy JSON file (default: allow-all)
+  --slug <slug>     ScopeBlind tenant slug (optional)
+  --enforce         Enable enforcement mode (default: observe-only)
+  --verbose         Enable debug logging
+  --help            Show help
+```
+
+## Programmatic API
+
+```typescript
+import { ProtectGateway, loadPolicy } from '@scopeblind/protect-mcp';
+
+const { policy, digest } = loadPolicy('./policy.json');
+
+const gateway = new ProtectGateway({
+  command: 'node',
+  args: ['my-server.js'],
+  policy,
+  policyDigest: digest,
+  enforce: true,
+});
+
+await gateway.start();
+```
+
+## License
+
+FSL-1.1-MIT

package/dist/chunk-L3QWKSGY.mjs

@@ -0,0 +1,297 @@
+// src/policy.ts
+import { createHash } from "crypto";
+import { readFileSync } from "fs";
+function loadPolicy(path) {
+  const raw = readFileSync(path, "utf-8");
+  const parsed = JSON.parse(raw);
+  if (!parsed.tools || typeof parsed.tools !== "object") {
+    throw new Error(`Invalid policy file: missing "tools" object in ${path}`);
+  }
+  const policy = { tools: parsed.tools };
+  const digest = computePolicyDigest(policy);
+  return { policy, digest };
+}
+function computePolicyDigest(policy) {
+  const canonical = JSON.stringify(sortKeysDeep(policy));
+  return createHash("sha256").update(canonical).digest("hex").slice(0, 16);
+}
+function sortKeysDeep(obj) {
+  if (obj === null || typeof obj !== "object") return obj;
+  if (Array.isArray(obj)) return obj.map(sortKeysDeep);
+  const sorted = {};
+  for (const key of Object.keys(obj).sort()) {
+    sorted[key] = sortKeysDeep(obj[key]);
+  }
+  return sorted;
+}
+function getToolPolicy(toolName, policy) {
+  if (!policy) {
+    return { require: "any" };
+  }
+  if (policy.tools[toolName]) {
+    return policy.tools[toolName];
+  }
+  if (policy.tools["*"]) {
+    return policy.tools["*"];
+  }
+  return { require: "any" };
+}
+function parseRateLimit(spec) {
+  const match = spec.match(/^(\d+)\/(second|minute|hour|day)$/);
+  if (!match) {
+    throw new Error(`Invalid rate limit format: "${spec}". Expected "N/unit" (e.g. "5/hour")`);
+  }
+  const count = parseInt(match[1], 10);
+  const unit = match[2];
+  const windowMs = {
+    second: 1e3,
+    minute: 6e4,
+    hour: 36e5,
+    day: 864e5
+  };
+  return { count, windowMs: windowMs[unit] };
+}
+function checkRateLimit(key, limit, store) {
+  const now = Date.now();
+  const windowStart = now - limit.windowMs;
+  const timestamps = (store.get(key) || []).filter((t) => t > windowStart);
+  if (timestamps.length >= limit.count) {
+    store.set(key, timestamps);
+    return { allowed: false, remaining: 0 };
+  }
+  timestamps.push(now);
+  store.set(key, timestamps);
+  return { allowed: true, remaining: limit.count - timestamps.length };
+}
+
+// src/gateway.ts
+import { spawn } from "child_process";
+import { randomUUID } from "crypto";
+import { createInterface } from "readline";
+var ProtectGateway = class {
+  child = null;
+  config;
+  rateLimitStore = /* @__PURE__ */ new Map();
+  clientReader = null;
+  constructor(config) {
+    this.config = config;
+  }
+  /**
+   * Start the gateway: spawn child process and wire up message relay.
+   */
+  async start() {
+    const { command, args, verbose } = this.config;
+    if (verbose) {
+      this.log(`Starting gateway in ${this.config.enforce ? "enforce" : "observe"} mode`);
+      this.log(`Wrapping: ${command} ${args.join(" ")}`);
+      if (this.config.policy) {
+        this.log(`Policy digest: ${this.config.policyDigest}`);
+      }
+    }
+    this.child = spawn(command, args, {
+      stdio: ["pipe", "pipe", "pipe"],
+      env: { ...process.env }
+    });
+    if (!this.child.stdin || !this.child.stdout || !this.child.stderr) {
+      throw new Error("Failed to create pipes to child process");
+    }
+    this.child.stderr.on("data", (data) => {
+      process.stderr.write(data);
+    });
+    const childReader = createInterface({ input: this.child.stdout, crlfDelay: Infinity });
+    childReader.on("line", (line) => {
+      this.handleServerMessage(line);
+    });
+    this.clientReader = createInterface({ input: process.stdin, crlfDelay: Infinity });
+    this.clientReader.on("line", (line) => {
+      this.handleClientMessage(line);
+    });
+    this.child.on("exit", (code, signal) => {
+      if (this.config.verbose) {
+        this.log(`Child process exited (code=${code}, signal=${signal})`);
+      }
+      process.exit(code ?? 1);
+    });
+    this.child.on("error", (err) => {
+      this.log(`Child process error: ${err.message}`);
+      process.exit(1);
+    });
+    process.on("SIGINT", () => this.stop());
+    process.on("SIGTERM", () => this.stop());
+    process.stdin.on("end", () => {
+      if (this.config.verbose) {
+        this.log("Client stdin closed, closing child stdin");
+      }
+      if (this.child?.stdin?.writable) {
+        this.child.stdin.end();
+      }
+    });
+  }
+  /**
+   * Handle a message from the MCP client (stdin).
+   * Intercept tools/call requests; pass through everything else.
+   */
+  handleClientMessage(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed) return;
+    let message;
+    try {
+      message = JSON.parse(trimmed);
+    } catch {
+      this.sendToChild(trimmed);
+      return;
+    }
+    if (message.method === "tools/call" && message.id !== void 0) {
+      const result = this.interceptToolCall(message);
+      if (result) {
+        this.sendToClient(JSON.stringify(result));
+        return;
+      }
+    }
+    this.sendToChild(trimmed);
+  }
+  /**
+   * Handle a message from the wrapped MCP server (child stdout).
+   * Forward to client (stdout) transparently.
+   */
+  handleServerMessage(raw) {
+    this.sendToClient(raw);
+  }
+  /**
+   * Intercept a tools/call request. Returns a JSON-RPC error response if denied, null if allowed.
+   */
+  interceptToolCall(request) {
+    const toolName = request.params?.name || "unknown";
+    const requestId = randomUUID().slice(0, 12);
+    const toolPolicy = getToolPolicy(toolName, this.config.policy);
+    if (toolPolicy.block) {
+      this.emitDecisionLog({
+        tool: toolName,
+        decision: "deny",
+        reason_code: "policy_block",
+        request_id: requestId
+      });
+      if (this.config.enforce) {
+        return this.makeErrorResponse(request.id, -32600, `Tool "${toolName}" is blocked by policy`);
+      }
+      return null;
+    }
+    if (toolPolicy.rate_limit) {
+      try {
+        const limit = parseRateLimit(toolPolicy.rate_limit);
+        const key = `tool:${toolName}`;
+        const { allowed, remaining } = checkRateLimit(key, limit, this.rateLimitStore);
+        if (!allowed) {
+          this.emitDecisionLog({
+            tool: toolName,
+            decision: "deny",
+            reason_code: "rate_limit_exceeded",
+            request_id: requestId,
+            rate_limit_remaining: 0
+          });
+          if (this.config.enforce) {
+            return this.makeErrorResponse(
+              request.id,
+              -32600,
+              `Tool "${toolName}" rate limit exceeded (${toolPolicy.rate_limit})`
+            );
+          }
+          return null;
+        }
+        this.emitDecisionLog({
+          tool: toolName,
+          decision: "allow",
+          reason_code: "policy_allow",
+          request_id: requestId,
+          rate_limit_remaining: remaining
+        });
+      } catch {
+        this.emitDecisionLog({
+          tool: toolName,
+          decision: "allow",
+          reason_code: "default_allow",
+          request_id: requestId
+        });
+      }
+    } else {
+      const reasonCode = this.config.enforce ? "policy_allow" : "observe_mode";
+      this.emitDecisionLog({
+        tool: toolName,
+        decision: "allow",
+        reason_code: reasonCode,
+        request_id: requestId
+      });
+    }
+    return null;
+  }
+  /**
+   * Emit a structured decision log to stderr.
+   */
+  emitDecisionLog(entry) {
+    const log = {
+      v: 1,
+      tool: entry.tool || "unknown",
+      decision: entry.decision || "allow",
+      reason_code: entry.reason_code || "default_allow",
+      policy_digest: this.config.policyDigest,
+      request_id: entry.request_id || randomUUID().slice(0, 12),
+      timestamp: Date.now(),
+      mode: this.config.enforce ? "enforce" : "observe",
+      ...entry.rate_limit_remaining !== void 0 && { rate_limit_remaining: entry.rate_limit_remaining }
+    };
+    process.stderr.write(`[PROTECT_MCP] ${JSON.stringify(log)}
+`);
+  }
+  /**
+   * Create a JSON-RPC error response.
+   */
+  makeErrorResponse(id, code, message) {
+    return {
+      jsonrpc: "2.0",
+      id,
+      error: { code, message }
+    };
+  }
+  /**
+   * Send a message to the child process (wrapped MCP server).
+   */
+  sendToChild(message) {
+    if (this.child?.stdin?.writable) {
+      this.child.stdin.write(message + "\n");
+    }
+  }
+  /**
+   * Send a message to the MCP client (stdout).
+   */
+  sendToClient(message) {
+    process.stdout.write(message + "\n");
+  }
+  /**
+   * Log a message to stderr (debug output).
+   */
+  log(message) {
+    process.stderr.write(`[PROTECT_MCP] ${message}
+`);
+  }
+  /**
+   * Stop the gateway: kill child process and exit.
+   */
+  stop() {
+    if (this.clientReader) {
+      this.clientReader.close();
+    }
+    if (this.child) {
+      this.child.kill("SIGTERM");
+      this.child = null;
+    }
+    process.exit(0);
+  }
+};
+
+export {
+  loadPolicy,
+  getToolPolicy,
+  parseRateLimit,
+  checkRateLimit,
+  ProtectGateway
+};

package/dist/cli.d.mts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node