@strixgov/mcp-proxy 0.1.0

package/src/proxy.mjs

@@ -0,0 +1,212 @@
+/**
+ * Strix MCP Proxy — core.
+ *
+ * Architectural shape:
+ *
+ *   MCP Client ──stdio──▶ [Strix Proxy: server] ──governMCPServer──▶ [client] ──stdio──▶ Upstream MCP Server
+ *
+ * The proxy IS an MCP server (toward the consumer's client) AND an MCP
+ * client (toward the upstream tool). Every callTool entering the proxy
+ * is routed through `governMCPServer` from `@strixgov/mcp-adapter`,
+ * which applies policy, fires the approval gate when needed, executes
+ * via the upstream client, and emits a signed Ed25519 receipt.
+ *
+ * Today (v0.1.0) — Mode 1 (Observed) and Mode 2 (Approval-Gated).
+ *
+ * Designed for Mode 3 upgrade. The downstream-call seam at
+ * `buildUpstreamIface()` is the single place where Mode 3 enforcement
+ * will attach in v0.2.0: a future option (`mode: "enforced"`) wraps
+ * every outbound call with the `execution_authorization_v1` token
+ * mint + transport step from
+ * `docs/architecture/mcp-mode-3-enforcement-v1.md` §6, without
+ * touching the policy / approval / receipt pipeline above it.
+ *
+ * Why a proxy at all? Because changing a `mcp-server-command` config
+ * value is something every MCP-aware client already supports
+ * (Claude Desktop, mcp-cli, IDE integrations); changing the
+ * application's authorization model is not. The proxy is the
+ * "change your MCP endpoint" wedge — minimal developer friction,
+ * maximum coverage of the actual MCP-call surface.
+ */
+
+import { governMCPServer } from "@strixgov/mcp-adapter";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+/**
+ * Start the proxy. Returns a handle with a `stop()` method so callers
+ * (CLI, tests) can shut it down cleanly.
+ *
+ * @param {{
+ *   upstream: { command: string, args?: string[], env?: Record<string, string> },
+ *   serverId?: string,
+ *   capabilities?: Array<object>,
+ *   policy?: object,
+ *   approval?: object,
+ *   storagePath?: string,
+ *   signingKey?: object,
+ *   connectedMode?: object,
+ *   onReceipt?: (receipt: object) => void,
+ *   onAudit?: (event: { kind: string, detail: object }) => void,
+ *   transport?: { kind: "stdio" } | { kind: "test", server: object, client: object },
+ * }} opts
+ * @returns {Promise<{ stop: () => Promise<void>, gateway: object, signingKey: object }>}
+ */
+export async function startProxy(opts) {
+  if (!opts) {
+    throw new TypeError("startProxy: opts is required");
+  }
+  const serverId = opts.serverId ?? "proxy";
+  const transportKind = opts.transport?.kind ?? "stdio";
+  // In real (stdio) mode opts.upstream.command is required; in test mode the
+  // caller supplies a pre-connected upstream client instead.
+  if (transportKind === "stdio") {
+    if (!opts.upstream || typeof opts.upstream.command !== "string") {
+      throw new TypeError("startProxy: opts.upstream.command is required for stdio mode");
+    }
+  }
+
+  // ─── 1. Connect to the upstream MCP server ─────────────────────────────────
+  // Test mode lets callers pre-build the upstream client (e.g. with an
+  // InMemoryTransport pair) so the proxy can be exercised end-to-end
+  // without spawning a real subprocess.
+  let upstreamClient;
+  if (transportKind === "test" && opts.transport.upstreamClient) {
+    upstreamClient = opts.transport.upstreamClient;
+    audit(opts, { kind: "upstream.connected", detail: { command: "(test mode)" } });
+  } else {
+    upstreamClient = new Client(
+      { name: `strix-proxy:${serverId}`, version: "0.1.0" },
+      { capabilities: {} },
+    );
+    const upstreamTransport = new StdioClientTransport({
+      command: opts.upstream.command,
+      args: opts.upstream.args ?? [],
+      env: opts.upstream.env ?? process.env,
+    });
+    await upstreamClient.connect(upstreamTransport);
+    audit(opts, { kind: "upstream.connected", detail: { command: opts.upstream.command } });
+  }
+
+  // ─── 2. Build the iface mcp-adapter expects ───────────────────────────────
+  const upstreamIface = buildUpstreamIface(upstreamClient, serverId);
+
+  // ─── 3. Wrap with governMCPServer (Mode 1/2) ───────────────────────────────
+  const governed = governMCPServer(upstreamIface, {
+    serverId,
+    capabilities: opts.capabilities,
+    policy: opts.policy ?? { default: "DENY" },
+    approval: opts.approval ?? { enabled: false },
+    storagePath: opts.storagePath,
+    signingKey: opts.signingKey,
+    connectedMode: opts.connectedMode,
+  });
+
+  if (typeof opts.onReceipt === "function") {
+    governed.gateway.on("receipt", opts.onReceipt);
+  }
+
+  // ─── 4. Expose the proxy as an MCP server toward the consumer ──────────────
+  const proxyServer = new Server(
+    { name: `strix-proxy:${serverId}`, version: "0.1.0" },
+    { capabilities: { tools: {} } },
+  );
+
+  proxyServer.setRequestHandler(ListToolsRequestSchema, async () => {
+    const tools = await governed.listTools();
+    // governed.listTools returns [{ name, description? }]; the MCP wire
+    // spec expects { tools: [{ name, description, inputSchema }] }.
+    // Re-fetch the full descriptors from the upstream so callers see
+    // the original argument shapes — governance doesn't reshape tools.
+    const upstream = await upstreamClient.listTools();
+    const upstreamByName = new Map(upstream.tools.map((t) => [t.name, t]));
+    return {
+      tools: tools.map((t) => upstreamByName.get(t.name) ?? { name: t.name }),
+    };
+  });
+
+  proxyServer.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    // Forward actor context if the client put it in _meta — this is how
+    // mcp-aware clients attribute calls to a specific agent identity.
+    const ctx = {
+      actorId: request.params?._meta?.strix_actor_id,
+      actorRole: request.params?._meta?.strix_actor_role,
+    };
+    try {
+      const result = await governed.callTool(name, args, ctx);
+      return result;
+    } catch (err) {
+      audit(opts, { kind: "call.denied", detail: { name, code: err?.code, message: err?.message } });
+      // Re-throw as an MCP-shaped error so the consumer's client sees
+      // a structured failure rather than a generic exception.
+      throw err;
+    }
+  });
+
+  // ─── 5. Connect the proxy server to its outbound transport ─────────────────
+  let proxyTransport;
+  if (transportKind === "stdio") {
+    proxyTransport = new StdioServerTransport();
+    await proxyServer.connect(proxyTransport);
+    audit(opts, { kind: "proxy.listening", detail: { serverId, transport: "stdio" } });
+  } else if (transportKind === "test") {
+    // Test-mode: caller supplies the proxy-server-side Transport
+    // (typically an InMemoryTransport linked to a paired transport
+    // they hand to a test Client). Lets the test suite drive the
+    // proxy end-to-end without spawning child processes.
+    if (!opts.transport.serverTransport) {
+      throw new TypeError("startProxy: transport.kind='test' requires transport.serverTransport");
+    }
+    proxyTransport = opts.transport.serverTransport;
+    await proxyServer.connect(proxyTransport);
+    audit(opts, { kind: "proxy.listening", detail: { serverId, transport: "test" } });
+  } else {
+    throw new TypeError(`startProxy: unknown transport kind '${transportKind}'`);
+  }
+
+  return {
+    gateway: governed.gateway,
+    signingKey: governed.signingKey,
+    async stop() {
+      try { await proxyServer.close(); } catch { /* best-effort */ }
+      try { await upstreamClient.close(); } catch { /* best-effort */ }
+      audit(opts, { kind: "proxy.stopped", detail: { serverId } });
+    },
+  };
+}
+
+// ─── internal ─────────────────────────────────────────────────────────
+
+/**
+ * The single seam where Mode 3 enforcement will attach in v0.2.0.
+ * Today this just forwards to the upstream client. In v0.2.0 a
+ * `mode: "enforced"` option will mint an execution_authorization_v1
+ * token at this layer and attach it via the chosen transport
+ * (header for HTTP upstream, _meta for stdio first-party MCP) per
+ * docs/architecture/mcp-mode-3-enforcement-v1.md §6.
+ */
+function buildUpstreamIface(client, serverId) {
+  return {
+    serverId,
+    listTools: async () => {
+      const out = await client.listTools();
+      return out.tools.map((t) => ({ name: t.name, description: t.description }));
+    },
+    handler: async (name, args) => {
+      return await client.callTool({ name, arguments: args ?? {} });
+    },
+  };
+}
+
+function audit(opts, event) {
+  if (typeof opts.onAudit === "function") {
+    try { opts.onAudit(event); } catch { /* swallow audit-handler errors */ }
+  }
+}

