@calibress/curl-mcp-bridge 0.1.0

package/README.md

@@ -0,0 +1,79 @@
+# curl-mcp-bridge
+
+A local MCP `stdio` bridge that proxies MCP JSON-RPC to a Calibress hosted `/mcp` HTTP endpoint.
+
+This lets any MCP client that supports `stdio` (Claude Desktop, Roo, etc.) talk to the hosted multi-tenant MCP gateway.
+
+## Requirements
+
+- Node.js >= 18
+
+## Usage
+
+Set these env vars:
+
+- `CALIBRESS_ENDPOINT` (required) — Hosted MCP URL (e.g. `https://enterprise-plan.dev.calibress.com/mcp`)
+- `CALIBRESS_API_KEY` (required) — Tenant/project API key (Bearer). Prefer project-scoped keys so “project selection” is implicit.
+
+Then run:
+
+```bash
+CALIBRESS_ENDPOINT="https://enterprise-plan.dev.calibress.com/mcp" \
+CALIBRESS_API_KEY="cmcp_..." \
+node ./bin/curl-mcp-bridge.js
+```
+
+CLI overrides are also available (`--endpoint`, `--api-key`, `--session-id`).
+
+The bridge reads MCP messages from stdin and writes MCP responses to stdout (1 JSON object per line).
+
+## Run via npx (npm)
+
+```bash
+CALIBRESS_ENDPOINT="https://enterprise-plan.dev.calibress.com/mcp" \
+CALIBRESS_API_KEY="cmcp_..." \
+npx -y @calibress/curl-mcp-bridge
+```
+
+If you need to run an unpublished build, you can still run from GitHub:
+
+```bash
+CALIBRESS_ENDPOINT="https://enterprise-plan.dev.calibress.com/mcp" \
+CALIBRESS_API_KEY="cmcp_..." \
+npx -y github:calibress/curl-mcp-bridge
+```
+
+## MCP client configuration
+
+Example (Roo / Claude Desktop style):
+
+```json
+{
+  "curl-mcp-enterprise-plan": {
+    "transport": "stdio",
+    "command": "node",
+    "args": ["/ABS/PATH/TO/curl-mcp-bridge/bin/curl-mcp-bridge.js"],
+    "env": {
+      "CALIBRESS_ENDPOINT": "https://enterprise-plan.dev.calibress.com/mcp",
+      "CALIBRESS_API_KEY": "cmcp_REPLACE_ME"
+    },
+    "alwaysAllow": ["curl_request", "mcp_version"]
+  }
+}
+```
+
+## Session handling
+
+- The hosted MCP endpoint issues `Mcp-Session-Id` on `initialize`.
+- The bridge caches that session id in-process and automatically sends it on subsequent requests.
+- If a client sends a request before `initialize`, the bridge will bootstrap a session and retry once.
+
+## Extensibility
+
+The bridge forwards all JSON-RPC methods as-is.
+
+When the hosted MCP gateway adds new tools (e.g. `list_connections`), existing clients automatically see them via `tools/list` without changing the bridge.
+
+## Notes
+
+- To publish, bump `package.json` version and run `npm publish` (public access is configured).

package/bin/curl-mcp-bridge.js

