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

package/README.md

@@ -69,6 +69,10 @@ body property declared as a single-entry `allOf` (usually `allOf: [{ $ref }]`
 beside its own `description`) takes `type`, `nullable` and `items` from the
 referenced schema; a multi-entry `allOf` is forwarded verbatim, and a property
 with no declared type is advertised untyped so it accepts any value.
+OpenAPI's `nullable` becomes JSON Schema at every depth — inside `items`,
+`properties`, `additionalProperties` and `oneOf` / `anyOf` / `allOf`
+alternatives: `nullable: true` adds `'null'` to the `type`, and the keyword is
+dropped.
 Parameters declared at the **path-item level** (shared by every operation on a
 path) are merged into each operation; an operation-level parameter overrides a
 path-item one with the same `name`+`in`.
@@ -130,7 +134,7 @@ registerOpenApiTools({
   callApi,
   options: {
     excludeExtension: 'x-mcp-exclude', // operations flagged truthy are skipped
-    serverManagedExtension: 'x-mcp-server-managed', // values hidden from the input schema
+    serverManagedExtension: 'x-mcp-server-managed', // or several: ['x-a', 'x-b']
     argumentNames: 'camelCase', // or 'verbatim'
     documents: { './tags.yaml': tagsDocument }, // targets of cross-file $refs
   },
@@ -139,8 +143,8 @@ registerOpenApiTools({
 
 - **`excludeExtension`** (default `x-mcp-exclude`) — an operation with this
   extension set truthy is omitted from the tool surface.
-- **`serverManagedExtension`** (default `x-mcp-server-managed`) — see
-  [Server-managed values](#server-managed-values).
+- **`serverManagedExtension`** (default `x-mcp-server-managed`) — one name or
+  an array of names; see [Server-managed values](#server-managed-values).
 - **`argumentNames`** (default `camelCase`) — `verbatim` keeps the spec's
   parameter and property names as tool argument names.
 - **`documents`** — sibling documents for `$ref`s with a file part, keyed by
@@ -173,6 +177,12 @@ registerOpenApiTools({
 With `openApiToToolDefinitions`, set each entry's `argName` in the args before
 calling `tool.path` / `tool.query`.
 
+A **string** extension value pins the parameter: `wait` declared with
+`x-mcp-server-managed: 'true'` is always sent as `wait=true`. `tool.path` and
+`tool.query` apply pinned values themselves, over anything in the args or
+`serverParameters`, and the entry in `serverManagedParameters` carries it as
+`value`.
+
 ### Reading custom extensions
 
 Every `x-` prefixed extension on an operation is forwarded verbatim on

package/dist/index.cjs

@@ -319,6 +319,85 @@ var buildBodyFn = bodyProps => {
   };
 };
 
+//#endregion
+//#region src/serverManaged.ts
+/**
+* Whether a parameter or body property carries one of the server-managed
+* extensions, and the value it pins when the extension is a string.
+*
+* A string pins the value (`x-mcp-server-managed: 'true'` always sends
+* `true`); any other truthy value only hides it. The first matching name wins.
+*/
+var readServerManaged = args => {
+  const names = Array.isArray(args.extension) ? args.extension : [args.extension];
+  for (const name of names) {
+    const flag = args.node[name];
+    if (typeof flag === "string") return {
+      managed: true,
+      value: flag
+    };
+    if (flag) return {
+      managed: true
+    };
+  }
+  return {
+    managed: false
+  };
+};
+/** The args each pinned parameter is always sent with, keyed by `argName`. */
+var pinnedArgs = parameters => {
+  const pinned = {};
+  for (const parameter of parameters) if (parameter.value !== void 0) pinned[parameter.argName] = parameter.value;
+  return pinned;
+};
+/**
+* Wraps a `path` / `query` builder so pinned values replace whatever the args
+* carry. Applied in the builder itself, so every consumer of the tool
+* definition sends them, not only `registerOpenApiTools`.
+*/
+var withPinned = args => {
+  const {
+    build,
+    pinned
+  } = args;
+  if (!build || Object.keys(pinned).length === 0) return build;
+  return values => {
+    return build({
+      ...values,
+      ...pinned
+    });
+  };
+};
+var isPlainObject$1 = value => {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+};
+var mergeNullIntoType = schema => {
+  const {
+    type
+  } = schema;
+  if (typeof type === "string") schema.type = [type, "null"];else if (Array.isArray(type) && !type.includes("null")) schema.type = [...type, "null"];
+};
+/**
+* Turns OpenAPI's `nullable` into JSON Schema at every depth: `nullable: true`
+* merges `'null'` into a sibling `type` and is dropped where there is none.
+* JSON Schema has no `nullable`, so a validator or model reading it would
+* refuse `null` where the API accepts it.
+*
+* Only a boolean `nullable` is the keyword; a property *named* `nullable`
+* inside `properties` is a schema and is kept.
+*/
+var normalizeNullable = value => {
+  if (Array.isArray(value)) return value.map(normalizeNullable);
+  if (!isPlainObject$1(value)) return value;
+  const result = {};
+  for (const [key, nested] of Object.entries(value)) {
+    if (key === "nullable" && typeof nested === "boolean") continue;
+    result[key] = normalizeNullable(nested);
+  }
+  if (value.nullable === true) mergeNullIntoType(result);
+  return result;
+};
+
 //#endregion
 //#region src/types.ts
 var DEFAULT_EXCLUDE_EXTENSION = "x-mcp-exclude";
@@ -352,6 +431,14 @@ var dedupeByName = items => {
   for (const item of items) byName.set(item.name, item);
   return [...byName.values()];
 };
+var managedFields = flag => {
+  return flag.value === void 0 ? {
+    serverManaged: flag.managed
+  } : {
+    serverManaged: true,
+    pinnedValue: flag.value
+  };
+};
 var extractPathParams = args => {
   const toArgName = args.toArgName ?? snakeToCamel;
   const flag = args.serverManagedExtension ?? "x-mcp-server-managed";
@@ -363,7 +450,10 @@ var extractPathParams = args => {
     return {
       name: p.name || "",
       argName: toArgName(p.name || ""),
-      serverManaged: Boolean(p[flag])
+      ...managedFields(readServerManaged({
+        node: p,
+        extension: flag
+      }))
     };
   }));
 };
@@ -383,11 +473,13 @@ var extractQueryParams = args => {
       type: p.schema?.type || "string",
       style: p.style,
       explode: p.explode,
-      serverManaged: Boolean(p[flag])
+      ...managedFields(readServerManaged({
+        node: p,
+        extension: flag
+      }))
     };
   }));
 };
-/** Lists the path and query params flagged as server-managed. */
 var collectServerManagedParameters = args => {
   return [...args.pathParams.map(p => {
     return {
@@ -405,7 +497,10 @@ var collectServerManagedParameters = args => {
     return {
       name: p.name,
       in: p.in,
-      argName: p.argName
+      argName: p.argName,
+      ...(p.pinnedValue === void 0 ? {} : {
+        value: p.pinnedValue
+      })
     };
   });
 };
@@ -498,7 +593,7 @@ var buildInputSchema = (pathParams, queryParams, bodyProps) => {
     return p.argName;
   })];
   const properties = {};
-  for (const param of allParams) properties[param.argName] = "description" in param ? buildTypedProperty(param) : {
+  for (const param of allParams) properties[param.argName] = "description" in param ? normalizeNullable(buildTypedProperty(param)) : {
     type: "string",
     description: ""
   };
@@ -550,7 +645,10 @@ var extractBodyProps = args => {
   const bodySchema = resolveBodySchema(args);
   if (!bodySchema?.properties) return [];
   return Object.entries(bodySchema.properties).filter(([, value]) => {
-    return !value[args.serverManagedExtension];
+    return !readServerManaged({
+      node: value,
+      extension: args.serverManagedExtension
+    }).managed;
   }).map(([key, value]) => {
     const val = flattenSingleAllOf(value);
     return {
@@ -607,6 +705,11 @@ var processOperation = args => {
     toArgName
   });
   const inputSchema = buildInputSchema(pathParams, queryParams, bodyProps);
+  const serverManagedParameters = collectServerManagedParameters({
+    pathParams,
+    queryParams
+  });
+  const pinned = pinnedArgs(serverManagedParameters);
   const acceptedBodyFields = extractAcceptedBodyFields({
     requestBody: args.operation.requestBody,
     spec: args.spec,
@@ -619,15 +722,18 @@ var processOperation = args => {
     method: httpMethod,
     pathTemplate: args.pathTemplate,
     operationId: args.operation.operationId,
-    path: buildPathFn(args.pathTemplate, pathParams),
-    query: buildQueryFn(queryParams),
+    path: withPinned({
+      build: buildPathFn(args.pathTemplate, pathParams),
+      pinned
+    }),
+    query: withPinned({
+      build: buildQueryFn(queryParams),
+      pinned
+    }),
     body: buildBodyFn(bodyProps),
     acceptedBodyFields,
     extensions: extractExtensions(args.operation),
-    serverManagedParameters: collectServerManagedParameters({
-      pathParams,
-      queryParams
-    })
+    serverManagedParameters
   };
 };
 var processPath = args => {

package/dist/index.d.cts

@@ -84,6 +84,11 @@ interface ServerManagedParameter {
   in: 'path' | 'query';
   /** The args key `path` / `query` read the value from. */
   argName: string;
+  /**
+   * The value the spec pins, when the extension is a string. `path` / `query`
+   * always send it, whatever the args or `serverParameters` carry.
+   */
+  value?: string;
 }
 /** Minimal shape of an OpenAPI document consumed by the generator. */
 interface OpenApiSpec {
@@ -150,11 +155,14 @@ interface OpenApiToToolsOptions {
    * - 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.
+   *   `serverManagedParameters` and the consumer supplies its value. A string
+   *   extension value (`'true'`) pins it: the builders always send that value.
+   *
+   * Several names may be given; a node flagged by any of them is managed.
    *
    * @default 'x-mcp-server-managed'
    */
-  serverManagedExtension?: string;
+  serverManagedExtension?: string | string[];
   /**
    * How tool argument names are derived from the spec's parameter and
    * body-property names.
@@ -181,6 +189,10 @@ type ResolvedToolOptions = Required<Omit<OpenApiToToolsOptions, 'documents'>> &
 declare const DEFAULT_EXCLUDE_EXTENSION = "x-mcp-exclude";
 declare const DEFAULT_SERVER_MANAGED_EXTENSION = "x-mcp-server-managed";
 //#endregion
+//#region src/serverManaged.d.ts
+/** One extension name, or several that all mean "the server sets this". */
+type ServerManagedExtension = string | string[];
+//#endregion
 //#region src/parameters.d.ts
 /**
  * Folds `_` and `-` separators into camelCase. OpenAPI operation and parameter
@@ -200,12 +212,13 @@ type ExtractParamsArgs = {
   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;
+  serverManagedExtension?: ServerManagedExtension;
 };
 declare const extractPathParams: (args: ExtractParamsArgs) => Array<{
   name: string;
   argName: string;
   serverManaged: boolean;
+  pinnedValue?: string;
 }>;
 declare const extractQueryParams: (args: ExtractParamsArgs) => Array<{
   name: string;
@@ -216,6 +229,7 @@ declare const extractQueryParams: (args: ExtractParamsArgs) => Array<{
   style?: string;
   explode?: boolean;
   serverManaged: boolean;
+  pinnedValue?: string;
 }>;
 //#endregion
 //#region src/registerOpenApiTools.d.ts
@@ -415,7 +429,7 @@ declare const extractAcceptedBodyFields: (args: {
 declare const extractBodyProps: (args: {
   requestBody?: RequestBodySpec;
   spec: OpenApiSpec;
-  serverManagedExtension: string;
+  serverManagedExtension: ServerManagedExtension;
   documents?: OpenApiDocuments; /** Maps a spec name to its tool argument name. @default snakeToCamel */
   toArgName?: ToArgName;
 }) => Array<{

package/dist/index.d.mts

@@ -84,6 +84,11 @@ interface ServerManagedParameter {
   in: 'path' | 'query';
   /** The args key `path` / `query` read the value from. */
   argName: string;
+  /**
+   * The value the spec pins, when the extension is a string. `path` / `query`
+   * always send it, whatever the args or `serverParameters` carry.
+   */
+  value?: string;
 }
 /** Minimal shape of an OpenAPI document consumed by the generator. */
 interface OpenApiSpec {
@@ -150,11 +155,14 @@ interface OpenApiToToolsOptions {
    * - 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.
+   *   `serverManagedParameters` and the consumer supplies its value. A string
+   *   extension value (`'true'`) pins it: the builders always send that value.
+   *
+   * Several names may be given; a node flagged by any of them is managed.
    *
    * @default 'x-mcp-server-managed'
    */
-  serverManagedExtension?: string;
+  serverManagedExtension?: string | string[];
   /**
    * How tool argument names are derived from the spec's parameter and
    * body-property names.
@@ -181,6 +189,10 @@ type ResolvedToolOptions = Required<Omit<OpenApiToToolsOptions, 'documents'>> &
 declare const DEFAULT_EXCLUDE_EXTENSION = "x-mcp-exclude";
 declare const DEFAULT_SERVER_MANAGED_EXTENSION = "x-mcp-server-managed";
 //#endregion
+//#region src/serverManaged.d.ts
+/** One extension name, or several that all mean "the server sets this". */
+type ServerManagedExtension = string | string[];
+//#endregion
 //#region src/parameters.d.ts
 /**
  * Folds `_` and `-` separators into camelCase. OpenAPI operation and parameter
@@ -200,12 +212,13 @@ type ExtractParamsArgs = {
   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;
+  serverManagedExtension?: ServerManagedExtension;
 };
 declare const extractPathParams: (args: ExtractParamsArgs) => Array<{
   name: string;
   argName: string;
   serverManaged: boolean;
+  pinnedValue?: string;
 }>;
 declare const extractQueryParams: (args: ExtractParamsArgs) => Array<{
   name: string;
@@ -216,6 +229,7 @@ declare const extractQueryParams: (args: ExtractParamsArgs) => Array<{
   style?: string;
   explode?: boolean;
   serverManaged: boolean;
+  pinnedValue?: string;
 }>;
 //#endregion
 //#region src/registerOpenApiTools.d.ts
@@ -415,7 +429,7 @@ declare const extractAcceptedBodyFields: (args: {
 declare const extractBodyProps: (args: {
   requestBody?: RequestBodySpec;
   spec: OpenApiSpec;
-  serverManagedExtension: string;
+  serverManagedExtension: ServerManagedExtension;
   documents?: OpenApiDocuments; /** Maps a spec name to its tool argument name. @default snakeToCamel */
   toArgName?: ToArgName;
 }) => Array<{

package/dist/index.mjs

@@ -316,6 +316,85 @@ var buildBodyFn = bodyProps => {
   };
 };
 
+//#endregion
+//#region src/serverManaged.ts
+/**
+* Whether a parameter or body property carries one of the server-managed
+* extensions, and the value it pins when the extension is a string.
+*
+* A string pins the value (`x-mcp-server-managed: 'true'` always sends
+* `true`); any other truthy value only hides it. The first matching name wins.
+*/
+var readServerManaged = args => {
+  const names = Array.isArray(args.extension) ? args.extension : [args.extension];
+  for (const name of names) {
+    const flag = args.node[name];
+    if (typeof flag === "string") return {
+      managed: true,
+      value: flag
+    };
+    if (flag) return {
+      managed: true
+    };
+  }
+  return {
+    managed: false
+  };
+};
+/** The args each pinned parameter is always sent with, keyed by `argName`. */
+var pinnedArgs = parameters => {
+  const pinned = {};
+  for (const parameter of parameters) if (parameter.value !== void 0) pinned[parameter.argName] = parameter.value;
+  return pinned;
+};
+/**
+* Wraps a `path` / `query` builder so pinned values replace whatever the args
+* carry. Applied in the builder itself, so every consumer of the tool
+* definition sends them, not only `registerOpenApiTools`.
+*/
+var withPinned = args => {
+  const {
+    build,
+    pinned
+  } = args;
+  if (!build || Object.keys(pinned).length === 0) return build;
+  return values => {
+    return build({
+      ...values,
+      ...pinned
+    });
+  };
+};
+var isPlainObject$1 = value => {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+};
+var mergeNullIntoType = schema => {
+  const {
+    type
+  } = schema;
+  if (typeof type === "string") schema.type = [type, "null"];else if (Array.isArray(type) && !type.includes("null")) schema.type = [...type, "null"];
+};
+/**
+* Turns OpenAPI's `nullable` into JSON Schema at every depth: `nullable: true`
+* merges `'null'` into a sibling `type` and is dropped where there is none.
+* JSON Schema has no `nullable`, so a validator or model reading it would
+* refuse `null` where the API accepts it.
+*
+* Only a boolean `nullable` is the keyword; a property *named* `nullable`
+* inside `properties` is a schema and is kept.
+*/
+var normalizeNullable = value => {
+  if (Array.isArray(value)) return value.map(normalizeNullable);
+  if (!isPlainObject$1(value)) return value;
+  const result = {};
+  for (const [key, nested] of Object.entries(value)) {
+    if (key === "nullable" && typeof nested === "boolean") continue;
+    result[key] = normalizeNullable(nested);
+  }
+  if (value.nullable === true) mergeNullIntoType(result);
+  return result;
+};
+
 //#endregion
 //#region src/types.ts
 var DEFAULT_EXCLUDE_EXTENSION = "x-mcp-exclude";
@@ -349,6 +428,14 @@ var dedupeByName = items => {
   for (const item of items) byName.set(item.name, item);
   return [...byName.values()];
 };
+var managedFields = flag => {
+  return flag.value === void 0 ? {
+    serverManaged: flag.managed
+  } : {
+    serverManaged: true,
+    pinnedValue: flag.value
+  };
+};
 var extractPathParams = args => {
   const toArgName = args.toArgName ?? snakeToCamel;
   const flag = args.serverManagedExtension ?? "x-mcp-server-managed";
@@ -360,7 +447,10 @@ var extractPathParams = args => {
     return {
       name: p.name || "",
       argName: toArgName(p.name || ""),
-      serverManaged: Boolean(p[flag])
+      ...managedFields(readServerManaged({
+        node: p,
+        extension: flag
+      }))
     };
   }));
 };
@@ -380,11 +470,13 @@ var extractQueryParams = args => {
       type: p.schema?.type || "string",
       style: p.style,
       explode: p.explode,
-      serverManaged: Boolean(p[flag])
+      ...managedFields(readServerManaged({
+        node: p,
+        extension: flag
+      }))
     };
   }));
 };
-/** Lists the path and query params flagged as server-managed. */
 var collectServerManagedParameters = args => {
   return [...args.pathParams.map(p => {
     return {
@@ -402,7 +494,10 @@ var collectServerManagedParameters = args => {
     return {
       name: p.name,
       in: p.in,
-      argName: p.argName
+      argName: p.argName,
+      ...(p.pinnedValue === void 0 ? {} : {
+        value: p.pinnedValue
+      })
     };
   });
 };
@@ -495,7 +590,7 @@ var buildInputSchema = (pathParams, queryParams, bodyProps) => {
     return p.argName;
   })];
   const properties = {};
-  for (const param of allParams) properties[param.argName] = "description" in param ? buildTypedProperty(param) : {
+  for (const param of allParams) properties[param.argName] = "description" in param ? normalizeNullable(buildTypedProperty(param)) : {
     type: "string",
     description: ""
   };
@@ -547,7 +642,10 @@ var extractBodyProps = args => {
   const bodySchema = resolveBodySchema(args);
   if (!bodySchema?.properties) return [];
   return Object.entries(bodySchema.properties).filter(([, value]) => {
-    return !value[args.serverManagedExtension];
+    return !readServerManaged({
+      node: value,
+      extension: args.serverManagedExtension
+    }).managed;
   }).map(([key, value]) => {
     const val = flattenSingleAllOf(value);
     return {
@@ -604,6 +702,11 @@ var processOperation = args => {
     toArgName
   });
   const inputSchema = buildInputSchema(pathParams, queryParams, bodyProps);
+  const serverManagedParameters = collectServerManagedParameters({
+    pathParams,
+    queryParams
+  });
+  const pinned = pinnedArgs(serverManagedParameters);
   const acceptedBodyFields = extractAcceptedBodyFields({
     requestBody: args.operation.requestBody,
     spec: args.spec,
@@ -616,15 +719,18 @@ var processOperation = args => {
     method: httpMethod,
     pathTemplate: args.pathTemplate,
     operationId: args.operation.operationId,
-    path: buildPathFn(args.pathTemplate, pathParams),
-    query: buildQueryFn(queryParams),
+    path: withPinned({
+      build: buildPathFn(args.pathTemplate, pathParams),
+      pinned
+    }),
+    query: withPinned({
+      build: buildQueryFn(queryParams),
+      pinned
+    }),
     body: buildBodyFn(bodyProps),
     acceptedBodyFields,
     extensions: extractExtensions(args.operation),
-    serverManagedParameters: collectServerManagedParameters({
-      pathParams,
-      queryParams
-    })
+    serverManagedParameters
   };
 };
 var processPath = args => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttoss/http-server-mcp-openapi",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Generate Model Context Protocol (MCP) tools from an OpenAPI specification for @ttoss/http-server-mcp",
   "keywords": [
     "ai",
@@ -42,8 +42,8 @@
     "jest": "^30.4.2",
     "supertest": "^7.2.2",
     "tsdown": "^0.22.2",
-    "@ttoss/http-server": "^0.8.1",
-    "@ttoss/config": "^1.38.0"
+    "@ttoss/config": "^1.38.0",
+    "@ttoss/http-server": "^0.8.1"
   },
   "publishConfig": {
     "access": "public",