rapidoc 12.0.0 → 12.1.0

package/src/utils/mcp/manifest.js

@@ -0,0 +1,382 @@
+/**
+ * Builds the MCP manifest: a plain JSON description of an API's tools that a runtime executes.
+ * Pure, no dependencies; takes a raw OpenAPI 3.x / Swagger 2.0 object or the result of
+ * `ProcessSpec` (`tags[].paths[]`).
+ */
+import {
+  AUTH_TRANSPORT_HEADERS,
+  deriveToolName,
+  sanitizeDescription,
+  toSnakeCase,
+} from "./common.js";
+import { resolvePointer, toJsonSchema } from "./schema.js";
+import { compileWorkflows } from "./workflows.js";
+import { indexOperations, indexResolvedSpec } from "../arazzo/operations.js";
+
+export { toJsonSchema };
+
+export const MANIFEST_VERSION = 1;
+
+const METHODS = ["get", "put", "post", "delete", "options", "head", "patch", "trace", "query"];
+const RESOURCE_PATH_HINTS = [
+  "/reference",
+  "/currencies",
+  "/countries",
+  "/tiers",
+  "/categories",
+  "/status",
+  "/schema",
+];
+const SECURITY_KEYS = [
+  "type",
+  "description",
+  "in",
+  "name",
+  "scheme",
+  "bearerFormat",
+  "openIdConnectUrl",
+];
+
+function isProcessedSpec(spec) {
+  return (
+    "specLoadError" in spec ||
+    (Array.isArray(spec.tags) && spec.tags.some((t) => Array.isArray(t?.paths)))
+  );
+}
+
+/**
+ * Follows a `#/...` $ref within `spec` (a few hops, for refs to refs); anything else is returned as is.
+ * A raw spec keeps its parameters, request bodies and path items as $refs to components; a processed
+ * one (`<rapi-doc>`'s resolvedSpec) is already dereferenced.
+ */
+function follow(node, spec) {
+  for (
+    let hops = 0;
+    hops < 10 && typeof node?.$ref === "string" && node.$ref.startsWith("#/");
+    hops++
+  ) {
+    let target = spec;
+    for (const segment of node.$ref.slice(2).split("/")) {
+      const key = decodeURIComponent(segment).replace(/~1/g, "/").replace(/~0/g, "~");
+      target = target?.[key];
+    }
+    if (!target || typeof target !== "object") return node;
+    node = target;
+  }
+  return node;
+}
+
+/** Every operation with the fields the manifest needs, from either spec shape. */
+function collectOperations(spec, processed) {
+  const operations = [];
+  if (processed) {
+    for (const tag of spec.tags || []) {
+      for (const p of tag.paths || []) {
+        operations.push({
+          method: String(p.method || "get").toLowerCase(),
+          path: p.path || "",
+          operationId: p.rawOperation?.operationId || "",
+          summary: p.summary || "",
+          description: p.description || "",
+          deprecated: p.deprecated === true,
+          isWebhook: p.isWebhook === true,
+          internal: p.xInternal === true || p.xHidden === true,
+          parameters: Array.isArray(p.parameters) ? p.parameters : [],
+          requestBody: p.requestBody || null,
+          security: p.security,
+          tag: tag.name || "",
+        });
+      }
+    }
+    return operations;
+  }
+  const params = (list) => (Array.isArray(list) ? list.map((p) => follow(p, spec)) : []);
+  for (const [path, rawItem] of Object.entries(spec.paths || {})) {
+    const item = follow(rawItem, spec);
+    if (!item || typeof item !== "object") continue;
+    const common = params(item.parameters);
+    for (const method of METHODS) {
+      const op = item[method];
+      if (!op || typeof op !== "object") continue;
+      const own = params(op.parameters);
+      // Path-level parameters apply unless the operation redefines them (same name and location)
+      const parameters = common
+        .filter((c) => !own.some((o) => o?.name === c?.name && o?.in === c?.in))
+        .concat(own);
+      operations.push({
+        method,
+        path,
+        operationId: op.operationId || "",
+        summary: op.summary || "",
+        description: op.description || "",
+        deprecated: op.deprecated === true,
+        isWebhook: false,
+        internal:
+          op["x-internal"] === true ||
+          op["x-hidden"] === true ||
+          item["x-internal"] === true ||
+          item["x-hidden"] === true,
+        parameters,
+        requestBody: follow(op.requestBody, spec) || null,
+        security: op.security ?? spec.security,
+        tag: Array.isArray(op.tags) ? op.tags[0] || "" : "",
+      });
+    }
+  }
+  return operations;
+}
+
+/** The spec's security schemes as `{ id: { type, in, name, scheme, ... } }`, from either shape. */
+function collectSecuritySchemes(spec, processed) {
+  const out = {};
+  const add = (id, scheme) => {
+    if (!scheme || typeof scheme !== "object" || !scheme.type) return;
+    const entry = {};
+    for (const key of SECURITY_KEYS) if (scheme[key] !== undefined) entry[key] = scheme[key];
+    if (scheme.type === "oauth2" && scheme.flows && typeof scheme.flows === "object") {
+      entry.flows = scheme.flows;
+    }
+    out[id] = entry;
+  };
+  if (processed) {
+    for (const s of spec.securitySchemes || []) {
+      // The scheme <rapi-doc>'s api-key attributes inject is the page's, not the API's
+      if (s?.securitySchemeId && s.securitySchemeId !== "_rapidoc_api_key") {
+        add(s.securitySchemeId, s.type === "apiKey" ? s : { ...s, in: undefined, name: undefined });
+      }
+    }
+  } else {
+    const schemes = spec.components?.securitySchemes || spec.securityDefinitions || {};
+    for (const [id, scheme] of Object.entries(schemes)) {
+      add(id, scheme?.$ref ? resolvePointer(spec, scheme.$ref) : scheme);
+    }
+  }
+  return out;
+}
+
+function baseUrlOf(spec, processed) {
+  const server = spec.servers?.[0];
+  if (server?.url) {
+    let url = String(server.url);
+    for (const [name, v] of Object.entries(server.variables || {})) {
+      url = url.split(`{${name}}`).join(String(v?.default ?? v?.enum?.[0] ?? ""));
+    }
+    return url;
+  }
+  if (!processed && spec.host) {
+    return `${spec.schemes?.[0] || "https"}://${spec.host}${spec.basePath || ""}`;
+  }
+  return "http://localhost";
+}
+
+/** A parameter's schema, from `schema`, `content` or Swagger 2.0's inline type keywords. */
+function parameterSchema(param, root) {
+  if (param.schema) return toJsonSchema(param.schema, root);
+  if (param.content && typeof param.content === "object") {
+    const first = Object.values(param.content)[0];
+    if (first?.schema) return toJsonSchema(first.schema, root);
+  }
+  const inline = {};
+  for (const key of [
+    "type",
+    "format",
+    "enum",
+    "items",
+    "default",
+    "minimum",
+    "maximum",
+    "pattern",
+  ]) {
+    if (param[key] !== undefined) inline[key] = param[key];
+  }
+  return inline.type ? toJsonSchema(inline, root) : { type: "string" };
+}
+
+function bodyContent(requestBody) {
+  const content = requestBody?.content;
+  if (!content || typeof content !== "object") return null;
+  const types = Object.keys(content);
+  const pick =
+    types.find((t) => t === "application/json") ||
+    types.find((t) => t.endsWith("+json")) ||
+    types.find((t) => t === "application/x-www-form-urlencoded") ||
+    types.find((t) => t === "multipart/form-data") ||
+    types[0];
+  return pick ? { contentType: pick, schema: content[pick]?.schema } : null;
+}
+
+/**
+ * @param {object} spec Raw OpenAPI / Swagger object, or `ProcessSpec`'s result
+ * @param {object} [options]
+ * @param {string} [options.serverName] the MCP server's name; defaults to the API title
+ * @param {object|string} [options.arazzo] a parsed Arazzo document (or JSON text) whose workflows
+ *   become tools; its first OpenAPI source description is this API
+ * @param {(problem: { level: string, path: string, message: string }) => void} [options.onProblem]
+ *   receives one entry per workflow the runtime cannot run, which is left out
+ * @param {string} [options.sourceName] the key of the API in `sources`: the Arazzo document's
+ *   first OpenAPI source name, else `api`
+ * @param {Record<string, object>} [options.sources] the other OpenAPI documents the Arazzo
+ *   document's workflows use, by source description name; each becomes a manifest source and its
+ *   operations resolve for workflow steps
+ * @param {boolean} [options.includeInternal] keep `x-internal` / `x-hidden` operations
+ * @param {boolean} [options.includeDeprecated] keep deprecated operations
+ * @param {boolean} [options.includeOperations] `false` leaves the operations out: a manifest of the
+ *   Arazzo document's workflow tools alone (the sources stay, the runtime needs them)
+ * @returns {object} the manifest: `{ manifestVersion, server, sources, tools, resources,
+ *   workflows }`. A workflow tool has `workflow` (its id in `workflows`) instead of `operation`. Each tool has `name`, `description`, `inputSchema` (JSON Schema; parameters by
+ *   name plus `body`), `annotations` (`readOnlyHint`, `destructiveHint`, `idempotentHint`) and
+ *   `operation` (`source`, `method`, `path`, `params` [{ name, in, arg?, contentType? }],
+ *   `security`).
+ */
+export function buildMcpManifest(spec, options = {}) {
+  const src = spec && typeof spec === "object" ? spec : {};
+  const processed = isProcessedSpec(src);
+  const { includeInternal = false, includeDeprecated = false, includeOperations = true } = options;
+  const info = src.info || {};
+  const title = info.title || "OpenAPI MCP Server";
+  const arazzo = typeof options.arazzo === "string" ? JSON.parse(options.arazzo) : options.arazzo;
+  const firstSource = (arazzo?.sourceDescriptions || []).find(
+    (s) => s?.name && (!s.type || s.type === "openapi"),
+  );
+  const sourceName = options.sourceName || firstSource?.name || "api";
+  const securitySchemes = collectSecuritySchemes(src, processed);
+  // Header, query and cookie parameters that carry a credential are the runtime's business
+  const credentialParams = new Set(
+    Object.values(securitySchemes)
+      .filter((s) => s.type === "apiKey" && s.name)
+      .map((s) => `${s.in || "header"}:${String(s.name).toLowerCase()}`),
+  );
+
+  const tools = [];
+  const resources = [];
+  const usedNames = new Map();
+
+  for (const op of includeOperations ? collectOperations(src, processed) : []) {
+    if (op.isWebhook) continue;
+    if (op.internal && !includeInternal) continue;
+    if (op.deprecated && !includeDeprecated) continue;
+
+    const properties = {};
+    const required = [];
+    const params = [];
+    for (const p of op.parameters) {
+      if (!p?.name) continue;
+      const where = p.in || "query";
+      const lower = String(p.name).toLowerCase();
+      if (where === "header" && AUTH_TRANSPORT_HEADERS.has(lower)) continue;
+      if (credentialParams.has(`${where}:${lower}`)) continue;
+      if (where === "body") {
+        // Swagger 2.0 body parameter
+        const schema = parameterSchema(p, src);
+        if (p.description) schema.description = sanitizeDescription(p.description);
+        properties.body = schema;
+        if (p.required) required.push("body");
+        params.push({ name: "body", in: "body", contentType: "application/json" });
+        continue;
+      }
+      if (where === "formData") continue;
+      let arg = p.name;
+      if (arg in properties) arg = `${p.name}_${where}`;
+      const schema = parameterSchema(p, src);
+      if (p.description) schema.description = sanitizeDescription(p.description);
+      properties[arg] = schema;
+      if (p.required || where === "path") required.push(arg);
+      params.push(arg === p.name ? { name: p.name, in: where } : { name: p.name, in: where, arg });
+    }
+    const body = bodyContent(op.requestBody);
+    if (body) {
+      const schema = body.schema ? toJsonSchema(body.schema, src) : { type: "object" };
+      if (op.requestBody.description) {
+        schema.description = sanitizeDescription(op.requestBody.description);
+      }
+      properties.body = schema;
+      if (op.requestBody.required) required.push("body");
+      params.push({ name: "body", in: "body", contentType: body.contentType });
+    }
+    const inputSchema = { type: "object", properties };
+    if (required.length) inputSchema.required = required;
+
+    let name = toSnakeCase(op.operationId || deriveToolName(op.method, op.path));
+    const seen = usedNames.get(name) || 0;
+    usedNames.set(name, seen + 1);
+    if (seen) name = `${name}_${seen + 1}`;
+
+    const description = sanitizeDescription(
+      op.summary || op.description || `${op.method.toUpperCase()} ${op.path}`,
+    );
+    const operation = {
+      source: sourceName,
+      method: op.method.toUpperCase(),
+      path: op.path,
+      params,
+      security: Array.isArray(op.security)
+        ? op.security.filter((s) => s && typeof s === "object")
+        : [],
+    };
+    const isGet = op.method === "get";
+    const isResource =
+      isGet && !required.length && RESOURCE_PATH_HINTS.some((hint) => op.path.includes(hint));
+    if (isResource) {
+      resources.push({
+        name,
+        uri: `reference://${name.replace(/^get_/, "").replace(/_/g, "-")}`,
+        description,
+        mimeType: "application/json",
+        operation,
+      });
+      continue;
+    }
+    tools.push({
+      name,
+      description,
+      inputSchema,
+      annotations: {
+        readOnlyHint: isGet,
+        // POST adds; PUT, PATCH and DELETE change or remove what is there
+        destructiveHint: ["put", "patch", "delete"].includes(op.method),
+        idempotentHint: ["get", "put", "delete"].includes(op.method),
+      },
+      operation,
+    });
+  }
+
+  const workflows = {};
+  const sources = { [sourceName]: { baseUrl: baseUrlOf(src, processed), securitySchemes } };
+  if (arazzo && typeof arazzo === "object") {
+    const indexes = new Map([
+      [sourceName, processed ? indexResolvedSpec(src) : indexOperations(src)],
+    ]);
+    for (const [name, doc] of Object.entries(options.sources || {})) {
+      if (name === sourceName || !doc || typeof doc !== "object") continue;
+      const docProcessed = isProcessedSpec(doc);
+      indexes.set(name, docProcessed ? indexResolvedSpec(doc) : indexOperations(doc));
+      sources[name] = {
+        baseUrl: baseUrlOf(doc, docProcessed),
+        securitySchemes: collectSecuritySchemes(doc, docProcessed),
+      };
+    }
+    const compiled = compileWorkflows(arazzo, {
+      sources: indexes,
+      onProblem: options.onProblem,
+    });
+    for (const tool of compiled.tools) {
+      const seen = usedNames.get(tool.name) || 0;
+      usedNames.set(tool.name, seen + 1);
+      tools.push(seen ? { ...tool, name: `${tool.name}_${seen + 1}` } : tool);
+    }
+    Object.assign(workflows, compiled.workflows);
+  }
+
+  return {
+    manifestVersion: MANIFEST_VERSION,
+    server: {
+      name: toSnakeCase(options.serverName || title),
+      version: info.version || "1.0.0",
+      description: sanitizeDescription(info.description || ""),
+    },
+    sources,
+    tools,
+    resources,
+    workflows,
+  };
+}

