openapi-to-mcp-bridge-mcp 1.0.0

package/README.md

@@ -0,0 +1,47 @@
+# openapi-to-mcp-bridge-mcp
+
+Bridge any OpenAPI 3.x spec → MCP server in one call. Inspect tools, preview JSON Schemas, generate a runnable Node MCP server, or stream-call endpoints live without writing a wrapper.
+
+## Why
+Every AI agent dev wants to give Claude/GPT access to their existing REST APIs. Today they write MCP wrappers by hand — one tool per endpoint, schemas duplicated, auth boilerplate. This bridge eats an OpenAPI spec and emits MCP — automatically.
+
+## Install
+```bash
+npm install -g openapi-to-mcp-bridge-mcp
+```
+
+## Tools
+
+| Tool | What it does |
+|------|--------------|
+| `from_url` | Fetch spec from URL → summary (info / base URL / operation list) |
+| `from_spec` | Same, but takes inline JSON/YAML |
+| `preview_tools` | Return MCP-shaped `{name, description, inputSchema}` for every operation — paste into any MCP host |
+| `generate_server` | Emit a runnable Node ESM MCP server wrapping all operations |
+| `call_endpoint` | Fire one HTTP call against an `operationId` with validated args |
+
+## Quickstart
+
+```jsonc
+// claude_desktop_config.json
+{
+  "mcpServers": {
+    "openapi-bridge": {
+      "command": "npx",
+      "args": ["-y", "openapi-to-mcp-bridge-mcp"]
+    }
+  }
+}
+```
+
+Then ask Claude:
+> "Use openapi-bridge.from_url with https://petstore3.swagger.io/api/v3/openapi.json — show me the tool list."
+
+## Generated server runtime env
+
+The output of `generate_server` reads:
+- `OPENAPI_BASE_URL` — override `servers[0].url`
+- `OPENAPI_AUTH_HEADER` — single header to inject, e.g. `Authorization: Bearer XYZ`
+
+## License
+MIT

package/index.js

