fastmcp 4.17.1 → 4.19.0

package/dist/openapi/index.js

@@ -0,0 +1,662 @@
+import {
+  FastMCP,
+  UserError,
+  jsonSchemaAdapter
+} from "../chunk-UODI5E6U.js";
+import "../chunk-KWRV7CHJ.js";
+
+// src/openapi/loadSpec.ts
+import SwaggerParser from "@apidevtools/swagger-parser";
+async function loadSpec(spec) {
+  const document = await SwaggerParser.bundle(
+    spec
+  );
+  if (!document.openapi?.startsWith("3.")) {
+    throw new Error(
+      `fromOpenAPI only supports OpenAPI 3.x documents (found ${document.openapi ?? document.swagger ?? "an unrecognized version"}). Swagger 2.0 is not supported.`
+    );
+  }
+  return {
+    document,
+    origin: typeof spec === "string" && isHttpUrl(spec) ? spec : void 0
+  };
+}
+function isHttpUrl(value) {
+  return value.startsWith("http://") || value.startsWith("https://");
+}
+
+// src/openapi/naming.ts
+var MAX_NAME_LENGTH = 56;
+var MAX_BASE_LENGTH = MAX_NAME_LENGTH - 5;
+function generateNames(routes, mcpNames) {
+  const names = /* @__PURE__ */ new Map();
+  const used = /* @__PURE__ */ new Set();
+  for (const route of routes) {
+    const base = slugify(baseNameFor(route, mcpNames));
+    let candidate = base;
+    let suffix = 1;
+    while (used.has(candidate)) {
+      suffix += 1;
+      candidate = `${base}_${suffix}`;
+    }
+    used.add(candidate);
+    names.set(route, candidate);
+  }
+  return names;
+}
+function baseNameFor(route, mcpNames) {
+  if (route.operationId) {
+    return mcpNames?.[route.operationId] ?? route.operationId.split("__")[0];
+  }
+  return route.summary || `${route.method}_${route.path}`;
+}
+function slugify(value) {
+  const slug = value.replace(/[^a-zA-Z0-9_]+/g, "_").replace(/_+/g, "_").replace(/^_|_$/g, "").slice(0, MAX_BASE_LENGTH);
+  return slug || "operation";
+}
+
+// src/openapi/requestBuilder.ts
+async function executeRequest(options) {
+  const baseUrl = resolveBaseUrl(
+    options.servers,
+    options.origin,
+    options.baseUrlOverride
+  );
+  const pathParams = {};
+  const query = new URLSearchParams();
+  const headers = new Headers(await resolveHeaders(options.headers));
+  const bodyProps = {};
+  for (const [key, value] of Object.entries(options.args)) {
+    const mapping = options.parameterMap[key];
+    if (!mapping || value === void 0) {
+      continue;
+    }
+    switch (mapping.in) {
+      case "body":
+        bodyProps[mapping.name] = value;
+        break;
+      case "cookie": {
+        const existing = headers.get("cookie");
+        headers.set(
+          "cookie",
+          existing ? `${existing}; ${mapping.name}=${String(value)}` : `${mapping.name}=${String(value)}`
+        );
+        break;
+      }
+      case "header":
+        headers.set(mapping.name, String(value));
+        break;
+      case "path":
+        pathParams[mapping.name] = String(value);
+        break;
+      case "query":
+        for (const item of Array.isArray(value) ? value : [value]) {
+          query.append(mapping.name, String(item));
+        }
+        break;
+    }
+  }
+  let path = options.route.path;
+  for (const [name, value] of Object.entries(pathParams)) {
+    path = path.replace(`{${name}}`, encodeURIComponent(value));
+  }
+  const url = new URL(baseUrl.replace(/\/$/, "") + path);
+  url.search = query.toString();
+  let body;
+  if (Object.keys(bodyProps).length > 0) {
+    const payload = options.wholeBodyKey ? bodyProps[options.wholeBodyKey] : bodyProps;
+    if (options.bodyEncoding === "form") {
+      if (!headers.has("content-type")) {
+        headers.set("content-type", "application/x-www-form-urlencoded");
+      }
+      body = encodeFormBody(payload);
+    } else {
+      if (!headers.has("content-type")) {
+        headers.set("content-type", "application/json");
+      }
+      body = JSON.stringify(payload);
+    }
+  }
+  const response = await options.fetchImpl(url.toString(), {
+    body,
+    headers,
+    method: options.route.method.toUpperCase()
+  });
+  const text = await response.text();
+  if (!response.ok) {
+    throw new UserError(
+      `${options.route.method.toUpperCase()} ${path} failed with ${response.status}: ${text.slice(0, 2e3)}`
+    );
+  }
+  if (response.headers.get("content-type")?.includes("json")) {
+    try {
+      return JSON.stringify(JSON.parse(text), null, 2);
+    } catch {
+      return text;
+    }
+  }
+  return text;
+}
+function resolveBaseUrl(servers, origin, overrideUrl) {
+  if (overrideUrl) {
+    return overrideUrl.replace(/\/$/, "");
+  }
+  const server = servers?.[0];
+  if (!server) {
+    throw new Error(
+      "The OpenAPI document has no `servers` entry. Pass `baseUrl` to fromOpenAPI() explicitly."
+    );
+  }
+  let url = server.url;
+  for (const [name, variable] of Object.entries(server.variables ?? {})) {
+    url = url.replaceAll(`{${name}}`, variable.default);
+  }
+  try {
+    return new URL(url).toString().replace(/\/$/, "");
+  } catch {
+    if (!origin) {
+      throw new Error(
+        `The OpenAPI document's servers[0].url ("${url}") is relative, and the spec was not loaded from an http(s) URL, so it cannot be resolved to an absolute address. Pass \`baseUrl\` to fromOpenAPI() explicitly.`
+      );
+    }
+    return new URL(url, origin).toString().replace(/\/$/, "");
+  }
+}
+function encodeFormBody(payload) {
+  const params = new URLSearchParams();
+  if (payload && typeof payload === "object" && !Array.isArray(payload)) {
+    for (const [key, value] of Object.entries(
+      payload
+    )) {
+      if (value === void 0) {
+        continue;
+      }
+      for (const item of Array.isArray(value) ? value : [value]) {
+        params.append(
+          key,
+          item !== null && typeof item === "object" ? JSON.stringify(item) : String(item)
+        );
+      }
+    }
+  }
+  return params.toString();
+}
+async function resolveHeaders(headers) {
+  if (!headers) {
+    return {};
+  }
+  return typeof headers === "function" ? await headers() : { ...headers };
+}
+
+// src/openapi/resourceMapping.ts
+function buildResourceMapping(route, name, parameterMap, requiredKeys) {
+  const entries = Object.entries(parameterMap);
+  if (entries.length === 0) {
+    return { kind: "resource", uri: `openapi://${name}${route.path}` };
+  }
+  const required = new Set(requiredKeys ?? []);
+  const args = [];
+  const queryKeys = [];
+  let path = route.path;
+  for (const [flatKey, mapping] of entries) {
+    if (mapping.in === "path") {
+      if (flatKey !== mapping.name) {
+        path = path.replace(`{${mapping.name}}`, `{${flatKey}}`);
+      }
+    } else {
+      queryKeys.push(flatKey);
+    }
+    args.push({ name: flatKey, required: required.has(flatKey) });
+  }
+  const uriTemplate = `openapi://${name}${path}` + (queryKeys.length > 0 ? `{?${queryKeys.join(",")}}` : "");
+  return { args, kind: "template", uriTemplate };
+}
+function isEligibleForResource(route) {
+  return route.parameters.every((param) => {
+    if (param.in === "header" || param.in === "cookie") {
+      return false;
+    }
+    return param.schema?.type !== "array";
+  });
+}
+
+// src/openapi/routes.ts
+var HTTP_METHODS = ["get", "put", "post", "delete", "patch"];
+function extractRoutes(document) {
+  const routes = [];
+  for (const [path, pathItem] of Object.entries(document.paths ?? {})) {
+    const pathLevelParams = (pathItem.parameters ?? []).map(
+      (param) => resolveRef(document, param)
+    );
+    for (const method of HTTP_METHODS) {
+      const operation = pathItem[method];
+      if (!operation) {
+        continue;
+      }
+      const operationParams = (operation.parameters ?? []).map(
+        (param) => resolveRef(document, param)
+      );
+      routes.push({
+        deprecated: operation.deprecated ?? false,
+        method,
+        operationId: operation.operationId,
+        parameters: mergeParameters(pathLevelParams, operationParams),
+        path,
+        requestBody: operation.requestBody ? resolveRef(document, operation.requestBody) : void 0,
+        summary: operation.summary,
+        tags: operation.tags ?? []
+      });
+    }
+  }
+  return routes;
+}
+function mergeParameters(pathLevel, operationLevel) {
+  const overridden = new Set(
+    operationLevel.map((param) => `${param.in}:${param.name}`)
+  );
+  return [
+    ...pathLevel.filter(
+      (param) => !overridden.has(`${param.in}:${param.name}`)
+    ),
+    ...operationLevel
+  ];
+}
+function resolveRef(document, value) {
+  if (!value || typeof value !== "object" || !("$ref" in value)) {
+    return value;
+  }
+  const pointer = value.$ref;
+  if (!pointer.startsWith("#/")) {
+    throw new Error(`Unexpected external $ref after bundling: ${pointer}`);
+  }
+  const segments = pointer.slice(2).split("/").map(
+    (segment) => decodeURIComponent(segment.replaceAll("~1", "/").replaceAll("~0", "~"))
+  );
+  let node = document;
+  for (const segment of segments) {
+    node = node?.[segment];
+  }
+  return node;
+}
+
+// src/openapi/schemas.ts
+var SCHEMA_MAP_KEYS = /* @__PURE__ */ new Set([
+  "$defs",
+  "definitions",
+  "dependentSchemas",
+  "patternProperties",
+  "properties"
+]);
+var DATA_KEYS = /* @__PURE__ */ new Set(["const", "default", "enum", "example", "examples"]);
+function buildFlatSchema(route, sharedDefs) {
+  const byName = /* @__PURE__ */ new Map();
+  for (const param of route.parameters) {
+    const list = byName.get(param.name) ?? [];
+    list.push(param);
+    byName.set(param.name, list);
+  }
+  const {
+    bodyEncoding,
+    properties: bodyProperties,
+    unsupportedBodyContentType,
+    wholeBodyKey
+  } = extractBodyProperties(
+    route.method === "get" ? void 0 : route.requestBody,
+    sharedDefs
+  );
+  const properties = {};
+  const required = [];
+  const parameterMap = {};
+  for (const [name, occurrences] of byName) {
+    const collides = occurrences.length > 1 || bodyProperties.has(name);
+    for (const param of occurrences) {
+      const key = collides ? `${name}__${param.in}` : name;
+      properties[key] = rewriteComponentRefs(
+        param.schema ?? { type: "string" }
+      );
+      parameterMap[key] = { in: param.in, name };
+      if (param.in === "path" || param.required) {
+        required.push(key);
+      }
+    }
+  }
+  for (const [name, { required: isRequired, schema }] of bodyProperties) {
+    properties[name] = rewriteComponentRefs(schema);
+    parameterMap[name] = { in: "body", name };
+    if (isRequired) {
+      required.push(name);
+    }
+  }
+  const flatSchema = {
+    additionalProperties: false,
+    properties,
+    type: "object",
+    ...required.length > 0 ? { required } : {}
+  };
+  const usedDefs = sharedDefs && filterReferencedDefs(properties, sharedDefs);
+  if (usedDefs) {
+    flatSchema.$defs = usedDefs;
+  }
+  return {
+    bodyEncoding,
+    flatSchema,
+    parameterMap,
+    unsupportedBodyContentType,
+    wholeBodyKey
+  };
+}
+function buildSharedDefs(document) {
+  const schemas = document.components?.schemas;
+  if (!schemas || Object.keys(schemas).length === 0) {
+    return void 0;
+  }
+  return rewriteNode(schemas, "schemaMap");
+}
+function rewriteComponentRefs(value) {
+  return rewriteNode(value, "schema");
+}
+function childMode(key) {
+  if (DATA_KEYS.has(key)) {
+    return "data";
+  }
+  return SCHEMA_MAP_KEYS.has(key) ? "schemaMap" : "schema";
+}
+function componentSchemaName(ref) {
+  for (const prefix of ["#/components/schemas/", "#/$defs/"]) {
+    if (ref.startsWith(prefix)) {
+      return ref.slice(prefix.length);
+    }
+  }
+  return void 0;
+}
+function extractBodyProperties(requestBody, sharedDefs) {
+  const properties = /* @__PURE__ */ new Map();
+  const content = requestBody?.content;
+  if (!content) {
+    return { properties };
+  }
+  const hasJson = "application/json" in content;
+  const hasForm = "application/x-www-form-urlencoded" in content;
+  if (!hasJson && !hasForm) {
+    const contentTypes = Object.keys(content);
+    return contentTypes.length > 0 ? { properties, unsupportedBodyContentType: contentTypes[0] } : { properties };
+  }
+  const bodyEncoding = hasJson ? "json" : "form";
+  const declaredSchema = hasJson ? content["application/json"]?.schema : content["application/x-www-form-urlencoded"]?.schema;
+  if (!declaredSchema) {
+    return { bodyEncoding, properties };
+  }
+  const schema = bodyEncoding === "form" ? resolveComponentRef(declaredSchema, sharedDefs) : declaredSchema;
+  const schemaProperties = schema.properties;
+  if (schema.type === "object" && schemaProperties) {
+    const requiredNames = new Set(
+      schema.required ?? []
+    );
+    for (const [name, propertySchema] of Object.entries(schemaProperties)) {
+      properties.set(name, {
+        required: requiredNames.has(name),
+        schema: propertySchema
+      });
+    }
+    return { bodyEncoding, properties };
+  }
+  if (bodyEncoding === "form") {
+    return {
+      properties,
+      unsupportedBodyContentType: "application/x-www-form-urlencoded"
+    };
+  }
+  properties.set("body", {
+    required: requestBody?.required ?? false,
+    schema
+  });
+  return { bodyEncoding, properties, wholeBodyKey: "body" };
+}
+function filterReferencedDefs(node, allDefs) {
+  const referenced = /* @__PURE__ */ new Set();
+  const stack = [node];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    if (Array.isArray(current)) {
+      stack.push(...current);
+      continue;
+    }
+    if (!current || typeof current !== "object") {
+      continue;
+    }
+    for (const [key, value] of Object.entries(
+      current
+    )) {
+      if (key === "$ref" && typeof value === "string" && value.startsWith("#/$defs/")) {
+        const name = value.slice("#/$defs/".length);
+        if (allDefs[name] && !referenced.has(name)) {
+          referenced.add(name);
+          stack.push(allDefs[name]);
+        }
+        continue;
+      }
+      stack.push(value);
+    }
+  }
+  if (referenced.size === 0) {
+    return void 0;
+  }
+  return Object.fromEntries(
+    [...referenced].map((name) => [name, allDefs[name]])
+  );
+}
+function normalizeNullable(schema) {
+  if (!("nullable" in schema)) {
+    return schema;
+  }
+  const { nullable, type, ...rest } = schema;
+  if (nullable !== true) {
+    return rest;
+  }
+  if (typeof type === "string") {
+    return { ...rest, type: [type, "null"] };
+  }
+  if (Array.isArray(type)) {
+    return { ...rest, type: [.../* @__PURE__ */ new Set(["null", ...type])] };
+  }
+  return rest;
+}
+function resolveComponentRef(schema, sharedDefs) {
+  const seen = /* @__PURE__ */ new Set();
+  let current = schema;
+  let ref = current.$ref;
+  while (typeof ref === "string") {
+    const name = componentSchemaName(ref);
+    const target = name === void 0 ? void 0 : sharedDefs?.[name];
+    if (name === void 0 || target === void 0 || seen.has(name)) {
+      break;
+    }
+    seen.add(name);
+    current = target;
+    ref = current.$ref;
+  }
+  return current;
+}
+function rewriteNode(value, mode) {
+  if (mode === "data") {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => rewriteNode(item, "schema"));
+  }
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+  const entries = Object.entries(value).map(
+    ([key, entryValue]) => {
+      if (mode === "schemaMap") {
+        return [key, rewriteNode(entryValue, "schema")];
+      }
+      if (key === "$ref" && typeof entryValue === "string" && entryValue.startsWith("#/components/schemas/")) {
+        return [key, entryValue.replace("#/components/schemas/", "#/$defs/")];
+      }
+      return [key, rewriteNode(entryValue, childMode(key))];
+    }
+  );
+  const rewritten = Object.fromEntries(entries);
+  return mode === "schemaMap" ? rewritten : normalizeNullable(rewritten);
+}
+
+// src/openapi/selection.ts
+var DEFAULT_MAX_OPERATIONS = 40;
+var METHOD_PRIORITY = {
+  delete: 4,
+  get: 0,
+  patch: 3,
+  post: 1,
+  put: 2
+};
+function selectRoutes(routes, options) {
+  let selected = routes.filter((route) => !route.deprecated);
+  if (options.include) {
+    const include = options.include;
+    selected = selected.filter((route) => include(toSummary(route)));
+  }
+  if (options.exclude) {
+    const exclude = options.exclude;
+    selected = selected.filter((route) => !exclude(toSummary(route)));
+  }
+  selected = [...selected].sort((a, b) => {
+    const byMethod = METHOD_PRIORITY[a.method] - METHOD_PRIORITY[b.method];
+    return byMethod !== 0 ? byMethod : a.path.localeCompare(b.path);
+  });
+  const noSelectionGiven = !options.include && !options.exclude;
+  if (noSelectionGiven && options.maxTools === void 0 && selected.length > DEFAULT_MAX_OPERATIONS) {
+    throw new Error(
+      `fromOpenAPI found ${selected.length} operations, which exceeds the default limit of ${DEFAULT_MAX_OPERATIONS}. This is a deliberate stop, not a bug: turning every operation in a large spec into a tool produces a tool list most MCP clients can't use well. Pass \`include\`/\`exclude\` to choose the operations you actually want, or \`maxTools\` to raise this limit explicitly.`
+    );
+  }
+  if (options.maxTools !== void 0 && selected.length > options.maxTools) {
+    throw new Error(
+      `fromOpenAPI found ${selected.length} operations, which exceeds maxTools (${options.maxTools}). Narrow the spec with \`include\`/\`exclude\`, or raise \`maxTools\`.`
+    );
+  }
+  return selected;
+}
+function toSummary(route) {
+  return {
+    deprecated: route.deprecated,
+    method: route.method,
+    operationId: route.operationId,
+    path: route.path,
+    tags: route.tags
+  };
+}
+
+// src/openapi/fromOpenAPI.ts
+async function fromOpenAPI(options) {
+  const { document, origin } = await loadSpec(options.spec);
+  const routes = extractRoutes(document);
+  const selected = selectRoutes(routes, options);
+  const names = generateNames(selected, options.mcpNames);
+  const sharedDefs = buildSharedDefs(document);
+  const server = options.server ?? new FastMCP({
+    name: options.name ?? document.info?.title ?? "OpenAPI Server",
+    version: options.version ?? "1.0.0"
+  });
+  const skippedOperations = [];
+  for (const route of selected) {
+    const name = names.get(route);
+    if (!name) {
+      continue;
+    }
+    const {
+      bodyEncoding,
+      flatSchema,
+      parameterMap,
+      unsupportedBodyContentType,
+      wholeBodyKey
+    } = buildFlatSchema(route, sharedDefs);
+    const execOptions = {
+      baseUrlOverride: options.baseUrl,
+      fetchImpl: options.fetch ?? fetch,
+      headers: options.headers,
+      origin,
+      parameterMap,
+      route,
+      servers: document.servers
+    };
+    if (options.resources && route.method === "get" && isEligibleForResource(route)) {
+      registerResource(
+        server,
+        route,
+        name,
+        parameterMap,
+        flatSchema.required,
+        execOptions
+      );
+      continue;
+    }
+    if (unsupportedBodyContentType) {
+      skippedOperations.push({
+        contentType: unsupportedBodyContentType,
+        method: route.method,
+        path: route.path
+      });
+      continue;
+    }
+    server.addTool({
+      description: route.summary ?? `${route.method.toUpperCase()} ${route.path}`,
+      execute: async (args) => executeRequest({
+        ...execOptions,
+        args,
+        bodyEncoding,
+        wholeBodyKey
+      }),
+      name,
+      parameters: jsonSchemaAdapter(flatSchema)
+    });
+  }
+  if (skippedOperations.length > 0) {
+    console.warn(
+      `fromOpenAPI: skipped ${skippedOperations.length} operation(s) whose request body can't be turned into tool parameters (supported: application/json, or application/x-www-form-urlencoded with a flat object schema): ` + skippedOperations.map(
+        (op) => `${op.method.toUpperCase()} ${op.path} (${op.contentType})`
+      ).join(", ")
+    );
+  }
+  return server;
+}
+function registerResource(server, route, name, parameterMap, requiredKeys, execOptions) {
+  const mapping = buildResourceMapping(route, name, parameterMap, requiredKeys);
+  const description = route.summary ?? `GET ${route.path}`;
+  if (mapping.kind === "resource") {
+    server.addResource({
+      description,
+      load: async () => wrapAsResourceResult(
+        await executeRequest({ ...execOptions, args: {} })
+      ),
+      name,
+      uri: mapping.uri
+    });
+    return;
+  }
+  server.addResourceTemplate({
+    arguments: mapping.args,
+    description,
+    load: async (args) => wrapAsResourceResult(
+      await executeRequest({
+        ...execOptions,
+        args
+      })
+    ),
+    name,
+    uriTemplate: mapping.uriTemplate
+  });
+}
+function wrapAsResourceResult(text) {
+  try {
+    JSON.parse(text);
+    return { mimeType: "application/json", text };
+  } catch {
+    return { mimeType: "text/plain", text };
+  }
+}
+export {
+  fromOpenAPI
+};
+//# sourceMappingURL=index.js.map