rapidoc 12.0.0 → 12.1.0

package/src/utils/mcp/zip.js

@@ -0,0 +1,102 @@
+/**
+ * A minimal ZIP writer (stored entries, no compression) for the exported MCP project, so the
+ * download needs no library. Entries are UTF-8 text files.
+ */
+
+const CRC_TABLE = (() => {
+  const table = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    table[n] = c >>> 0;
+  }
+  return table;
+})();
+
+export function crc32(bytes) {
+  let crc = 0xffffffff;
+  for (let i = 0; i < bytes.length; i++) crc = CRC_TABLE[(crc ^ bytes[i]) & 0xff] ^ (crc >>> 8);
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+/**
+ * @param {Record<string, string>} files path → text content, in the order they should be stored
+ * @returns {Uint8Array} the archive
+ */
+export function createZip(files) {
+  const encoder = new TextEncoder();
+  const entries = Object.entries(files).map(([path, text]) => ({
+    name: encoder.encode(path),
+    data: encoder.encode(String(text ?? "")),
+  }));
+  for (const e of entries) e.crc = crc32(e.data);
+
+  const localSize = entries.reduce((n, e) => n + 30 + e.name.length + e.data.length, 0);
+  const centralSize = entries.reduce((n, e) => n + 46 + e.name.length, 0);
+  const out = new Uint8Array(localSize + centralSize + 22);
+  const view = new DataView(out.buffer);
+  let pos = 0;
+  const u16 = (v) => {
+    view.setUint16(pos, v, true);
+    pos += 2;
+  };
+  const u32 = (v) => {
+    view.setUint32(pos, v >>> 0, true);
+    pos += 4;
+  };
+  const bytes = (b) => {
+    out.set(b, pos);
+    pos += b.length;
+  };
+  // Fixed timestamp (1980-01-01 00:00), flag bit 11: names are UTF-8
+  const DOS_TIME = 0;
+  const DOS_DATE = 0x21;
+  const FLAGS = 0x0800;
+
+  for (const e of entries) {
+    e.offset = pos;
+    u32(0x04034b50);
+    u16(20);
+    u16(FLAGS);
+    u16(0); // stored
+    u16(DOS_TIME);
+    u16(DOS_DATE);
+    u32(e.crc);
+    u32(e.data.length);
+    u32(e.data.length);
+    u16(e.name.length);
+    u16(0);
+    bytes(e.name);
+    bytes(e.data);
+  }
+  const centralOffset = pos;
+  for (const e of entries) {
+    u32(0x02014b50);
+    u16(20);
+    u16(20);
+    u16(FLAGS);
+    u16(0);
+    u16(DOS_TIME);
+    u16(DOS_DATE);
+    u32(e.crc);
+    u32(e.data.length);
+    u32(e.data.length);
+    u16(e.name.length);
+    u16(0);
+    u16(0);
+    u16(0);
+    u16(0);
+    u32(0);
+    u32(e.offset);
+    bytes(e.name);
+  }
+  u32(0x06054b50);
+  u16(0);
+  u16(0);
+  u16(entries.length);
+  u16(entries.length);
+  u32(centralSize);
+  u32(centralOffset);
+  u16(0);
+  return out;
+}

package/src/utils/mcp-generator.js

@@ -1,143 +1,47 @@
 /**
- * MCP (Model Context Protocol) Server Generator for RapiDoc
+ * MCP (Model Context Protocol) server export for RapiDoc.
  *
- * Implements client-side, zero-runtime-dependency translation from OpenAPI specs
- * into curated, token-efficient MCP servers across multiple language ecosystems:
- *   - TypeScript (@modelcontextprotocol/sdk + zod)
- *   - Python (fastmcp + standard urllib)
- *   - Go (mark3labs/mcp-go)
- *   - C# (.NET / ModelContextProtocol.NET)
- *   - Rust (mcp-sdk / rmcp)
- *   - Java (Spring AI MCP)
- *
- * Honors primary `x-mcp` extensions and compatibility aliases from Redocly,
- * Scalar, OpenAI (x-openai-isConsequential), and Speakeasy.
+ * An OpenAPI document becomes an MCP manifest (plain JSON: one tool per operation, with JSON
+ * Schema arguments and MCP safety annotations), and the exported project is that manifest plus
+ * two fixed files: a runtime that executes it with fetch, and a stdio server built on
+ * @modelcontextprotocol/sdk.
  */
 
 export {
   AUTH_TRANSPORT_HEADERS,
-  VALID_MCP_TARGETS,
-  MCP_TARGET_LABELS,
-  parseMcpTargets,
+  parseMcpEnabled,
   toSnakeCase,
-  toPascalCase,
-  toCamelCase,
   sanitizeDescription,
   deriveToolName,
-  extractParameters,
-  extractMcpOperations,
   estimateTokenCost,
+  envNameFor,
   generateHostConfigs,
 } from "./mcp/common.js";
+export { buildMcpManifest, toJsonSchema, MANIFEST_VERSION } from "./mcp/manifest.js";
+export { compileWorkflows } from "./mcp/workflows.js";
+export { createMcpRuntime, buildRequest, credentialsFromEnv } from "./mcp/runtime.js";
+export { writeMcpProject } from "./mcp/project.js";
+export { createZip } from "./mcp/zip.js";
 
-import { extractMcpOperations, estimateTokenCost, generateHostConfigs } from "./mcp/common.js";
-import {
-  generateTypeScriptMcpServer,
-  generateTypeScriptFiles,
-} from "./mcp/generators/typescript.js";
-import { generatePythonFastMcpServer, generatePythonFiles } from "./mcp/generators/python.js";
-import { generateGoMcpServer, generateGoFiles } from "./mcp/generators/go.js";
-import { generateCSharpMcpServer, generateCSharpFiles } from "./mcp/generators/csharp.js";
-import { generateRustMcpServer, generateRustFiles } from "./mcp/generators/rust.js";
-import { generateJavaMcpServer, generateJavaFiles } from "./mcp/generators/java.js";
-
-export {
-  generateTypeScriptMcpServer,
-  generatePythonFastMcpServer,
-  generateGoMcpServer,
-  generateCSharpMcpServer,
-  generateRustMcpServer,
-  generateJavaMcpServer,
-};
+import { estimateTokenCost, generateHostConfigs } from "./mcp/common.js";
+import { buildMcpManifest } from "./mcp/manifest.js";
+import { writeMcpProject } from "./mcp/project.js";
 
 /**
- * Main orchestrator: extracts MCP operations, computes budget, and generates
- * language-specific server implementation and packaging manifests.
+ * Builds the manifest and the files of the exported project.
  *
- * @param {object} parsedSpec Raw or parsed OpenAPI specification object
- * @param {object} options Target language, server name, and filtering options
- * @returns {object} { target, serverCode, hostConfig, budget, files, extracted }
+ * @param {object} spec Raw OpenAPI object or `ProcessSpec`'s result
+ * @param {object} [options] `serverName`, `includeInternal`, `includeDeprecated`, `arazzo`,
+ *   `workflowRuntime` (the text of workflow-runtime.js for the export; see project.js)
+ * @returns {{ manifest: object, files: Record<string, string>, budget: object, hostConfig: string,
+ *   problems: object[] }} `problems` lists the workflows left out and why
  */
-export function generateMcpServer(parsedSpec, options = {}) {
-  const rawTarget = (options.target || "typescript").toLowerCase();
-  const target = rawTarget === "c#" ? "csharp" : rawTarget;
-  const extracted = extractMcpOperations(parsedSpec, options);
-  const budget = estimateTokenCost(extracted.tools, extracted.resources, extracted.workflows);
-  const hostConfigs = generateHostConfigs(options.serverName || extracted.metadata.title, {
-    target,
-  });
-
-  let serverCode;
-  let targetFiles;
-
-  if (target === "python") {
-    serverCode = generatePythonFastMcpServer(
-      extracted.metadata,
-      extracted.tools,
-      extracted.resources,
-      extracted.workflows,
-      options,
-    );
-    targetFiles = generatePythonFiles(serverCode, extracted.metadata, options);
-  } else if (target === "go") {
-    serverCode = generateGoMcpServer(
-      extracted.metadata,
-      extracted.tools,
-      extracted.resources,
-      extracted.workflows,
-      options,
-    );
-    targetFiles = generateGoFiles(serverCode, extracted.metadata, options);
-  } else if (target === "csharp") {
-    serverCode = generateCSharpMcpServer(
-      extracted.metadata,
-      extracted.tools,
-      extracted.resources,
-      extracted.workflows,
-      options,
-    );
-    targetFiles = generateCSharpFiles(serverCode, extracted.metadata, options);
-  } else if (target === "rust") {
-    serverCode = generateRustMcpServer(
-      extracted.metadata,
-      extracted.tools,
-      extracted.resources,
-      extracted.workflows,
-      options,
-    );
-    targetFiles = generateRustFiles(serverCode, extracted.metadata, options);
-  } else if (target === "java") {
-    serverCode = generateJavaMcpServer(
-      extracted.metadata,
-      extracted.tools,
-      extracted.resources,
-      extracted.workflows,
-      options,
-    );
-    targetFiles = generateJavaFiles(serverCode, extracted.metadata, options);
-  } else {
-    // Default: TypeScript
-    serverCode = generateTypeScriptMcpServer(
-      extracted.metadata,
-      extracted.tools,
-      extracted.resources,
-      extracted.workflows,
-      options,
-    );
-    targetFiles = generateTypeScriptFiles(serverCode, extracted.metadata, options);
-  }
-
-  const files = {
-    "claude_desktop_config.json": hostConfigs.claudeDesktopConfig,
-    ...targetFiles,
-  };
-
-  return {
-    target,
-    serverCode,
-    hostConfig: hostConfigs.claudeDesktopConfig,
-    budget,
-    files,
-    extracted,
-  };
+export function generateMcpServer(spec, options = {}) {
+  const problems = [];
+  const manifest = buildMcpManifest(spec, { ...options, onProblem: (p) => problems.push(p) });
+  const files = writeMcpProject(manifest, options);
+  const budget = estimateTokenCost(manifest);
+  const schemes = Object.values(manifest.sources).flatMap((s) => Object.keys(s.securitySchemes));
+  const hostConfig = generateHostConfigs(manifest.server.name, { schemes }).claudeDesktopConfig;
+  return { manifest, files, budget, hostConfig, problems };
 }

package/src/utils/mock-interceptor.js

@@ -23,29 +23,75 @@ const STATUS_TEXTS = {
   504: "Gateway Timeout",
 };
 
-let isMockActive = false;
 let originalFetch = null;
 let originalXhrOpen = null;
 let originalXhrSend = null;
 let originalXhrSetRequestHeader = null;
 
-let compiledRoutes = [];
-let mockConfig = {
-  statusCode: "",
-  statusStrategy: "first",
-  delay: 0,
-  log: "true",
-};
+/**
+ * One mock per owner (the element that turned it on), so several <rapi-doc> and <rapi-doc-mini>
+ * on a page can each mock their own API: `{ routes, config, cycle }`. Calls without an owner use
+ * DEFAULT_OWNER, so a page with one mocked element works as before.
+ */
+const mocks = new Map();
+const DEFAULT_OWNER = Symbol("rapidoc-mock");
 
-const routeCycleIndices = new Map();
+/**
+ * The status setting: a string of codes (`"200, 404"`) for every operation, or a map by
+ * operation (`{ "POST /store/order": "503, 200", "*": "200" }`, `*` the default), also as JSON
+ * text. Map keys are the spec's method and path template, method case-insensitive.
+ */
+function normalizeStatus(value) {
+  if (value && typeof value === "object") {
+    const map = {};
+    for (const [key, codes] of Object.entries(value)) {
+      const k = key.trim();
+      if (!k || !codes) continue;
+      map[k === "*" ? "*" : k.replace(/^(\w+)\s+/, (m, method) => `${method.toUpperCase()} `)] =
+        String(codes);
+    }
+    return map;
+  }
+  const text = typeof value === "string" ? value.trim() : "";
+  if (text.startsWith("{")) {
+    try {
+      return normalizeStatus(JSON.parse(text));
+    } catch {
+      return "";
+    }
+  }
+  return text;
+}
+
+/** The codes for a route: its own entry of a status map, else the map's `*`, else the string. */
+function codesFor(status, routeKey) {
+  if (!status || typeof status === "string") return status || "";
+  return status[routeKey] ?? status["*"] ?? "";
+}
+
+function normalizeConfig(options = {}, current = {}) {
+  return {
+    statusCode:
+      options.statusCode !== undefined
+        ? normalizeStatus(options.statusCode)
+        : current.statusCode || "",
+    statusStrategy:
+      options.statusStrategy !== undefined
+        ? options.statusStrategy || "first"
+        : current.statusStrategy || "first",
+    delay: options.delay !== undefined ? Number(options.delay) || 0 : current.delay || 0,
+    log: options.log !== undefined ? options.log !== "false" : current.log !== false,
+  };
+}
 
 /**
- * Normalizes and extracts base paths and hostnames from OpenAPI servers array.
+ * The bases a route can be requested under, from the OpenAPI servers: `{ origin, base }` per
+ * server (origin null for a relative server URL), plus the bare path (`{ origin: null, base: "" }`)
+ * so a request without the server's base path still matches.
  */
 function extractServerBases(servers = []) {
-  const bases = new Set();
-  // Always include empty root base path
-  bases.add("");
+  const bases = new Map();
+  bases.set("|", { origin: null, base: "" });
 
   servers.forEach((s) => {
     const rawUrl = s.computedUrl || s.url || "";
@@ -55,17 +101,17 @@ function extractServerBases(servers = []) {
       if (rawUrl.startsWith("http://") || rawUrl.startsWith("https://")) {
         const u = new URL(rawUrl);
         const p = u.pathname.replace(/\/+$/, "");
-        if (p) bases.add(p);
+        bases.set(`${u.origin}|${p}`, { origin: u.origin, base: p });
       } else {
         const p = rawUrl.replace(/\/+$/, "");
-        if (p) bases.add(p.startsWith("/") ? p : `/${p}`);
+        if (p) bases.set(`|${p}`, { origin: null, base: p.startsWith("/") ? p : `/${p}` });
       }
     } catch {
       // Ignore invalid URL formats
     }
   });
 
-  return Array.from(bases);
+  return Array.from(bases.values());
 }
 
 /**
@@ -114,7 +160,11 @@ export function compileRoutes(spec) {
       const endpointBases =
         pathItem.servers?.length > 0 ? extractServerBases(pathItem.servers) : rootBases;
 
-      const patterns = endpointBases.map((base) => compileRoutePattern(pathTemplate, base));
+      const patterns = endpointBases.map(({ origin, base }) => ({
+        regex: compileRoutePattern(pathTemplate, base),
+        origin,
+        base,
+      }));
 
       routes.push({
         method,
@@ -131,10 +181,12 @@ export function compileRoutes(spec) {
 }
 
 /**
- * Matches a request (method + URL) against the compiled routes.
+ * Matches a request (method + URL) against every mock's routes. With several mocks, the most
+ * specific match wins: a route under the server's origin and base path beats one under the base
+ * path alone, which beats a bare path; ties go to the mock enabled first.
  */
 function matchRoute(method, urlStr) {
-  if (!compiledRoutes.length || !urlStr) {
+  if (!mocks.size || !urlStr) {
     return null;
   }
 
@@ -152,30 +204,32 @@ function matchRoute(method, urlStr) {
   const upperMethod = (method || "GET").toUpperCase();
   const pathname = decodeURI(reqUrl.pathname);
 
-  for (const route of compiledRoutes) {
-    if (route.method !== upperMethod) {
-      continue;
-    }
+  let best = null;
+  for (const mock of mocks.values()) {
+    for (const route of mock.routes) {
+      if (route.method !== upperMethod) {
+        continue;
+      }
 
-    for (const pattern of route.patterns) {
-      const match = pathname.match(pattern);
-      if (match) {
-        return {
-          route,
-          pathParams: match.groups || {},
-          url: reqUrl,
-        };
+      for (const pattern of route.patterns) {
+        const match = pathname.match(pattern.regex);
+        if (!match) continue;
+        const rank =
+          (pattern.base ? 1 : 0) + (pattern.origin && pattern.origin === reqUrl.origin ? 1 : 0);
+        if (!best || rank > best.rank) {
+          best = { mock, route, rank, pathParams: match.groups || {}, url: reqUrl };
+        }
       }
     }
   }
 
-  return null;
+  return best;
 }
 
 /**
  * Chooses the status code based on config and strategy (first, cycle, random).
  */
-function selectStatusCode(configuredCodesStr, strategy, endpointKey, responses = {}) {
+function selectStatusCode(configuredCodesStr, strategy, endpointKey, responses = {}, cycle) {
   const codes = (configuredCodesStr || "")
     .split(",")
     .map((s) => s.trim())
@@ -194,10 +248,10 @@ function selectStatusCode(configuredCodesStr, strategy, endpointKey, responses =
     return codes[Math.floor(Math.random() * codes.length)];
   }
 
-  if (strategy === "cycle") {
-    const currentIndex = routeCycleIndices.get(endpointKey) || 0;
+  if (strategy === "cycle" && cycle) {
+    const currentIndex = cycle.get(endpointKey) || 0;
     const selected = codes[currentIndex % codes.length];
-    routeCycleIndices.set(endpointKey, (currentIndex + 1) % codes.length);
+    cycle.set(endpointKey, (currentIndex + 1) % codes.length);
     return selected;
   }
 
@@ -309,23 +363,32 @@ function buildMockResponsePayload(route, statusCode) {
   };
 }
 
+/** The status and payload of a matched request, by the mock that owns the route. */
+function answer(match) {
+  const { config, cycle } = match.mock;
+  const statusCode = selectStatusCode(
+    codesFor(config.statusCode, match.route.routeKey),
+    config.statusStrategy,
+    match.route.routeKey,
+    match.route.responses,
+    cycle,
+  );
+  return { config, statusCode, payload: buildMockResponsePayload(match.route, statusCode) };
+}
+
 /**
- * Enables the in-browser mock server by patching window.fetch and XMLHttpRequest.
+ * Enables the in-browser mock for `options.owner` (the element; omitted: a page-wide default),
+ * replacing that owner's routes and config. Other owners' mocks stay. window.fetch and
+ * XMLHttpRequest are patched once, while at least one mock is enabled.
  */
 export function enableMockServer(spec, options = {}) {
-  mockConfig = {
-    statusCode: options.statusCode || "",
-    statusStrategy: options.statusStrategy || "first",
-    delay: Number(options.delay) || 0,
-    log: options.log !== "false",
-  };
-
-  compiledRoutes = compileRoutes(spec);
-  routeCycleIndices.clear();
-
-  if (isMockActive) {
-    return;
-  }
+  const owner = options.owner || DEFAULT_OWNER;
+  const current = mocks.get(owner);
+  mocks.set(owner, {
+    routes: compileRoutes(spec),
+    config: normalizeConfig(options, current?.config),
+    cycle: new Map(),
+  });
 
   if (typeof window === "undefined") {
     return;
@@ -336,7 +399,7 @@ export function enableMockServer(spec, options = {}) {
     originalFetch = window.fetch;
 
     window.fetch = async function mockFetch(input, init = {}) {
-      if (!isMockActive) {
+      if (!mocks.size) {
         return originalFetch.apply(this, arguments);
       }
 
@@ -359,19 +422,13 @@ export function enableMockServer(spec, options = {}) {
         return originalFetch.apply(this, arguments);
       }
 
-      const statusCode = selectStatusCode(
-        mockConfig.statusCode,
-        mockConfig.statusStrategy,
-        match.route.routeKey,
-        match.route.responses,
-      );
-      const payload = buildMockResponsePayload(match.route, statusCode);
+      const { config, payload } = answer(match);
 
-      if (mockConfig.delay > 0) {
-        await new Promise((resolve) => setTimeout(resolve, mockConfig.delay));
+      if (config.delay > 0) {
+        await new Promise((resolve) => setTimeout(resolve, config.delay));
       }
 
-      if (mockConfig.log) {
+      if (config.log) {
         console.info(
           `%c[RapiDoc Mock]%c ${method.toUpperCase()} ${match.url.pathname} ➔ ${payload.statusCode} ${payload.statusText}`,
           "color:#10b981; font-weight:bold;",
@@ -408,7 +465,7 @@ export function enableMockServer(spec, options = {}) {
     };
 
     window.XMLHttpRequest.prototype.send = function mockXhrSend() {
-      if (!isMockActive) {
+      if (!mocks.size) {
         return originalXhrSend.apply(this, arguments);
       }
 
@@ -417,18 +474,12 @@ export function enableMockServer(spec, options = {}) {
         return originalXhrSend.apply(this, arguments);
       }
 
-      const statusCode = selectStatusCode(
-        mockConfig.statusCode,
-        mockConfig.statusStrategy,
-        match.route.routeKey,
-        match.route.responses,
-      );
-      const payload = buildMockResponsePayload(match.route, statusCode);
+      const { config, payload } = answer(match);
 
-      const delayMs = mockConfig.delay > 0 ? mockConfig.delay : 10;
+      const delayMs = config.delay > 0 ? config.delay : 10;
 
       setTimeout(() => {
-        if (mockConfig.log) {
+        if (config.log) {
           console.info(
             `%c[RapiDoc Mock (XHR)]%c ${this._mockMethod.toUpperCase()} ${match.url.pathname} ➔ ${payload.statusCode} ${payload.statusText}`,
             "color:#10b981; font-weight:bold;",
@@ -465,17 +516,15 @@ export function enableMockServer(spec, options = {}) {
       }, delayMs);
     };
   }
-
-  isMockActive = true;
 }
 
 /**
- * Disables the mock server and restores original network primitives.
+ * Disables the mock of `owner` (omitted: the page-wide default). The original fetch and
+ * XMLHttpRequest come back once no mock is enabled.
  */
-export function disableMockServer() {
-  isMockActive = false;
-  compiledRoutes = [];
-  routeCycleIndices.clear();
+export function disableMockServer(owner = DEFAULT_OWNER) {
+  mocks.delete(owner);
+  if (mocks.size) return;
 
   if (typeof window !== "undefined") {
     if (originalFetch) {
@@ -494,15 +543,15 @@ export function disableMockServer() {
 }
 
 /**
- * Updates mock options without re-registering or recompiling routes.
+ * Updates the options of `options.owner`'s mock (omitted: the page-wide default) without
+ * recompiling its routes. Does nothing for an owner without a mock.
  */
 export function updateMockConfig(options = {}) {
-  if (options.statusCode !== undefined) mockConfig.statusCode = options.statusCode;
-  if (options.statusStrategy !== undefined) mockConfig.statusStrategy = options.statusStrategy;
-  if (options.delay !== undefined) mockConfig.delay = Number(options.delay) || 0;
-  if (options.log !== undefined) mockConfig.log = options.log !== "false";
+  const mock = mocks.get(options.owner || DEFAULT_OWNER);
+  if (mock) mock.config = normalizeConfig(options, mock.config);
 }
 
-export function isMockServerActive() {
-  return isMockActive;
+/** Whether `owner`'s mock is enabled; without an owner, whether any mock is. */
+export function isMockServerActive(owner) {
+  return owner ? mocks.has(owner) : mocks.size > 0;
 }