@ttoss/http-server-mcp-openapi 0.3.0 → 0.5.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
@@ -153,8 +157,9 @@ registerOpenApiTools({
 
 A value flagged with `serverManagedExtension` is never offered to the model:
 
-- A **request-body property** is hidden from `inputSchema` and never sent (the
-  API sets it itself). It still appears in `acceptedBodyFields`.
+- A **request-body property** is hidden from `inputSchema` and, unless pinned,
+  never sent (the API sets it itself). It still appears in
+  `acceptedBodyFields`.
 - A **path or query parameter** is hidden from `inputSchema` and listed in
   `tool.serverManagedParameters`. `registerOpenApiTools` discards anything the
   model sent for it and fills it from `serverParameters`, keyed by spec name:
@@ -173,6 +178,18 @@ 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`.
+
+A pinned **request-body property** is sent by `tool.body`, over anything in the
+args, as the JSON type its schema declares: `'true'` on a `boolean` is `true`,
+`'3'` on an `integer` is `3`. A pin its type cannot hold (`'yes'` on a
+`boolean`, any pin on an `object`, `array` or untyped property) throws while
+the tools are generated, naming the operation and property.
+
 ### Reading custom extensions
 
 Every `x-` prefixed extension on an operation is forwarded verbatim on

package/dist/index.cjs

@@ -319,6 +319,136 @@ 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 parseNumber = value => {
+  const parsed = Number(value);
+  return value.trim() !== "" && Number.isFinite(parsed) ? parsed : void 0;
+};
+/** Each JSON type a pin can hold, and how its text reads as that type. */
+var PIN_PARSERS = {
+  string: value => {
+    return value;
+  },
+  boolean: value => {
+    if (value === "true") return true;
+    if (value === "false") return false;
+  },
+  number: parseNumber,
+  integer: value => {
+    const parsed = parseNumber(value);
+    return parsed !== void 0 && Number.isInteger(parsed) ? parsed : void 0;
+  }
+};
+/**
+* Reads a pinned body value as the JSON type its schema declares. A body is
+* JSON, so `'true'` on a boolean must reach the API as `true`; a query string
+* carries the text either way. A pin the type cannot hold is a spec error.
+*/
+var typedPin = args => {
+  const {
+    value,
+    type,
+    where
+  } = args;
+  const typed = (typeof type === "string" ? PIN_PARSERS[type] : void 0)?.(value);
+  if (typed !== void 0) return typed;
+  throw new Error(`${where}: cannot pin '${value}' on a property of type ${JSON.stringify(type ?? "any")}; a pinned body property must be a boolean, integer, number or string that holds the value.`);
+};
+/**
+* Wraps a `body` builder so pinned values replace whatever the args carry. An
+* operation whose only body properties are pinned still gets a builder.
+*/
+var withPinnedBody = args => {
+  const {
+    build,
+    pinned
+  } = args;
+  if (Object.keys(pinned).length === 0) return build;
+  return values => {
+    return {
+      ...(build ? 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 +482,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 +501,10 @@ var extractPathParams = args => {
     return {
       name: p.name || "",
       argName: toArgName(p.name || ""),
-      serverManaged: Boolean(p[flag])
+      ...managedFields(readServerManaged({
+        node: p,
+        extension: flag
+      }))
     };
   }));
 };
@@ -383,11 +524,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,11 +548,102 @@ var collectServerManagedParameters = args => {
     return {
       name: p.name,
       in: p.in,
-      argName: p.argName
+      argName: p.argName,
+      ...(p.pinnedValue === void 0 ? {} : {
+        value: p.pinnedValue
+      })
     };
   });
 };
 
+//#endregion
+//#region src/body.ts
+var resolveBodySchema = args => {
+  const rawBodySchema = args.requestBody?.content?.["application/json"]?.schema;
+  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
+* declares, including server-managed ones.
+*/
+var extractAcceptedBodyFields = args => {
+  const bodySchema = resolveBodySchema(args);
+  return Object.keys(bodySchema?.properties ?? {});
+};
+var isPlainObject = value => {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+};
+/**
+* Folds a single-entry `allOf` into the property that wraps it. OpenAPI
+* declares `allOf: [{ $ref }]` so a property can carry its own `description`
+* next to a referenced schema; without folding, the referenced `type`,
+* `nullable` and `items` would be lost. Keys on the wrapper win over the
+* referenced schema's. Multi-entry `allOf` is left intact.
+*/
+var flattenSingleAllOf = schema => {
+  const {
+    allOf,
+    ...rest
+  } = schema;
+  if (!Array.isArray(allOf) || allOf.length !== 1) return schema;
+  const [entry] = allOf;
+  if (!isPlainObject(entry)) return rest;
+  return {
+    ...flattenSingleAllOf(entry),
+    ...rest
+  };
+};
+var extractBodyProps = args => {
+  const toArgName = args.toArgName ?? snakeToCamel;
+  const bodySchema = resolveBodySchema(args);
+  if (!bodySchema?.properties) return [];
+  return Object.entries(bodySchema.properties).filter(([, value]) => {
+    return !readServerManaged({
+      node: value,
+      extension: args.serverManagedExtension
+    }).managed;
+  }).map(([key, value]) => {
+    const val = flattenSingleAllOf(value);
+    return {
+      snakeName: 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,
+      items: val.items,
+      nullable: val.nullable === true,
+      oneOf: Array.isArray(val.oneOf) ? val.oneOf : void 0,
+      anyOf: Array.isArray(val.anyOf) ? val.anyOf : void 0,
+      allOf: Array.isArray(val.allOf) ? val.allOf : void 0
+    };
+  });
+};
+/**
+* The value each server-managed body property pins, typed by its schema and
+* keyed by its spec name. A property whose extension is not a string pins
+* nothing: it is only hidden, for the consumer to fill.
+*/
+var extractPinnedBody = args => {
+  const bodySchema = resolveBodySchema(args);
+  const pinned = {};
+  for (const [key, value] of Object.entries(bodySchema?.properties ?? {})) {
+    const node = value;
+    const {
+      value: pin
+    } = readServerManaged({
+      node,
+      extension: args.serverManagedExtension
+    });
+    if (pin === void 0) continue;
+    pinned[key] = typedPin({
+      value: pin,
+      type: flattenSingleAllOf(node).type,
+      where: `${args.operationId} body property '${key}'`
+    });
+  }
+  return pinned;
+};
+
 //#endregion
 //#region src/toolDefinitions.ts
 /** Converts a camelCase `operationId` to a kebab-case tool name. */
@@ -498,7 +732,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: ""
   };
@@ -510,63 +744,6 @@ var buildInputSchema = (pathParams, queryParams, bodyProps) => {
     } : {})
   };
 };
-var resolveBodySchema = args => {
-  const rawBodySchema = args.requestBody?.content?.["application/json"]?.schema;
-  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
-* declares, including server-managed ones.
-*/
-var extractAcceptedBodyFields = args => {
-  const bodySchema = resolveBodySchema(args);
-  return Object.keys(bodySchema?.properties ?? {});
-};
-var isPlainObject = value => {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-};
-/**
-* Folds a single-entry `allOf` into the property that wraps it. OpenAPI
-* declares `allOf: [{ $ref }]` so a property can carry its own `description`
-* next to a referenced schema; without folding, the referenced `type`,
-* `nullable` and `items` would be lost. Keys on the wrapper win over the
-* referenced schema's. Multi-entry `allOf` is left intact.
-*/
-var flattenSingleAllOf = schema => {
-  const {
-    allOf,
-    ...rest
-  } = schema;
-  if (!Array.isArray(allOf) || allOf.length !== 1) return schema;
-  const [entry] = allOf;
-  if (!isPlainObject(entry)) return rest;
-  return {
-    ...flattenSingleAllOf(entry),
-    ...rest
-  };
-};
-var extractBodyProps = args => {
-  const toArgName = args.toArgName ?? snakeToCamel;
-  const bodySchema = resolveBodySchema(args);
-  if (!bodySchema?.properties) return [];
-  return Object.entries(bodySchema.properties).filter(([, value]) => {
-    return !value[args.serverManagedExtension];
-  }).map(([key, value]) => {
-    const val = flattenSingleAllOf(value);
-    return {
-      snakeName: 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,
-      items: val.items,
-      nullable: val.nullable === true,
-      oneOf: Array.isArray(val.oneOf) ? val.oneOf : void 0,
-      anyOf: Array.isArray(val.anyOf) ? val.anyOf : void 0,
-      allOf: Array.isArray(val.allOf) ? val.allOf : void 0
-    };
-  });
-};
 /** Collects every `x-` prefixed extension declared on the operation. */
 var extractExtensions = operation => {
   const extensions = {};
@@ -599,19 +776,22 @@ var processOperation = args => {
     toArgName,
     serverManagedExtension
   });
-  const bodyProps = extractBodyProps({
+  const bodyArgs = {
     requestBody: args.operation.requestBody,
     spec: args.spec,
     serverManagedExtension,
-    documents,
+    documents
+  };
+  const bodyProps = extractBodyProps({
+    ...bodyArgs,
     toArgName
   });
   const inputSchema = buildInputSchema(pathParams, queryParams, bodyProps);
-  const acceptedBodyFields = extractAcceptedBodyFields({
-    requestBody: args.operation.requestBody,
-    spec: args.spec,
-    documents
+  const serverManagedParameters = collectServerManagedParameters({
+    pathParams,
+    queryParams
   });
+  const pinned = pinnedArgs(serverManagedParameters);
   return {
     name: toolName,
     description: sanitizeDescription(args.operation.description),
@@ -619,15 +799,24 @@ var processOperation = args => {
     method: httpMethod,
     pathTemplate: args.pathTemplate,
     operationId: args.operation.operationId,
-    path: buildPathFn(args.pathTemplate, pathParams),
-    query: buildQueryFn(queryParams),
-    body: buildBodyFn(bodyProps),
-    acceptedBodyFields,
+    path: withPinned({
+      build: buildPathFn(args.pathTemplate, pathParams),
+      pinned
+    }),
+    query: withPinned({
+      build: buildQueryFn(queryParams),
+      pinned
+    }),
+    body: withPinnedBody({
+      build: buildBodyFn(bodyProps),
+      pinned: extractPinnedBody({
+        ...bodyArgs,
+        operationId: args.operation.operationId
+      })
+    }),
+    acceptedBodyFields: extractAcceptedBodyFields(bodyArgs),
     extensions: extractExtensions(args.operation),
-    serverManagedParameters: collectServerManagedParameters({
-      pathParams,
-      queryParams
-    })
+    serverManagedParameters
   };
 };
 var processPath = args => {
@@ -787,6 +976,7 @@ exports.dereferenceSchema = dereferenceSchema;
 exports.extractAcceptedBodyFields = extractAcceptedBodyFields;
 exports.extractBodyProps = extractBodyProps;
 exports.extractPathParams = extractPathParams;
+exports.extractPinnedBody = extractPinnedBody;
 exports.extractQueryParams = extractQueryParams;
 exports.getJsonSchemaType = getJsonSchemaType;
 exports.openApiToToolDefinitions = openApiToToolDefinitions;

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,8 +229,50 @@ declare const extractQueryParams: (args: ExtractParamsArgs) => Array<{
   style?: string;
   explode?: boolean;
   serverManaged: boolean;
+  pinnedValue?: string;
 }>;
 //#endregion
+//#region src/body.d.ts
+/**
+ * snake_case names of every top-level property an operation's request schema
+ * declares, including server-managed ones.
+ */
+declare const extractAcceptedBodyFields: (args: {
+  requestBody?: RequestBodySpec;
+  spec: OpenApiSpec;
+  documents?: OpenApiDocuments;
+}) => string[];
+declare const extractBodyProps: (args: {
+  requestBody?: RequestBodySpec;
+  spec: OpenApiSpec;
+  serverManagedExtension: ServerManagedExtension;
+  documents?: OpenApiDocuments; /** Maps a spec name to its tool argument name. @default snakeToCamel */
+  toArgName?: ToArgName;
+}) => Array<{
+  snakeName: string;
+  argName: string;
+  description: string;
+  required: boolean;
+  type?: string;
+  items?: unknown;
+  nullable: boolean;
+  oneOf?: unknown[];
+  anyOf?: unknown[];
+  allOf?: unknown[];
+}>;
+/**
+ * The value each server-managed body property pins, typed by its schema and
+ * keyed by its spec name. A property whose extension is not a string pins
+ * nothing: it is only hidden, for the consumer to fill.
+ */
+declare const extractPinnedBody: (args: {
+  requestBody?: RequestBodySpec;
+  spec: OpenApiSpec;
+  serverManagedExtension: ServerManagedExtension;
+  documents?: OpenApiDocuments;
+  operationId: string;
+}) => Record<string, string | number | boolean>;
+//#endregion
 //#region src/registerOpenApiTools.d.ts
 /** The resolved HTTP request a tool call maps to, before transport concerns. */
 interface ResolvedRequest {
@@ -403,33 +458,6 @@ declare const buildInputSchema: (pathParams: Array<{
   anyOf?: unknown[];
   allOf?: unknown[];
 }>) => JsonObjectSchema;
-/**
- * snake_case names of every top-level property an operation's request schema
- * declares, including server-managed ones.
- */
-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;
-  argName: string;
-  description: string;
-  required: boolean;
-  type?: string;
-  items?: unknown;
-  nullable: boolean;
-  oneOf?: unknown[];
-  anyOf?: unknown[];
-  allOf?: unknown[];
-}>;
 declare const processOperation: (args: {
   pathTemplate: string;
   method: string;
@@ -470,4 +498,4 @@ declare const openApiToToolDefinitions: (args: {
   options?: OpenApiToToolsOptions;
 }) => ToolDefinition[];
 //#endregion
-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 };
+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, extractPinnedBody, extractQueryParams, getJsonSchemaType, openApiToToolDefinitions, operationIdToToolName, processOperation, processPath, registerOpenApiTools, resolveParameter, resolveSchema, snakeToCamel };

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,8 +229,50 @@ declare const extractQueryParams: (args: ExtractParamsArgs) => Array<{
   style?: string;
   explode?: boolean;
   serverManaged: boolean;
+  pinnedValue?: string;
 }>;
 //#endregion
+//#region src/body.d.ts
+/**
+ * snake_case names of every top-level property an operation's request schema
+ * declares, including server-managed ones.
+ */
+declare const extractAcceptedBodyFields: (args: {
+  requestBody?: RequestBodySpec;
+  spec: OpenApiSpec;
+  documents?: OpenApiDocuments;
+}) => string[];
+declare const extractBodyProps: (args: {
+  requestBody?: RequestBodySpec;
+  spec: OpenApiSpec;
+  serverManagedExtension: ServerManagedExtension;
+  documents?: OpenApiDocuments; /** Maps a spec name to its tool argument name. @default snakeToCamel */
+  toArgName?: ToArgName;
+}) => Array<{
+  snakeName: string;
+  argName: string;
+  description: string;
+  required: boolean;
+  type?: string;
+  items?: unknown;
+  nullable: boolean;
+  oneOf?: unknown[];
+  anyOf?: unknown[];
+  allOf?: unknown[];
+}>;
+/**
+ * The value each server-managed body property pins, typed by its schema and
+ * keyed by its spec name. A property whose extension is not a string pins
+ * nothing: it is only hidden, for the consumer to fill.
+ */
+declare const extractPinnedBody: (args: {
+  requestBody?: RequestBodySpec;
+  spec: OpenApiSpec;
+  serverManagedExtension: ServerManagedExtension;
+  documents?: OpenApiDocuments;
+  operationId: string;
+}) => Record<string, string | number | boolean>;
+//#endregion
 //#region src/registerOpenApiTools.d.ts
 /** The resolved HTTP request a tool call maps to, before transport concerns. */
 interface ResolvedRequest {
@@ -403,33 +458,6 @@ declare const buildInputSchema: (pathParams: Array<{
   anyOf?: unknown[];
   allOf?: unknown[];
 }>) => JsonObjectSchema;
-/**
- * snake_case names of every top-level property an operation's request schema
- * declares, including server-managed ones.
- */
-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;
-  argName: string;
-  description: string;
-  required: boolean;
-  type?: string;
-  items?: unknown;
-  nullable: boolean;
-  oneOf?: unknown[];
-  anyOf?: unknown[];
-  allOf?: unknown[];
-}>;
 declare const processOperation: (args: {
   pathTemplate: string;
   method: string;
@@ -470,4 +498,4 @@ declare const openApiToToolDefinitions: (args: {
   options?: OpenApiToToolsOptions;
 }) => ToolDefinition[];
 //#endregion
-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 };
+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, extractPinnedBody, extractQueryParams, getJsonSchemaType, openApiToToolDefinitions, operationIdToToolName, processOperation, processPath, registerOpenApiTools, resolveParameter, resolveSchema, snakeToCamel };

package/dist/index.mjs

@@ -316,6 +316,136 @@ 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 parseNumber = value => {
+  const parsed = Number(value);
+  return value.trim() !== "" && Number.isFinite(parsed) ? parsed : void 0;
+};
+/** Each JSON type a pin can hold, and how its text reads as that type. */
+var PIN_PARSERS = {
+  string: value => {
+    return value;
+  },
+  boolean: value => {
+    if (value === "true") return true;
+    if (value === "false") return false;
+  },
+  number: parseNumber,
+  integer: value => {
+    const parsed = parseNumber(value);
+    return parsed !== void 0 && Number.isInteger(parsed) ? parsed : void 0;
+  }
+};
+/**
+* Reads a pinned body value as the JSON type its schema declares. A body is
+* JSON, so `'true'` on a boolean must reach the API as `true`; a query string
+* carries the text either way. A pin the type cannot hold is a spec error.
+*/
+var typedPin = args => {
+  const {
+    value,
+    type,
+    where
+  } = args;
+  const typed = (typeof type === "string" ? PIN_PARSERS[type] : void 0)?.(value);
+  if (typed !== void 0) return typed;
+  throw new Error(`${where}: cannot pin '${value}' on a property of type ${JSON.stringify(type ?? "any")}; a pinned body property must be a boolean, integer, number or string that holds the value.`);
+};
+/**
+* Wraps a `body` builder so pinned values replace whatever the args carry. An
+* operation whose only body properties are pinned still gets a builder.
+*/
+var withPinnedBody = args => {
+  const {
+    build,
+    pinned
+  } = args;
+  if (Object.keys(pinned).length === 0) return build;
+  return values => {
+    return {
+      ...(build ? 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 +479,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 +498,10 @@ var extractPathParams = args => {
     return {
       name: p.name || "",
       argName: toArgName(p.name || ""),
-      serverManaged: Boolean(p[flag])
+      ...managedFields(readServerManaged({
+        node: p,
+        extension: flag
+      }))
     };
   }));
 };
@@ -380,11 +521,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,11 +545,102 @@ var collectServerManagedParameters = args => {
     return {
       name: p.name,
       in: p.in,
-      argName: p.argName
+      argName: p.argName,
+      ...(p.pinnedValue === void 0 ? {} : {
+        value: p.pinnedValue
+      })
     };
   });
 };
 
+//#endregion
+//#region src/body.ts
+var resolveBodySchema = args => {
+  const rawBodySchema = args.requestBody?.content?.["application/json"]?.schema;
+  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
+* declares, including server-managed ones.
+*/
+var extractAcceptedBodyFields = args => {
+  const bodySchema = resolveBodySchema(args);
+  return Object.keys(bodySchema?.properties ?? {});
+};
+var isPlainObject = value => {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+};
+/**
+* Folds a single-entry `allOf` into the property that wraps it. OpenAPI
+* declares `allOf: [{ $ref }]` so a property can carry its own `description`
+* next to a referenced schema; without folding, the referenced `type`,
+* `nullable` and `items` would be lost. Keys on the wrapper win over the
+* referenced schema's. Multi-entry `allOf` is left intact.
+*/
+var flattenSingleAllOf = schema => {
+  const {
+    allOf,
+    ...rest
+  } = schema;
+  if (!Array.isArray(allOf) || allOf.length !== 1) return schema;
+  const [entry] = allOf;
+  if (!isPlainObject(entry)) return rest;
+  return {
+    ...flattenSingleAllOf(entry),
+    ...rest
+  };
+};
+var extractBodyProps = args => {
+  const toArgName = args.toArgName ?? snakeToCamel;
+  const bodySchema = resolveBodySchema(args);
+  if (!bodySchema?.properties) return [];
+  return Object.entries(bodySchema.properties).filter(([, value]) => {
+    return !readServerManaged({
+      node: value,
+      extension: args.serverManagedExtension
+    }).managed;
+  }).map(([key, value]) => {
+    const val = flattenSingleAllOf(value);
+    return {
+      snakeName: 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,
+      items: val.items,
+      nullable: val.nullable === true,
+      oneOf: Array.isArray(val.oneOf) ? val.oneOf : void 0,
+      anyOf: Array.isArray(val.anyOf) ? val.anyOf : void 0,
+      allOf: Array.isArray(val.allOf) ? val.allOf : void 0
+    };
+  });
+};
+/**
+* The value each server-managed body property pins, typed by its schema and
+* keyed by its spec name. A property whose extension is not a string pins
+* nothing: it is only hidden, for the consumer to fill.
+*/
+var extractPinnedBody = args => {
+  const bodySchema = resolveBodySchema(args);
+  const pinned = {};
+  for (const [key, value] of Object.entries(bodySchema?.properties ?? {})) {
+    const node = value;
+    const {
+      value: pin
+    } = readServerManaged({
+      node,
+      extension: args.serverManagedExtension
+    });
+    if (pin === void 0) continue;
+    pinned[key] = typedPin({
+      value: pin,
+      type: flattenSingleAllOf(node).type,
+      where: `${args.operationId} body property '${key}'`
+    });
+  }
+  return pinned;
+};
+
 //#endregion
 //#region src/toolDefinitions.ts
 /** Converts a camelCase `operationId` to a kebab-case tool name. */
@@ -495,7 +729,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: ""
   };
@@ -507,63 +741,6 @@ var buildInputSchema = (pathParams, queryParams, bodyProps) => {
     } : {})
   };
 };
-var resolveBodySchema = args => {
-  const rawBodySchema = args.requestBody?.content?.["application/json"]?.schema;
-  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
-* declares, including server-managed ones.
-*/
-var extractAcceptedBodyFields = args => {
-  const bodySchema = resolveBodySchema(args);
-  return Object.keys(bodySchema?.properties ?? {});
-};
-var isPlainObject = value => {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-};
-/**
-* Folds a single-entry `allOf` into the property that wraps it. OpenAPI
-* declares `allOf: [{ $ref }]` so a property can carry its own `description`
-* next to a referenced schema; without folding, the referenced `type`,
-* `nullable` and `items` would be lost. Keys on the wrapper win over the
-* referenced schema's. Multi-entry `allOf` is left intact.
-*/
-var flattenSingleAllOf = schema => {
-  const {
-    allOf,
-    ...rest
-  } = schema;
-  if (!Array.isArray(allOf) || allOf.length !== 1) return schema;
-  const [entry] = allOf;
-  if (!isPlainObject(entry)) return rest;
-  return {
-    ...flattenSingleAllOf(entry),
-    ...rest
-  };
-};
-var extractBodyProps = args => {
-  const toArgName = args.toArgName ?? snakeToCamel;
-  const bodySchema = resolveBodySchema(args);
-  if (!bodySchema?.properties) return [];
-  return Object.entries(bodySchema.properties).filter(([, value]) => {
-    return !value[args.serverManagedExtension];
-  }).map(([key, value]) => {
-    const val = flattenSingleAllOf(value);
-    return {
-      snakeName: 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,
-      items: val.items,
-      nullable: val.nullable === true,
-      oneOf: Array.isArray(val.oneOf) ? val.oneOf : void 0,
-      anyOf: Array.isArray(val.anyOf) ? val.anyOf : void 0,
-      allOf: Array.isArray(val.allOf) ? val.allOf : void 0
-    };
-  });
-};
 /** Collects every `x-` prefixed extension declared on the operation. */
 var extractExtensions = operation => {
   const extensions = {};
@@ -596,19 +773,22 @@ var processOperation = args => {
     toArgName,
     serverManagedExtension
   });
-  const bodyProps = extractBodyProps({
+  const bodyArgs = {
     requestBody: args.operation.requestBody,
     spec: args.spec,
     serverManagedExtension,
-    documents,
+    documents
+  };
+  const bodyProps = extractBodyProps({
+    ...bodyArgs,
     toArgName
   });
   const inputSchema = buildInputSchema(pathParams, queryParams, bodyProps);
-  const acceptedBodyFields = extractAcceptedBodyFields({
-    requestBody: args.operation.requestBody,
-    spec: args.spec,
-    documents
+  const serverManagedParameters = collectServerManagedParameters({
+    pathParams,
+    queryParams
   });
+  const pinned = pinnedArgs(serverManagedParameters);
   return {
     name: toolName,
     description: sanitizeDescription(args.operation.description),
@@ -616,15 +796,24 @@ var processOperation = args => {
     method: httpMethod,
     pathTemplate: args.pathTemplate,
     operationId: args.operation.operationId,
-    path: buildPathFn(args.pathTemplate, pathParams),
-    query: buildQueryFn(queryParams),
-    body: buildBodyFn(bodyProps),
-    acceptedBodyFields,
+    path: withPinned({
+      build: buildPathFn(args.pathTemplate, pathParams),
+      pinned
+    }),
+    query: withPinned({
+      build: buildQueryFn(queryParams),
+      pinned
+    }),
+    body: withPinnedBody({
+      build: buildBodyFn(bodyProps),
+      pinned: extractPinnedBody({
+        ...bodyArgs,
+        operationId: args.operation.operationId
+      })
+    }),
+    acceptedBodyFields: extractAcceptedBodyFields(bodyArgs),
     extensions: extractExtensions(args.operation),
-    serverManagedParameters: collectServerManagedParameters({
-      pathParams,
-      queryParams
-    })
+    serverManagedParameters
   };
 };
 var processPath = args => {
@@ -773,4 +962,4 @@ var registerOpenApiTools = args => {
 };
 
 //#endregion
-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 };
+export { DEFAULT_EXCLUDE_EXTENSION, DEFAULT_SERVER_MANAGED_EXTENSION, NO_CONTENT_TEXT, buildBodyFn, buildInputSchema, buildPathFn, buildQueryFn, dereferenceSchema, extractAcceptedBodyFields, extractBodyProps, extractPathParams, extractPinnedBody, 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.3.0",
+  "version": "0.5.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",