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

package/dist/index.d.mts

@@ -30,8 +30,8 @@ type JsonSchemaProperty = {
 /**
  * A REST-backed MCP tool derived from a single OpenAPI operation.
  *
- * The `path` / `query` / `body` builders turn the camelCase arguments an MCP
- * client sends into the pieces of an HTTP request against the original REST
+ * The `path` / `query` / `body` builders turn the arguments an MCP client
+ * sends (named per {@link OpenApiToToolsOptions.argumentNames}) into the pieces of an HTTP request against the original REST
  * API. They intentionally hold no transport concerns (base URL, auth); the
  * caller wires those in when it performs the request.
  */
@@ -40,7 +40,7 @@ interface ToolDefinition {
   name: string;
   /** Sanitised operation description (quotes escaped, newlines flattened). */
   description: string;
-  /** Plain JSON Schema describing the tool's camelCase input object. */
+  /** Plain JSON Schema describing the tool's input object. */
   inputSchema: JsonObjectSchema;
   /** Uppercase HTTP method (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`). */
   method: string;
@@ -52,10 +52,13 @@ interface ToolDefinition {
   path: (args: Record<string, unknown>) => string;
   /** Builds the query string (including leading `?`), or `undefined` if none. */
   query?: (args: Record<string, unknown>) => string;
-  /** Builds the snake_case request body, or `undefined` if the op has no body. */
+  /**
+   * Builds the request body keyed by the spec's property names, or `undefined`
+   * if the op has no body.
+   */
   body?: (args: Record<string, unknown>) => Record<string, unknown>;
   /**
-   * snake_case names of every top-level request-body property the operation's
+   * Spec names of every top-level request-body property the operation's
    * schema declares, including server-managed ones hidden from `inputSchema`.
    */
   acceptedBodyFields: string[];
@@ -65,6 +68,22 @@ interface ToolDefinition {
    * without this package needing to know about it.
    */
   extensions: Record<string, unknown>;
+  /**
+   * Path and query parameters flagged with the server-managed extension. They
+   * are absent from `inputSchema`, but `path` / `query` still read them from
+   * the args under `argName`, so the consumer fills them before building the
+   * request — `registerOpenApiTools` does it through `serverParameters`.
+   */
+  serverManagedParameters: ServerManagedParameter[];
+}
+/** A path or query parameter the server sets, never offered to the model. */
+interface ServerManagedParameter {
+  /** The parameter's name in the spec. */
+  name: string;
+  /** Where the parameter goes. */
+  in: 'path' | 'query';
+  /** The args key `path` / `query` read the value from. */
+  argName: string;
 }
 /** Minimal shape of an OpenAPI document consumed by the generator. */
 interface OpenApiSpec {
@@ -74,6 +93,12 @@ interface OpenApiSpec {
     parameters?: Record<string, unknown>;
   };
 }
+/**
+ * Documents a `$ref` may point into, keyed by the file part of the ref exactly
+ * as the spec writes it (`./tags.yaml` in `./tags.yaml#/components/schemas/Tag`).
+ * A leading `./` is optional on either side.
+ */
+type OpenApiDocuments = Record<string, OpenApiSpec>;
 type RequestBodySpec = {
   required?: boolean;
   content?: {
@@ -119,16 +144,80 @@ interface OpenApiToToolsOptions {
    */
   excludeExtension?: string;
   /**
-   * Body-property extension flag that, when truthy, hides the property from the
-   * generated `inputSchema` while keeping it in `acceptedBodyFields` (for
-   * server-managed fields the API sets itself).
+   * Extension flag that, when truthy, hides a value the server sets from the
+   * generated `inputSchema`.
+   *
+   * - On a **request-body property**, the property stays in
+   *   `acceptedBodyFields` and is never sent (the API sets it itself).
+   * - On a **path or query parameter**, the parameter is listed in
+   *   `serverManagedParameters` and the consumer supplies its value.
+   *
    * @default 'x-mcp-server-managed'
    */
   serverManagedExtension?: string;
+  /**
+   * How tool argument names are derived from the spec's parameter and
+   * body-property names.
+   *
+   * - `'camelCase'` folds `_` / `-` separators (`agent_id` → `agentId`) and maps
+   *   them back when building the request.
+   * - `'verbatim'` uses the spec's names unchanged, so the MCP contract matches
+   *   the REST contract exactly.
+   *
+   * @default 'camelCase'
+   */
+  argumentNames?: 'camelCase' | 'verbatim';
+  /**
+   * Documents that `$ref`s with a file part resolve against, keyed by that
+   * file part as the spec writes it — `./tags.yaml` for
+   * `./tags.yaml#/components/schemas/Tag`. Refs inside a document resolve
+   * relative to that document. A ref to a file absent from this map resolves
+   * to an empty schema, which accepts any value.
+   */
+  documents?: OpenApiDocuments;
 }
+/** {@link OpenApiToToolsOptions} with every default applied. */
+type ResolvedToolOptions = Required<Omit<OpenApiToToolsOptions, 'documents'>> & Pick<OpenApiToToolsOptions, 'documents'>;
 declare const DEFAULT_EXCLUDE_EXTENSION = "x-mcp-exclude";
 declare const DEFAULT_SERVER_MANAGED_EXTENSION = "x-mcp-server-managed";
 //#endregion
+//#region src/parameters.d.ts
+/**
+ * Folds `_` and `-` separators into camelCase. OpenAPI operation and parameter
+ * names may be snake_case (`agent_id`) or kebab-case (`list-tools`); with the
+ * default `argumentNames: 'camelCase'` both are folded into tool arguments.
+ */
+declare const snakeToCamel: (str: string) => string;
+/** Maps a spec parameter or property name to a tool argument name. */
+type ToArgName = (name: string) => string;
+/** Arguments shared by the parameter extractors. */
+type ExtractParamsArgs = {
+  parameters?: Array<{
+    name?: string;
+    in?: string;
+    [key: string]: unknown;
+  }>;
+  spec: OpenApiSpec; /** Sibling documents cross-file `$ref`s resolve against. */
+  documents?: OpenApiDocuments; /** Maps a spec name to its tool argument name. @default snakeToCamel */
+  toArgName?: ToArgName; /** @default DEFAULT_SERVER_MANAGED_EXTENSION */
+  serverManagedExtension?: string;
+};
+declare const extractPathParams: (args: ExtractParamsArgs) => Array<{
+  name: string;
+  argName: string;
+  serverManaged: boolean;
+}>;
+declare const extractQueryParams: (args: ExtractParamsArgs) => Array<{
+  name: string;
+  argName: string;
+  description: string;
+  required: boolean;
+  type: string;
+  style?: string;
+  explode?: boolean;
+  serverManaged: boolean;
+}>;
+//#endregion
 //#region src/registerOpenApiTools.d.ts
 /** The resolved HTTP request a tool call maps to, before transport concerns. */
 interface ResolvedRequest {
@@ -136,10 +225,16 @@ interface ResolvedRequest {
   method: string;
   /** Request path including the query string, e.g. `/agents/agt_1?limit=10`. */
   url: string;
-  /** snake_case request body, or `undefined` when the operation has none. */
+  /** Request body keyed by the spec's names, or `undefined` when the operation has none. */
   body?: Record<string, unknown>;
   /** The tool definition the call resolved to (for auth/metadata lookups). */
   tool: ToolDefinition;
+  /**
+   * The headers `createMcpRouter`'s `getApiHeaders` produced for the MCP
+   * request this call belongs to — typically the caller's credentials. `{}`
+   * when `getApiHeaders` is not configured.
+   */
+  headers: Record<string, string>;
 }
 interface RegisterOpenApiToolsArgs {
   /** The MCP server the generated tools are registered on. */
@@ -155,15 +250,35 @@ interface RegisterOpenApiToolsArgs {
    */
   callApi: (request: ResolvedRequest) => Promise<unknown> | unknown;
   /**
-   * Serialises the raw API data into the MCP tool's text payload.
-   * @default (data) => JSON.stringify(data, null, 2)
+   * Serialises the raw API data into the MCP tool's text payload. The default
+   * passes strings through, pretty-prints anything else as JSON, and answers
+   * {@link NO_CONTENT_TEXT} for an empty body (e.g. a `204`).
    */
   toText?: (data: unknown) => string;
+  /**
+   * Supplies the values of the tool's server-managed path and query
+   * parameters (`tool.serverManagedParameters`), keyed by their spec name.
+   * Runs on every call, after any value the model sent for those parameters
+   * has been discarded.
+   *
+   * @example
+   * ```typescript
+   * serverParameters: ({ headers }) => ({
+   *   project_id: projectIdFromToken(headers.Authorization),
+   * }),
+   * ```
+   */
+  serverParameters?: (args: {
+    tool: ToolDefinition;
+    headers: Record<string, string>;
+  }) => Record<string, unknown> | Promise<Record<string, unknown>>;
 }
+/** The text the default `toText` answers when the API returned no body. */
+declare const NO_CONTENT_TEXT = "Succeeded. The operation returned no content.";
 /**
  * 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.
  *
@@ -177,10 +292,10 @@ interface RegisterOpenApiToolsArgs {
  * 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();
@@ -203,16 +318,18 @@ type ResolvedSchema = {
  * `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}.
  */
-declare const dereferenceSchema: (schema: Record<string, unknown> | undefined, spec: OpenApiSpec) => Record<string, unknown> | undefined;
+declare const dereferenceSchema: (schema: Record<string, unknown> | undefined, spec: OpenApiSpec, documents?: OpenApiDocuments) => Record<string, unknown> | undefined;
 /**
  * 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.
  */
-declare const resolveSchema: (schema: Record<string, unknown> | undefined, spec: OpenApiSpec) => ResolvedSchema;
-/** Follows a parameter `$ref` into `components.parameters`, if present. */
-declare const resolveParameter: (param: Record<string, unknown> | undefined, spec: OpenApiSpec) => {
+declare const resolveSchema: (schema: Record<string, unknown> | undefined, spec: OpenApiSpec, documents?: OpenApiDocuments) => ResolvedSchema;
+/** A parameter object after its `$ref` (if any) is followed. */
+type ResolvedParameter = {
   name?: string;
   in?: string;
   required?: boolean;
@@ -225,16 +342,22 @@ declare const resolveParameter: (param: Record<string, unknown> | undefined, spe
       type?: string;
     };
   };
+  [extension: string]: unknown;
 };
+/**
+ * Follows a parameter `$ref` — into `components.parameters`, or into another
+ * file through `documents` — if present.
+ */
+declare const resolveParameter: (param: Record<string, unknown> | undefined, spec: OpenApiSpec, documents?: OpenApiDocuments) => ResolvedParameter;
 /** Builds a function that substitutes path params into the path template. */
 declare const buildPathFn: (pathTemplate: string, pathParams: Array<{
   name: string;
-  camelName: string;
+  argName: string;
 }>) => ((args: Record<string, unknown>) => string);
 /** Query parameter with the OpenAPI serialisation rules declared for it. */
 type QueryParamSerialization = {
   name: string;
-  camelName: string; /** OpenAPI `style` (`form`, `deepObject`, `spaceDelimited`, `pipeDelimited`). */
+  argName: string; /** OpenAPI `style` (`form`, `deepObject`, `spaceDelimited`, `pipeDelimited`). */
   style?: string; /** OpenAPI `explode`. Defaults to `true` for `form`, `false` otherwise. */
   explode?: boolean;
 };
@@ -245,36 +368,32 @@ type QueryParamSerialization = {
  */
 declare const buildQueryFn: (queryParams: QueryParamSerialization[]) => ((args: Record<string, unknown>) => string) | undefined;
 /**
- * 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.
  */
 declare const buildBodyFn: (bodyProps: Array<{
   snakeName: string;
-  camelName: string;
+  argName: string;
 }>) => ((args: Record<string, unknown>) => Record<string, unknown>) | undefined;
 //#endregion
 //#region src/toolDefinitions.d.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.
- */
-declare const snakeToCamel: (str: string) => string;
 /** Converts a camelCase `operationId` to a kebab-case tool name. */
 declare const operationIdToToolName: (operationId: string) => string;
 declare const getJsonSchemaType: (schemaType: string | undefined) => JsonSchemaProperty["type"];
 declare const buildInputSchema: (pathParams: Array<{
   name: string;
-  camelName: string;
+  argName: string;
+  serverManaged?: boolean;
 }>, queryParams: Array<{
   name: string;
-  camelName: string;
+  argName: string;
   description: string;
   required: boolean;
   type: string;
+  serverManaged?: boolean;
 }>, bodyProps: Array<{
   snakeName: string;
-  camelName: string;
+  argName: string;
   description: string;
   required: boolean;
   type?: string;
@@ -284,33 +403,6 @@ declare const buildInputSchema: (pathParams: Array<{
   anyOf?: unknown[];
   allOf?: unknown[];
 }>) => JsonObjectSchema;
-declare const extractPathParams: (args: {
-  parameters?: Array<{
-    name?: string;
-    in?: string;
-    [key: string]: unknown;
-  }>;
-  spec: OpenApiSpec;
-}) => Array<{
-  name: string;
-  camelName: string;
-}>;
-declare const extractQueryParams: (args: {
-  parameters?: Array<{
-    name?: string;
-    in?: string;
-    [key: string]: unknown;
-  }>;
-  spec: OpenApiSpec;
-}) => Array<{
-  name: string;
-  camelName: string;
-  description: string;
-  required: boolean;
-  type: string;
-  style?: string;
-  explode?: boolean;
-}>;
 /**
  * snake_case names of every top-level property an operation's request schema
  * declares, including server-managed ones.
@@ -318,14 +410,17 @@ declare const extractQueryParams: (args: {
 declare const extractAcceptedBodyFields: (args: {
   requestBody?: RequestBodySpec;
   spec: OpenApiSpec;
+  documents?: OpenApiDocuments;
 }) => string[];
 declare const extractBodyProps: (args: {
   requestBody?: RequestBodySpec;
   spec: OpenApiSpec;
   serverManagedExtension: string;
+  documents?: OpenApiDocuments; /** Maps a spec name to its tool argument name. @default snakeToCamel */
+  toArgName?: ToArgName;
 }) => Array<{
   snakeName: string;
-  camelName: string;
+  argName: string;
   description: string;
   required: boolean;
   type?: string;
@@ -340,7 +435,7 @@ declare const processOperation: (args: {
   method: string;
   operation: OperationSpec;
   spec: OpenApiSpec;
-  options: Required<OpenApiToToolsOptions>;
+  options: ResolvedToolOptions;
   /**
    * Parameters declared at the path-item level (shared by every operation on
    * the path). Merged ahead of the operation's own parameters so operation-level
@@ -356,7 +451,7 @@ declare const processPath: (args: {
   pathTemplate: string;
   pathItem: Record<string, OperationSpec>;
   spec: OpenApiSpec;
-  options: Required<OpenApiToToolsOptions>;
+  options: ResolvedToolOptions;
 }) => ToolDefinition[];
 /**
  * Translates one or more OpenAPI documents into REST-backed MCP tool
@@ -375,4 +470,4 @@ declare const openApiToToolDefinitions: (args: {
   options?: OpenApiToToolsOptions;
 }) => ToolDefinition[];
 //#endregion
-export { DEFAULT_EXCLUDE_EXTENSION, DEFAULT_SERVER_MANAGED_EXTENSION, type JsonSchemaProperty, type OpenApiSpec, type OpenApiToToolsOptions, type OperationSpec, type QueryParamSerialization, type RegisterOpenApiToolsArgs, type RequestBodySpec, type ResolvedRequest, type ToolDefinition, 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, type JsonSchemaProperty, NO_CONTENT_TEXT, type OpenApiDocuments, type OpenApiSpec, type OpenApiToToolsOptions, type OperationSpec, type QueryParamSerialization, type RegisterOpenApiToolsArgs, type RequestBodySpec, type ResolvedParameter, type ResolvedRequest, type ResolvedToolOptions, type ServerManagedParameter, type ToolDefinition, buildBodyFn, buildInputSchema, buildPathFn, buildQueryFn, dereferenceSchema, extractAcceptedBodyFields, extractBodyProps, extractPathParams, extractQueryParams, getJsonSchemaType, openApiToToolDefinitions, operationIdToToolName, processOperation, processPath, registerOpenApiTools, resolveParameter, resolveSchema, snakeToCamel };