@ttoss/http-server-mcp-openapi 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024, Terezinha Tech Operations (ttoss)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,143 @@
+# @ttoss/http-server-mcp-openapi
+
+Generate [Model Context Protocol (MCP)](https://modelcontextprotocol.io) tools
+from an [OpenAPI](https://www.openapis.org/) specification and register them on
+a [@ttoss/http-server-mcp](https://ttoss.dev/docs/modules/packages/http-server-mcp)
+server.
+
+Point it at your existing OpenAPI document and every operation becomes an MCP
+tool whose handler resolves the incoming arguments into an HTTP request against
+your REST API. The OpenAPI spec stays the single source of truth for both your
+REST surface and your MCP tool surface.
+
+## Installation
+
+```bash
+pnpm add @ttoss/http-server-mcp-openapi @ttoss/http-server-mcp
+```
+
+## Quick Start
+
+```typescript
+import { App, bodyParser } from '@ttoss/http-server';
+import { createMcpRouter, McpServer } from '@ttoss/http-server-mcp';
+import { registerOpenApiTools } from '@ttoss/http-server-mcp-openapi';
+
+import openApiDocument from './openapi.json' with { type: 'json' };
+
+const server = new McpServer({ name: 'my-api', version: '1.0.0' });
+
+registerOpenApiTools({
+  server,
+  spec: openApiDocument,
+  // You own how the request is executed — base URL, auth, fetch impl.
+  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();
+  },
+});
+
+const app = new App();
+app.use(bodyParser());
+app.use(createMcpRouter(server).routes());
+app.listen(3000);
+```
+
+## How Operations Map to Tools
+
+Each OpenAPI operation with an `operationId` and a supported HTTP method
+(`GET`, `POST`, `PUT`, `PATCH`, `DELETE`) becomes one tool:
+
+| OpenAPI                   | MCP tool                                     |
+| ------------------------- | -------------------------------------------- |
+| `operationId: listAgents` | tool name `list-agents` (kebab-case)         |
+| path/query/body params    | a single camelCase `inputSchema` object      |
+| `$ref`, `oneOf`, `anyOf`  | dereferenced and merged into a flat schema   |
+| snake_case body fields    | camelCase tool inputs, mapped back on call   |
+| operation `description`   | tool description (quotes/newlines sanitised) |
+
+Path params are always required strings. Query and body params carry their
+declared type and `required` flag. Array params keep their `items` schema.
+
+Tool arguments are **camelCase** (`agentId`, `projectId`); the generated
+request path, query string, and body use the original **snake_case** names.
+
+## `registerOpenApiTools`
+
+| Field      | Description                                                                                                   |
+| ---------- | ------------------------------------------------------------------------------------------------------------- |
+| `server`   | The `McpServer` to register tools on.                                                                         |
+| `spec`     | One OpenAPI document, or an array of them (tools are flattened).                                              |
+| `callApi`  | Runs the resolved `{ method, url, body, tool }` request and returns the raw data.                             |
+| `toText?`  | Serialises the raw data into the tool's text payload. Defaults to pretty JSON; strings pass through verbatim. |
+| `options?` | See [Options](#options).                                                                                      |
+
+Returns the list of `ToolDefinition`s that were registered.
+
+## `openApiToToolDefinitions`
+
+Use the lower-level function when you want the tool definitions without
+registering them — to inspect, filter, or wire handlers yourself:
+
+```typescript
+import { openApiToToolDefinitions } from '@ttoss/http-server-mcp-openapi';
+
+const tools = openApiToToolDefinitions({ spec: openApiDocument });
+
+for (const tool of tools) {
+  // tool.name, tool.method, tool.inputSchema, tool.extensions, ...
+  const url = tool.path(args) + (tool.query ? tool.query(args) : '');
+  const body = tool.body?.(args);
+}
+```
+
+Each `ToolDefinition` exposes `name`, `description`, `inputSchema`, `method`,
+`pathTemplate`, `operationId`, the `path`/`query`/`body` builders,
+`acceptedBodyFields`, and `extensions`.
+
+## Options
+
+```typescript
+registerOpenApiTools({
+  server,
+  spec,
+  callApi,
+  options: {
+    excludeExtension: 'x-mcp-exclude', // operations flagged truthy are skipped
+    serverManagedExtension: 'x-mcp-server-managed', // body fields hidden from the input schema
+  },
+});
+```
+
+- **`excludeExtension`** (default `x-mcp-exclude`) — an operation with this
+  extension set truthy is omitted from the tool surface.
+- **`serverManagedExtension`** (default `x-mcp-server-managed`) — a request-body
+  property with this extension set truthy is hidden from the tool's
+  `inputSchema` (the caller can't set it) but still appears in
+  `acceptedBodyFields`.
+
+### Reading custom extensions
+
+Every `x-` prefixed extension on an operation is forwarded verbatim on
+`tool.extensions`, so you can attach and read your own metadata without this
+package needing to know about it:
+
+```typescript
+const tools = openApiToToolDefinitions({ spec: openApiDocument });
+const iamAction = tools[0].extensions['x-iam-action'];
+```
+
+## Related Packages
+
+- [@ttoss/http-server-mcp](https://ttoss.dev/docs/modules/packages/http-server-mcp) - MCP server integration for @ttoss/http-server
+- [@ttoss/http-server](https://ttoss.dev/docs/modules/packages/http-server) - HTTP server foundation
+- [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/sdk) - MCP SDK
+
+## Resources
+
+- [MCP Documentation](https://modelcontextprotocol.io)
+- [OpenAPI Specification](https://spec.openapis.org/oas/latest.html)

package/dist/index.cjs

@@ -0,0 +1,456 @@
+/** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
+Object.defineProperty(exports, Symbol.toStringTag, {
+  value: 'Module'
+});
+let _ttoss_http_server_mcp = require("@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) (0, _ttoss_http_server_mcp.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
+exports.DEFAULT_EXCLUDE_EXTENSION = DEFAULT_EXCLUDE_EXTENSION;
+exports.DEFAULT_SERVER_MANAGED_EXTENSION = DEFAULT_SERVER_MANAGED_EXTENSION;
+exports.buildBodyFn = buildBodyFn;
+exports.buildInputSchema = buildInputSchema;
+exports.buildPathFn = buildPathFn;
+exports.buildQueryFn = buildQueryFn;
+exports.dereferenceSchema = dereferenceSchema;
+exports.extractAcceptedBodyFields = extractAcceptedBodyFields;
+exports.extractBodyProps = extractBodyProps;
+exports.extractPathParams = extractPathParams;
+exports.extractQueryParams = extractQueryParams;
+exports.getJsonSchemaType = getJsonSchemaType;
+exports.openApiToToolDefinitions = openApiToToolDefinitions;
+exports.operationIdToToolName = operationIdToToolName;
+exports.processOperation = processOperation;
+exports.processPath = processPath;
+exports.registerOpenApiTools = registerOpenApiTools;
+exports.resolveParameter = resolveParameter;
+exports.resolveSchema = resolveSchema;
+exports.snakeToCamel = snakeToCamel;