@vruum/mcp 0.14.0 → 0.15.1

package/README.md

@@ -75,6 +75,30 @@ Verify it works without configuring anything:
 npx -y @modelcontextprotocol/inspector --cli npx -y @vruum/mcp --method tools/list
 ```
 
+## Reliability diagnostics
+
+The bridge records content-free operational metadata: generated attempt IDs,
+the declared client family (Claude/Codex/ChatGPT/unknown), known tool name,
+start/outcome, timestamp and duration. It never records tool arguments, results,
+credentials, raw error text or conversations. The private outbox is under
+`~/.vruum/mcp-diagnostics/` (or `VRUUM_CONFIG_DIR`), separated by endpoint.
+
+Records survive bridge restarts and upload to that same endpoint's authenticated
+`/diagnostics` route after connectivity returns. Only a durable acknowledgement
+removes them. A restored connection drains the backlog in bounded batches.
+Transient failures retry once per minute while the bridge is alive; authentication
+or unsupported-endpoint responses wait for subsequent activity/startup.
+Uploads never follow redirects or transmit credentials over non-local HTTP.
+The queue retains at most 500 records per endpoint and reports overflow;
+disk failures print a coverage warning on stderr. Stdout remains MCP JSON-RPC.
+
+Missing-token, connection, protocol, cancellation, invalid-cursor and call
+failures are observable when the bridge runs. An offline machine cannot deliver
+reports until it reconnects, and an old installed package has none of these
+diagnostics. A bridge success means it received the remote result, not that the
+host used it correctly. Business calls are never automatically replayed after
+an ambiguous failure. Server and bridge evidence correlate by attempt ID.
+
 ## What you can ask for
 
 Once connected, these are ordinary requests to your agent:
@@ -198,7 +222,7 @@ npm test        # builds, then runs the black-box suite
 npm run typecheck
 ```
 
-Tests drive the built binary over stdin/stdout and assert **at the wire level** rather than through an SDK client — an SDK-mediated test hides protocol mistakes, since it will happily hand back a result object whether the server returned `result` or `error`. They cover the initialize handshake, credential-free listing, protocol-vs-execution error semantics, cursor rejection, capability declaration, and stdout hygiene.
+Tests drive the built binary over stdin/stdout and assert **at the wire level** rather than through an SDK client — an SDK-mediated test hides protocol mistakes, since it will happily hand back a result object whether the server returned `result` or `error`. They cover the initialize handshake (including negotiation down to older clients on earlier spec revisions), credential-free listing, protocol-vs-execution error semantics, cursor rejection, capability declaration, and stdout hygiene.
 
 **Issues and PRs are welcome here.** Maintainers apply accepted changes upstream in the monorepo and they flow back on the next sync — so a merged fix here may appear as part of a sync commit rather than your original one. Changes to `tools.json` must come from the generator, not by hand.
 

package/dist/diagnostics.js

