@vruum/mcp 0.2.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vruum (vruum-gtm)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# Vruum MCP (`@vruum/mcp`)
+
+Official MCP access to [Vruum](https://vruum.ai) — the AI revenue platform. Operate outbound, deals, pipeline, and CRM automation from your agent: people, deals, outreach, engagement, and research tools over one MCP.
+
+This package is the **stdio bridge** to the hosted Vruum MCP server. It serves the advertised tool surface locally (no credentials needed to introspect) and proxies tool execution to `https://api.vruum.ai/mcp` under your Vruum token. Every call is authorized server-side; the bridge grants no authority beyond what your Vruum account can already do.
+
+> **Connecting a modern client? Prefer the remote server directly.**
+> Clients that support remote MCP (Claude Code, Claude Desktop, Cursor, Codex, …) should connect straight to `https://api.vruum.ai/mcp` (OAuth 2.1, or `Authorization: Bearer vk_live_…`). This bridge exists for stdio-only clients and for tool-surface introspection. See [vruum.ai/docs/mcp](https://vruum.ai/docs/mcp).
+
+## Install & connect
+
+```json
+{
+  "mcpServers": {
+    "vruum": {
+      "command": "npx",
+      "args": ["-y", "@vruum/mcp"],
+      "env": { "VRUUM_MCP_TOKEN": "vk_live_…" }
+    }
+  }
+}
+```
+
+Get a token in the Vruum web app under **Settings → API tokens**. A Vruum account is required to execute tools; listing tools works without one.
+
+Already using the CLI? `npx @vruum/cli` → `vruum login --token vk_live_…` stores credentials in `~/.vruum/credentials`, and the bridge picks them up automatically.
+
+### Configuration
+
+| Env var | Meaning | Default |
+| --- | --- | --- |
+| `VRUUM_MCP_TOKEN` | Vruum personal access token | — (falls back to `VRUUM_TOKEN`, then `~/.vruum/credentials`) |
+| `VRUUM_MCP_URL` | Hosted MCP endpoint | `https://api.vruum.ai/mcp` |
+| `VRUUM_MCP_TIMEOUT_MS` | Per-call timeout (research/import tools run long) | `300000` |
+| `VRUUM_CONFIG_DIR` | Credentials directory | `~/.vruum` |
+
+## What's inside
+
+- **[`tools.json`](tools.json)** — the client-advertised tool surface: **29 curated compound tools** (`search`, `fetch`, `research`, `skill`, and the `manage_*` / `get_*` families covering people, deals, outreach, engagement, content, campaigns, and revenue), each carrying MCP safety annotations. This is exactly what a real Vruum session is advertised — one tool per decision rather than a sprawl of granular endpoints, so an agent never has to disambiguate between overlapping legacy verbs. Generated from the live server definition and served verbatim for `tools/list`.
+- **[`src/index.ts`](src/index.ts)** — the bridge: static listings, proxied calls, and structured errors
+  (a missing token is an explanation, not a crash). **A failed call is never automatically
+  retried** — many of these tools send outreach or spend money, and an ambiguous failure may
+  mean the server already executed, so a silent replay could double-send. The dead connection
+  is discarded, the error says so, and your agent decides whether the tool is safe to re-run.
+
+The distinctive design position of the Vruum MCP: **your AI harness authors all sales and marketing prose.** The server schedules, gates, persists, and sends — it has no server-side message generation. Outreach drafts surface to your agent as work items rather than being written for you.
+
+## Development
+
+This repository is a **build artifact of the Vruum monorepo**, resynced automatically on release — `tools.json` is regenerated from the live server definition, so it never drifts from what the hosted server actually exposes.
+
+Issues and PRs are welcome here: maintainers upstream accepted changes into the monorepo, and they flow back on the next sync.
+
+```sh
+npm install
+npm test        # builds, then black-box JSON-RPC tests against the built binary
+```
+
+## Links
+
+- [Vruum](https://vruum.ai) · [MCP docs](https://vruum.ai/docs/mcp) · [Getting started](https://vruum.ai/docs/getting-started)
+- Official registry entry: `ai.vruum/mcp` · Claude/Codex plugin: [`vruum-gtm/skills`](https://github.com/vruum-gtm/skills)
+
+## License
+
+[MIT](LICENSE)

package/dist/index.js

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+/**
+ * @vruum/mcp — stdio bridge for the hosted Vruum MCP.
+ *
+ * Two jobs, deliberately small:
+ *
+ * 1. `tools/list` is served STATICALLY from the bundled `tools.json` (the
+ *    member-visible surface of https://api.vruum.ai/mcp, generated in the
+ *    Vruum monorepo by `backend/scripts/dump_member_tools.py`). This is what
+ *    lets registry crawlers and stdio-only clients introspect the tool
+ *    surface without credentials.
+ *
+ * 2. `tools/call` proxies to the hosted server over Streamable HTTP with the
+ *    caller's Vruum token. Without a token, calls return a structured error
+ *    explaining how to get one — never a hang or a crash.
+ *
+ * Token resolution (mirrors @vruum/cli's `lib/config.ts` precedence):
+ *   VRUUM_MCP_TOKEN env > VRUUM_TOKEN env > ~/.vruum/credentials (written by
+ *   `vruum login`; directory overridable via VRUUM_CONFIG_DIR).
+ *
+ * Endpoint resolution:
+ *   VRUUM_MCP_URL env > credentials apiUrl + "/mcp" > https://api.vruum.ai/mcp
+ *
+ * Note: `tools.json` intentionally carries no outputSchema — declaring one
+ * would make this bridge's local error responses (which have no
+ * structuredContent) protocol violations under SDK output validation.
+ */
+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";
+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;
+function resolveCallTimeoutMs() {
+    const raw = Number(process.env.VRUUM_MCP_TIMEOUT_MS);
+    return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_CALL_TIMEOUT_MS;
+}
+const HERE = dirname(fileURLToPath(import.meta.url));
+// dist/index.js → package root sibling tools.json (also works from src/ via tsx).
+const TOOLS_PATH = join(HERE, "..", "tools.json");
+const PKG_PATH = join(HERE, "..", "package.json");
+function readJson(path) {
+    return JSON.parse(readFileSync(path, "utf8"));
+}
+function readCredentials() {
+    try {
+        const dir = process.env.VRUUM_CONFIG_DIR || join(homedir(), ".vruum");
+        const parsed = readJson(join(dir, "credentials"));
+        if (!parsed || typeof parsed.token !== "string" || !parsed.token)
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function resolveToken(creds) {
+    return (process.env.VRUUM_MCP_TOKEN || process.env.VRUUM_TOKEN || creds?.token || null);
+}
+function resolveMcpUrl(creds) {
+    if (process.env.VRUUM_MCP_URL)
+        return process.env.VRUUM_MCP_URL;
+    if (creds?.apiUrl)
+        return creds.apiUrl.replace(/\/+$/, "") + "/mcp";
+    return DEFAULT_MCP_URL;
+}
+const NO_TOKEN_HELP = [
+    "No Vruum token configured, so this call was not sent.",
+    "",
+    "The bridge needs a Vruum personal access token to execute tools:",
+    "  1. Sign in at https://vruum.ai and create a token under Settings → API tokens (vk_live_…),",
+    "  2. then either `export VRUUM_MCP_TOKEN=<token>` for this client,",
+    "     or run `npx @vruum/cli` → `vruum login --token <token>` once.",
+    "",
+    "If your MCP client supports remote servers, prefer connecting it directly to",
+    `${DEFAULT_MCP_URL} (OAuth) instead of this stdio bridge.`,
+].join("\n");
+function errorResult(text) {
+    return { content: [{ type: "text", text }], isError: true };
+}
+/**
+ * Lazily-connected client to the hosted server.
+ *
+ * Failure semantics, deliberately conservative: a failed `tools/call` is
+ * NEVER automatically retried. Many Vruum tools mutate state, send outreach
+ * externally, or spend money, and an ambiguous failure (timeout, dropped
+ * response) may mean the server already executed — a client-side replay could
+ * double-send. The failed connection is discarded so the NEXT call gets a
+ * fresh session, the error is surfaced structurally, and the calling harness
+ * decides whether the tool is safe to retry. (This mirrors Vruum's own
+ * server-side durable-send-intent discipline: ambiguous outcomes park, they
+ * are not replayed.)
+ */
+class RemoteProxy {
+    url;
+    token;
+    version;
+    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) {
+        this.url = url;
+        this.token = token;
+        this.version = version;
+    }
+    getClient() {
+        if (this.client)
+            return Promise.resolve(this.client);
+        if (!this.connecting) {
+            this.connecting = (async () => {
+                const transport = new StreamableHTTPClientTransport(new URL(this.url), {
+                    requestInit: {
+                        headers: { Authorization: `Bearer ${this.token}` },
+                    },
+                });
+                const client = new Client({ name: "vruum-mcp-bridge", version: this.version }, { capabilities: {} });
+                await client.connect(transport);
+                this.client = client;
+                return client;
+            })().finally(() => {
+                this.connecting = null;
+            });
+        }
+        return this.connecting;
+    }
+    /** Discard `failed` only if it is still the current client — a concurrent
+     * call may already have replaced it with a healthy connection. */
+    discard(failed) {
+        if (this.client === failed)
+            this.client = null;
+        void failed.close().catch(() => {
+            /* already dead */
+        });
+    }
+    /**
+     * Raw tools/call — deliberately NOT `client.callTool()`: the helper
+     * validates results against outputSchemas cached by `listTools()`, and the
+     * remote advertises outputSchemas this bridge intentionally does not. The
+     * raw request form has no cache and no validation, so passthrough stays
+     * passthrough. Timeout is raised above the SDK's 60s default because real
+     * 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 });
+    }
+    async call(name, args) {
+        let client;
+        try {
+            client = await this.getClient();
+        }
+        catch (connectErr) {
+            // 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.
+            const msg = connectErr instanceof Error ? connectErr.message : String(connectErr);
+            return errorResult(`Could not connect to the Vruum MCP at ${this.url}: ${msg}\n` +
+                "Check that your token is valid (Settings → API tokens) and the " +
+                "endpoint is reachable.");
+        }
+        try {
+            return await this.rawCall(client, name, args);
+        }
+        catch (callErr) {
+            this.discard(client);
+            const msg = callErr instanceof Error ? callErr.message : String(callErr);
+            return errorResult(`Vruum MCP call '${name}' failed against ${this.url}: ${msg}\n` +
+                "NOT automatically retried — the server may or may not have executed " +
+                "the action, and replaying a send/spend tool could duplicate it. " +
+                "Verify state with a read tool (e.g. fetch/search) before retrying; " +
+                "the next call will use a fresh connection.");
+        }
+    }
+}
+async function main() {
+    const pkg = readJson(PKG_PATH);
+    const toolsDoc = readJson(TOOLS_PATH);
+    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
+        // notifications/tools/list_changed.
+        capabilities: { tools: { listChanged: false } },
+        instructions: "Bridge to the hosted Vruum revenue-platform MCP. Tool listings are " +
+            "served locally; tool calls execute against " +
+            `${mcpUrl} under your Vruum token and are authorized server-side.`,
+    });
+    server.setRequestHandler(ListToolsRequestSchema, async (request) => {
+        // 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 " +
+                "never issues a nextCursor.");
+        }
+        return { tools: toolsDoc.tools };
+    });
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        // 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}`);
+        }
+        // A missing token IS an execution error — the tool exists and the model
+        // should see why it could not run.
+        if (!proxy)
+            return errorResult(NO_TOKEN_HELP);
+        return proxy.call(name, (args ?? {}));
+    });
+    await server.connect(new StdioServerTransport());
+}
+main().catch((err) => {
+    console.error(`vruum-mcp fatal: ${err instanceof Error ? err.message : err}`);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@vruum/mcp",
+  "version": "0.2.2",
+  "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",
+  "type": "module",
+  "bin": {
+    "vruum-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vruum-gtm/mcp.git"
+  },
+  "homepage": "https://vruum.ai/docs/mcp",
+  "bugs": {
+    "url": "https://github.com/vruum-gtm/mcp/issues"
+  },
+  "files": [
+    "dist",
+    "tools.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "postbuild": "chmod +x dist/index.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "prepublishOnly": "npm run typecheck && npm run test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.7.0"
+  },
+  "keywords": [
+    "vruum",
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "sales",
+    "crm",
+    "revenue",
+    "outreach",
+    "gtm"
+  ]
+}