rapidoc 12.0.0 → 12.1.0

package/src/utils/mcp/workflow-runtime.js

@@ -0,0 +1,374 @@
+/**
+ * RapiDoc MCP workflow runtime: runs the compiled Arazzo workflows of a manifest (see
+ * workflows.js) on top of runtime.js: runtime expressions, success criteria, success and failure
+ * actions (end, goto, retry) and outputs. Kept apart from runtime.js so dist/rapidoc-min.js,
+ * which exports operation tools only, carries no Arazzo code; dist/rapidoc-flow-min.js and
+ * @rapidoc/mcp include it.
+ *
+ * This file is copied verbatim into exported MCP server projects that have workflows as
+ * `workflow-runtime.js`, so it imports only `./runtime.js`.
+ */
+import { createMcpRuntime } from "./runtime.js";
+
+function serialize(value) {
+  if (typeof value === "string") return value;
+  if (value && typeof value === "object") return JSON.stringify(value);
+  return String(value);
+}
+
+function errorResult(text) {
+  return { isError: true, content: [{ type: "text", text }] };
+}
+
+// ---- Arazzo runtime expressions ----
+
+/** RFC 6901 JSON pointer lookup; "" is the whole value. */
+function pointer(value, path) {
+  if (!path) return value;
+  let node = value;
+  for (const raw of path.split("/").slice(1)) {
+    const key = raw.replace(/~1/g, "/").replace(/~0/g, "~");
+    if (node === null || typeof node !== "object") return undefined;
+    node = node[key];
+  }
+  return node;
+}
+
+function walk(value, keys) {
+  let node = value;
+  for (const key of keys) {
+    if (node === null || typeof node !== "object") return undefined;
+    node = node[key];
+  }
+  return node;
+}
+
+/**
+ * One Arazzo runtime expression against the step context: `$inputs.x`, `$steps.id.outputs.x`,
+ * `$statusCode`, `$response.body` (`#/pointer`), `$response.header.Name`, `$request.body`,
+ * `$request.header.Name`, `$url`, `$method`.
+ */
+export function evaluateExpression(expr, ctx) {
+  const m = String(expr).match(/^\$([A-Za-z]+)((?:\.[^.#\s]+)*)(?:#(.*))?$/);
+  if (!m) return undefined;
+  const [, root, dotted, ptr] = m;
+  const keys = dotted ? dotted.slice(1).split(".") : [];
+  switch (root) {
+    case "inputs":
+      return walk(ctx.inputs || {}, keys);
+    case "steps":
+      return walk(ctx.steps || {}, keys);
+    case "statusCode":
+      return ctx.response?.status;
+    case "url":
+      return ctx.request?.url;
+    case "method":
+      return ctx.request?.method;
+    case "response":
+    case "request": {
+      const msg = ctx[root];
+      if (!msg) return undefined;
+      const [part, ...rest] = keys;
+      if (part === "body") return walk(pointer(msg.body, ptr || ""), rest);
+      if (part === "header" || part === "headers") {
+        const name = rest.join(".").toLowerCase();
+        const headers = msg.headers || {};
+        const hit = Object.keys(headers).find((h) => h.toLowerCase() === name);
+        return hit === undefined ? undefined : headers[hit];
+      }
+      if (part === "query" || part === "path") return walk(msg[part] || {}, rest);
+      return undefined;
+    }
+    default:
+      return undefined;
+  }
+}
+
+const WHOLE_EXPRESSION = /^\$[A-Za-z][^\s{}]*$/;
+
+/** A parameter or payload value with its expressions filled in; `{$expr}` inside text is interpolated. */
+export function resolveValue(value, ctx) {
+  if (typeof value === "string") {
+    if (WHOLE_EXPRESSION.test(value)) return evaluateExpression(value, ctx);
+    return value.replace(/\{(\$[^{}]+)\}/g, (_, expr) => {
+      const v = evaluateExpression(expr, ctx);
+      return v === undefined || v === null ? "" : serialize(v);
+    });
+  }
+  if (Array.isArray(value)) return value.map((v) => resolveValue(v, ctx));
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) out[k] = resolveValue(v, ctx);
+    return out;
+  }
+  return value;
+}
+
+// ---- Simple conditions: `$statusCode == 200 && $response.body#/status != 'placed'` ----
+
+function tokenize(condition) {
+  const tokens = [];
+  const re =
+    /\s*(?:(&&|\|\||==|!=|<=|>=|<|>|!|\(|\))|('(?:[^'\\]|\\.)*'|"(?:[^"\\]|\\.)*")|(-?\d+(?:\.\d+)?)|(\$[^\s()&|=!<>]+)|(true|false|null))/y;
+  let last = 0;
+  for (;;) {
+    re.lastIndex = last;
+    const m = re.exec(condition);
+    if (!m) break;
+    last = re.lastIndex;
+    if (m[1]) tokens.push({ op: m[1] });
+    else if (m[2]) tokens.push({ value: m[2].slice(1, -1).replace(/\\(.)/g, "$1") });
+    else if (m[3]) tokens.push({ value: Number(m[3]) });
+    else if (m[4]) tokens.push({ expr: m[4] });
+    else if (m[5]) tokens.push({ value: m[5] === "true" ? true : m[5] === "false" ? false : null });
+  }
+  if (condition.slice(last).trim()) throw new Error(`Cannot parse condition "${condition}"`);
+  return tokens;
+}
+
+/** `==` in a simple condition: null and a missing value are the same; numbers and strings compare as text. */
+function looseEquals(a, b) {
+  if (a === b) return true;
+  const missing = (v) => v === null || v === undefined;
+  if (missing(a) || missing(b)) return missing(a) && missing(b);
+  if (typeof a === "object" || typeof b === "object")
+    return JSON.stringify(a) === JSON.stringify(b);
+  return String(a) === String(b);
+}
+
+/** Evaluates a simple Arazzo condition. Throws when it cannot be parsed. */
+export function evaluateCondition(condition, ctx) {
+  const tokens = tokenize(condition);
+  let i = 0;
+  const peek = () => tokens[i];
+  const takeOp = (...ops) => (peek()?.op && ops.includes(peek().op) ? tokens[i++].op : null);
+  const unary = () => {
+    if (takeOp("!")) return !unary();
+    if (takeOp("(")) {
+      const v = or();
+      if (!takeOp(")")) throw new Error(`Missing ) in "${condition}"`);
+      return v;
+    }
+    const t = tokens[i++];
+    if (!t || t.op) throw new Error(`Unexpected ${t ? t.op : "end"} in "${condition}"`);
+    return t.expr !== undefined ? evaluateExpression(t.expr, ctx) : t.value;
+  };
+  const cmp = () => {
+    const left = unary();
+    const op = takeOp("==", "!=", "<=", ">=", "<", ">");
+    if (!op) return left;
+    const right = unary();
+    if (op === "==") return looseEquals(left, right);
+    if (op === "!=") return !looseEquals(left, right);
+    const [a, b] = [Number(left), Number(right)];
+    if (op === "<") return a < b;
+    if (op === ">") return a > b;
+    if (op === "<=") return a <= b;
+    return a >= b;
+  };
+  const and = () => {
+    let v = cmp();
+    while (takeOp("&&")) v = cmp() && v;
+    return v;
+  };
+  const or = () => {
+    let v = and();
+    while (takeOp("||")) v = and() || v;
+    return v;
+  };
+  const result = or();
+  if (i < tokens.length) throw new Error(`Unexpected ${tokens[i].op ?? "token"} in "${condition}"`);
+  return Boolean(result);
+}
+
+/** Sets the value at a JSON pointer inside a payload (an Arazzo request body replacement). */
+function replaceAt(payload, target, value) {
+  const keys = String(target)
+    .split("/")
+    .slice(1)
+    .map((k) => k.replace(/~1/g, "/").replace(/~0/g, "~"));
+  if (!keys.length) return value;
+  const root = Array.isArray(payload) ? [...payload] : { ...payload };
+  let node = root;
+  for (const [i, key] of keys.entries()) {
+    if (i === keys.length - 1) {
+      node[key] = value;
+      break;
+    }
+    const next = node[key];
+    node[key] = Array.isArray(next) ? [...next] : { ...next };
+    node = node[key];
+  }
+  return root;
+}
+
+const MAX_STEP_RUNS = 1000;
+
+function evaluateAll(criteria, ctx) {
+  return (criteria || []).every((c) => {
+    try {
+      return evaluateCondition(c.condition, ctx);
+    } catch {
+      return false;
+    }
+  });
+}
+
+/**
+ * Runs a workflow tool. Pass as createMcpRuntime's `runWorkflow` option, or use
+ * createMcpWorkflowRuntime().
+ *
+ * @param {object} runtime from createMcpRuntime()
+ * @param {object} tool a manifest tool with `workflow`
+ * @param {object} args the workflow inputs
+ * @param {object} [hooks]
+ * @param {Function} [hooks.onStepStart] gets `{ workflowId, stepId, attempt }` before each request
+ * @param {Function} [hooks.onStep] gets `{ workflowId, stepId, attempt, outcome, request,
+ *   response, outputs, failedCriterion, action }` after each step run
+ * @param {(ms: number) => Promise<void>} [hooks.sleep] waits between retries (default setTimeout)
+ * @param {Function} [hooks.requestHeaders] gets `{ workflowId, stepId, attempt, operation }` and
+ *   returns extra headers for that request (a mock's `Prefer: code=503`, say), or nothing
+ * @returns {Promise<object>} the MCP result: the workflow's outputs as `structuredContent`, or an
+ *   error result naming the step, the failed criterion and the response
+ */
+export async function runWorkflow(runtime, tool, args, hooks = {}) {
+  const workflow = runtime.manifest.workflows?.[tool.workflow];
+  if (!workflow) return errorResult(`Workflow "${tool.workflow}" is not in the manifest`);
+  const sleep = hooks.sleep || ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const inputs = args || {};
+  const required = (workflow.inputs?.required || []).filter((name) => inputs[name] === undefined);
+  if (required.length) return errorResult(`Missing input ${required.join(", ")}`);
+
+  const steps = workflow.steps;
+  const indexOf = (stepId) => steps.findIndex((s) => s.stepId === stepId);
+  const stepsCtx = {};
+  const attempts = new Map();
+  let index = 0;
+  let runs = 0;
+  while (index >= 0 && index < steps.length) {
+    if (++runs > MAX_STEP_RUNS) {
+      return errorResult(`Workflow ${workflow.workflowId} ran more than ${MAX_STEP_RUNS} steps`);
+    }
+    const step = steps[index];
+    const attempt = (attempts.get(step.stepId) || 0) + 1;
+    attempts.set(step.stepId, attempt);
+    const ctx = { inputs, steps: stepsCtx };
+    const stepArgs = {};
+    for (const p of step.parameters || []) stepArgs[p.name] = resolveValue(p.value, ctx);
+    if (step.requestBody) {
+      let payload = resolveValue(step.requestBody.payload, ctx);
+      for (const r of step.requestBody.replacements || []) {
+        payload = replaceAt(payload, r.target, resolveValue(r.value, ctx));
+      }
+      stepArgs.body = payload;
+    }
+    const event = { workflowId: workflow.workflowId, stepId: step.stepId, attempt };
+    hooks.onStepStart?.(event);
+    const headers = hooks.requestHeaders?.({ ...event, operation: step.operation });
+    const sent = await runtime.execute(step.operation, stepArgs, headers ? { headers } : {});
+    const stepCtx = {
+      ...ctx,
+      request: sent.request && {
+        url: sent.request.url,
+        method: sent.request.method,
+        headers: sent.request.headers,
+        body: stepArgs.body,
+      },
+      response: sent.response && {
+        status: sent.response.status,
+        headers: sent.headers,
+        body: sent.data === undefined ? sent.text : sent.data,
+      },
+    };
+    let failedCriterion = sent.error ? sent.error.content[0].text : "";
+    // Without criteria of its own, a step succeeds on a 2xx response
+    if (!failedCriterion && !(step.successCriteria || []).length && !sent.response.ok) {
+      failedCriterion = `HTTP ${sent.response.status}`;
+    }
+    if (!failedCriterion) {
+      for (const c of step.successCriteria || []) {
+        let ok;
+        try {
+          ok = evaluateCondition(c.condition, stepCtx);
+        } catch (err) {
+          ok = false;
+          failedCriterion = err.message;
+        }
+        if (!ok) {
+          failedCriterion ||= c.condition;
+          break;
+        }
+      }
+    }
+    const outcome = failedCriterion ? "failure" : "success";
+    let outputs;
+    if (outcome === "success") {
+      outputs = {};
+      for (const [name, expr] of Object.entries(step.outputs || {})) {
+        outputs[name] = resolveValue(expr, stepCtx);
+      }
+      stepsCtx[step.stepId] = { outputs };
+    }
+    const candidates = outcome === "success" ? step.onSuccess : step.onFailure;
+    const action = (candidates || []).find((a) => evaluateAll(a.criteria, stepCtx));
+    hooks.onStep?.({
+      workflowId: workflow.workflowId,
+      stepId: step.stepId,
+      attempt,
+      outcome,
+      request: stepCtx.request,
+      response: stepCtx.response,
+      outputs,
+      failedCriterion: failedCriterion || undefined,
+      action: action ? { type: action.type, name: action.name, stepId: action.stepId } : null,
+    });
+
+    const failure = (why) =>
+      errorResult(
+        `Workflow ${workflow.workflowId} failed at step ${step.stepId}: ${why}` +
+          (stepCtx.response
+            ? `\nHTTP ${stepCtx.response.status}\n${serialize(stepCtx.response.body)}`
+            : ""),
+      );
+    if (outcome === "success") {
+      if (!action) index++;
+      else if (action.type === "end") break;
+      else if (action.type === "goto") index = indexOf(action.stepId);
+      else index++;
+      continue;
+    }
+    if (!action || action.type === "end") return failure(failedCriterion);
+    if (action.type === "goto") {
+      index = indexOf(action.stepId);
+      continue;
+    }
+    // retry
+    const target = action.stepId ? indexOf(action.stepId) : index;
+    const key = `${step.stepId}:${action.name}`;
+    const tried = (attempts.get(key) || 0) + 1;
+    attempts.set(key, tried);
+    if (tried > (action.retryLimit ?? 1)) {
+      return failure(`${failedCriterion} (after ${action.retryLimit ?? 1} retries)`);
+    }
+    if (action.retryAfter) await sleep(action.retryAfter * 1000);
+    index = target;
+  }
+
+  const outputs = {};
+  for (const [name, expr] of Object.entries(workflow.outputs || {})) {
+    outputs[name] = resolveValue(expr, { inputs, steps: stepsCtx });
+  }
+  return {
+    content: [{ type: "text", text: JSON.stringify(outputs, null, 2) }],
+    structuredContent: outputs,
+  };
+}
+
+/** createMcpRuntime() with workflow support plugged in; `options.sleep` waits between retries. */
+export function createMcpWorkflowRuntime(manifest, options = {}) {
+  return createMcpRuntime(manifest, {
+    ...options,
+    runWorkflow: (runtime, tool, args, hooks) =>
+      runWorkflow(runtime, tool, args, { sleep: options.sleep, ...hooks }),
+  });
+}

package/src/utils/mcp/workflows.js

@@ -0,0 +1,240 @@
+/**
+ * Compiles the workflows of an Arazzo document into the manifest: one tool per workflow, and a
+ * `workflows` entry whose steps name resolved operations (source, method, path), so the runtime
+ * needs no Arazzo or OpenAPI document. A workflow that uses something the runtime does not run
+ * (another workflow, non-simple criteria, `$workflows` or `$components` expressions) is reported
+ * through `onProblem` and left out.
+ */
+import { sanitizeDescription, toSnakeCase } from "./common.js";
+import { toJsonSchema } from "./schema.js";
+import { resolveComponentRef } from "../arazzo/components.js";
+import { resolveOperation } from "../arazzo/operations.js";
+import { collectRefs } from "../arazzo/refs.js";
+
+const PARAM_LOCATIONS = new Set(["path", "query", "header", "cookie"]);
+const ACTION_TYPES = new Set(["end", "goto", "retry"]);
+
+function criteria(list, where, problems) {
+  const out = [];
+  for (const [i, c] of (Array.isArray(list) ? list : []).entries()) {
+    if (!c || typeof c.condition !== "string") continue;
+    const type = typeof c.type === "string" ? c.type : c.type?.type || "simple";
+    if (type !== "simple") {
+      problems.push(
+        `${where}[${i}]: criterion type ${type} is not supported, only simple conditions`,
+      );
+      continue;
+    }
+    out.push({ condition: c.condition });
+  }
+  return out;
+}
+
+function actions(doc, list, kind, where, stepIds, problems) {
+  const out = [];
+  for (const [i, raw] of (Array.isArray(list) ? list : []).entries()) {
+    const a = resolveComponentRef(doc, raw, kind);
+    if (!a || !ACTION_TYPES.has(a.type)) continue;
+    const p = `${where}[${i}]`;
+    if (a.workflowId) {
+      problems.push(`${p}: ${a.type} to another workflow is not supported`);
+      continue;
+    }
+    if (a.stepId && !stepIds.has(a.stepId)) {
+      problems.push(`${p}: no step "${a.stepId}"`);
+      continue;
+    }
+    const action = {
+      name: a.name || "",
+      type: a.type,
+      criteria: criteria(a.criteria, p, problems),
+    };
+    if (a.stepId) action.stepId = a.stepId;
+    if (a.type === "retry") {
+      action.retryLimit = Number.isFinite(a.retryLimit) ? a.retryLimit : 1;
+      action.retryAfter = Number.isFinite(a.retryAfter) ? a.retryAfter : 0;
+    }
+    out.push(action);
+  }
+  return out;
+}
+
+/** The step's own actions, then the workflow's minus those the step overrides by name. */
+function merge(own, inherited) {
+  const names = new Set(own.map((a) => a.name).filter(Boolean));
+  return [...own, ...inherited.filter((a) => !a.name || !names.has(a.name))];
+}
+
+function unsupportedRefs(value, where, problems) {
+  for (const ref of collectRefs(value)) {
+    if (ref.kind === "workflow") {
+      problems.push(`${where}: ${ref.expr} refers to another workflow, which is not supported`);
+    }
+  }
+}
+
+function compileStep(doc, step, workflow, sources, stepIds, problems) {
+  const where = `steps.${step.stepId}`;
+  if (step.workflowId) {
+    problems.push(`${where}: calls workflow "${step.workflowId}", which is not supported`);
+    return null;
+  }
+  const op = resolveOperation(step, sources);
+  if (!op) {
+    const ref = step.operationId || step.operationPath || "(no operation)";
+    problems.push(
+      `${where}: operation ${ref} was not found in ${[...sources.keys()].join(", ") || "any source"}`,
+    );
+    return null;
+  }
+  const params = [];
+  const parameters = [];
+  for (const [i, raw] of (Array.isArray(step.parameters) ? step.parameters : []).entries()) {
+    const p = resolveComponentRef(doc, raw, "parameters");
+    if (!p?.name) continue;
+    if (!PARAM_LOCATIONS.has(p.in)) {
+      problems.push(`${where}.parameters[${i}]: "in" must be path, query, header or cookie`);
+      continue;
+    }
+    params.push({ name: p.name, in: p.in });
+    parameters.push({ name: p.name, in: p.in, value: p.value });
+    unsupportedRefs(p.value, `${where}.parameters[${i}]`, problems);
+  }
+  let requestBody = null;
+  if (step.requestBody && typeof step.requestBody === "object") {
+    const contentType = step.requestBody.contentType || "application/json";
+    requestBody = { contentType, payload: step.requestBody.payload ?? null };
+    if (Array.isArray(step.requestBody.replacements)) {
+      requestBody.replacements = step.requestBody.replacements
+        .filter((r) => r && typeof r.target === "string")
+        .map((r) => ({ target: r.target, value: r.value }));
+    }
+    params.push({ name: "body", in: "body", contentType });
+    unsupportedRefs(step.requestBody, `${where}.requestBody`, problems);
+  }
+  const onSuccess = actions(
+    doc,
+    step.onSuccess,
+    "successActions",
+    `${where}.onSuccess`,
+    stepIds,
+    problems,
+  );
+  const onFailure = actions(
+    doc,
+    step.onFailure,
+    "failureActions",
+    `${where}.onFailure`,
+    stepIds,
+    problems,
+  );
+  const outputs = {};
+  for (const [name, expr] of Object.entries(step.outputs || {})) {
+    outputs[name] = expr;
+    unsupportedRefs(expr, `${where}.outputs.${name}`, problems);
+  }
+  return {
+    stepId: step.stepId,
+    description: step.description || "",
+    operation: {
+      source: op.source,
+      method: op.method.toUpperCase(),
+      path: op.path,
+      params,
+      security: Array.isArray(op.security)
+        ? op.security.filter((s) => s && typeof s === "object")
+        : [],
+    },
+    parameters,
+    requestBody,
+    successCriteria: criteria(step.successCriteria, `${where}.successCriteria`, problems),
+    onSuccess: merge(onSuccess, workflow.successActions),
+    onFailure: merge(onFailure, workflow.failureActions),
+    outputs,
+  };
+}
+
+/**
+ * @param {object} arazzo A parsed Arazzo document
+ * @param {object} options
+ * @param {Map<string, {byId: Map, byPath: Map}>} options.sources operation indexes by Arazzo
+ *   source description name (`indexOperations` / `indexResolvedSpec`); a step resolves against
+ *   them and its `operation.source` is the index's name
+ * @param {(problem: { level: string, path: string, message: string }) => void} [options.onProblem]
+ *   called once per workflow that is left out, with every reason joined
+ * @returns {{ tools: object[], workflows: Record<string, object> }} a tool is
+ *   `{ name, description, inputSchema, annotations, workflow }`; a workflow is
+ *   `{ workflowId, summary, description, inputs, steps, outputs }`
+ */
+export function compileWorkflows(arazzo, options = {}) {
+  const sources = options.sources || new Map();
+  const tools = [];
+  const workflows = {};
+  const list = Array.isArray(arazzo?.workflows) ? arazzo.workflows : [];
+  for (const [wi, w] of list.entries()) {
+    if (!w?.workflowId) continue;
+    const problems = [];
+    const stepsRaw = Array.isArray(w.steps) ? w.steps : [];
+    const stepIds = new Set(stepsRaw.map((s) => s?.stepId).filter(Boolean));
+    const shared = {
+      successActions: actions(
+        arazzo,
+        w.successActions,
+        "successActions",
+        "successActions",
+        stepIds,
+        problems,
+      ),
+      failureActions: actions(
+        arazzo,
+        w.failureActions,
+        "failureActions",
+        "failureActions",
+        stepIds,
+        problems,
+      ),
+    };
+    const steps = stepsRaw
+      .filter((s) => s?.stepId)
+      .map((s) => compileStep(arazzo, s, shared, sources, stepIds, problems))
+      .filter(Boolean);
+    if (!steps.length) problems.push("has no runnable step");
+    const outputs = {};
+    for (const [name, expr] of Object.entries(w.outputs || {})) {
+      outputs[name] = expr;
+      unsupportedRefs(expr, `outputs.${name}`, problems);
+    }
+    if (problems.length) {
+      options.onProblem?.({
+        level: "error",
+        path: `workflows[${wi}]`,
+        message: `workflow ${w.workflowId} is left out of the MCP export: ${problems.join("; ")}`,
+      });
+      continue;
+    }
+    const inputs = w.inputs ? toJsonSchema(w.inputs, arazzo) : { type: "object", properties: {} };
+    if (!inputs.type) inputs.type = "object";
+    if (!inputs.properties) inputs.properties = {};
+    const methods = steps.map((s) => s.operation.method);
+    tools.push({
+      name: toSnakeCase(w.workflowId),
+      description: sanitizeDescription(w.summary || w.description || w.workflowId),
+      inputSchema: inputs,
+      annotations: {
+        readOnlyHint: methods.every((m) => m === "GET"),
+        destructiveHint: methods.some((m) => ["PUT", "PATCH", "DELETE"].includes(m)),
+        idempotentHint: false,
+      },
+      workflow: w.workflowId,
+    });
+    workflows[w.workflowId] = {
+      workflowId: w.workflowId,
+      summary: w.summary || "",
+      description: w.description || "",
+      inputs,
+      steps,
+      outputs,
+    };
+  }
+  return { tools, workflows };
+}