@auctra/mcp-gateway 0.1.1

package/README.md

@@ -0,0 +1,39 @@
+# @auctra/mcp-gateway
+
+Stage 0 MCP gateway adapter. Wrap MCP tool calls with Auctra `action.execute` before execution.
+
+```ts
+import { Auctra } from "@auctra/sdk";
+import { gateMcpToolCall, withAuctraGate } from "@auctra/mcp-gateway";
+
+const client = new Auctra({ apiKey: process.env.AUCTRA_API_KEY! });
+
+await gateMcpToolCall({
+  client,
+  agentId: "agent-uuid",
+  toolName: "send_email",
+  args: { to: "vendor@example.com" },
+});
+
+const sendEmail = withAuctraGate({
+  client,
+  agentId: "agent-uuid",
+  toolName: "send_email",
+  execute: async (args) => mailer.send(args),
+});
+```
+
+Blocked or approval-required tool calls throw `McpToolBlockedError` with the decision evidence hash when present.
+
+## Stdio MCP server
+
+Run the package as a real MCP stdio server:
+
+```bash
+AUCTRA_API_KEY=... AUCTRA_AGENT_ID=agent-uuid npx auctra-mcp-gateway
+```
+
+Exposed tools:
+
+- `gate_tool_call`
+- `verify_audit_chain`

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@auctra/mcp-gateway",
+  "version": "0.1.1",
+  "description": "Stage 0 MCP gateway adapter — gate MCP tool calls through Auctra action.execute",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "bin": {
+    "auctra-mcp-gateway": "src/server.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node --input-type=module -e \"import('./src/index.js').then((m) => { if (typeof m.gateMcpToolCall !== 'function') throw new Error('gateMcpToolCall missing'); console.log('mcp-gateway build ok'); })\"",
+    "test": "npm run build && node --test test/*.test.mjs"
+  },
+  "auctra": {
+    "role": "implementation",
+    "note": "Single MCP authorization implementation. @auctra/mcp re-exports this package only."
+  },
+  "keywords": [
+    "auctra",
+    "mcp",
+    "authority",
+    "delegation"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/index.js

@@ -0,0 +1,71 @@
+export class McpToolBlockedError extends Error {
+  constructor(message, decision, evidence) {
+    super(message);
+    this.name = "McpToolBlockedError";
+    this.decision = decision;
+    this.evidence = evidence;
+  }
+}
+
+function resolveActionType(input) {
+  return input.actionType ?? input.actionTypeMap?.[input.toolName] ?? "execute_tool";
+}
+
+function evidenceIdFromResult(result) {
+  return result.evidence_payload?.evidence_id ?? result.action_request_id ?? null;
+}
+
+/** Provenance for a tool/MCP result — attach on the next consequential action.execute. */
+export function declareToolResponseInput(input) {
+  return {
+    source: `mcp:${input.toolName}`,
+    source_type: "mcp_tool_response",
+    trust_level: "untrusted",
+    authority: "none",
+    content_hash: input.contentHash,
+    received_at: new Date().toISOString(),
+    source_id: input.sourceId,
+  };
+}
+
+export async function gateMcpToolCall(input) {
+  const result = await input.client.action.execute({
+    agentId: input.agentId,
+    actionType: resolveActionType(input),
+    payload: {
+      tool: input.toolName,
+      arguments: input.args ?? {},
+    },
+    claimedIntentId: input.claimedIntentId,
+    intentAnchorToken: input.intentAnchorToken,
+    action: {
+      target: `mcp:${input.toolName}`,
+      description: `MCP tool ${input.toolName}`,
+      metadata: {
+        inputs: [
+          {
+            source: `mcp:${input.toolName}:invocation`,
+            source_type: "mcp_tool_response",
+            trust_level: "untrusted",
+            authority: "none",
+          },
+        ],
+      },
+    },
+  });
+
+  if (result.decision !== "allowed") {
+    const evidenceId = evidenceIdFromResult(result);
+    const message = evidenceId ? `${result.reason} (evidence: ${evidenceId})` : result.reason;
+    throw new McpToolBlockedError(message, result.decision, result.evidence);
+  }
+
+  return result;
+}
+
+export function withAuctraGate(input) {
+  return async (args) => {
+    await gateMcpToolCall({ ...input, args });
+    return input.execute(args);
+  };
+}

package/src/index.ts

@@ -0,0 +1,137 @@
+export type ExecuteActionClient = {
+  action: {
+    execute(input: {
+      agentId: string;
+      actionType: string;
+      payload?: Record<string, unknown>;
+      claimedIntentId?: string;
+      intentAnchorToken?: string;
+      action?: {
+        target?: string;
+        description?: string;
+        riskLevel?: string;
+        metadata?: Record<string, unknown>;
+      };
+    }): Promise<{
+      decision: "allowed" | "blocked" | "require_approval";
+      reason: string;
+      action_request_id?: string;
+      evidence?: {
+        format: string;
+        payload_hash: string;
+        signed: boolean;
+      };
+      evidence_payload?: { evidence_id?: string };
+    }>;
+  };
+};
+
+/** @deprecated Use ExecuteActionClient — kept as type alias for migration notes only */
+export type EvaluateActionClient = ExecuteActionClient;
+
+export type McpToolGateInput = {
+  client: ExecuteActionClient;
+  agentId: string;
+  toolName: string;
+  args?: Record<string, unknown>;
+  /** Explicit action type override (wins over actionTypeMap). */
+  actionType?: string;
+  /** Optional map from MCP tool name → Auctra action_type. */
+  actionTypeMap?: Record<string, string>;
+  claimedIntentId?: string;
+  intentAnchorToken?: string;
+};
+
+export class McpToolBlockedError extends Error {
+  readonly decision: "blocked" | "require_approval";
+  readonly evidence?: Awaited<ReturnType<ExecuteActionClient["action"]["execute"]>>["evidence"];
+
+  constructor(
+    message: string,
+    decision: "blocked" | "require_approval",
+    evidence?: Awaited<ReturnType<ExecuteActionClient["action"]["execute"]>>["evidence"],
+  ) {
+    super(message);
+    this.name = "McpToolBlockedError";
+    this.decision = decision;
+    this.evidence = evidence;
+  }
+}
+
+function resolveActionType(input: McpToolGateInput) {
+  return input.actionType ?? input.actionTypeMap?.[input.toolName] ?? "execute_tool";
+}
+
+function evidenceIdFromResult(
+  result: Awaited<ReturnType<ExecuteActionClient["action"]["execute"]>>,
+) {
+  return result.evidence_payload?.evidence_id ?? result.action_request_id ?? null;
+}
+
+/**
+ * Provenance for a tool/MCP result — attach on the *next* consequential
+ * action.execute so Engine 03 treats the output as untrusted evidence.
+ */
+export function declareToolResponseInput(input: {
+  toolName: string;
+  contentHash?: string;
+  sourceId?: string;
+}) {
+  return {
+    source: `mcp:${input.toolName}`,
+    source_type: "mcp_tool_response" as const,
+    trust_level: "untrusted" as const,
+    authority: "none" as const,
+    content_hash: input.contentHash,
+    received_at: new Date().toISOString(),
+    source_id: input.sourceId,
+  };
+}
+
+/** Gate an MCP tool invocation through Auctra action.execute (Authority Runtime). */
+export async function gateMcpToolCall(input: McpToolGateInput) {
+  const result = await input.client.action.execute({
+    agentId: input.agentId,
+    actionType: resolveActionType(input),
+    payload: {
+      tool: input.toolName,
+      arguments: input.args ?? {},
+    },
+    claimedIntentId: input.claimedIntentId,
+    intentAnchorToken: input.intentAnchorToken,
+    action: {
+      target: `mcp:${input.toolName}`,
+      description: `MCP tool ${input.toolName}`,
+      metadata: {
+        inputs: [
+          {
+            source: `mcp:${input.toolName}:invocation`,
+            source_type: "mcp_tool_response",
+            trust_level: "untrusted",
+            authority: "none",
+          },
+        ],
+      },
+    },
+  });
+
+  if (result.decision !== "allowed") {
+    const evidenceId = evidenceIdFromResult(result);
+    const message = evidenceId ? `${result.reason} (evidence: ${evidenceId})` : result.reason;
+    throw new McpToolBlockedError(message, result.decision, result.evidence);
+  }
+
+  return result;
+}
+
+/** Wrap a tool executor so every call is executed under Auctra authority first. */
+export function withAuctraGate<TArgs extends Record<string, unknown>, TResult>(
+  input: McpToolGateInput & {
+    execute: (args: TArgs) => Promise<TResult> | TResult;
+  },
+) {
+  return async (args: TArgs) => {
+    await gateMcpToolCall({ ...input, args });
+    return input.execute(args);
+  };
+}

package/src/server.js

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+import { gateMcpToolCall } from "./index.js";
+
+const API_KEY = process.env.AUCTRA_API_KEY;
+const BASE_URL = (process.env.AUCTRA_BASE_URL ?? "https://app.auctra.tech").replace(/\/$/, "");
+const DEFAULT_AGENT_ID = process.env.AUCTRA_AGENT_ID ?? null;
+
+function writeMessage(message) {
+  const body = Buffer.from(JSON.stringify(message), "utf8");
+  process.stdout.write(`Content-Length: ${body.length}\r\n\r\n`);
+  process.stdout.write(body);
+}
+
+async function auctraRequest(path, body) {
+  if (!API_KEY) {
+    throw new Error("AUCTRA_API_KEY is required for the MCP gateway server");
+  }
+
+  const response = await fetch(`${BASE_URL}${path}`, {
+    method: "POST",
+    headers: {
+      authorization: `Bearer ${API_KEY}`,
+      "content-type": "application/json",
+    },
+    body: JSON.stringify(body),
+  });
+  const payload = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    throw new Error(
+      typeof payload.error === "string" ? payload.error : `Auctra API error (${response.status})`,
+    );
+  }
+  return payload;
+}
+
+const client = {
+  action: {
+    execute(input) {
+      return auctraRequest("/v1/actions/execute", {
+        agent_id: input.agentId,
+        action_type: input.actionType,
+        payload: input.payload ?? {},
+        dry_run: false,
+      });
+    },
+  },
+};
+
+async function handleRpc(message) {
+  if (message.method === "initialize") {
+    return {
+      protocolVersion: "2025-06-18",
+      capabilities: { tools: {} },
+      serverInfo: { name: "auctra-mcp-gateway", version: "0.1.0" },
+    };
+  }
+
+  if (message.method === "tools/list") {
+    return {
+      tools: [
+        {
+          name: "gate_tool_call",
+          description: "Gate an MCP tool invocation through Auctra authority evaluation.",
+          inputSchema: {
+            type: "object",
+            required: ["tool_name"],
+            properties: {
+              agent_id: { type: "string", description: "Optional override for AUCTRA_AGENT_ID" },
+              tool_name: { type: "string" },
+              action_type: { type: "string", default: "execute_tool" },
+              args: { type: "object", additionalProperties: true },
+            },
+          },
+        },
+        {
+          name: "verify_audit_chain",
+          description:
+            "Verify the Auctra hash-chained audit ledger for the current API key organization.",
+          inputSchema: { type: "object", properties: {} },
+        },
+      ],
+    };
+  }
+
+  if (message.method === "tools/call") {
+    const { name, arguments: args = {} } = message.params ?? {};
+    if (name === "gate_tool_call") {
+      const agentId = args.agent_id ?? DEFAULT_AGENT_ID;
+      if (!agentId) throw new Error("agent_id is required or set AUCTRA_AGENT_ID");
+      const result = await gateMcpToolCall({
+        client,
+        agentId,
+        toolName: args.tool_name,
+        actionType: args.action_type,
+        args: args.args ?? {},
+      });
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(result),
+          },
+        ],
+      };
+    }
+
+    if (name === "verify_audit_chain") {
+      if (!API_KEY) throw new Error("AUCTRA_API_KEY is required for audit verification");
+      const response = await fetch(`${BASE_URL}/v1/audit-events/verify`, {
+        headers: { authorization: `Bearer ${API_KEY}` },
+      });
+      const payload = await response.json().catch(() => ({}));
+      if (!response.ok) {
+        throw new Error(
+          typeof payload.error === "string"
+            ? payload.error
+            : `Auctra API error (${response.status})`,
+        );
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(payload),
+          },
+        ],
+      };
+    }
+
+    throw new Error(`Unknown tool: ${name}`);
+  }
+
+  return null;
+}
+
+let buffer = Buffer.alloc(0);
+process.stdin.on("data", async (chunk) => {
+  buffer = Buffer.concat([buffer, chunk]);
+
+  while (true) {
+    const headerEnd = buffer.indexOf("\r\n\r\n");
+    if (headerEnd === -1) break;
+
+    const headerText = buffer.slice(0, headerEnd).toString("utf8");
+    const match = headerText.match(/Content-Length:\s*(\d+)/i);
+    if (!match) {
+      buffer = Buffer.alloc(0);
+      break;
+    }
+
+    const length = Number(match[1]);
+    const total = headerEnd + 4 + length;
+    if (buffer.length < total) break;
+
+    const raw = buffer.slice(headerEnd + 4, total).toString("utf8");
+    buffer = buffer.slice(total);
+
+    const message = JSON.parse(raw);
+    if (!("id" in message) || !message.method) continue;
+
+    try {
+      const result = await handleRpc(message);
+      writeMessage({ jsonrpc: "2.0", id: message.id, result });
+    } catch (error) {
+      writeMessage({
+        jsonrpc: "2.0",
+        id: message.id,
+        error: {
+          code: -32000,
+          message: error instanceof Error ? error.message : "Unknown error",
+        },
+      });
+    }
+  }
+});