@@ -0,0 +1,399 @@
+#!/usr/bin/env node
+/**
+ * openapi-to-mcp-bridge-mcp
+ * ────────────────────────
+ * One MCP server that turns any OpenAPI 3.x spec into MCP tools.
+ *
+ * Tools:
+ *   from_url        — fetch spec from URL, normalize, list ops as MCP tools
+ *   from_spec       — same as from_url but takes spec inline (string or JSON)
+ *   preview_tools   — return MCP-shaped tool definitions for a spec (name, desc, inputSchema)
+ *   generate_server — emit a runnable Node MCP server (Node ESM) wrapping all operations
+ *   call_endpoint   — fire one HTTP call against an operationId with validated args
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+// ─── Spec loading ─────────────────────────────────────────────────────────
+function safeJson(s, fallback = null) { try { return JSON.parse(s); } catch { return fallback; } }
+
+function looksLikeYaml(s) {
+  if (typeof s !== "string") return false;
+  const t = s.trim();
+  if (!t || t.startsWith("{") || t.startsWith("[")) return false;
+  return /^(openapi|swagger|info|paths|components):/m.test(t);
+}
+
+// Minimal YAML-ish loader — handles flat OpenAPI specs reasonably; for complex anchors
+// the caller should pre-convert to JSON. We try JSON first then a forgiving YAML parser.
+function parseSpec(raw) {
+  if (raw && typeof raw === "object") return raw;
+  const s = String(raw || "");
+  const j = safeJson(s);
+  if (j) return j;
+  if (looksLikeYaml(s)) {
+    // Cheap two-pass YAML→JSON: convert lines to objects. Good enough for spec parsing
+    // when no anchors/multiline scalars are used.
+    return naiveYamlParse(s);
+  }
+  throw new Error("Spec must be JSON or simple YAML; pass it via from_spec with valid content.");
+}
+
+function naiveYamlParse(text) {
+  // Stack-based indent parser: handles mappings + sequences + scalar leaves.
+  const lines = text.split(/\r?\n/).filter((l) => l.trim() && !l.trim().startsWith("#"));
+  const root = {};
+  const stack = [{ indent: -1, value: root }];
+  for (const raw of lines) {
+    const indent = raw.match(/^( *)/)[1].length;
+    const line = raw.trim();
+    while (stack.length > 1 && stack[stack.length - 1].indent >= indent) stack.pop();
+    const parent = stack[stack.length - 1].value;
+    if (line.startsWith("- ")) {
+      const item = line.slice(2);
+      if (!Array.isArray(parent.__list)) parent.__list = [];
+      if (item.includes(": ")) {
+        const [k, v] = splitKV(item);
+        const obj = { [k]: castScalar(v) };
+        parent.__list.push(obj);
+        stack.push({ indent, value: obj });
+      } else if (item.endsWith(":")) {
+        const k = item.slice(0, -1);
+        const obj = { [k]: {} };
+        parent.__list.push(obj);
+        stack.push({ indent, value: obj[k] });
+      } else {
+        parent.__list.push(castScalar(item));
+      }
+    } else if (line.endsWith(":")) {
+      const k = line.slice(0, -1);
+      parent[k] = {};
+      stack.push({ indent, value: parent[k] });
+    } else if (line.includes(": ")) {
+      const [k, v] = splitKV(line);
+      parent[k] = castScalar(v);
+    }
+  }
+  return liftLists(root);
+}
+function splitKV(s) {
+  const i = s.indexOf(": ");
+  return [s.slice(0, i).trim(), s.slice(i + 2).trim()];
+}
+function castScalar(v) {
+  if (v == null) return null;
+  if (/^(true|false)$/i.test(v)) return v.toLowerCase() === "true";
+  if (/^-?\d+$/.test(v)) return parseInt(v, 10);
+  if (/^-?\d*\.\d+$/.test(v)) return parseFloat(v);
+  return v.replace(/^["']|["']$/g, "");
+}
+function liftLists(node) {
+  if (Array.isArray(node)) return node.map(liftLists);
+  if (node && typeof node === "object") {
+    if (node.__list) return node.__list.map(liftLists);
+    const out = {};
+    for (const k of Object.keys(node)) out[k] = liftLists(node[k]);
+    return out;
+  }
+  return node;
+}
+
+async function fetchSpec(url) {
+  const ctrl = typeof AbortController === "function" ? new AbortController() : null;
+  const t = ctrl ? setTimeout(() => ctrl.abort(), 15000) : null;
+  try {
+    const res = await fetch(url, { signal: ctrl?.signal, headers: { "user-agent": "openapi-to-mcp-bridge/1.0" } });
+    if (!res.ok) throw new Error(`HTTP ${res.status} fetching ${url}`);
+    const text = await res.text();
+    return parseSpec(text);
+  } finally {
+    if (t) clearTimeout(t);
+  }
+}
+
+// ─── Spec → tool definitions ─────────────────────────────────────────────
+const PRIM_MAP = { string: "string", integer: "number", number: "number", boolean: "boolean", array: "array", object: "object" };
+
+function paramSchema(p) {
+  const s = p.schema || {};
+  const t = PRIM_MAP[s.type] || "string";
+  const out = { type: t };
+  if (s.enum) out.enum = s.enum;
+  if (s.format) out.format = s.format;
+  if (s.minimum != null) out.minimum = s.minimum;
+  if (s.maximum != null) out.maximum = s.maximum;
+  if (s.default != null) out.default = s.default;
+  if (s.items) out.items = { type: PRIM_MAP[s.items.type] || "string" };
+  if (p.description) out.description = p.description;
+  return out;
+}
+
+function bodySchema(reqBody, spec) {
+  if (!reqBody) return null;
+  const c = reqBody.content || {};
+  const json = c["application/json"] || c["application/*+json"] || c[Object.keys(c)[0]];
+  if (!json) return null;
+  const schema = resolveRef(json.schema, spec) || { type: "object" };
+  return schema;
+}
+
+function resolveRef(node, spec) {
+  if (!node || typeof node !== "object") return node;
+  if (typeof node.$ref === "string") {
+    const path = node.$ref.replace(/^#\//, "").split("/");
+    let cur = spec;
+    for (const seg of path) { if (cur == null) return null; cur = cur[seg]; }
+    return resolveRef(cur, spec);
+  }
+  return node;
+}
+
+function opToTool(op, path, method, spec) {
+  const opId = op.operationId || `${method.toLowerCase()}_${path.replace(/[^a-zA-Z0-9]+/g, "_").replace(/^_|_$/g, "")}`;
+  const params = (op.parameters || []).map((p) => resolveRef(p, spec)).filter(Boolean);
+  const properties = {};
+  const required = [];
+  for (const p of params) {
+    properties[p.name] = paramSchema(p);
+    properties[p.name].__in = p.in;
+    if (p.required) required.push(p.name);
+  }
+  const body = bodySchema(resolveRef(op.requestBody, spec), spec);
+  if (body) {
+    properties.body = { ...body, description: "Request body (JSON)" };
+    if (op.requestBody?.required) required.push("body");
+  }
+  return {
+    name: opId,
+    description: (op.summary || op.description || `${method.toUpperCase()} ${path}`).slice(0, 280),
+    method: method.toUpperCase(),
+    path,
+    inputSchema: { type: "object", properties, required },
+    tags: op.tags || [],
+  };
+}
+
+function specToTools(spec) {
+  const tools = [];
+  const paths = spec.paths || {};
+  for (const [p, pi] of Object.entries(paths)) {
+    for (const m of ["get","post","put","patch","delete","head","options"]) {
+      if (pi[m]) tools.push(opToTool(pi[m], p, m, spec));
+    }
+  }
+  return tools;
+}
+
+function deriveBaseUrl(spec, override) {
+  if (override) return String(override).replace(/\/+$/, "");
+  const s = spec.servers?.[0]?.url;
+  if (s) return String(s).replace(/\/+$/, "");
+  return null;
+}
+
+// ─── Generator: produce a runnable Node MCP server ───────────────────────
+function generateServerCode(spec, { name, base_url }) {
+  const tools = specToTools(spec);
+  const baseUrl = deriveBaseUrl(spec, base_url) || "https://REPLACE.example.com";
+  const safeName = (name || (spec.info?.title || "openapi-mcp")).toString().toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-|-$/g, "");
+  const meta = {
+    name: safeName,
+    version: "1.0.0",
+    description: spec.info?.description || `${spec.info?.title || "OpenAPI"} bridged to MCP`,
+  };
+  const toolDefs = tools.map((t) => ({
+    name: t.name,
+    description: t.description,
+    method: t.method,
+    path: t.path,
+    inputSchema: t.inputSchema,
+  }));
+  return [
+    `#!/usr/bin/env node`,
+    `// Auto-generated by openapi-to-mcp-bridge-mcp v1.0.0`,
+    `// Source: ${spec.info?.title || "OpenAPI"} ${spec.info?.version || ""}`,
+    `import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";`,
+    `import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";`,
+    `import { z } from "zod";`,
+    ``,
+    `const BASE_URL = process.env.OPENAPI_BASE_URL || ${JSON.stringify(baseUrl)};`,
+    `const AUTH_HEADER = process.env.OPENAPI_AUTH_HEADER || ""; // e.g. "Authorization: Bearer XYZ"`,
+    ``,
+    `const TOOLS = ${JSON.stringify(toolDefs, null, 2)};`,
+    ``,
+    `function buildUrl(path, args) {`,
+    `  let p = path;`,
+    `  const query = new URLSearchParams();`,
+    `  for (const [k, v] of Object.entries(args || {})) {`,
+    `    if (k === "body") continue;`,
+    `    if (p.includes("{" + k + "}")) { p = p.replace("{" + k + "}", encodeURIComponent(v)); continue; }`,
+    `    query.set(k, String(v));`,
+    `  }`,
+    `  const q = query.toString();`,
+    `  return BASE_URL + p + (q ? "?" + q : "");`,
+    `}`,
+    ``,
+    `async function callOp(op, args) {`,
+    `  const url = buildUrl(op.path, args);`,
+    `  const headers = { "content-type": "application/json", "accept": "application/json" };`,
+    `  if (AUTH_HEADER) { const [k, ...rest] = AUTH_HEADER.split(":"); headers[k.trim()] = rest.join(":").trim(); }`,
+    `  const body = args && args.body != null ? JSON.stringify(args.body) : undefined;`,
+    `  const res = await fetch(url, { method: op.method, headers, body });`,
+    `  const text = await res.text();`,
+    `  try { return { ok: res.ok, status: res.status, data: JSON.parse(text) }; }`,
+    `  catch { return { ok: res.ok, status: res.status, data: text }; }`,
+    `}`,
+    ``,
+    `const server = new McpServer(${JSON.stringify(meta, null, 2)});`,
+    ``,
+    `for (const op of TOOLS) {`,
+    `  const shape = {};`,
+    `  for (const [name, schema] of Object.entries(op.inputSchema.properties || {})) {`,
+    `    let s = z.any();`,
+    `    if (schema.type === "string") s = z.string();`,
+    `    else if (schema.type === "number") s = z.number();`,
+    `    else if (schema.type === "boolean") s = z.boolean();`,
+    `    else if (schema.type === "array") s = z.array(z.any());`,
+    `    if (!(op.inputSchema.required || []).includes(name)) s = s.optional();`,
+    `    if (schema.description) s = s.describe(schema.description);`,
+    `    shape[name] = s;`,
+    `  }`,
+    `  server.tool(op.name, op.description, shape, async (args) => {`,
+    `    const out = await callOp(op, args);`,
+    `    return { content: [{ type: "text", text: JSON.stringify(out, null, 2) }] };`,
+    `  });`,
+    `}`,
+    ``,
+    `await server.connect(new StdioServerTransport());`,
+    ``,
+  ].join("\n");
+}
+
+// ─── Live caller — for the hosted bridge ─────────────────────────────────
+async function liveCall({ spec, base_url, auth_header, operation_id, args }) {
+  const tools = specToTools(spec);
+  const tool = tools.find((t) => t.name === operation_id);
+  if (!tool) return { error: `unknown operation: ${operation_id}. Available: ${tools.slice(0, 12).map((t) => t.name).join(", ")}${tools.length > 12 ? ` (+${tools.length - 12} more)` : ""}` };
+  const baseUrl = deriveBaseUrl(spec, base_url);
+  if (!baseUrl) return { error: "no base_url — pass base_url explicitly or include a servers[] entry in the spec" };
+  let path = tool.path;
+  const query = new URLSearchParams();
+  for (const [k, v] of Object.entries(args || {})) {
+    if (k === "body") continue;
+    if (path.includes("{" + k + "}")) { path = path.replace("{" + k + "}", encodeURIComponent(String(v))); continue; }
+    query.set(k, String(v));
+  }
+  const url = baseUrl + path + (query.toString() ? "?" + query.toString() : "");
+  const headers = { "content-type": "application/json", "accept": "application/json", "user-agent": "openapi-to-mcp-bridge/1.0" };
+  if (auth_header) {
+    const [k, ...rest] = String(auth_header).split(":");
+    headers[k.trim()] = rest.join(":").trim();
+  }
+  const body = args && args.body != null ? JSON.stringify(args.body) : undefined;
+  const ctrl = typeof AbortController === "function" ? new AbortController() : null;
+  const t = ctrl ? setTimeout(() => ctrl.abort(), 20000) : null;
+  try {
+    const res = await fetch(url, { method: tool.method, headers, body, signal: ctrl?.signal });
+    const text = await res.text();
+    let data; try { data = JSON.parse(text); } catch { data = text; }
+    return { ok: res.ok, status: res.status, url, method: tool.method, data };
+  } catch (e) {
+    return { error: e?.message || String(e), url, method: tool.method };
+  } finally {
+    if (t) clearTimeout(t);
+  }
+}
+
+// ─── MCP server wiring ───────────────────────────────────────────────────
+const server = new McpServer({
+  name: "openapi-to-mcp-bridge-mcp",
+  version: "1.0.0",
+  description: "Bridge any OpenAPI 3.x spec → MCP server in one call. Inspect tools, preview JSON Schemas, generate a runnable Node MCP server, or stream-call endpoints live.",
+});
+
+server.tool(
+  "from_url",
+  "Fetch an OpenAPI 3.x spec from URL and return a summary (info, server, tool count, tool names).",
+  { url: z.string().url(), base_url_override: z.string().optional() },
+  async ({ url, base_url_override }) => {
+    const spec = await fetchSpec(url);
+    const tools = specToTools(spec);
+    const summary = {
+      ok: true,
+      source: url,
+      title: spec.info?.title,
+      version: spec.info?.version,
+      base_url: deriveBaseUrl(spec, base_url_override),
+      operation_count: tools.length,
+      tools: tools.map((t) => ({ name: t.name, method: t.method, path: t.path, tags: t.tags, required: t.inputSchema.required })),
+    };
+    return { content: [{ type: "text", text: JSON.stringify(summary, null, 2) }] };
+  }
+);
+
+server.tool(
+  "from_spec",
+  "Parse a spec passed inline (JSON string, JSON object, or simple YAML) and return a summary.",
+  { spec: z.union([z.string(), z.record(z.any())]), base_url_override: z.string().optional() },
+  async ({ spec: raw, base_url_override }) => {
+    const spec = parseSpec(raw);
+    const tools = specToTools(spec);
+    const summary = {
+      ok: true,
+      title: spec.info?.title,
+      version: spec.info?.version,
+      base_url: deriveBaseUrl(spec, base_url_override),
+      operation_count: tools.length,
+      tools: tools.map((t) => ({ name: t.name, method: t.method, path: t.path })),
+    };
+    return { content: [{ type: "text", text: JSON.stringify(summary, null, 2) }] };
+  }
+);
+
+server.tool(
+  "preview_tools",
+  "Return MCP-shaped tool definitions (name, description, inputSchema) for every operation in a spec — paste directly into your MCP host.",
+  { spec_or_url: z.string(), include_full_schema: z.boolean().default(true) },
+  async ({ spec_or_url, include_full_schema }) => {
+    const spec = /^https?:\/\//.test(spec_or_url) ? await fetchSpec(spec_or_url) : parseSpec(spec_or_url);
+    const tools = specToTools(spec).map((t) => ({
+      name: t.name,
+      description: t.description,
+      inputSchema: include_full_schema ? t.inputSchema : { type: "object", required: t.inputSchema.required },
+      _hint: `${t.method} ${t.path}`,
+    }));
+    return { content: [{ type: "text", text: JSON.stringify({ count: tools.length, tools }, null, 2) }] };
+  }
+);
+
+server.tool(
+  "generate_server",
+  "Emit a runnable Node MCP server (ESM) wrapping every operation. Set env OPENAPI_BASE_URL and OPENAPI_AUTH_HEADER at runtime.",
+  { spec_or_url: z.string(), name: z.string().optional(), base_url: z.string().optional() },
+  async ({ spec_or_url, name, base_url }) => {
+    const spec = /^https?:\/\//.test(spec_or_url) ? await fetchSpec(spec_or_url) : parseSpec(spec_or_url);
+    const code = generateServerCode(spec, { name, base_url });
+    return { content: [{ type: "text", text: code }] };
+  }
+);
+
+server.tool(
+  "call_endpoint",
+  "Fire one HTTP call against an operationId with validated args (path / query / body) — useful to test the bridge before generating a server.",
+  {
+    spec_or_url: z.string(),
+    operation_id: z.string(),
+    args: z.record(z.any()).default({}),
+    base_url: z.string().optional(),
+    auth_header: z.string().optional().describe('e.g. "Authorization: Bearer XYZ"'),
+  },
+  async ({ spec_or_url, operation_id, args, base_url, auth_header }) => {
+    const spec = /^https?:\/\//.test(spec_or_url) ? await fetchSpec(spec_or_url) : parseSpec(spec_or_url);
+    const out = await liveCall({ spec, base_url, auth_header, operation_id, args });
+    return { content: [{ type: "text", text: JSON.stringify(out, null, 2) }] };
+  }
+);
+
+await server.connect(new StdioServerTransport());

package/mcpize.yaml

@@ -0,0 +1,12 @@
+name: openapi-to-mcp-bridge-mcp
+version: 1.0.0
+description: Bridge any OpenAPI 3.x spec → MCP server in one call. Inspect tools, preview JSON Schemas, generate a runnable Node MCP server, or stream-call endpoints live without writing a wrapper.
+license: MIT
+runtime: node
+entry: index.js
+tools:
+  - from_url
+  - from_spec
+  - preview_tools
+  - generate_server
+  - call_endpoint

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "openapi-to-mcp-bridge-mcp",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Bridge any OpenAPI 3.x spec → MCP server in one call. Inspect tools, preview JSON Schemas, generate a runnable Node MCP server, or stream-call endpoints live without writing a wrapper.",
+  "bin": { "openapi-to-mcp-bridge-mcp": "index.js" },
+  "main": "index.js",
+  "mcp": {
+    "tools": [
+      "from_url",
+      "from_spec",
+      "preview_tools",
+      "generate_server",
+      "call_endpoint"
+    ]
+  },
+  "keywords": [
+    "mcp",
+    "openapi",
+    "swagger",
+    "rest",
+    "bridge",
+    "codegen",
+    "agent"
+  ],
+  "license": "MIT",
+  "author": "lazymac2x",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "latest",
+    "zod": "^3.23.0"
+  }
+}