@vorim/mcp-server 1.1.3 → 1.1.5

package/build/index.js

@@ -21,6 +21,18 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
+// SECURITY: The MCP server uses a single process-wide Vorim API key
+// taken from VORIM_API_KEY at startup. The stdio transport between
+// the MCP host (e.g. Claude Desktop) and this process carries NO
+// per-call auth — every tool call is attributed to the configured
+// key. Two consequences:
+//   1. Scope the key tightly. The key's scopes (audit:read,
+//      audit:write, agent:write, etc.) determine which MCP tools
+//      will actually work; a least-privilege scoped key reduces
+//      blast radius if the host environment is compromised.
+//   2. Do not share a key across MCP installations. Each user /
+//      machine should mint its own key so revocation surgically
+//      kills exactly one installation.
 const API_KEY = process.env.VORIM_API_KEY || "";
 const BASE_URL = (process.env.VORIM_BASE_URL || "https://api.vorim.ai").replace(/\/$/, "");
 if (!API_KEY) {
@@ -28,16 +40,46 @@ if (!API_KEY) {
     process.exit(1);
 }
 // ─── HTTP Client ──────────────────────────────────────────────────────────
+// Read the package version once so the User-Agent string and the MCP
+// server's advertised version stay in sync with package.json.
+// require() works in the CommonJS build path; for the ESM-only build
+// we fall back to a constant that must match package.json.
+const MCP_VERSION = "1.1.5";
+/**
+ * URL-encode a user-supplied path segment. Agent ids, scopes, and
+ * chain ids all reach the API via path interpolation; raw slashes or
+ * other special characters from a misbehaving caller would otherwise
+ * either escape the intended route or be sent verbatim.
+ */
+function encId(s) {
+    return encodeURIComponent(s);
+}
 async function vorimRequest(method, path, body) {
     const response = await fetch(`${BASE_URL}/v1${path}`, {
         method,
         headers: {
             "Authorization": `Bearer ${API_KEY}`,
             "Content-Type": "application/json",
-            "User-Agent": "vorim-mcp-server/1.0.0",
+            "User-Agent": `vorim-mcp-server/${MCP_VERSION}`,
         },
         body: body ? JSON.stringify(body) : undefined,
     });
+    // Hand out clearer error messages for the common cases an MCP user
+    // will see. Auth: the API key is wrong or revoked. Scope: the key
+    // is missing the scope this route requires (e.g. audit:write).
+    if (response.status === 401) {
+        throw new Error("Vorim API key is invalid, revoked, or expired. Check VORIM_API_KEY.");
+    }
+    if (response.status === 403) {
+        const j = await response.json().catch(() => ({}));
+        const err = j.error;
+        const code = err?.code;
+        if (code === "INSUFFICIENT_SCOPE") {
+            throw new Error(err?.message ||
+                "Vorim API key is missing the scope required for this operation. Mint a new key with the required scope and update VORIM_API_KEY.");
+        }
+        throw new Error(err?.message || "Vorim API rejected with 403");
+    }
     const json = await response.json();
     if (!response.ok) {
         const err = json.error;
@@ -64,15 +106,16 @@ function text(data) {
 // ─── MCP Server ───────────────────────────────────────────────────────────
 const server = new McpServer({
     name: "vorim",
-    version: "1.0.0",
+    version: MCP_VERSION,
 });
 // ─── Health ───────────────────────────────────────────────────────────────
 server.registerTool("vorim_ping", {
     description: "Check Vorim AI API health and connectivity. Returns status, version, and service health.",
     inputSchema: {},
+    annotations: { readOnlyHint: true },
 }, async () => {
     const response = await fetch(`${BASE_URL}/health`, {
-        headers: { "User-Agent": "vorim-mcp-server/1.0.0" },
+        headers: { "User-Agent": `vorim-mcp-server/${MCP_VERSION}` },
     });
     const data = await response.json();
     return text(data);
@@ -96,7 +139,7 @@ server.registerTool("vorim_get_agent", {
         agent_id: z.string().describe("The agent identifier (e.g. agid_acme_a1b2c3d4)"),
     },
 }, async ({ agent_id }) => {
-    const result = await vorimGet(`/agents/${agent_id}`);
+    const result = await vorimGet(`/agents/${encId(agent_id)}`);
     return text(result);
 });
 server.registerTool("vorim_list_agents", {
@@ -129,7 +172,7 @@ server.registerTool("vorim_update_agent", {
     },
 }, async ({ agent_id, ...updates }) => {
     const body = Object.fromEntries(Object.entries(updates).filter(([, v]) => v !== undefined));
-    const result = await vorimPatch(`/agents/${agent_id}`, body);
+    const result = await vorimPatch(`/agents/${encId(agent_id)}`, body);
     return text(result);
 });
 server.registerTool("vorim_revoke_agent", {
@@ -137,8 +180,9 @@ server.registerTool("vorim_revoke_agent", {
     inputSchema: {
         agent_id: z.string().describe("The agent identifier to revoke"),
     },
+    annotations: { destructiveHint: true, idempotentHint: true, readOnlyHint: false },
 }, async ({ agent_id }) => {
-    const result = await vorimDelete(`/agents/${agent_id}`);
+    const result = await vorimDelete(`/agents/${encId(agent_id)}`);
     return text(result);
 });
 // ─── Permissions ──────────────────────────────────────────────────────────
@@ -148,8 +192,9 @@ server.registerTool("vorim_check_permission", {
         agent_id: z.string().describe("The agent identifier"),
         scope: z.string().describe("Permission scope to check (e.g. agent:read, agent:execute)"),
     },
+    annotations: { readOnlyHint: true },
 }, async ({ agent_id, scope }) => {
-    const result = await vorimPost(`/agents/${agent_id}/permissions/verify`, { scope });
+    const result = await vorimPost(`/agents/${encId(agent_id)}/permissions/verify`, { scope });
     return text(result);
 });
 server.registerTool("vorim_grant_permission", {
@@ -168,7 +213,7 @@ server.registerTool("vorim_grant_permission", {
     if (rate_limit_max && rate_limit_window) {
         body.rate_limit = { max: rate_limit_max, window: rate_limit_window };
     }
-    const result = await vorimPost(`/agents/${agent_id}/permissions`, body);
+    const result = await vorimPost(`/agents/${encId(agent_id)}/permissions`, body);
     return text(result);
 });
 server.registerTool("vorim_list_permissions", {
@@ -176,8 +221,9 @@ server.registerTool("vorim_list_permissions", {
     inputSchema: {
         agent_id: z.string().describe("The agent identifier"),
     },
+    annotations: { readOnlyHint: true },
 }, async ({ agent_id }) => {
-    const result = await vorimGet(`/agents/${agent_id}/permissions`);
+    const result = await vorimGet(`/agents/${encId(agent_id)}/permissions`);
     return text(result);
 });
 server.registerTool("vorim_revoke_permission", {
@@ -186,13 +232,14 @@ server.registerTool("vorim_revoke_permission", {
         agent_id: z.string().describe("The agent identifier"),
         scope: z.string().describe("Permission scope to revoke"),
     },
+    annotations: { destructiveHint: true, idempotentHint: true, readOnlyHint: false },
 }, async ({ agent_id, scope }) => {
-    const result = await vorimDelete(`/agents/${agent_id}/permissions/${scope}`);
+    const result = await vorimDelete(`/agents/${encId(agent_id)}/permissions/${encId(scope)}`);
     return text(result);
 });
 // ─── Audit ────────────────────────────────────────────────────────────────
 server.registerTool("vorim_emit_event", {
-    description: "Log an audit event for an agent action. Every agent action should be logged for compliance and traceability.",
+    description: "Log an audit event for an agent action. Every agent action should be logged for compliance and traceability. NOTE: events emitted via the MCP server are sent unsigned because the MCP server does not hold the agent's private key. For tamper-evident audit trails sign client-side via @vorim/sdk before emit.",
     inputSchema: {
         agent_id: z.string().describe("The agent that performed the action"),
         event_type: z.string().describe("Event category: tool_call, api_request, message_sent, permission_change, status_change"),
@@ -217,11 +264,12 @@ server.registerTool("vorim_emit_event", {
     return text(data);
 });
 server.registerTool("vorim_export_audit", {
-    description: "Export a signed audit bundle for a date range. Returns events with a SHA-256 manifest for tamper-proof verification.",
+    description: "Export a signed audit bundle for a date range. Returns events with a SHA-256 manifest for tamper-proof verification. Window must be <= 90 days; the server returns 400 if from > to or the range exceeds the cap. The returned bundle has up to 1,000,000 events; if truncated, the response carries `truncated: true` and the caller should re-export a narrower window.",
     inputSchema: {
-        from: z.string().describe("Start date (ISO 8601)"),
-        to: z.string().describe("End date (ISO 8601)"),
+        from: z.string().describe("Start date in ISO 8601 (e.g. 2026-06-01T00:00:00Z)"),
+        to: z.string().describe("End date in ISO 8601 (must be on or after `from`; window <= 90 days)"),
     },
+    annotations: { readOnlyHint: true },
 }, async ({ from, to }) => {
     const result = await vorimPost("/audit/export", { from, to });
     return text(result);
@@ -233,8 +281,8 @@ server.registerTool("vorim_verify_trust", {
         agent_id: z.string().describe("The agent identifier to verify"),
     },
 }, async ({ agent_id }) => {
-    const response = await fetch(`${BASE_URL}/v1/trust/verify/${agent_id}`, {
-        headers: { "User-Agent": "vorim-mcp-server/1.0.0" },
+    const response = await fetch(`${BASE_URL}/v1/trust/verify/${encId(agent_id)}`, {
+        headers: { "User-Agent": `vorim-mcp-server/${MCP_VERSION}` },
     });
     const json = await response.json();
     return text(json.data || json);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vorim/mcp-server",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "mcpName": "io.github.Kzino/vorim-mcp-server",
   "description": "MCP server for Vorim AI — AI agent identity, permissions, and audit trails",
   "type": "module",
@@ -9,6 +9,7 @@
   },
   "scripts": {
     "build": "tsc && chmod 755 build/index.js",
+    "prepublishOnly": "npm run build",
     "dev": "tsx src/index.ts"
   },
   "files": [