@ttoss/http-server-mcp-openapi 0.2.15 → 0.3.0

package/dist/index.mjs

@@ -1,7 +1,10 @@
 /** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
-import { registerToolFromSchema } from "@ttoss/http-server-mcp";
+import { getApiHeaders, registerToolFromSchema } from "@ttoss/http-server-mcp";
 
 //#region src/schema.ts
+var isRecord = value => {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+};
 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;
@@ -23,36 +26,96 @@ var mergeResolvedSchemas = resolvedAlternatives => {
     required: requiredIntersection && requiredIntersection.length > 0 ? requiredIntersection : void 0
   };
 };
+var stripDotSlash = file => {
+  return file.replace(/^\.\//, "");
+};
+var findDocument = args => {
+  if (!args.documents) return void 0;
+  const wanted = stripDotSlash(args.file);
+  for (const [key, document] of Object.entries(args.documents)) if (stripDotSlash(key) === wanted) return document;
+};
+/** Follows an RFC 6901 JSON pointer (`/components/schemas/Tag`) into a value. */
+var followPointer = args => {
+  const tokens = args.pointer.split("/").slice(1);
+  let current = args.root;
+  for (const rawToken of tokens) {
+    if (!isRecord(current) && !Array.isArray(current)) return void 0;
+    const token = decodeURIComponent(rawToken).replace(/~1/g, "/").replace(/~0/g, "~");
+    current = current[token];
+  }
+  return current;
+};
+/** Stable identity for each document, so cycle keys never collide across files. */
+var documentIds = /* @__PURE__ */new WeakMap();
+var nextDocumentId = 0;
+var documentId = spec => {
+  const known = documentIds.get(spec);
+  if (known !== void 0) return known;
+  nextDocumentId += 1;
+  documentIds.set(spec, nextDocumentId);
+  return nextDocumentId;
+};
+/**
+* Resolves a `$ref` to its target and the document the target lives in (the
+* scope its own nested refs resolve against). A ref without a file part
+* (`#/components/schemas/X`) points into the current document; one with a
+* file part (`./tags.yaml#/components/schemas/Tag`) points into the matching
+* entry of `documents`. Returns `undefined` when the target does not exist.
+*/
+var resolveRef = args => {
+  const hashIndex = args.ref.indexOf("#");
+  const file = hashIndex === -1 ? args.ref : args.ref.slice(0, hashIndex);
+  const pointer = hashIndex === -1 ? "" : args.ref.slice(hashIndex + 1);
+  const spec = file === "" ? args.scope.spec : findDocument({
+    file,
+    documents: args.scope.documents
+  });
+  if (!spec) return void 0;
+  const value = followPointer({
+    root: spec,
+    pointer
+  });
+  if (value === void 0) return void 0;
+  return {
+    value,
+    scope: {
+      spec,
+      documents: args.scope.documents
+    },
+    key: `${documentId(spec)}#${pointer}`
+  };
+};
 var dereferenceValue = args => {
   const {
     value,
-    spec,
+    scope,
     seenRefs
   } = args;
   if (Array.isArray(value)) return value.map(item => {
     return dereferenceValue({
       value: item,
-      spec,
+      scope,
       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];
-      if (resolved === void 0) return {};
+  if (isRecord(value)) {
+    if (typeof value.$ref === "string") {
+      const target = resolveRef({
+        ref: value.$ref,
+        scope
+      });
+      if (!target) return {};
+      if (seenRefs.has(target.key)) return {};
       return dereferenceValue({
-        value: resolved,
-        spec,
-        seenRefs: new Set(seenRefs).add(refName)
+        value: target.value,
+        scope: target.scope,
+        seenRefs: new Set(seenRefs).add(target.key)
       });
     }
     const result = {};
-    for (const [key, entryValue] of Object.entries(obj)) result[key] = dereferenceValue({
+    for (const [key, entryValue] of Object.entries(value)) result[key] = dereferenceValue({
       value: entryValue,
-      spec,
+      scope,
       seenRefs
     });
     return result;
@@ -64,12 +127,17 @@ var dereferenceValue = args => {
 * `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.
+*
+* Refs into other files resolve against `documents`; see {@link OpenApiDocuments}.
 */
-var dereferenceSchema = (schema, spec) => {
+var dereferenceSchema = (schema, spec, documents) => {
   if (!schema) return schema;
   return dereferenceValue({
     value: schema,
-    spec,
+    scope: {
+      spec,
+      documents
+    },
     seenRefs: /* @__PURE__ */new Set()
   });
 };
@@ -78,25 +146,39 @@ var dereferenceSchema = (schema, spec) => {
 * and merges `oneOf` / `anyOf` alternatives (union of properties, intersection
 * of `required`) so the caller sees one flat property set.
 */
-var resolveSchema = (schema, spec) => {
+var resolveSchema = (schema, spec, documents) => {
   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 target = resolveRef({
+      ref: schema.$ref,
+      scope: {
+        spec,
+        documents
+      }
+    });
+    return resolveSchema(target?.value, target?.scope.spec ?? spec, documents);
   }
   const alternatives = getAlternativeSchemas(schema);
   if (alternatives) return mergeResolvedSchemas(alternatives.map(candidate => {
-    return resolveSchema(candidate, spec);
+    return resolveSchema(candidate, spec, documents);
   }));
   return schema;
 };
-/** Follows a parameter `$ref` into `components.parameters`, if present. */
-var resolveParameter = (param, spec) => {
+/**
+* Follows a parameter `$ref` — into `components.parameters`, or into another
+* file through `documents` — if present.
+*/
+var resolveParameter = (param, spec, documents) => {
   if (!param) return {};
   if (typeof param.$ref === "string") {
-    const refName = param.$ref.replace("#/components/parameters/", "");
-    return spec.components?.parameters?.[refName] || {};
+    const target = resolveRef({
+      ref: param.$ref,
+      scope: {
+        spec,
+        documents
+      }
+    });
+    return isRecord(target?.value) ? target.value : {};
   }
   return param;
 };
@@ -106,9 +188,9 @@ var buildPathFn = (pathTemplate, pathParams) => {
     let result = pathTemplate;
     for (const {
       name,
-      camelName
+      argName
     } of pathParams) {
-      const value = args[camelName];
+      const value = args[argName];
       if (value !== void 0) result = result.replace(`{${name}}`, encodeURIComponent(String(value)));
     }
     return result;
@@ -119,9 +201,6 @@ var NON_EXPLODED_DELIMITERS = {
   spaceDelimited: " ",
   pipeDelimited: "|"
 };
-var isRecord = value => {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-};
 /**
 * Appends a `deepObject` value as bracketed keys — `filters[documentId][$eq]`.
 * OpenAPI only defines one level, but the APIs that ask for `deepObject`
@@ -209,7 +288,7 @@ var buildQueryFn = queryParams => {
   return args => {
     const search = new URLSearchParams();
     for (const param of queryParams) {
-      const value = args[param.camelName];
+      const value = args[param.argName];
       if (value === void 0 || value === null) continue;
       appendQueryValue({
         search,
@@ -222,8 +301,8 @@ var buildQueryFn = queryParams => {
   };
 };
 /**
-* 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.
+* Builds a function that maps tool args back to a request body keyed by the
+* spec's property names, skipping `undefined` args. Returns `undefined` when the op has no body.
 */
 var buildBodyFn = bodyProps => {
   if (bodyProps.length === 0) return void 0;
@@ -231,8 +310,8 @@ var buildBodyFn = bodyProps => {
     const body = {};
     for (const {
       snakeName,
-      camelName
-    } of bodyProps) if (args[camelName] !== void 0) body[snakeName] = args[camelName];
+      argName
+    } of bodyProps) if (args[argName] !== void 0) body[snakeName] = args[argName];
     return body;
   };
 };
@@ -243,17 +322,93 @@ var DEFAULT_EXCLUDE_EXTENSION = "x-mcp-exclude";
 var DEFAULT_SERVER_MANAGED_EXTENSION = "x-mcp-server-managed";
 
 //#endregion
-//#region src/toolDefinitions.ts
+//#region src/parameters.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.
+* names may be snake_case (`agent_id`) or kebab-case (`list-tools`); with the
+* default `argumentNames: 'camelCase'` both are folded into tool arguments.
 */
 var snakeToCamel = str => {
   return str.replace(/[_-]([a-z])/g, (_, letter) => {
     return letter.toUpperCase();
   });
 };
+var verbatim = name => {
+  return name;
+};
+var argNameMapper = argumentNames => {
+  return argumentNames === "verbatim" ? verbatim : snakeToCamel;
+};
+/**
+* Deduplicates parameter entries by `name`, keeping the last occurrence. When
+* path-item-level and operation-level parameters are concatenated (operation
+* last), this makes the operation-level entry win — as the OpenAPI spec requires.
+*/
+var dedupeByName = items => {
+  const byName = /* @__PURE__ */new Map();
+  for (const item of items) byName.set(item.name, item);
+  return [...byName.values()];
+};
+var extractPathParams = args => {
+  const toArgName = args.toArgName ?? snakeToCamel;
+  const flag = args.serverManagedExtension ?? "x-mcp-server-managed";
+  return dedupeByName((args.parameters || []).map(p => {
+    return resolveParameter(p, args.spec, args.documents);
+  }).filter(p => {
+    return p.in === "path";
+  }).map(p => {
+    return {
+      name: p.name || "",
+      argName: toArgName(p.name || ""),
+      serverManaged: Boolean(p[flag])
+    };
+  }));
+};
+var extractQueryParams = args => {
+  const toArgName = args.toArgName ?? snakeToCamel;
+  const flag = args.serverManagedExtension ?? "x-mcp-server-managed";
+  return dedupeByName((args.parameters || []).map(p => {
+    return resolveParameter(p, args.spec, args.documents);
+  }).filter(p => {
+    return p.in === "query";
+  }).map(p => {
+    return {
+      name: p.name || "",
+      argName: toArgName(p.name || ""),
+      description: p.description || "",
+      required: p.required || false,
+      type: p.schema?.type || "string",
+      style: p.style,
+      explode: p.explode,
+      serverManaged: Boolean(p[flag])
+    };
+  }));
+};
+/** Lists the path and query params flagged as server-managed. */
+var collectServerManagedParameters = args => {
+  return [...args.pathParams.map(p => {
+    return {
+      ...p,
+      in: "path"
+    };
+  }), ...args.queryParams.map(p => {
+    return {
+      ...p,
+      in: "query"
+    };
+  })].filter(p => {
+    return p.serverManaged;
+  }).map(p => {
+    return {
+      name: p.name,
+      in: p.in,
+      argName: p.argName
+    };
+  });
+};
+
+//#endregion
+//#region src/toolDefinitions.ts
 /** Converts a camelCase `operationId` to a kebab-case tool name. */
 var operationIdToToolName = operationId => {
   return operationId.replace(/([A-Z])/g, "-$1").toLowerCase().replace(/^-/, "");
@@ -318,23 +473,29 @@ var buildTypedProperty = param => {
   };
 };
 var buildInputSchema = (pathParams, queryParams, bodyProps) => {
-  const allParams = [...pathParams, ...queryParams, ...bodyProps];
+  const modelPathParams = pathParams.filter(p => {
+    return !p.serverManaged;
+  });
+  const modelQueryParams = queryParams.filter(p => {
+    return !p.serverManaged;
+  });
+  const allParams = [...modelPathParams, ...modelQueryParams, ...bodyProps];
   if (allParams.length === 0) return {
     type: "object"
   };
-  const requiredFields = [...pathParams.map(p => {
-    return p.camelName;
-  }), ...queryParams.filter(p => {
+  const requiredFields = [...modelPathParams.map(p => {
+    return p.argName;
+  }), ...modelQueryParams.filter(p => {
     return p.required;
   }).map(p => {
-    return p.camelName;
+    return p.argName;
   }), ...bodyProps.filter(p => {
     return p.required;
   }).map(p => {
-    return p.camelName;
+    return p.argName;
   })];
   const properties = {};
-  for (const param of allParams) properties[param.camelName] = "description" in param ? buildTypedProperty(param) : {
+  for (const param of allParams) properties[param.argName] = "description" in param ? buildTypedProperty(param) : {
     type: "string",
     description: ""
   };
@@ -346,48 +507,9 @@ var buildInputSchema = (pathParams, queryParams, bodyProps) => {
     } : {})
   };
 };
-/**
-* Deduplicates parameter entries by `name`, keeping the last occurrence. When
-* path-item-level and operation-level parameters are concatenated (operation
-* last), this makes the operation-level entry win — as the OpenAPI spec requires.
-*/
-var dedupeByName = items => {
-  const byName = /* @__PURE__ */new Map();
-  for (const item of items) byName.set(item.name, item);
-  return [...byName.values()];
-};
-var extractPathParams = args => {
-  return dedupeByName((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 dedupeByName((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",
-      style: p.style,
-      explode: p.explode
-    };
-  }));
-};
 var resolveBodySchema = args => {
   const rawBodySchema = args.requestBody?.content?.["application/json"]?.schema;
-  return resolveSchema(dereferenceSchema(rawBodySchema, args.spec), args.spec);
+  return resolveSchema(dereferenceSchema(rawBodySchema, args.spec, args.documents), args.spec, args.documents);
 };
 /**
 * snake_case names of every top-level property an operation's request schema
@@ -421,6 +543,7 @@ var flattenSingleAllOf = schema => {
   };
 };
 var extractBodyProps = args => {
+  const toArgName = args.toArgName ?? snakeToCamel;
   const bodySchema = resolveBodySchema(args);
   if (!bodySchema?.properties) return [];
   return Object.entries(bodySchema.properties).filter(([, value]) => {
@@ -429,7 +552,7 @@ var extractBodyProps = args => {
     const val = flattenSingleAllOf(value);
     return {
       snakeName: key,
-      camelName: snakeToCamel(key),
+      argName: toArgName(key),
       description: typeof val.description === "string" ? val.description : "",
       required: (bodySchema.required || []).includes(key),
       type: typeof val.type === "string" ? val.type : void 0,
@@ -454,23 +577,37 @@ var processOperation = args => {
   if (args.operation[args.options.excludeExtension]) return null;
   const toolName = operationIdToToolName(args.operation.operationId);
   const parameters = [...(args.pathItemParameters ?? []), ...(args.operation.parameters ?? [])];
+  const {
+    documents,
+    serverManagedExtension
+  } = args.options;
+  const toArgName = argNameMapper(args.options.argumentNames);
   const pathParams = extractPathParams({
     parameters,
-    spec: args.spec
+    spec: args.spec,
+    documents,
+    toArgName,
+    serverManagedExtension
   });
   const queryParams = extractQueryParams({
     parameters,
-    spec: args.spec
+    spec: args.spec,
+    documents,
+    toArgName,
+    serverManagedExtension
   });
   const bodyProps = extractBodyProps({
     requestBody: args.operation.requestBody,
     spec: args.spec,
-    serverManagedExtension: args.options.serverManagedExtension
+    serverManagedExtension,
+    documents,
+    toArgName
   });
   const inputSchema = buildInputSchema(pathParams, queryParams, bodyProps);
   const acceptedBodyFields = extractAcceptedBodyFields({
     requestBody: args.operation.requestBody,
-    spec: args.spec
+    spec: args.spec,
+    documents
   });
   return {
     name: toolName,
@@ -483,7 +620,11 @@ var processOperation = args => {
     query: buildQueryFn(queryParams),
     body: buildBodyFn(bodyProps),
     acceptedBodyFields,
-    extensions: extractExtensions(args.operation)
+    extensions: extractExtensions(args.operation),
+    serverManagedParameters: collectServerManagedParameters({
+      pathParams,
+      queryParams
+    })
   };
 };
 var processPath = args => {
@@ -504,6 +645,15 @@ var processPath = args => {
   }
   return tools;
 };
+/** Applies the defaults to {@link OpenApiToToolsOptions}. */
+var resolveOptions = (options = {}) => {
+  return {
+    excludeExtension: options.excludeExtension ?? "x-mcp-exclude",
+    serverManagedExtension: options.serverManagedExtension ?? "x-mcp-server-managed",
+    argumentNames: options.argumentNames ?? "camelCase",
+    documents: options.documents
+  };
+};
 /**
 * Translates one or more OpenAPI documents into REST-backed MCP tool
 * definitions. Each translatable operation (has an `operationId`, a supported
@@ -517,10 +667,7 @@ var processPath = args => {
 * ```
 */
 var openApiToToolDefinitions = args => {
-  const options = {
-    excludeExtension: args.options?.excludeExtension ?? "x-mcp-exclude",
-    serverManagedExtension: args.options?.serverManagedExtension ?? "x-mcp-server-managed"
-  };
+  const options = resolveOptions(args.options);
   const specs = Array.isArray(args.spec) ? args.spec : [args.spec];
   const tools = [];
   for (const spec of specs) {
@@ -537,13 +684,34 @@ var openApiToToolDefinitions = args => {
 
 //#endregion
 //#region src/registerOpenApiTools.ts
+/** The text the default `toText` answers when the API returned no body. */
+var NO_CONTENT_TEXT = "Succeeded. The operation returned no content.";
 var defaultToText = data => {
+  if (data === void 0 || data === "") return NO_CONTENT_TEXT;
   return typeof data === "string" ? data : JSON.stringify(data, null, 2);
 };
 /**
+* Replaces whatever the model sent for server-managed parameters with the
+* values `serverParameters` supplies, so the model can never set them.
+*/
+var applyServerParameters = async args => {
+  const managed = args.tool.serverManagedParameters;
+  if (managed.length === 0) return args.handlerArgs;
+  const result = {
+    ...args.handlerArgs
+  };
+  for (const param of managed) delete result[param.argName];
+  const values = args.serverParameters ? await args.serverParameters({
+    tool: args.tool,
+    headers: args.headers
+  }) : {};
+  for (const param of managed) if (values[param.name] !== void 0) result[param.argName] = values[param.name];
+  return result;
+};
+/**
 * 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`.
+* MCP server. Every tool's handler resolves the incoming args into a concrete
+* HTTP request and delegates execution to `callApi`.
 *
 * @returns The list of {@link ToolDefinition} that were registered.
 *
@@ -557,10 +725,10 @@ var defaultToText = data => {
 * registerOpenApiTools({
 *   server,
 *   spec: myOpenApiDocument,
-*   callApi: async ({ method, url, body }) => {
+*   callApi: async ({ method, url, body, headers }) => {
 *     const res = await fetch(`https://api.example.com${url}`, {
 *       method,
-*       headers: { 'Content-Type': 'application/json' },
+*       headers: { ...headers, 'Content-Type': 'application/json' },
 *       body: body ? JSON.stringify(body) : undefined,
 *     });
 *     return res.json();
@@ -578,7 +746,14 @@ var registerOpenApiTools = args => {
     name: tool.name,
     description: tool.description,
     inputSchema: tool.inputSchema,
-    handler: async handlerArgs => {
+    handler: async rawArgs => {
+      const headers = getApiHeaders();
+      const handlerArgs = await applyServerParameters({
+        tool,
+        handlerArgs: rawArgs,
+        headers,
+        serverParameters: args.serverParameters
+      });
       const url = tool.path(handlerArgs) + (tool.query ? tool.query(handlerArgs) : "");
       return {
         content: [{
@@ -587,7 +762,8 @@ var registerOpenApiTools = args => {
             method: tool.method,
             url,
             body: tool.body ? tool.body(handlerArgs) : void 0,
-            tool
+            tool,
+            headers
           }))
         }]
       };
@@ -597,4 +773,4 @@ var registerOpenApiTools = args => {
 };
 
 //#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 };
+export { DEFAULT_EXCLUDE_EXTENSION, DEFAULT_SERVER_MANAGED_EXTENSION, NO_CONTENT_TEXT, buildBodyFn, buildInputSchema, buildPathFn, buildQueryFn, dereferenceSchema, extractAcceptedBodyFields, extractBodyProps, extractPathParams, extractQueryParams, getJsonSchemaType, openApiToToolDefinitions, operationIdToToolName, processOperation, processPath, registerOpenApiTools, resolveParameter, resolveSchema, snakeToCamel };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttoss/http-server-mcp-openapi",
-  "version": "0.2.15",
+  "version": "0.3.0",
   "description": "Generate Model Context Protocol (MCP) tools from an OpenAPI specification for @ttoss/http-server-mcp",
   "keywords": [
     "ai",
@@ -35,15 +35,15 @@
     "dist"
   ],
   "dependencies": {
-    "@ttoss/http-server-mcp": "^0.28.2"
+    "@ttoss/http-server-mcp": "^0.29.0"
   },
   "devDependencies": {
     "@modelcontextprotocol/server": "^2.0.0",
     "jest": "^30.4.2",
     "supertest": "^7.2.2",
     "tsdown": "^0.22.2",
-    "@ttoss/config": "^1.38.0",
-    "@ttoss/http-server": "^0.8.1"
+    "@ttoss/http-server": "^0.8.1",
+    "@ttoss/config": "^1.38.0"
   },
   "publishConfig": {
     "access": "public",