package/src/types.d.ts

@@ -0,0 +1,52 @@
+/**
+ * TypeScript surface for @strixgov/mcp-proxy.
+ */
+
+export interface UpstreamConfig {
+  command: string;
+  args?: string[];
+  env?: Record<string, string>;
+}
+
+export interface ProxyOptions {
+  upstream: UpstreamConfig;
+  serverId?: string;
+  capabilities?: Array<{ id: string; name: string; risk: string; mode: string; description?: string }>;
+  policy?: {
+    rules?: Record<string, "ALLOW" | "DENY" | "APPROVAL_REQUIRED">;
+    riskOverrides?: Record<string, "ALLOW" | "DENY" | "APPROVAL_REQUIRED">;
+    default?: "ALLOW" | "DENY";
+  };
+  approval?: {
+    enabled?: boolean;
+    prompt?: (cap: object, invocation: object, opts: object) => Promise<{ approved: boolean; approver?: string }>;
+    timeoutMs?: number;
+  };
+  storagePath?: string;
+  signingKey?: object;
+  connectedMode?: { kernelUrl: string; apiKey: string; tenantId: string };
+  onReceipt?: (receipt: object) => void;
+  onAudit?: (event: { kind: string; detail: object }) => void;
+  transport?: { kind: "stdio" } | { kind: "test"; [k: string]: unknown };
+}
+
+export interface ProxyHandle {
+  stop(): Promise<void>;
+  gateway: object;
+  signingKey: object;
+}
+
+export interface ProxyConfigFile {
+  serverId?: string;
+  upstream: UpstreamConfig;
+  capabilities?: string | Array<object>;
+  policy?: ProxyOptions["policy"];
+  approval?: ProxyOptions["approval"];
+  storagePath?: string;
+}
+
+export declare function startProxy(opts: ProxyOptions): Promise<ProxyHandle>;
+export declare function loadConfig(filePath: string): Promise<ProxyConfigFile>;
+export declare function resolveCapabilities(
+  capabilities: string | Array<object> | undefined,
+): Promise<Array<object> | undefined>;