@@ -0,0 +1,122 @@
+/** Bounded, private metadata outbox. Never stores tokens, arguments or results. */
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, readdir, rename, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+export function family(name) {
+    const value = (name ?? "").toLowerCase();
+    for (const prefix of ["claude", "codex", "chatgpt", "vruum-mcp-bridge"]) {
+        if (value === prefix || value.startsWith(prefix + "-") || value.startsWith(prefix + "/"))
+            return prefix;
+    }
+    return "unknown";
+}
+const MAX_PENDING = 500;
+const FILE = /^\d{13}-[0-9a-f-]{36}\.json$/;
+export class Diagnostics {
+    endpoint;
+    token;
+    tools;
+    getClient;
+    directory;
+    active = null;
+    writing = Promise.resolve();
+    retry = null;
+    constructor(root, endpoint, token, tools, getClient) {
+        this.endpoint = endpoint;
+        this.token = token;
+        this.tools = tools;
+        this.getClient = getClient;
+        // Keep environments separate without retaining the configured URL.
+        this.directory = join(root, "mcp-diagnostics", createHash("sha256").update(endpoint).digest("hex"));
+    }
+    async record(attempt, method, tool, outcome, duration = 0) {
+        const observation = {
+            id: randomUUID(), attempt_id: attempt, observed_at: new Date().toISOString(),
+            client: this.getClient(), method, tool_name: this.tools.has(tool) ? tool : "unknown",
+            outcome, duration_ms: Math.min(86400000, Math.max(0, Math.round(duration))),
+        };
+        this.writing = this.writing.then(async () => {
+            await mkdir(this.directory, { recursive: true, mode: 0o700 });
+            const names = (await readdir(this.directory)).filter((name) => FILE.test(name)).sort();
+            if (names.length >= MAX_PENDING) {
+                // Preserve an explicit loss marker, even when connectivity is absent.
+                await Promise.all(names.slice(0, 2).map((name) => unlink(join(this.directory, name)).catch(() => { })));
+                await this.write({ ...observation, id: randomUUID(), outcome: "queue_overflow" });
+                console.error("vruum-mcp diagnostics queue overflow; coverage is incomplete");
+            }
+            await this.write(observation);
+        }).catch(() => {
+            console.error("vruum-mcp diagnostics storage unavailable; coverage is incomplete");
+        });
+        await this.writing;
+    }
+    async write(observation) {
+        const destination = join(this.directory, `${Date.now()}-${observation.id}.json`);
+        const temporary = destination + ".tmp";
+        await writeFile(temporary, JSON.stringify(observation), { mode: 0o600, flag: "wx" });
+        await rename(temporary, destination);
+    }
+    flush() {
+        if (!this.token)
+            return Promise.resolve();
+        if (!this.active) {
+            if (this.retry)
+                clearTimeout(this.retry);
+            this.retry = null;
+            this.active = this.upload().finally(() => { this.active = null; });
+        }
+        return this.active;
+    }
+    retryLater() {
+        if (this.retry)
+            return;
+        this.retry = setTimeout(() => {
+            this.retry = null;
+            void this.flush();
+        }, 60000).unref();
+    }
+    async upload() {
+        try {
+            const url = new URL(this.endpoint);
+            // A diagnostic must not leak credentials through a redirect or downgrade.
+            if (url.protocol !== "https:" && !(url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)))
+                return;
+            url.pathname = url.pathname.replace(/\/+$/, "") + "/diagnostics";
+            url.search = "";
+            url.hash = "";
+            // Drain the bounded backlog without requiring another business call.
+            // Ten batches match the collector's per-minute allowance.
+            for (let batch = 0; batch < 10; batch++) {
+                await this.writing;
+                const names = (await readdir(this.directory).catch(() => []))
+                    .filter((name) => FILE.test(name)).sort().slice(0, 50);
+                if (!names.length)
+                    return;
+                const events = await Promise.all(names.map(async (name) => {
+                    const raw = await readFile(join(this.directory, name), "utf8");
+                    if (raw.length > 4096)
+                        throw new Error("invalid diagnostic");
+                    return JSON.parse(raw);
+                }));
+                const response = await fetch(url, {
+                    method: "POST", redirect: "error", signal: AbortSignal.timeout(2000),
+                    headers: { Authorization: `Bearer ${this.token}`, "Content-Type": "application/json", "X-Vruum-Client": this.getClient() },
+                    body: JSON.stringify({ events }),
+                });
+                if (response.status !== 200) {
+                    if (response.status === 429 || response.status >= 500)
+                        this.retryLater();
+                    return;
+                }
+                await Promise.all(names.map((name) => unlink(join(this.directory, name)).catch(() => { })));
+            }
+            if ((await readdir(this.directory)).some((name) => FILE.test(name)))
+                this.retryLater();
+        }
+        catch {
+            // Durable records stay for a later connection. Never log the exception:
+            // fetch errors and endpoint URLs can carry credentials.
+            this.retryLater();
+        }
+    }
+}

package/dist/index.js

@@ -29,15 +29,17 @@ import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, CallToolResultSchema, ErrorCode, ListToolsRequestSchema, McpError, } from "@modelcontextprotocol/sdk/types.js";
+import { randomUUID } from "node:crypto";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { Diagnostics, family } from "./diagnostics.js";
+import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
+import { ProtocolError, ProtocolErrorCode, Server, } from "@modelcontextprotocol/server";
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
 const DEFAULT_MCP_URL = "https://api.vruum.ai/mcp";
 // The SDK's per-request default is 60s, which real Vruum tools (research,
 // imports) legitimately exceed. Overridable via VRUUM_MCP_TIMEOUT_MS.
 const DEFAULT_CALL_TIMEOUT_MS = 300_000;
