voidgate-mcp 1.0.0

package/README.md

@@ -0,0 +1,105 @@
+# voidgate-mcp
+
+Stdio MCP bridge for [VoidGate](https://github.com/your-org/voidgate).  
+Wraps VoidGate's Streamable HTTP endpoint into a standard MCP stdio server so any AI client (Claude Desktop, Cursor, Windsurf, …) can use it without extra configuration.
+
+## How it works
+
+```
+AI client (Claude Desktop / Cursor / …)
+    ↕ MCP stdio
+npx voidgate-mcp [app-id]
+    ↕ Streamable HTTP  (JSON-RPC 2.0)
+VoidGate  /server/{connectionId}?key=…
+    ↕ HTTP
+Your business API
+```
+
+## Requirements
+
+- Node.js ≥ 18
+- A running VoidGate instance
+- A valid `x-access-token` (user JWT from your auth service)
+
+## Usage
+
+### Mode A — direct URL
+
+If you already have a VoidGate Streamable HTTP URL:
+
+```bash
+VOIDGATE_URL="http://localhost:8081/server/c_xxx?key=k_yyy" npx -y voidgate-mcp
+```
+
+### Mode B — auto-connect (recommended)
+
+The bridge calls `POST /v1/mcp/connections` to get or reuse a connection URL automatically.
+
+```bash
+VOIDGATE_BASE_URL="http://localhost:8081" \
+VOIDGATE_TOKEN="eyJhbGci..." \
+VOIDGATE_APP_MCP_ID="1" \
+npx -y voidgate-mcp
+```
+
+You can also pass the app ID as a positional argument (useful for Claude Desktop config):
+
+```bash
+VOIDGATE_BASE_URL="http://localhost:8081" \
+VOIDGATE_TOKEN="eyJhbGci..." \
+npx -y voidgate-mcp 1
+```
+
+## Claude Desktop setup
+
+Edit `~/.claude/claude_desktop_config.json` (Mac/Linux) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "invoice-service": {
+      "command": "npx",
+      "args": ["-y", "voidgate-mcp", "1"],
+      "env": {
+        "VOIDGATE_BASE_URL": "https://your-voidgate.com",
+        "VOIDGATE_TOKEN": "eyJhbGci..."
+      }
+    },
+    "recognition-service": {
+      "command": "npx",
+      "args": ["-y", "voidgate-mcp", "2"],
+      "env": {
+        "VOIDGATE_BASE_URL": "https://your-voidgate.com",
+        "VOIDGATE_TOKEN": "eyJhbGci..."
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The tools from each VoidGate app will appear automatically.
+
+## Cursor / other clients
+
+Add to your MCP client config with the same `command` / `args` / `env` structure above.  
+Most clients that support MCP stdio follow the same schema.
+
+## Environment variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `VOIDGATE_URL` | A or B | Full Streamable HTTP URL (skip auto-connect) |
+| `VOIDGATE_BASE_URL` | B | Base URL of your VoidGate instance |
+| `VOIDGATE_TOKEN` | B | User access token (`x-access-token`) |
+| `VOIDGATE_APP_MCP_ID` | B* | App MCP ID (can also be the first CLI arg) |
+
+\* Required in Mode B unless passed as positional argument.
+
+## Logs
+
+All bridge logs go to **stderr** so they never interfere with the MCP stdio stream.  
+Redirect stderr to a file for debugging:
+
+```bash
+VOIDGATE_URL="..." npx voidgate-mcp 2>bridge.log
+```

package/index.js

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+/**
+ * voidgate-mcp — stdio MCP bridge for VoidGate
+ *
+ * Usage:
+ *   # Mode 1: direct Streamable HTTP URL
+ *   VOIDGATE_URL="http://host/server/c_xxx?key=k_yyy" npx voidgate-mcp
+ *
+ *   # Mode 2: auto-connect (VoidGate creates the connection)
+ *   VOIDGATE_BASE_URL="http://host" \
+ *   VOIDGATE_TOKEN="eyJ..." \
+ *   VOIDGATE_APP_MCP_ID="1" \
+ *   npx voidgate-mcp
+ *
+ *   # Mode 2b: app ID as positional arg (overrides env var)
+ *   VOIDGATE_BASE_URL="http://host" VOIDGATE_TOKEN="eyJ..." npx voidgate-mcp 1
+ *
+ * Claude Desktop config example (~/.claude/claude_desktop_config.json):
+ *   {
+ *     "mcpServers": {
+ *       "invoice-service": {
+ *         "command": "npx",
+ *         "args": ["-y", "voidgate-mcp", "1"],
+ *         "env": {
+ *           "VOIDGATE_BASE_URL": "https://your-voidgate.com",
+ *           "VOIDGATE_TOKEN": "eyJ..."
+ *         }
+ *       }
+ *     }
+ *   }
+ */
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+// ─── config resolution ────────────────────────────────────────────────────────
+
+function env(key) {
+  return (process.env[key] ?? "").trim();
+}
+
+async function resolveURL() {
+  // Mode 1: direct URL already known
+  const direct = env("VOIDGATE_URL");
+  if (direct) return direct;
+
+  // Mode 2: auto-connect via VoidGate management API
+  const baseUrl = env("VOIDGATE_BASE_URL").replace(/\/$/, "");
+  const token   = env("VOIDGATE_TOKEN");
+
+  // App MCP ID: positional CLI arg takes precedence over env var
+  const rawId = process.argv[2]?.trim() || env("VOIDGATE_APP_MCP_ID");
+
+  if (!baseUrl || !token || !rawId) {
+    throw new Error(
+      "Configuration missing.\n" +
+      "  Option A — set VOIDGATE_URL\n" +
+      "  Option B — set VOIDGATE_BASE_URL + VOIDGATE_TOKEN + VOIDGATE_APP_MCP_ID (or pass ID as first arg)"
+    );
+  }
+
+  const appMcpId = parseInt(rawId, 10);
+  if (!Number.isFinite(appMcpId) || appMcpId <= 0) {
+    throw new Error(`Invalid app MCP ID: "${rawId}" — must be a positive integer`);
+  }
+
+  log(`Connecting to VoidGate app #${appMcpId} at ${baseUrl} …`);
+
+  const res = await fetch(`${baseUrl}/v1/mcp/connections`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "x-access-token": token,
+    },
+    body: JSON.stringify({ appMcpId }),
+  });
+
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    throw new Error(`VoidGate connection failed (HTTP ${res.status}): ${body}`);
+  }
+
+  const data = await res.json();
+  if (!data.url) throw new Error("VoidGate returned no MCP URL");
+
+  log(data.reused ? "Reusing existing connection." : "New connection created.");
+  return data.url;
+}
+
+// ─── VoidGate RPC helper ──────────────────────────────────────────────────────
+
+async function rpc(mcpUrl, method, params) {
+  const res = await fetch(mcpUrl, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Accept: "application/json, text/event-stream",
+    },
+    body: JSON.stringify({
+      jsonrpc: "2.0",
+      id: Date.now(),
+      method,
+      params: params ?? {},
+    }),
+  });
+
+  if (!res.ok) {
+    throw new Error(`VoidGate RPC error: HTTP ${res.status} on ${method}`);
+  }
+
+  let payload;
+  const ct = res.headers.get("content-type") ?? "";
+  if (ct.includes("text/event-stream")) {
+    // Stateless Streamable HTTP may return SSE; grab first data line
+    const text = await res.text();
+    const line = text.split("\n").find((l) => l.startsWith("data:"));
+    if (!line) throw new Error(`No data in SSE response for ${method}`);
+    payload = JSON.parse(line.slice(5).trim());
+  } else {
+    payload = await res.json();
+  }
+
+  if (payload.error) {
+    const msg = payload.error.message ?? JSON.stringify(payload.error);
+    throw new Error(`VoidGate error on ${method}: ${msg}`);
+  }
+  return payload.result;
+}
+
+// ─── logging (stderr only — stdout is reserved for MCP stdio) ────────────────
+
+function log(msg) {
+  process.stderr.write(`[voidgate-mcp] ${msg}\n`);
+}
+
+// ─── main ─────────────────────────────────────────────────────────────────────
+
+async function main() {
+  const mcpUrl = await resolveURL();
+  log(`MCP URL: ${mcpUrl}`);
+
+  const server = new Server(
+    { name: "voidgate", version: "1.0.0" },
+    { capabilities: { tools: {} } }
+  );
+
+  // tools/list — forward to VoidGate, return upstream result unchanged
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return await rpc(mcpUrl, "tools/list", {});
+  });
+
+  // tools/call — forward to VoidGate, return upstream result unchanged
+  server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    return await rpc(mcpUrl, "tools/call", req.params);
+  });
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  log("Bridge ready — listening on stdio.");
+}
+
+main().catch((err) => {
+  process.stderr.write(`[voidgate-mcp] fatal: ${err.message}\n`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "voidgate-mcp",
+  "version": "1.0.0",
+  "description": "Stdio MCP bridge for VoidGate — connect any MCP app to Claude Desktop, Cursor, and other AI clients",
+  "type": "module",
+  "bin": {
+    "voidgate-mcp": "index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "voidgate",
+    "claude",
+    "ai"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  }
+}