package/src/utils/mcp/project/server.ts

@@ -0,0 +1,53 @@
+/**
+ * MCP server over stdio for the API described in manifest.json. Exported by RapiDoc.
+ *
+ * The tools, resources and the API's base URL come from the manifest and the requests are made
+ * by runtime.js, so this file is the same for every API. Credentials come from environment
+ * variables named after the API's security schemes (see claude_desktop_config.json);
+ * API_BASE_URL overrides the base URL.
+ */
+import { readFileSync } from "node:fs";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListResourcesRequestSchema,
+  ListToolsRequestSchema,
+  ReadResourceRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { createMcpRuntime, credentialsFromEnv } from "./runtime.js";
+
+// workflow-runtime.js is part of the export only when the manifest has workflow tools
+const { runWorkflow } = await import("./workflow-runtime.js").catch(() => ({
+  runWorkflow: undefined,
+}));
+
+const manifest = JSON.parse(readFileSync(new URL("./manifest.json", import.meta.url), "utf8"));
+
+const baseUrls: Record<string, string> = {};
+if (process.env.API_BASE_URL) {
+  for (const name of Object.keys(manifest.sources)) baseUrls[name] = process.env.API_BASE_URL;
+}
+const runtime = createMcpRuntime(manifest, {
+  credentials: credentialsFromEnv(manifest, process.env),
+  baseUrls,
+  runWorkflow,
+});
+
+const server = new Server(
+  { name: manifest.server.name, version: manifest.server.version },
+  { capabilities: { tools: {}, resources: {} } },
+);
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: runtime.listTools() }));
+server.setRequestHandler(CallToolRequestSchema, async (request) =>
+  runtime.callTool(request.params.name, request.params.arguments ?? {}),
+);
+server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+  resources: runtime.listResources(),
+}));
+server.setRequestHandler(ReadResourceRequestSchema, async (request) =>
+  runtime.readResource(request.params.uri),
+);
+
+await server.connect(new StdioServerTransport());
+console.error(`[MCP] ${manifest.server.name}: ${manifest.tools.length} tools on stdio`);

