@scopeblind/protect-mcp 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,157 @@
+interface ProtectPolicy {
+    tools: Record<string, ToolPolicy>;
+}
+interface ToolPolicy {
+    /**
+     * Identity requirement for this tool.
+     * 'gateway' = must pass through this gateway. 'any' = no restriction. 'none' = no identity needed.
+     *
+     * NOTE: v1 does not enforce this field — it is metadata only, logged in decision entries
+     * for policy documentation purposes. Per-request identity enforcement requires the
+     * SSE transport mode planned for v2.
+     */
+    require?: 'gateway' | 'any' | 'none';
+    /** Rate limit spec, e.g. "5/hour", "100/day", "10/minute" */
+    rate_limit?: string;
+    /** Explicitly block this tool */
+    block?: boolean;
+}
+interface RateLimit {
+    count: number;
+    windowMs: number;
+}
+interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    id: string | number;
+    method: string;
+    params?: Record<string, unknown>;
+}
+interface JsonRpcResponse {
+    jsonrpc: '2.0';
+    id: string | number;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+interface DecisionLog {
+    /** Schema version */
+    v: 1;
+    /** Tool name that was called */
+    tool: string;
+    /** Decision: allow or deny */
+    decision: 'allow' | 'deny';
+    /** Why this decision was made */
+    reason_code: 'policy_allow' | 'policy_block' | 'rate_limit_exceeded' | 'observe_mode' | 'default_allow';
+    /** SHA-256 digest of the canonicalized policy file */
+    policy_digest: string;
+    /** Unique request identifier */
+    request_id: string;
+    /** Unix timestamp (ms) */
+    timestamp: number;
+    /** Remaining rate limit budget (if rate limit is configured) */
+    rate_limit_remaining?: number;
+    /** Operating mode */
+    mode: 'observe' | 'enforce';
+}
+interface ProtectConfig {
+    /** Command to spawn (first element of child process) */
+    command: string;
+    /** Arguments for the child process */
+    args: string[];
+    /** Loaded policy (or null for allow-all) */
+    policy: ProtectPolicy | null;
+    /** Computed policy digest */
+    policyDigest: string;
+    /** ScopeBlind tenant slug (optional, for future API integration) */
+    slug?: string;
+    /** Whether to enforce policy (default: false = observe mode) */
+    enforce?: boolean;
+    /** Verbose debug logging to stderr */
+    verbose?: boolean;
+}
+
+/**
+ * ProtectGateway — stdio MITM proxy for MCP servers.
+ *
+ * Sits between an MCP client (stdin/stdout) and a wrapped MCP server (child process).
+ * Intercepts `tools/call` requests for policy enforcement and decision logging.
+ * Passes through all other JSON-RPC messages transparently.
+ */
+declare class ProtectGateway {
+    private child;
+    private config;
+    private rateLimitStore;
+    private clientReader;
+    constructor(config: ProtectConfig);
+    /**
+     * Start the gateway: spawn child process and wire up message relay.
+     */
+    start(): Promise<void>;
+    /**
+     * Handle a message from the MCP client (stdin).
+     * Intercept tools/call requests; pass through everything else.
+     */
+    private handleClientMessage;
+    /**
+     * Handle a message from the wrapped MCP server (child stdout).
+     * Forward to client (stdout) transparently.
+     */
+    private handleServerMessage;
+    /**
+     * Intercept a tools/call request. Returns a JSON-RPC error response if denied, null if allowed.
+     */
+    private interceptToolCall;
+    /**
+     * Emit a structured decision log to stderr.
+     */
+    private emitDecisionLog;
+    /**
+     * Create a JSON-RPC error response.
+     */
+    private makeErrorResponse;
+    /**
+     * Send a message to the child process (wrapped MCP server).
+     */
+    private sendToChild;
+    /**
+     * Send a message to the MCP client (stdout).
+     */
+    private sendToClient;
+    /**
+     * Log a message to stderr (debug output).
+     */
+    private log;
+    /**
+     * Stop the gateway: kill child process and exit.
+     */
+    stop(): void;
+}
+
+/**
+ * Load and validate a policy file. Returns the policy and its digest.
+ */
+declare function loadPolicy(path: string): {
+    policy: ProtectPolicy;
+    digest: string;
+};
+/**
+ * Get the policy for a specific tool. Falls back to "*" wildcard, then default-allow.
+ */
+declare function getToolPolicy(toolName: string, policy: ProtectPolicy | null): ToolPolicy;
+/**
+ * Parse a rate limit spec like "5/hour", "100/day", "10/minute".
+ */
+declare function parseRateLimit(spec: string): RateLimit;
+/**
+ * In-memory sliding window rate limiter.
+ * Returns { allowed, remaining } based on recent invocations.
+ */
+declare function checkRateLimit(key: string, limit: RateLimit, store: Map<string, number[]>): {
+    allowed: boolean;
+    remaining: number;
+};
+
+export { type DecisionLog, type JsonRpcRequest, type JsonRpcResponse, type ProtectConfig, ProtectGateway, type ProtectPolicy, type RateLimit, type ToolPolicy, checkRateLimit, getToolPolicy, loadPolicy, parseRateLimit };

package/dist/index.js

@@ -0,0 +1,329 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ProtectGateway: () => ProtectGateway,
+  checkRateLimit: () => checkRateLimit,
+  getToolPolicy: () => getToolPolicy,
+  loadPolicy: () => loadPolicy,
+  parseRateLimit: () => parseRateLimit
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/gateway.ts
+var import_node_child_process = require("child_process");
+var import_node_crypto2 = require("crypto");
+var import_node_readline = require("readline");
+
+// src/policy.ts
+var import_node_crypto = require("crypto");
+var import_node_fs = require("fs");
+function loadPolicy(path) {
+  const raw = (0, import_node_fs.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 (0, import_node_crypto.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
+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 = (0, import_node_child_process.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 = (0, import_node_readline.createInterface)({ input: this.child.stdout, crlfDelay: Infinity });
+    childReader.on("line", (line) => {
+      this.handleServerMessage(line);
+    });
+    this.clientReader = (0, import_node_readline.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 = (0, import_node_crypto2.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 || (0, import_node_crypto2.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);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ProtectGateway,
+  checkRateLimit,
+  getToolPolicy,
+  loadPolicy,
+  parseRateLimit
+});

package/dist/index.mjs

@@ -0,0 +1,14 @@
+import {
+  ProtectGateway,
+  checkRateLimit,
+  getToolPolicy,
+  loadPolicy,
+  parseRateLimit
+} from "./chunk-L3QWKSGY.mjs";
+export {
+  ProtectGateway,
+  checkRateLimit,
+  getToolPolicy,
+  loadPolicy,
+  parseRateLimit
+};

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@scopeblind/protect-mcp",
+  "version": "0.1.0",
+  "description": "Security gateway for MCP servers. Tool-level policies, rate limiting, and structured decision logging. Observe-by-default.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "module": "dist/index.mjs",
+  "bin": {
+    "protect-mcp": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/cli.ts --format cjs,esm --dts --clean",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "dist/cli.js"
+  ],
+  "keywords": [
+    "scopeblind",
+    "mcp",
+    "model-context-protocol",
+    "security",
+    "gateway",
+    "rate-limiting",
+    "policy",
+    "audit",
+    "decision-log",
+    "tool-protection",
+    "ai-agent",
+    "llm-gateway"
+  ],
+  "author": "Tom Farley <tommy@scopeblind.com>",
+  "license": "FSL-1.1-MIT",
+  "homepage": "https://www.scopeblind.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tomjwxf/scopeblind-gateway"
+  },
+  "bugs": {
+    "url": "https://github.com/tomjwxf/scopeblind-gateway/issues"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "@types/node": "^20.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}