@ttoss/http-server-mcp-openapi 0.1.0

package/dist/index.mjs

@@ -0,0 +1,434 @@
+/** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
+import { registerToolFromSchema } from "@ttoss/http-server-mcp";
+
+//#region src/schema.ts
+var getAlternativeSchemas = schema => {
+  if (Array.isArray(schema.oneOf) && schema.oneOf.length > 0) return schema.oneOf;
+  if (Array.isArray(schema.anyOf) && schema.anyOf.length > 0) return schema.anyOf;
+};
+var mergeResolvedSchemas = resolvedAlternatives => {
+  const mergedProperties = Object.assign({}, ...resolvedAlternatives.map(candidate => {
+    return candidate.properties ?? {};
+  }));
+  const requiredIntersection = resolvedAlternatives.reduce((current, candidate) => {
+    const required = candidate.required ?? [];
+    if (current === void 0) return [...required];
+    return current.filter(field => {
+      return required.includes(field);
+    });
+  }, void 0);
+  return {
+    type: "object",
+    properties: Object.keys(mergedProperties).length > 0 ? mergedProperties : void 0,
+    required: requiredIntersection && requiredIntersection.length > 0 ? requiredIntersection : void 0
+  };
+};
+var dereferenceValue = args => {
+  const {
+    value,
+    spec,
+    seenRefs
+  } = args;
+  if (Array.isArray(value)) return value.map(item => {
+    return dereferenceValue({
+      value: item,
+      spec,
+      seenRefs
+    });
+  });
+  if (value && typeof value === "object") {
+    const obj = value;
+    if (typeof obj.$ref === "string") {
+      const refName = obj.$ref.replace("#/components/schemas/", "");
+      if (seenRefs.has(refName)) return {};
+      const resolved = spec.components?.schemas?.[refName];
+      return dereferenceValue({
+        value: resolved,
+        spec,
+        seenRefs: new Set(seenRefs).add(refName)
+      });
+    }
+    const result = {};
+    for (const [key, entryValue] of Object.entries(obj)) result[key] = dereferenceValue({
+      value: entryValue,
+      spec,
+      seenRefs
+    });
+    return result;
+  }
+  return value;
+};
+/**
+* Recursively inlines every `$ref` in a schema (including refs nested inside
+* `properties`, `items`, `oneOf`, `anyOf`, etc.), producing a self-contained
+* schema safe to hand to an MCP client or LLM provider as a tool definition —
+* provider tool schemas have no `components` section to resolve refs against.
+*/
+var dereferenceSchema = (schema, spec) => {
+  if (!schema) return schema;
+  return dereferenceValue({
+    value: schema,
+    spec,
+    seenRefs: /* @__PURE__ */new Set()
+  });
+};
+/**
+* Resolves a schema down to a single object shape: follows a top-level `$ref`
+* and merges `oneOf` / `anyOf` alternatives (union of properties, intersection
+* of `required`) so the caller sees one flat property set.
+*/
+var resolveSchema = (schema, spec) => {
+  if (!schema) return {};
+  if (typeof schema.$ref === "string") {
+    const refName = schema.$ref.replace("#/components/schemas/", "");
+    const resolved = spec.components?.schemas?.[refName];
+    return resolveSchema(resolved, spec);
+  }
+  const alternatives = getAlternativeSchemas(schema);
+  if (alternatives) return mergeResolvedSchemas(alternatives.map(candidate => {
+    return resolveSchema(candidate, spec);
+  }));
+  return schema;
+};
+/** Follows a parameter `$ref` into `components.parameters`, if present. */
+var resolveParameter = (param, spec) => {
+  if (!param) return {};
+  if (typeof param.$ref === "string") {
+    const refName = param.$ref.replace("#/components/parameters/", "");
+    return spec.components?.parameters?.[refName] || {};
+  }
+  return param;
+};
+/** Builds a function that substitutes path params into the path template. */
+var buildPathFn = (pathTemplate, pathParams) => {
+  return args => {
+    let result = pathTemplate;
+    for (const {
+      name,
+      camelName
+    } of pathParams) {
+      const value = args[camelName];
+      if (value !== void 0) result = result.replace(`{${name}}`, encodeURIComponent(String(value)));
+    }
+    return result;
+  };
+};
+/**
+* Builds a function that serialises query params into a query string
+* (including the leading `?`). Returns `undefined` when the op has no query
+* params. Array values are appended once per element.
+*/
+var buildQueryFn = queryParams => {
+  if (queryParams.length === 0) return void 0;
+  return args => {
+    const search = new URLSearchParams();
+    for (const {
+      name,
+      camelName
+    } of queryParams) {
+      const value = args[camelName];
+      if (value === void 0 || value === null) continue;
+      if (Array.isArray(value)) for (const item of value) search.append(name, String(item));else search.append(name, String(value));
+    }
+    const qs = search.toString();
+    return qs ? `?${qs}` : "";
+  };
+};
+/**
+* Builds a function that maps camelCase args back to a snake_case request
+* body, skipping `undefined` args. Returns `undefined` when the op has no body.
+*/
+var buildBodyFn = bodyProps => {
+  if (bodyProps.length === 0) return void 0;
+  return args => {
+    const body = {};
+    for (const {
+      snakeName,
+      camelName
+    } of bodyProps) if (args[camelName] !== void 0) body[snakeName] = args[camelName];
+    return body;
+  };
+};
+
+//#endregion
+//#region src/types.ts
+var DEFAULT_EXCLUDE_EXTENSION = "x-mcp-exclude";
+var DEFAULT_SERVER_MANAGED_EXTENSION = "x-mcp-server-managed";
+
+//#endregion
+//#region src/toolDefinitions.ts
+/**
+* Folds `_` and `-` separators into camelCase. OpenAPI operation and parameter
+* names may be snake_case (`agent_id`) or kebab-case (`list-tools`), and MCP
+* tool inputs are camelCase by convention, so both are folded here.
+*/
+var snakeToCamel = str => {
+  return str.replace(/[_-]([a-z])/g, (_, letter) => {
+    return letter.toUpperCase();
+  });
+};
+/** Converts a camelCase `operationId` to a kebab-case tool name. */
+var operationIdToToolName = operationId => {
+  return operationId.replace(/([A-Z])/g, "-$1").toLowerCase().replace(/^-/, "");
+};
+var getJsonSchemaType = schemaType => {
+  if (schemaType === "integer" || schemaType === "number") return "number";
+  if (schemaType === "boolean") return "boolean";
+  if (schemaType === "array") return "array";
+  if (schemaType === "object") return "object";
+  return "string";
+};
+var sanitizeDescription = description => {
+  return (description || "").replace(/'/g, "\\'").replace(/\n/g, " ").trim();
+};
+var buildInputSchema = (pathParams, queryParams, bodyProps) => {
+  const allParams = [...pathParams, ...queryParams, ...bodyProps];
+  if (allParams.length === 0) return {
+    type: "object"
+  };
+  const requiredFields = [...pathParams.map(p => {
+    return p.camelName;
+  }), ...queryParams.filter(p => {
+    return p.required;
+  }).map(p => {
+    return p.camelName;
+  }), ...bodyProps.filter(p => {
+    return p.required;
+  }).map(p => {
+    return p.camelName;
+  })];
+  const properties = {};
+  for (const param of allParams) if ("type" in param) {
+    const jsonType = getJsonSchemaType(param.type);
+    const description = sanitizeDescription(param.description);
+    if (param.type === "array") {
+      const itemsSchema = "items" in param && param.items ? param.items : {
+        type: "string"
+      };
+      properties[param.camelName] = {
+        type: "array",
+        items: itemsSchema,
+        description
+      };
+    } else properties[param.camelName] = {
+      type: jsonType,
+      description
+    };
+  } else properties[param.camelName] = {
+    type: "string",
+    description: ""
+  };
+  return {
+    type: "object",
+    properties,
+    required: requiredFields.length > 0 ? requiredFields : void 0
+  };
+};
+var extractPathParams = args => {
+  return (args.parameters || []).map(p => {
+    return resolveParameter(p, args.spec);
+  }).filter(p => {
+    return p.in === "path";
+  }).map(p => {
+    return {
+      name: p.name || "",
+      camelName: snakeToCamel(p.name || "")
+    };
+  });
+};
+var extractQueryParams = args => {
+  return (args.parameters || []).map(p => {
+    return resolveParameter(p, args.spec);
+  }).filter(p => {
+    return p.in === "query";
+  }).map(p => {
+    return {
+      name: p.name || "",
+      camelName: snakeToCamel(p.name || ""),
+      description: p.description || "",
+      required: p.required || false,
+      type: p.schema?.type || "string"
+    };
+  });
+};
+var resolveBodySchema = args => {
+  const rawBodySchema = args.requestBody?.content?.["application/json"]?.schema;
+  return resolveSchema(dereferenceSchema(rawBodySchema, args.spec), args.spec);
+};
+/**
+* snake_case names of every top-level property an operation's request schema
+* declares, including server-managed ones.
+*/
+var extractAcceptedBodyFields = args => {
+  const bodySchema = resolveBodySchema(args);
+  return Object.keys(bodySchema?.properties ?? {});
+};
+var extractBodyProps = args => {
+  const bodySchema = resolveBodySchema(args);
+  if (!bodySchema?.properties) return [];
+  return Object.entries(bodySchema.properties).filter(([, value]) => {
+    return !value[args.serverManagedExtension];
+  }).map(([key, value]) => {
+    const val = value;
+    return {
+      snakeName: key,
+      camelName: snakeToCamel(key),
+      description: typeof val.description === "string" ? val.description : "",
+      required: (bodySchema.required || []).includes(key),
+      type: typeof val.type === "string" ? val.type : "string",
+      items: val.items
+    };
+  });
+};
+/** Collects every `x-` prefixed extension declared on the operation. */
+var extractExtensions = operation => {
+  const extensions = {};
+  for (const [key, value] of Object.entries(operation)) if (key.startsWith("x-")) extensions[key] = value;
+  return extensions;
+};
+var processOperation = args => {
+  const httpMethod = args.method.toUpperCase();
+  if (!["GET", "POST", "PUT", "PATCH", "DELETE"].includes(httpMethod)) return null;
+  if (!args.operation.operationId) return null;
+  if (args.operation[args.options.excludeExtension]) return null;
+  const toolName = operationIdToToolName(args.operation.operationId);
+  const pathParams = extractPathParams({
+    parameters: args.operation.parameters || [],
+    spec: args.spec
+  });
+  const queryParams = extractQueryParams({
+    parameters: args.operation.parameters || [],
+    spec: args.spec
+  });
+  const bodyProps = extractBodyProps({
+    requestBody: args.operation.requestBody,
+    spec: args.spec,
+    serverManagedExtension: args.options.serverManagedExtension
+  });
+  const inputSchema = buildInputSchema(pathParams, queryParams, bodyProps);
+  const acceptedBodyFields = extractAcceptedBodyFields({
+    requestBody: args.operation.requestBody,
+    spec: args.spec
+  });
+  return {
+    name: toolName,
+    description: sanitizeDescription(args.operation.description),
+    inputSchema,
+    method: httpMethod,
+    pathTemplate: args.pathTemplate,
+    operationId: args.operation.operationId,
+    path: buildPathFn(args.pathTemplate, pathParams),
+    query: buildQueryFn(queryParams),
+    body: buildBodyFn(bodyProps),
+    acceptedBodyFields,
+    extensions: extractExtensions(args.operation)
+  };
+};
+var processPath = args => {
+  const tools = [];
+  for (const [method, operation] of Object.entries(args.pathItem)) {
+    const tool = processOperation({
+      pathTemplate: args.pathTemplate,
+      method,
+      operation,
+      spec: args.spec,
+      options: args.options
+    });
+    if (tool) tools.push(tool);
+  }
+  return tools;
+};
+/**
+* Translates one or more OpenAPI documents into REST-backed MCP tool
+* definitions. Each translatable operation (has an `operationId`, a supported
+* HTTP method, and is not excluded) becomes one {@link ToolDefinition}.
+*
+* @example
+* ```typescript
+* import { openApiToToolDefinitions } from '@ttoss/http-server-mcp-openapi';
+*
+* const tools = openApiToToolDefinitions({ spec: myOpenApiDocument });
+* ```
+*/
+var openApiToToolDefinitions = args => {
+  const options = {
+    excludeExtension: args.options?.excludeExtension ?? "x-mcp-exclude",
+    serverManagedExtension: args.options?.serverManagedExtension ?? "x-mcp-server-managed"
+  };
+  const specs = Array.isArray(args.spec) ? args.spec : [args.spec];
+  const tools = [];
+  for (const spec of specs) {
+    const paths = spec.paths || {};
+    for (const [pathTemplate, pathItem] of Object.entries(paths)) tools.push(...processPath({
+      pathTemplate,
+      pathItem,
+      spec,
+      options
+    }));
+  }
+  return tools;
+};
+
+//#endregion
+//#region src/registerOpenApiTools.ts
+var defaultToText = data => {
+  return typeof data === "string" ? data : JSON.stringify(data, null, 2);
+};
+/**
+* Derives MCP tools from OpenAPI document(s) and registers each on the given
+* MCP server. Every tool's handler resolves the incoming camelCase args into a
+* concrete HTTP request and delegates execution to `callApi`.
+*
+* @returns The list of {@link ToolDefinition} that were registered.
+*
+* @example
+* ```typescript
+* import { McpServer } from '@ttoss/http-server-mcp';
+* import { registerOpenApiTools } from '@ttoss/http-server-mcp-openapi';
+*
+* const server = new McpServer({ name: 'my-api', version: '1.0.0' });
+*
+* registerOpenApiTools({
+*   server,
+*   spec: myOpenApiDocument,
+*   callApi: async ({ method, url, body }) => {
+*     const res = await fetch(`https://api.example.com${url}`, {
+*       method,
+*       headers: { 'Content-Type': 'application/json' },
+*       body: body ? JSON.stringify(body) : undefined,
+*     });
+*     return res.json();
+*   },
+* });
+* ```
+*/
+var registerOpenApiTools = args => {
+  const toText = args.toText ?? defaultToText;
+  const tools = openApiToToolDefinitions({
+    spec: args.spec,
+    options: args.options
+  });
+  for (const tool of tools) registerToolFromSchema(args.server, {
+    name: tool.name,
+    description: tool.description,
+    inputSchema: tool.inputSchema,
+    handler: async handlerArgs => {
+      const url = tool.path(handlerArgs) + (tool.query ? tool.query(handlerArgs) : "");
+      return {
+        content: [{
+          type: "text",
+          text: toText(await args.callApi({
+            method: tool.method,
+            url,
+            body: tool.body ? tool.body(handlerArgs) : void 0,
+            tool
+          }))
+        }]
+      };
+    }
+  });
+  return tools;
+};
+
+//#endregion
+export { DEFAULT_EXCLUDE_EXTENSION, DEFAULT_SERVER_MANAGED_EXTENSION, buildBodyFn, buildInputSchema, buildPathFn, buildQueryFn, dereferenceSchema, extractAcceptedBodyFields, extractBodyProps, extractPathParams, extractQueryParams, getJsonSchemaType, openApiToToolDefinitions, operationIdToToolName, processOperation, processPath, registerOpenApiTools, resolveParameter, resolveSchema, snakeToCamel };

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@ttoss/http-server-mcp-openapi",
+  "version": "0.1.0",
+  "description": "Generate Model Context Protocol (MCP) tools from an OpenAPI specification for @ttoss/http-server-mcp",
+  "keywords": [
+    "ai",
+    "koa",
+    "llm",
+    "mcp",
+    "model-context-protocol",
+    "openapi",
+    "rest",
+    "server"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ttoss/ttoss.git",
+    "directory": "packages/http-server-mcp-openapi"
+  },
+  "license": "MIT",
+  "author": "ttoss",
+  "contributors": [
+    "Pedro Arantes <pedro@arantespp.com> (https://arantespp.com)"
+  ],
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.mts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@ttoss/http-server-mcp": "^0.22.0"
+  },
+  "devDependencies": {
+    "jest": "^30.4.2",
+    "supertest": "^7.2.2",
+    "tsdown": "^0.22.2",
+    "@ttoss/config": "^1.37.17",
+    "@ttoss/http-server": "^0.7.1"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "jest --projects tests/unit"
+  }
+}