@@ -0,0 +1,312 @@
+#!/usr/bin/env node
+
+import process from 'node:process'
+import readline from 'node:readline'
+import { createRequire } from 'node:module'
+
+const require = createRequire(import.meta.url)
+const { name: PACKAGE_NAME, version: PACKAGE_VERSION } = require('../package.json')
+
+function parseArgs(argv) {
+  const args = {
+    endpoint: undefined,
+    apiKey: undefined,
+    sessionId: undefined,
+    verbose: false,
+    help: false,
+    version: false,
+  }
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const current = argv[i]
+
+    if (current === '--help' || current === '-h') {
+      args.help = true
+      continue
+    }
+
+    if (current === '--version' || current === '-v') {
+      args.version = true
+      continue
+    }
+
+    if (current === '--verbose') {
+      args.verbose = true
+      continue
+    }
+
+    const [key, valueFromEquals] = current.split('=', 2)
+    const valueFromNext = argv[i + 1]
+
+    if (key === '--endpoint') {
+      args.endpoint = valueFromEquals ?? valueFromNext
+      if (valueFromEquals === undefined) i += 1
+      continue
+    }
+
+    if (key === '--api-key') {
+      args.apiKey = valueFromEquals ?? valueFromNext
+      if (valueFromEquals === undefined) i += 1
+      continue
+    }
+
+    if (key === '--session-id') {
+      args.sessionId = valueFromEquals ?? valueFromNext
+      if (valueFromEquals === undefined) i += 1
+      continue
+    }
+  }
+
+  return args
+}
+
+function printHelp() {
+  process.stderr.write(`${PACKAGE_NAME} ${PACKAGE_VERSION}\n\n`)
+  process.stderr.write(`Usage:\n`)
+  process.stderr.write(`  CALIBRESS_ENDPOINT=... CALIBRESS_API_KEY=... curl-mcp-bridge\n\n`)
+  process.stderr.write(`Options:\n`)
+  process.stderr.write(`  --endpoint <url>     Override CALIBRESS_ENDPOINT\n`)
+  process.stderr.write(`  --api-key <key>      Override CALIBRESS_API_KEY\n`)
+  process.stderr.write(`  --session-id <id>    Force Mcp-Session-Id (debug)\n`)
+  process.stderr.write(`  --verbose            Log non-sensitive diagnostics to stderr\n`)
+  process.stderr.write(`  --help               Show help\n`)
+  process.stderr.write(`  --version            Show version\n`)
+}
+
+function jsonRpcError(id, code, message) {
+  return {
+    jsonrpc: '2.0',
+    id: id ?? null,
+    error: {
+      code,
+      message,
+    },
+  }
+}
+
+function normalizeContentItem(item) {
+  if (!item || typeof item !== 'object') return item
+  if (item.type !== 'json') return item
+
+  const value = Object.prototype.hasOwnProperty.call(item, 'data')
+    ? item.data
+    : Object.prototype.hasOwnProperty.call(item, 'json')
+      ? item.json
+      : item
+
+  const text = typeof value === 'string' ? value : JSON.stringify(value, null, 2)
+  return { type: 'text', text }
+}
+
+function normalizeMcpPayload(payload) {
+  const normalizeOne = (message) => {
+    if (!message || typeof message !== 'object') return message
+    if (!message.result || typeof message.result !== 'object') return message
+    if (!Array.isArray(message.result.content)) return message
+
+    return {
+      ...message,
+      result: {
+        ...message.result,
+        content: message.result.content.map(normalizeContentItem),
+      },
+    }
+  }
+
+  return Array.isArray(payload) ? payload.map(normalizeOne) : normalizeOne(payload)
+}
+
+function safeStringify(value) {
+  return JSON.stringify(value)
+}
+
+function logVerbose(enabled, message) {
+  if (!enabled) return
+  process.stderr.write(`[curl-mcp-bridge] ${message}\n`)
+}
+
+const args = parseArgs(process.argv.slice(2))
+
+if (args.help) {
+  printHelp()
+  process.exit(0)
+}
+
+if (args.version) {
+  process.stdout.write(`${PACKAGE_VERSION}\n`)
+  process.exit(0)
+}
+
+const endpoint =
+  args.endpoint ??
+  process.env.CALIBRESS_ENDPOINT ??
+  process.env.CALIBRESS_MCP_ENDPOINT
+
+const apiKey =
+  args.apiKey ??
+  process.env.CALIBRESS_API_KEY ??
+  process.env.CALIBRESS_MCP_API_KEY
+
+if (!endpoint) {
+  process.stderr.write('Missing CALIBRESS_ENDPOINT\n')
+  process.exit(1)
+}
+
+if (!apiKey) {
+  process.stderr.write('Missing CALIBRESS_API_KEY\n')
+  process.exit(1)
+}
+
+let sessionId =
+  args.sessionId ??
+  process.env.CALIBRESS_MCP_SESSION_ID ??
+  undefined
+
+async function postJson(body, extraHeaders) {
+  const headers = {
+    Authorization: `Bearer ${apiKey}`,
+    'Content-Type': 'application/json',
+    Accept: 'application/json, text/event-stream',
+    ...extraHeaders,
+  }
+
+  const response = await fetch(endpoint, {
+    method: 'POST',
+    headers,
+    body: safeStringify(body),
+  })
+
+  const nextSessionId =
+    response.headers.get('mcp-session-id') ??
+    response.headers.get('Mcp-Session-Id')
+
+  if (nextSessionId) sessionId = nextSessionId
+
+  const text = await response.text()
+  if (!text) return null
+
+  try {
+    const parsed = JSON.parse(text)
+    return normalizeMcpPayload(parsed)
+  } catch {
+    const contentType = response.headers.get('content-type') ?? 'unknown'
+    const ngrokError = response.headers.get('ngrok-error-code')
+    const snippet = text.trim().slice(0, 160).replaceAll(/\s+/g, ' ')
+    const details = [
+      `HTTP ${response.status}`,
+      `content-type=${contentType}`,
+      ngrokError ? `ngrok-error-code=${ngrokError}` : null,
+    ]
+      .filter(Boolean)
+      .join(', ')
+
+    return jsonRpcError(
+      body?.id ?? null,
+      -32000,
+      `Upstream returned non-JSON response (${details}). Body: ${snippet}`
+    )
+  }
+}
+
+function shouldBootstrapFromError(payload) {
+  const message = payload?.error?.message
+  if (typeof message !== 'string') return false
+
+  if (message.includes('Mcp-Session-Id') && message.includes('required')) return true
+  if (message.toLowerCase().includes('server not initialized')) return true
+
+  return false
+}
+
+async function bootstrapSession() {
+  const initRequest = {
+    jsonrpc: '2.0',
+    id: 'bridge-init',
+    method: 'initialize',
+    params: {
+      protocolVersion: '2024-11-05',
+      capabilities: {},
+      clientInfo: {
+        name: PACKAGE_NAME,
+        version: PACKAGE_VERSION,
+      },
+    },
+  }
+
+  const payload = await postJson(initRequest, {})
+
+  if (!sessionId) {
+    const message = payload?.error?.message
+    throw new Error(
+      typeof message === 'string'
+        ? `Failed to establish session: ${message}`
+        : 'Failed to establish session'
+    )
+  }
+
+  return payload
+}
+
+async function proxyMessage(message) {
+  const headers = {}
+
+  if (sessionId) {
+    headers['Mcp-Session-Id'] = sessionId
+  }
+
+  const payload = await postJson(message, headers)
+
+  if (payload && shouldBootstrapFromError(payload)) {
+    logVerbose(args.verbose, 'Bootstrapping MCP session and retrying request')
+    await bootstrapSession()
+
+    const retryHeaders = {}
+    if (sessionId) retryHeaders['Mcp-Session-Id'] = sessionId
+
+    return postJson(message, retryHeaders)
+  }
+
+  return payload
+}
+
+function writeMessage(message) {
+  if (message === null || message === undefined) return
+  process.stdout.write(`${safeStringify(message)}\n`)
+}
+
+async function main() {
+  const rl = readline.createInterface({ input: process.stdin, crlfDelay: Infinity })
+  for await (const line of rl) {
+    const trimmed = line.trim()
+    if (!trimmed) continue
+
+    let parsed
+    try {
+      parsed = JSON.parse(trimmed)
+    } catch {
+      writeMessage(jsonRpcError(null, -32700, 'Parse error'))
+      continue
+    }
+
+    try {
+      const response = await proxyMessage(parsed)
+      writeMessage(response)
+    } catch (error) {
+      const message =
+        error instanceof Error && typeof error.message === 'string'
+          ? error.message
+          : 'Upstream request failed'
+
+      writeMessage(jsonRpcError(parsed?.id ?? null, -32000, message))
+    }
+  }
+}
+
+main().catch((error) => {
+  const message =
+    error instanceof Error && typeof error.message === 'string'
+      ? error.message
+      : 'Bridge failed'
+  process.stderr.write(`[curl-mcp-bridge] ${message}\n`)
+  process.exit(1)
+})

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@calibress/curl-mcp-bridge",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Local MCP stdio bridge that proxies to Calibress hosted /mcp over HTTP",
+  "keywords": [
+    "mcp",
+    "stdio",
+    "bridge",
+    "calibress"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/calibress/curl-mcp-bridge.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "curl-mcp-bridge": "bin/curl-mcp-bridge.js"
+  },
+  "scripts": {
+    "start": "node ./bin/curl-mcp-bridge.js"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}