@veridocs/mcp 0.1.0

package/dist/index.mjs

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+#!/usr/bin/env node
+
+// src/index.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+var API_KEY = process.env.VERIDOCS_API_KEY ?? "";
+var BASE_URL = (process.env.VERIDOCS_API_URL ?? "https://veridocs.dev").replace(/\/$/, "");
+if (!API_KEY) {
+  process.stderr.write("[veridocs-mcp] VERIDOCS_API_KEY is not set. Get a key at veridocs.dev\n");
+  process.exit(1);
+}
+async function vd(method, path, body) {
+  const res = await fetch(`${BASE_URL}${path}`, {
+    method,
+    headers: {
+      "Content-Type": "application/json",
+      "x-api-key": API_KEY
+    },
+    body: body ? JSON.stringify(body) : void 0
+  });
+  const text = await res.text();
+  let json;
+  try {
+    json = JSON.parse(text);
+  } catch {
+    throw new Error(`VeriDOCS API returned non-JSON (${res.status}): ${text.slice(0, 200)}`);
+  }
+  if (!res.ok) {
+    const err = json;
+    throw new Error(`VeriDOCS API error ${res.status}: ${err.error ?? err.message ?? text.slice(0, 200)}`);
+  }
+  return json;
+}
+var tools = [
+  {
+    name: "vd_evaluate",
+    description: "Submit an AI agent action proposal to VeriDOCS for governance evaluation. Returns a cryptographically-signed receipt with a verdict of EXECUTE, BLOCK, REVIEW, or SHADOW. Use this before any consequential agent action (sending emails, modifying data, making payments, etc.).",
+    inputSchema: {
+      type: "object",
+      required: ["action_type", "agent_id"],
+      properties: {
+        action_type: {
+          type: "string",
+          description: "Semantic name for the action (e.g. 'send_email', 'delete_record', 'make_payment')"
+        },
+        agent_id: {
+          type: "string",
+          description: "Identifier for the AI agent making the proposal"
+        },
+        parameters: {
+          type: "object",
+          description: "Action-specific parameters as a JSON object"
+        },
+        idempotency_key: {
+          type: "string",
+          description: "Optional unique key \u2014 same key returns the cached receipt"
+        },
+        guardian_timeout_policy: {
+          type: "string",
+          enum: ["fail_closed", "fail_open"],
+          description: "What to do if the Guardian times out. Default: fail_closed (block the action)"
+        }
+      }
+    }
+  },
+  {
+    name: "vd_get_receipt",
+    description: "Retrieve a VeriDOCS audit receipt by its UUID. Returns the full receipt including verdict, signature, and policy pack hash.",
+    inputSchema: {
+      type: "object",
+      required: ["receipt_id"],
+      properties: {
+        receipt_id: { type: "string", description: "UUID of the receipt to retrieve" }
+      }
+    }
+  },
+  {
+    name: "vd_verify_receipt",
+    description: "Cryptographically verify a VeriDOCS receipt. Checks the Ed25519 signature and confirms the signing key is ACTIVE. Returns valid: true/false with a reason.",
+    inputSchema: {
+      type: "object",
+      required: ["receipt_id"],
+      properties: {
+        receipt_id: { type: "string", description: "UUID of the receipt to verify" }
+      }
+    }
+  },
+  {
+    name: "vd_list_receipts",
+    description: "List recent VeriDOCS audit receipts for the authenticated tenant. Supports filtering by agent and verdict.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit: { type: "number", description: "Number of receipts to return (max 100, default 20)" },
+        offset: { type: "number", description: "Pagination offset (default 0)" },
+        agent_id: { type: "string", description: "Filter by agent ID" },
+        verdict: { type: "string", enum: ["EXECUTE", "BLOCK", "REVIEW", "SHADOW"], description: "Filter by verdict" }
+      }
+    }
+  },
+  {
+    name: "vd_usage",
+    description: "Get current VeriDOCS quota usage \u2014 receipts used, receipts remaining, credit balance, billing cycle dates, and plan tier.",
+    inputSchema: { type: "object", properties: {} }
+  },
+  {
+    name: "vd_list_policy_packs",
+    description: "List all governance policy packs for the authenticated tenant, including which one is currently active.",
+    inputSchema: { type: "object", properties: {} }
+  }
+];
+var server = new Server(
+  { name: "veridocs", version: "0.1.0" },
+  { capabilities: { tools: {} } }
+);
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const { name, arguments: args = {} } = req.params;
+  try {
+    switch (name) {
+      case "vd_evaluate": {
+        const result = await vd("POST", "/v1/evaluate", {
+          action_type: args.action_type,
+          agent_id: args.agent_id,
+          parameters: args.parameters ?? {},
+          idempotency_key: args.idempotency_key,
+          guardian_timeout_policy: args.guardian_timeout_policy ?? "fail_closed"
+        });
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      }
+      case "vd_get_receipt": {
+        const result = await vd("GET", `/v1/receipts/${args.receipt_id}`);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      }
+      case "vd_verify_receipt": {
+        const result = await vd("GET", `/v1/receipts/${args.receipt_id}/verify`);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      }
+      case "vd_list_receipts": {
+        const params = new URLSearchParams();
+        if (args.limit) params.set("limit", String(args.limit));
+        if (args.offset) params.set("offset", String(args.offset));
+        if (args.agent_id) params.set("agent_id", String(args.agent_id));
+        if (args.verdict) params.set("verdict", String(args.verdict));
+        const result = await vd("GET", `/v1/receipts?${params}`);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      }
+      case "vd_usage": {
+        const result = await vd("GET", "/v1/usage");
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      }
+      case "vd_list_policy_packs": {
+        const result = await vd("GET", "/v1/policy-packs");
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      }
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
+  }
+});
+var transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@veridocs/mcp",
+  "version": "0.1.0",
+  "description": "VeriDOCS MCP server — drop cryptographic AI governance into Claude Desktop, Cursor, Cline, or any MCP-aware host.",
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "bin": {
+    "veridocs-mcp": "./dist/index.mjs"
+  },
+  "exports": {
+    ".": {
+      "types":  "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": ["dist", "src"],
+  "scripts": {
+    "build": "tsup"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": { "node": ">=18" },
+  "license": "MIT",
+  "keywords": ["veridocs", "mcp", "model-context-protocol", "ai-governance", "audit", "receipts", "claude", "cursor"]
+}

package/src/index.ts

@@ -0,0 +1,210 @@
+#!/usr/bin/env node
+/**
+ * VeriDOCS MCP Server
+ *
+ * Drop AI governance into any MCP-aware host (Claude Desktop, Cursor, Cline, etc.)
+ * with a single config entry.
+ *
+ * Quick start — Claude Desktop (~/.claude/claude_desktop_config.json):
+ * {
+ *   "mcpServers": {
+ *     "veridocs": {
+ *       "command": "npx",
+ *       "args": ["-y", "@veridocs/mcp"],
+ *       "env": {
+ *         "VERIDOCS_API_KEY": "vdk_...",
+ *         "VERIDOCS_API_URL": "https://veridocs.dev"
+ *       }
+ *     }
+ *   }
+ * }
+ *
+ * Environment variables:
+ *   VERIDOCS_API_KEY  — required; your vdk_... key (get one at veridocs.dev)
+ *   VERIDOCS_API_URL  — optional; defaults to https://veridocs.dev
+ */
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  type Tool,
+} from "@modelcontextprotocol/sdk/types.js";
+
+const API_KEY = process.env.VERIDOCS_API_KEY ?? "";
+const BASE_URL = (process.env.VERIDOCS_API_URL ?? "https://veridocs.dev").replace(/\/$/, "");
+
+if (!API_KEY) {
+  process.stderr.write("[veridocs-mcp] VERIDOCS_API_KEY is not set. Get a key at veridocs.dev\n");
+  process.exit(1);
+}
+
+async function vd<T = unknown>(
+  method: "GET" | "POST",
+  path: string,
+  body?: unknown,
+): Promise<T> {
+  const res = await fetch(`${BASE_URL}${path}`, {
+    method,
+    headers: {
+      "Content-Type": "application/json",
+      "x-api-key": API_KEY,
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const text = await res.text();
+  let json: T;
+  try { json = JSON.parse(text) as T; }
+  catch { throw new Error(`VeriDOCS API returned non-JSON (${res.status}): ${text.slice(0, 200)}`); }
+  if (!res.ok) {
+    const err = json as Record<string, string>;
+    throw new Error(`VeriDOCS API error ${res.status}: ${err.error ?? err.message ?? text.slice(0, 200)}`);
+  }
+  return json;
+}
+
+const tools: Tool[] = [
+  {
+    name: "vd_evaluate",
+    description:
+      "Submit an AI agent action proposal to VeriDOCS for governance evaluation. " +
+      "Returns a cryptographically-signed receipt with a verdict of EXECUTE, BLOCK, REVIEW, or SHADOW. " +
+      "Use this before any consequential agent action (sending emails, modifying data, making payments, etc.).",
+    inputSchema: {
+      type: "object",
+      required: ["action_type", "agent_id"],
+      properties: {
+        action_type: {
+          type: "string",
+          description: "Semantic name for the action (e.g. 'send_email', 'delete_record', 'make_payment')",
+        },
+        agent_id: {
+          type: "string",
+          description: "Identifier for the AI agent making the proposal",
+        },
+        parameters: {
+          type: "object",
+          description: "Action-specific parameters as a JSON object",
+        },
+        idempotency_key: {
+          type: "string",
+          description: "Optional unique key — same key returns the cached receipt",
+        },
+        guardian_timeout_policy: {
+          type: "string",
+          enum: ["fail_closed", "fail_open"],
+          description: "What to do if the Guardian times out. Default: fail_closed (block the action)",
+        },
+      },
+    },
+  },
+  {
+    name: "vd_get_receipt",
+    description: "Retrieve a VeriDOCS audit receipt by its UUID. Returns the full receipt including verdict, signature, and policy pack hash.",
+    inputSchema: {
+      type: "object",
+      required: ["receipt_id"],
+      properties: {
+        receipt_id: { type: "string", description: "UUID of the receipt to retrieve" },
+      },
+    },
+  },
+  {
+    name: "vd_verify_receipt",
+    description:
+      "Cryptographically verify a VeriDOCS receipt. Checks the Ed25519 signature and confirms " +
+      "the signing key is ACTIVE. Returns valid: true/false with a reason.",
+    inputSchema: {
+      type: "object",
+      required: ["receipt_id"],
+      properties: {
+        receipt_id: { type: "string", description: "UUID of the receipt to verify" },
+      },
+    },
+  },
+  {
+    name: "vd_list_receipts",
+    description: "List recent VeriDOCS audit receipts for the authenticated tenant. Supports filtering by agent and verdict.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit:    { type: "number", description: "Number of receipts to return (max 100, default 20)" },
+        offset:   { type: "number", description: "Pagination offset (default 0)" },
+        agent_id: { type: "string", description: "Filter by agent ID" },
+        verdict:  { type: "string", enum: ["EXECUTE", "BLOCK", "REVIEW", "SHADOW"], description: "Filter by verdict" },
+      },
+    },
+  },
+  {
+    name: "vd_usage",
+    description:
+      "Get current VeriDOCS quota usage — receipts used, receipts remaining, credit balance, " +
+      "billing cycle dates, and plan tier.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "vd_list_policy_packs",
+    description: "List all governance policy packs for the authenticated tenant, including which one is currently active.",
+    inputSchema: { type: "object", properties: {} },
+  },
+];
+
+const server = new Server(
+  { name: "veridocs", version: "0.1.0" },
+  { capabilities: { tools: {} } },
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const { name, arguments: args = {} } = req.params;
+
+  try {
+    switch (name) {
+      case "vd_evaluate": {
+        const result = await vd("POST", "/v1/evaluate", {
+          action_type: args.action_type,
+          agent_id:    args.agent_id,
+          parameters:  args.parameters ?? {},
+          idempotency_key:          args.idempotency_key,
+          guardian_timeout_policy:  args.guardian_timeout_policy ?? "fail_closed",
+        });
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      }
+      case "vd_get_receipt": {
+        const result = await vd("GET", `/v1/receipts/${args.receipt_id}`);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      }
+      case "vd_verify_receipt": {
+        const result = await vd("GET", `/v1/receipts/${args.receipt_id}/verify`);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      }
+      case "vd_list_receipts": {
+        const params = new URLSearchParams();
+        if (args.limit)    params.set("limit",    String(args.limit));
+        if (args.offset)   params.set("offset",   String(args.offset));
+        if (args.agent_id) params.set("agent_id", String(args.agent_id));
+        if (args.verdict)  params.set("verdict",  String(args.verdict));
+        const result = await vd("GET", `/v1/receipts?${params}`);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      }
+      case "vd_usage": {
+        const result = await vd("GET", "/v1/usage");
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      }
+      case "vd_list_policy_packs": {
+        const result = await vd("GET", "/v1/policy-packs");
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      }
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+    }
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
+  }
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);