+const attempts = new AsyncLocalStorage();
 function resolveCallTimeoutMs() {
     const raw = Number(process.env.VRUUM_MCP_TIMEOUT_MS);
     return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_CALL_TIMEOUT_MS;
@@ -102,15 +104,19 @@ class RemoteProxy {
     url;
     token;
     version;
+    diagnostics;
+    clientName;
     client = null;
     /** Serializes connection creation so concurrent first calls share one
      * client instead of racing to overwrite `this.client` (and later closing
      * each other's healthy connections). */
     connecting = null;
-    constructor(url, token, version) {
+    constructor(url, token, version, diagnostics, clientName) {
         this.url = url;
         this.token = token;
         this.version = version;
+        this.diagnostics = diagnostics;
+        this.clientName = clientName;
     }
     getClient() {
         if (this.client)
@@ -118,6 +124,14 @@ class RemoteProxy {
         if (!this.connecting) {
             this.connecting = (async () => {
                 const transport = new StreamableHTTPClientTransport(new URL(this.url), {
+                    fetch: (url, init) => {
+                        const headers = new Headers(init?.headers);
+                        headers.set("X-Vruum-Client", this.clientName());
+                        const attempt = attempts.getStore();
+                        if (attempt)
+                            headers.set("X-Vruum-Attempt-Id", attempt);
+                        return fetch(url, { ...init, headers });
+                    },
                     requestInit: {
                         headers: { Authorization: `Bearer ${this.token}` },
                     },
@@ -150,7 +164,7 @@ class RemoteProxy {
      * Vruum tools (research, imports) legitimately run longer.
      */
     rawCall(client, name, args) {
-        return client.request({ method: "tools/call", params: { name, arguments: args } }, CallToolResultSchema, { timeout: resolveCallTimeoutMs(), resetTimeoutOnProgress: true });
+        return client.request({ method: "tools/call", params: { name, arguments: args } }, { timeout: resolveCallTimeoutMs(), resetTimeoutOnProgress: true });
     }
     async call(name, args) {
         let client;
@@ -158,6 +172,7 @@ class RemoteProxy {
             client = await this.getClient();
         }
         catch (connectErr) {
+            await this.diagnostics.record(attempts.getStore(), "tools/call", name, "connect_error");
             // First-connect failures (DNS, invalid token, endpoint down) get the
             // same structured error path as call failures — never a raw handler
             // throw that surfaces as an opaque JSON-RPC internal error.
@@ -170,6 +185,7 @@ class RemoteProxy {
             return await this.rawCall(client, name, args);
         }
         catch (callErr) {
+            await this.diagnostics.record(attempts.getStore(), "tools/call", name, "call_error");
             this.discard(client);
             const msg = callErr instanceof Error ? callErr.message : String(callErr);
             return errorResult(`Vruum MCP call '${name}' failed against ${this.url}: ${msg}\n` +
@@ -186,7 +202,6 @@ async function main() {
     const creds = readCredentials();
     const token = resolveToken(creds);
     const mcpUrl = resolveMcpUrl(creds);
-    const proxy = token ? new RemoteProxy(mcpUrl, token, pkg.version) : null;
     const server = new Server({ name: "vruum-mcp", version: pkg.version }, {
         // `listChanged: false` is the honest declaration: the listing is a
         // static snapshot bundled at release time, so this server never emits
@@ -196,32 +211,65 @@ async function main() {
             "served locally; tool calls execute against " +
             `${mcpUrl} under your Vruum token and are authorized server-side.`,
     });
-    server.setRequestHandler(ListToolsRequestSchema, async (request) => {
+    const diagnostics = new Diagnostics(process.env.VRUUM_CONFIG_DIR || join(homedir(), ".vruum"), mcpUrl, token, new Set(toolsDoc.tools.map((tool) => tool.name)), () => family(server.getClientVersion()?.name));
+    const proxy = token ? new RemoteProxy(mcpUrl, token, pkg.version, diagnostics, () => family(server.getClientVersion()?.name)) : null;
+    server.onerror = () => {
+        void diagnostics.record(randomUUID(), "unknown", "unknown", "protocol_error")
+            .then(() => diagnostics.flush());
+    };
+    server.setRequestHandler("tools/list", async (request) => {
+        const attempt = randomUUID();
+        await diagnostics.record(attempt, "tools/list", "unknown", "started");
         // The full list is returned in one page, so `nextCursor` is never set and
         // a client can never legitimately hold a cursor for this server. Spec:
         // "Invalid cursors SHOULD result in an error with code -32602."
         const cursor = request.params?.cursor;
         if (cursor !== undefined) {
-            throw new McpError(ErrorCode.InvalidParams, "Invalid cursor: this server returns all tools in a single page and " +
+            await diagnostics.record(attempt, "tools/list", "unknown", "invalid_cursor");
+            void diagnostics.flush();
+            throw new ProtocolError(ProtocolErrorCode.InvalidParams, "Invalid cursor: this server returns all tools in a single page and " +
                 "never issues a nextCursor.");
         }
+        await diagnostics.record(attempt, "tools/list", "unknown", "success");
+        void diagnostics.flush();
         return { tools: toolsDoc.tools };
     });
-    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    server.setRequestHandler("tools/call", async (request, ctx) => {
         const { name, arguments: args } = request.params;
+        const attempt = randomUUID();
+        const start = performance.now();
+        ctx.mcpReq.signal.addEventListener("abort", () => {
+            void diagnostics.record(attempt, "tools/call", name, "cancelled")
+                .then(() => diagnostics.flush());
+        }, { once: true });
+        await diagnostics.record(attempt, "tools/call", name, "started");
         // Spec (server/tools#error-handling): errors in *finding* the tool are
         // PROTOCOL errors, not `isError` results — only errors originating from a
         // tool's execution use `isError: true` (so the model can self-correct).
         if (!toolsDoc.tools.some((t) => t.name === name)) {
-            throw new McpError(ErrorCode.InvalidParams, `Unknown tool: ${name}`);
+            await diagnostics.record(attempt, "tools/call", name, "unknown_tool");
+            void diagnostics.flush();
+            throw new ProtocolError(ProtocolErrorCode.InvalidParams, `Unknown tool: ${name}`);
         }
         // A missing token IS an execution error — the tool exists and the model
         // should see why it could not run.
-        if (!proxy)
+        if (!proxy) {
+            await diagnostics.record(attempt, "tools/call", name, "missing_token");
             return errorResult(NO_TOKEN_HELP);
-        return proxy.call(name, (args ?? {}));
+        }
+        const result = await attempts.run(attempt, () => proxy.call(name, (args ?? {})));
+        await diagnostics.record(attempt, "tools/call", name, result.isError ? "tool_error" : "success", performance.now() - start);
+        void diagnostics.flush();
+        return result;
     });
+    // A Server connected straight to StdioServerTransport speaks only the
+    // 2025-era protocol (initialize handshake, 2024-10-07 … 2025-11-25), which
+    // is every client deployed today. Serving 2026-07-28 too would mean
+    // `serveStdio()`, where getClientVersion() is undefined on modern
+    // connections and the diagnostics client family needs the request envelope.
     await server.connect(new StdioServerTransport());
+    // Old offline reports may be uploaded even before a new tool is called.
+    void diagnostics.flush();
 }
 main().catch((err) => {
     console.error(`vruum-mcp fatal: ${err instanceof Error ? err.message : err}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vruum/mcp",
-  "version": "0.14.0",
+  "version": "0.15.1",
   "mcpName": "ai.vruum/mcp",
   "description": "Stdio MCP bridge for the hosted Vruum revenue-platform MCP (https://api.vruum.ai/mcp): serves the advertised tool surface for credential-free introspection and proxies tool calls with your Vruum token.",
   "license": "MIT",
@@ -34,7 +34,8 @@
     "prepublishOnly": "npm run typecheck && npm run test"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.30.0"
+    "@modelcontextprotocol/client": "^2.4.0",
+    "@modelcontextprotocol/server": "^2.4.0"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",