package/src/utils/mcp/project.js

@@ -0,0 +1,88 @@
+/**
+ * Writes the exported MCP server project: the manifest as data, plus fixed files that are the
+ * same for every API (the runtime and a stdio server that reads the manifest).
+ */
+import runtimeSource from "./runtime.js?raw";
+import serverSource from "./project/server.ts?raw";
+import { envNameFor, generateHostConfigs, toSnakeCase } from "./common.js";
+
+/**
+ * @param {object} manifest from buildMcpManifest()
+ * @param {object} [options]
+ * @param {string} [options.serverName] the package name; defaults to the manifest's server name
+ * @param {string} [options.workflowRuntime] the text of workflow-runtime.js, written as
+ *   `workflow-runtime.js` when the manifest has workflows (@rapidoc/mcp and <rapi-flow> supply it;
+ *   dist/rapidoc-min.js does not carry it)
+ * @returns {Record<string, string>} file path → content
+ */
+export function writeMcpProject(manifest, options = {}) {
+  const name = manifest.server.name || "api_mcp_server";
+  const hasWorkflows = Object.keys(manifest.workflows || {}).length > 0;
+  const schemeIds = Object.values(manifest.sources || {}).flatMap((s) =>
+    Object.keys(s.securitySchemes || {}),
+  );
+  const hostConfigs = generateHostConfigs(options.serverName || name, { schemes: schemeIds });
+  const packageJson = {
+    name: toSnakeCase(options.serverName || name).replace(/_/g, "-"),
+    version: manifest.server.version || "1.0.0",
+    private: true,
+    type: "module",
+    scripts: { start: "tsx server.ts" },
+    dependencies: { "@modelcontextprotocol/sdk": "^1.12.0" },
+    devDependencies: { tsx: "^4.19.0" },
+  };
+  const envLines = schemeIds.length
+    ? schemeIds.map((id) => {
+        const scheme = Object.values(manifest.sources)
+          .map((s) => s.securitySchemes?.[id])
+          .find(Boolean);
+        const what =
+          scheme?.type === "apiKey"
+            ? `the API key sent as ${scheme.in || "header"} \`${scheme.name}\``
+            : scheme?.type === "http" && String(scheme.scheme).toLowerCase() === "basic"
+              ? "`user:password` for HTTP Basic"
+              : "the bearer token";
+        return `- \`${envNameFor(id)}\`: ${what} (security scheme \`${id}\`)`;
+      })
+    : ["- `API_KEY`: not needed; this API declares no security scheme"];
+  const readme = `# ${manifest.server.name} MCP server
+
+Exported by RapiDoc from the API's OpenAPI document. \`manifest.json\` lists ${manifest.tools.length} tools${
+    hasWorkflows ? ` (${Object.keys(manifest.workflows).length} of them workflows)` : ""
+  }${manifest.resources.length ? ` and ${manifest.resources.length} resources` : ""}; \`server.ts\` serves them over stdio and \`runtime.js\` makes the requests${
+    hasWorkflows && options.workflowRuntime
+      ? ", with workflow-runtime.js running the workflows"
+      : ""
+  }.
+
+## Run
+
+\`\`\`bash
+npm install
+${schemeIds.map((id) => `${envNameFor(id)}="..." `).join("")}npm start
+\`\`\`
+
+Environment variables:
+
+${envLines.join("\n")}
+- \`API_BASE_URL\`: overrides the base URL in the manifest (${
+    Object.values(manifest.sources)[0]?.baseUrl || ""
+  })
+
+## Use with Claude Desktop or Cursor
+
+Copy the \`mcpServers\` entry from \`claude_desktop_config.json\` into your host's configuration
+and fill in the credentials.
+`;
+  return {
+    "manifest.json": JSON.stringify(manifest, null, 2),
+    "server.ts": serverSource,
+    "runtime.js": runtimeSource,
+    ...(hasWorkflows && options.workflowRuntime
+      ? { "workflow-runtime.js": options.workflowRuntime }
+      : {}),
+    "package.json": JSON.stringify(packageJson, null, 2),
+    "README.md": readme,
+    "claude_desktop_config.json": hostConfigs.claudeDesktopConfig,
+  };
+}