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

package/dist/index.cjs

@@ -5,6 +5,9 @@ Object.defineProperty(exports, Symbol.toStringTag, {
 let _ttoss_http_server_mcp = require("@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;
@@ -26,36 +29,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;
@@ -67,12 +130,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()
   });
 };
@@ -81,25 +149,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;
 };
@@ -109,9 +191,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;
@@ -122,9 +204,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`
@@ -212,7 +291,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,
@@ -225,8 +304,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;
@@ -234,8 +313,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;
   };
 };
@@ -246,17 +325,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(/^-/, "");
@@ -321,23 +476,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: ""
   };
@@ -349,48 +510,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
@@ -424,6 +546,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]) => {
@@ -432,7 +555,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,
@@ -457,23 +580,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,
@@ -486,7 +623,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 => {
@@ -507,6 +648,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
@@ -520,10 +670,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) {
@@ -540,13 +687,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.
 *
@@ -560,10 +728,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();
@@ -581,7 +749,14 @@ var registerOpenApiTools = args => {
     name: tool.name,
     description: tool.description,
     inputSchema: tool.inputSchema,
-    handler: async handlerArgs => {
+    handler: async rawArgs => {
+      const headers = (0, _ttoss_http_server_mcp.getApiHeaders)();
+      const handlerArgs = await applyServerParameters({
+        tool,
+        handlerArgs: rawArgs,
+        headers,
+        serverParameters: args.serverParameters
+      });
       const url = tool.path(handlerArgs) + (tool.query ? tool.query(handlerArgs) : "");
       return {
         content: [{
@@ -590,7 +765,8 @@ var registerOpenApiTools = args => {
             method: tool.method,
             url,
             body: tool.body ? tool.body(handlerArgs) : void 0,
-            tool
+            tool,
+            headers
           }))
         }]
       };
@@ -602,6 +778,7 @@ var registerOpenApiTools = args => {
 //#endregion
 exports.DEFAULT_EXCLUDE_EXTENSION = DEFAULT_EXCLUDE_EXTENSION;
 exports.DEFAULT_SERVER_MANAGED_EXTENSION = DEFAULT_SERVER_MANAGED_EXTENSION;
+exports.NO_CONTENT_TEXT = NO_CONTENT_TEXT;
 exports.buildBodyFn = buildBodyFn;
 exports.buildInputSchema = buildInputSchema;
 exports.buildPathFn = buildPathFn;