@ttoss/http-server-mcp-openapi 0.5.6 → 0.6.0

package/README.md

@@ -104,6 +104,43 @@ reaches the client as a success.
 
 Returns the list of `ToolDefinition`s that were registered.
 
+## Calling the API In-Process
+
+When the REST API runs in the same process as the MCP server,
+`createInProcessCallApi` dispatches each tool call through the app's own
+middleware chain with no socket (see `dispatchInProcess` in
+[@ttoss/http-server](https://ttoss.dev/docs/modules/packages/http-server)), so
+validation, authorization and error handling exist once, in the routes. The MCP
+request's headers — what `createMcpRouter`'s `getApiHeaders` produced — are
+forwarded onto the dispatched request.
+
+```typescript
+import {
+  createInProcessCallApi,
+  registerOpenApiTools,
+} from '@ttoss/http-server-mcp-openapi';
+
+registerOpenApiTools({
+  server,
+  spec,
+  callApi: createInProcessCallApi({
+    app, // or () => app, when the app is built after the tools
+    headers: () => ({ 'x-via': 'mcp' }), // optional, added to every call
+  }),
+});
+
+const router = createMcpRouter(server, {
+  getApiHeaders: (ctx) => ({ authorization: ctx.headers.authorization ?? '' }),
+});
+app.use(router.routes());
+```
+
+A 2xx answers its body. Anything else throws, so the client sees a tool error
+rather than an error body rendered as a result: the message is read from a
+string body, `{ error: '…' }`, `{ error: { code, message } }` (as
+`code: message`) or `{ message: '…' }` (exported as `errorMessageOf`), falling
+back to `HTTP <status>`. Pass `toError` to build the error yourself.
+
 ## `openApiToToolDefinitions`
 
 Use the lower-level function when you want the tool definitions without
@@ -137,6 +174,8 @@ registerOpenApiTools({
     serverManagedExtension: 'x-mcp-server-managed', // or several: ['x-a', 'x-b']
     argumentNames: 'camelCase', // or 'verbatim'
     documents: { './tags.yaml': tagsDocument }, // targets of cross-file $refs
+    schemaDetail: 'full', // or 'compact' (default)
+    describe: ({ operation, method, pathTemplate }) => operation.summary ?? '',
   },
 });
 ```
@@ -153,6 +192,31 @@ registerOpenApiTools({
   a sibling resolve against that sibling. A ref to a file missing from the map
   resolves to an empty schema, which accepts any value.
 
+- **`schemaDetail`** (default `compact`) — see [Schema detail](#schema-detail).
+- **`describe`** — builds each tool's description from `{ operation, method, pathTemplate }`
+  (method uppercase). The default is the operation's `description` flattened to one line.
+
+### Schema detail
+
+`compact` gives each top-level argument its `type`, `items` and `description`,
+with descriptions flattened to one line. It is the smallest surface, and the
+model learns nothing about which values are allowed.
+
+`full` gives each argument its whole schema: `enum`, `format`, `pattern`,
+`minimum`/`maximum`, `default`, nested `properties` and `required`, `oneOf`,
+`additionalProperties`, and descriptions verbatim. It changes only what JSON
+Schema cannot express:
+
+- `allOf` is merged — the properties and `required` of an object composition,
+  or a single referenced scalar with the wrapper's own `description` winning;
+- `nullable: true` adds `'null'` to the `type`, and `null` to an `enum`;
+- OpenAPI-only keywords (`example`, `discriminator`, `xml`, `externalDocs`) and
+  `x-` extensions are dropped;
+- a path or query parameter's own `description` wins over its schema's.
+
+`properties` is always present in `full`, even when empty. The same
+transformation is exported as `toToolSchema`, for a schema you derive yourself.
+
 ### Server-managed values
 
 A value flagged with `serverManagedExtension` is never offered to the model:

package/dist/index.cjs

@@ -2,10 +2,11 @@
 Object.defineProperty(exports, Symbol.toStringTag, {
   value: 'Module'
 });
+let _ttoss_http_server = require("@ttoss/http-server");
 let _ttoss_http_server_mcp = require("@ttoss/http-server-mcp");
 
 //#region src/schema.ts
-var isRecord = value => {
+var isRecord$1 = value => {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 };
 var getAlternativeSchemas = schema => {
@@ -42,7 +43,7 @@ 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;
+    if (!isRecord$1(current) && !Array.isArray(current)) return void 0;
     const token = decodeURIComponent(rawToken).replace(/~1/g, "/").replace(/~0/g, "~");
     current = current[token];
   }
@@ -101,7 +102,7 @@ var dereferenceValue = args => {
       seenRefs
     });
   });
-  if (isRecord(value)) {
+  if (isRecord$1(value)) {
     if (typeof value.$ref === "string") {
       const target = resolveRef({
         ref: value.$ref,
@@ -181,7 +182,7 @@ var resolveParameter = (param, spec, documents) => {
         documents
       }
     });
-    return isRecord(target?.value) ? target.value : {};
+    return isRecord$1(target?.value) ? target.value : {};
   }
   return param;
 };
@@ -220,7 +221,7 @@ var appendDeepObject = args => {
     });
     return;
   }
-  if (isRecord(args.value)) {
+  if (isRecord$1(args.value)) {
     for (const [property, propertyValue] of Object.entries(args.value)) appendDeepObject({
       search: args.search,
       key: `${args.key}[${property}]`,
@@ -272,7 +273,7 @@ var appendQueryValue = args => {
     });
     return;
   }
-  if (isRecord(args.value)) {
+  if (isRecord$1(args.value)) {
     appendObjectValue({
       ...serialization,
       value: args.value
@@ -501,6 +502,8 @@ var extractPathParams = args => {
     return {
       name: p.name || "",
       argName: toArgName(p.name || ""),
+      description: p.description,
+      schema: dereferenceSchema(p.schema, args.spec, args.documents),
       ...managedFields(readServerManaged({
         node: p,
         extension: flag
@@ -522,6 +525,7 @@ var extractQueryParams = args => {
       description: p.description || "",
       required: p.required || false,
       type: p.schema?.type || "string",
+      schema: dereferenceSchema(p.schema, args.spec, args.documents),
       style: p.style,
       explode: p.explode,
       ...managedFields(readServerManaged({
@@ -614,7 +618,8 @@ var extractBodyProps = args => {
       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
+      allOf: Array.isArray(val.allOf) ? val.allOf : void 0,
+      schema: value
     };
   });
 };
@@ -644,6 +649,209 @@ var extractPinnedBody = args => {
   return pinned;
 };
 
+//#endregion
+//#region src/fullSchema.ts
+var isRecord = value => {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+};
+var OPENAPI_ONLY_KEYWORDS = new Set(["discriminator", "example", "externalDocs", "xml"]);
+var SCHEMA_MAPS = new Set(["$defs", "definitions", "dependentSchemas", "patternProperties", "properties"]);
+var SCHEMA_VALUES = new Set(["additionalProperties", "contains", "else", "if", "items", "not", "propertyNames", "then", "unevaluatedItems", "unevaluatedProperties"]);
+var SCHEMA_LISTS = new Set(["anyOf", "oneOf", "prefixItems"]);
+/**
+* OpenAPI 3.0's `nullable: true` in JSON Schema: `'null'` joins the `type`,
+* and `null` joins an `enum`, which would otherwise still refuse it.
+*/
+var withNull = schema => {
+  const result = {
+    ...schema
+  };
+  if (typeof result.type === "string") result.type = [result.type, "null"];else if (Array.isArray(result.type) && !result.type.includes("null")) result.type = [...result.type, "null"];
+  if (Array.isArray(result.enum) && !result.enum.includes(null)) result.enum = [...result.enum, null];
+  return result;
+};
+/**
+* Merges an `allOf` into one schema, the shape a tool argument needs.
+*
+* Members that declare `properties` are an object composition — a write body
+* that is a patch plus two fields — and merge their properties and `required`.
+* Otherwise the `allOf` only wraps a referenced scalar so it can carry its own
+* `description` (the one way OpenAPI 3.0 allows beside a `$ref`), and the
+* members are merged as they are. Sibling keys win in both, because the
+* wrapper exists to say something the referenced schema does not.
+*/
+var mergeAllOf = args => {
+  const {
+    members,
+    siblings
+  } = args;
+  if (!members.some(member => {
+    return member.properties !== void 0;
+  })) return Object.assign({}, ...members, siblings);
+  const properties = {};
+  const required = [];
+  for (const member of members) {
+    Object.assign(properties, member.properties);
+    if (Array.isArray(member.required)) required.push(...member.required);
+  }
+  return {
+    ...siblings,
+    type: "object",
+    properties,
+    ...(required.length > 0 ? {
+      required: [...new Set(required)]
+    } : {})
+  };
+};
+var normalizeChildren = args => {
+  const {
+    schema,
+    next
+  } = args;
+  const result = {};
+  for (const [key, value] of Object.entries(schema)) {
+    if (OPENAPI_ONLY_KEYWORDS.has(key) || key.startsWith("x-")) continue;
+    if (SCHEMA_MAPS.has(key) && isRecord(value)) result[key] = Object.fromEntries(Object.entries(value).map(([name, child]) => {
+      return [name, next(child)];
+    }));else if (SCHEMA_VALUES.has(key) && isRecord(value)) result[key] = next(value);else if (SCHEMA_LISTS.has(key) && Array.isArray(value)) result[key] = value.map(next);else result[key] = value;
+  }
+  return result;
+};
+/**
+* Turns an already-dereferenced OpenAPI schema into the JSON Schema a tool
+* argument carries, keeping every constraint it declares — `enum`, `format`,
+* `pattern`, `minimum`, `default`, nested `properties` and `required`,
+* `oneOf` — and changing only what JSON Schema cannot express: `allOf` is
+* merged, `nullable` becomes a `'null'` type, and OpenAPI-only keywords and
+* `x-` extensions are dropped. Descriptions are kept verbatim.
+*/
+var toToolSchema = value => {
+  if (!isRecord(value)) return value;
+  const {
+    allOf,
+    nullable,
+    ...rest
+  } = value;
+  const own = normalizeChildren({
+    schema: rest,
+    next: toToolSchema
+  });
+  const merged = Array.isArray(allOf) ? mergeAllOf({
+    members: allOf.filter(isRecord).map(member => {
+      return toToolSchema(member);
+    }),
+    siblings: own
+  }) : own;
+  return nullable === true ? withNull(merged) : merged;
+};
+/** A path or query parameter's schema, with the parameter's own description. */
+var paramProperty = param => {
+  return {
+    ...(toToolSchema(param.schema) ?? {}),
+    ...(param.description ? {
+      description: param.description
+    } : {})
+  };
+};
+/**
+* The `inputSchema` of a tool under `schemaDetail: 'full'`: every parameter
+* and body property with its whole schema. `properties` is always present,
+* even when empty, because some clients refuse an object schema without it.
+*/
+var buildFullInputSchema = args => {
+  const params = [...args.pathParams, ...args.queryParams].filter(param => {
+    return !param.serverManaged;
+  });
+  const properties = {};
+  const required = [];
+  for (const param of params) {
+    properties[param.argName] = paramProperty(param);
+    if (param.required) required.push(param.argName);
+  }
+  for (const prop of args.bodyProps) {
+    properties[prop.argName] = toToolSchema(prop.schema);
+    if (prop.required) required.push(prop.argName);
+  }
+  return {
+    type: "object",
+    properties,
+    ...(required.length > 0 ? {
+      required: [...new Set(required)]
+    } : {})
+  };
+};
+
+//#endregion
+//#region src/inProcessCallApi.ts
+var nestedMessageOf = error => {
+  if (!error || typeof error !== "object") return null;
+  const {
+    code,
+    message
+  } = error;
+  if (typeof message !== "string") return null;
+  return typeof code === "string" ? `${code}: ${message}` : message;
+};
+/**
+* The message an error response carries, read from the envelopes REST APIs
+* commonly answer with: a plain string, `{ error: '…' }`,
+* `{ error: { code, message } }` (as `code: message`) or `{ message: '…' }`.
+* `null` when the body is none of them.
+*/
+var errorMessageOf = body => {
+  if (typeof body === "string") return body || null;
+  if (!body || typeof body !== "object") return null;
+  const {
+    error,
+    message
+  } = body;
+  if (typeof error === "string") return error;
+  return nestedMessageOf(error) ?? (typeof message === "string" ? message : null);
+};
+var defaultToError = response => {
+  return new Error(errorMessageOf(response.body) ?? `HTTP ${response.status}`);
+};
+/**
+* A `callApi` for {@link registerOpenApiTools} that serves each tool call
+* against the REST app in this same process, with no socket: validation,
+* authorization and error handling run once, in the routes, for both
+* surfaces.
+*
+* The MCP request's headers (what `createMcpRouter`'s `getApiHeaders`
+* produced — typically the caller's `Authorization`) are forwarded onto the
+* dispatched request. A 2xx answers its body; anything else throws, so the
+* client sees a tool error rather than an error body rendered as a result.
+*
+* @example
+* ```typescript
+* registerOpenApiTools({
+*   server,
+*   spec,
+*   callApi: createInProcessCallApi({ app }),
+* });
+* ```
+*/
+var createInProcessCallApi = ({
+  app,
+  headers,
+  toError = defaultToError
+}) => {
+  return async request => {
+    const response = await (0, _ttoss_http_server.dispatchInProcess)({
+      app: typeof app === "function" ? await app() : app,
+      method: request.method,
+      path: request.url,
+      headers: {
+        ...request.headers,
+        ...headers?.(request)
+      },
+      body: request.body
+    });
+    if (response.status < 200 || response.status >= 300) throw toError(response, request);
+    return response.body;
+  };
+};
+
 //#endregion
 //#region src/toolDefinitions.ts
 /** Converts a camelCase `operationId` to a kebab-case tool name. */
@@ -660,6 +868,11 @@ var getJsonSchemaType = schemaType => {
 var sanitizeDescription = description => {
   return (description || "").replace(/'/g, "\\'").replace(/\n/g, " ").trim();
 };
+var defaultDescribe = ({
+  operation
+}) => {
+  return sanitizeDescription(operation.description);
+};
 /**
 * Forwards a property's `oneOf` / `anyOf` / multi-entry `allOf` verbatim, or
 * returns `undefined` when it declares none.
@@ -716,8 +929,7 @@ var buildInputSchema = (pathParams, queryParams, bodyProps) => {
   const modelQueryParams = queryParams.filter(p => {
     return !p.serverManaged;
   });
-  const allParams = [...modelPathParams, ...modelQueryParams, ...bodyProps];
-  if (allParams.length === 0) return {
+  if ([...modelPathParams, ...modelQueryParams, ...bodyProps].length === 0) return {
     type: "object"
   };
   const requiredFields = [...modelPathParams.map(p => {
@@ -732,10 +944,11 @@ var buildInputSchema = (pathParams, queryParams, bodyProps) => {
     return p.argName;
   })];
   const properties = {};
-  for (const param of allParams) properties[param.argName] = "description" in param ? normalizeNullable(buildTypedProperty(param)) : {
+  for (const param of modelPathParams) properties[param.argName] = {
     type: "string",
     description: ""
   };
+  for (const param of [...modelQueryParams, ...bodyProps]) properties[param.argName] = normalizeNullable(buildTypedProperty(param));
   return {
     type: "object",
     properties,
@@ -744,6 +957,35 @@ var buildInputSchema = (pathParams, queryParams, bodyProps) => {
     } : {})
   };
 };
+var SUPPORTED_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
+/** The tool description, from `options.describe` or the default. */
+var describeOperation = args => {
+  const {
+    options,
+    operation,
+    method,
+    pathTemplate
+  } = args;
+  return (options.describe ?? defaultDescribe)({
+    operation,
+    method,
+    pathTemplate
+  });
+};
+/** The `inputSchema` at the detail {@link OpenApiToToolsOptions.schemaDetail} asks for. */
+var selectInputSchema = args => {
+  if (args.schemaDetail !== "full") return buildInputSchema(args.pathParams, args.queryParams, args.bodyProps);
+  return buildFullInputSchema({
+    pathParams: args.pathParams.map(param => {
+      return {
+        ...param,
+        required: true
+      };
+    }),
+    queryParams: args.queryParams,
+    bodyProps: args.bodyProps
+  });
+};
 /** Collects every `x-` prefixed extension declared on the operation. */
 var extractExtensions = operation => {
   const extensions = {};
@@ -752,9 +994,7 @@ var extractExtensions = operation => {
 };
 var processOperation = args => {
   const httpMethod = args.method.toUpperCase();
-  if (!["GET", "POST", "PUT", "PATCH", "DELETE"].includes(httpMethod)) return null;
-  if (!args.operation.operationId) return null;
-  if (args.operation[args.options.excludeExtension]) return null;
+  if (!SUPPORTED_METHODS.includes(httpMethod) || !args.operation.operationId || args.operation[args.options.excludeExtension]) return null;
   const toolName = operationIdToToolName(args.operation.operationId);
   const parameters = [...(args.pathItemParameters ?? []), ...(args.operation.parameters ?? [])];
   const {
@@ -762,20 +1002,15 @@ var processOperation = args => {
     serverManagedExtension
   } = args.options;
   const toArgName = argNameMapper(args.options.argumentNames);
-  const pathParams = extractPathParams({
-    parameters,
-    spec: args.spec,
-    documents,
-    toArgName,
-    serverManagedExtension
-  });
-  const queryParams = extractQueryParams({
+  const paramArgs = {
     parameters,
     spec: args.spec,
     documents,
     toArgName,
     serverManagedExtension
-  });
+  };
+  const pathParams = extractPathParams(paramArgs);
+  const queryParams = extractQueryParams(paramArgs);
   const bodyArgs = {
     requestBody: args.operation.requestBody,
     spec: args.spec,
@@ -786,7 +1021,12 @@ var processOperation = args => {
     ...bodyArgs,
     toArgName
   });
-  const inputSchema = buildInputSchema(pathParams, queryParams, bodyProps);
+  const inputSchema = selectInputSchema({
+    schemaDetail: args.options.schemaDetail,
+    pathParams,
+    queryParams,
+    bodyProps
+  });
   const serverManagedParameters = collectServerManagedParameters({
     pathParams,
     queryParams
@@ -794,7 +1034,10 @@ var processOperation = args => {
   const pinned = pinnedArgs(serverManagedParameters);
   return {
     name: toolName,
-    description: sanitizeDescription(args.operation.description),
+    description: describeOperation({
+      ...args,
+      method: httpMethod
+    }),
     inputSchema,
     method: httpMethod,
     pathTemplate: args.pathTemplate,
@@ -843,6 +1086,8 @@ var resolveOptions = (options = {}) => {
     excludeExtension: options.excludeExtension ?? "x-mcp-exclude",
     serverManagedExtension: options.serverManagedExtension ?? "x-mcp-server-managed",
     argumentNames: options.argumentNames ?? "camelCase",
+    schemaDetail: options.schemaDetail,
+    describe: options.describe,
     documents: options.documents
   };
 };
@@ -969,10 +1214,13 @@ 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.buildFullInputSchema = buildFullInputSchema;
 exports.buildInputSchema = buildInputSchema;
 exports.buildPathFn = buildPathFn;
 exports.buildQueryFn = buildQueryFn;
+exports.createInProcessCallApi = createInProcessCallApi;
 exports.dereferenceSchema = dereferenceSchema;
+exports.errorMessageOf = errorMessageOf;
 exports.extractAcceptedBodyFields = extractAcceptedBodyFields;
 exports.extractBodyProps = extractBodyProps;
 exports.extractPathParams = extractPathParams;
@@ -986,4 +1234,5 @@ exports.processPath = processPath;
 exports.registerOpenApiTools = registerOpenApiTools;
 exports.resolveParameter = resolveParameter;
 exports.resolveSchema = resolveSchema;
-exports.snakeToCamel = snakeToCamel;
+exports.snakeToCamel = snakeToCamel;
+exports.toToolSchema = toToolSchema;

package/dist/index.d.cts

@@ -1,5 +1,6 @@
 
 import { JsonObjectSchema, McpServer } from "@ttoss/http-server-mcp";
+import { App, InProcessResponse } from "@ttoss/http-server";
 
 //#region src/types.d.ts
 /** The JSON Schema primitive types this generator can derive from an OpenAPI `type`. */
@@ -121,6 +122,7 @@ type RequestBodySpec = {
 };
 interface OperationSpec {
   operationId?: string;
+  summary?: string;
   description?: string;
   parameters?: Array<{
     name?: string;
@@ -183,9 +185,39 @@ interface OpenApiToToolsOptions {
    * to an empty schema, which accepts any value.
    */
   documents?: OpenApiDocuments;
+  /**
+   * How much of each parameter's and body property's schema reaches the
+   * tool's `inputSchema`.
+   *
+   * - `'compact'` keeps the `type`, `items` and `description` of each
+   *   top-level argument, with descriptions flattened to one line.
+   * - `'full'` keeps the whole schema — `enum`, `format`, `pattern`,
+   *   `minimum`, `default`, nested `properties` and `required`, `oneOf` — and
+   *   changes only what JSON Schema cannot say: `allOf` is merged, `nullable`
+   *   becomes a `'null'` type (and joins an `enum`), and OpenAPI-only keywords
+   *   and `x-` extensions are dropped. Descriptions stay verbatim.
+   *
+   * @default 'compact'
+   */
+  schemaDetail?: 'compact' | 'full';
+  /**
+   * Builds each tool's description from its operation. The default is the
+   * operation's `description`, flattened to one line.
+   *
+   * @example
+   * ```typescript
+   * describe: ({ operation, method, pathTemplate }) =>
+   *   `${operation.summary}\n\n${operation.description}\n\n(${method} ${pathTemplate})`,
+   * ```
+   */
+  describe?: (args: {
+    operation: OperationSpec; /** Uppercase HTTP method. */
+    method: string;
+    pathTemplate: string;
+  }) => string;
 }
 /** {@link OpenApiToToolsOptions} with every default applied. */
-type ResolvedToolOptions = Required<Omit<OpenApiToToolsOptions, 'documents'>> & Pick<OpenApiToToolsOptions, 'documents'>;
+type ResolvedToolOptions = Required<Omit<OpenApiToToolsOptions, 'documents' | 'describe' | 'schemaDetail'>> & Pick<OpenApiToToolsOptions, 'documents' | 'describe' | 'schemaDetail'>;
 declare const DEFAULT_EXCLUDE_EXTENSION = "x-mcp-exclude";
 declare const DEFAULT_SERVER_MANAGED_EXTENSION = "x-mcp-server-managed";
 //#endregion
@@ -217,6 +249,8 @@ type ExtractParamsArgs = {
 declare const extractPathParams: (args: ExtractParamsArgs) => Array<{
   name: string;
   argName: string;
+  description?: string; /** The parameter's schema with every `$ref` inlined. */
+  schema?: Record<string, unknown>;
   serverManaged: boolean;
   pinnedValue?: string;
 }>;
@@ -225,7 +259,8 @@ declare const extractQueryParams: (args: ExtractParamsArgs) => Array<{
   argName: string;
   description: string;
   required: boolean;
-  type: string;
+  type: string; /** The parameter's schema with every `$ref` inlined. */
+  schema?: Record<string, unknown>;
   style?: string;
   explode?: boolean;
   serverManaged: boolean;
@@ -258,7 +293,8 @@ declare const extractBodyProps: (args: {
   nullable: boolean;
   oneOf?: unknown[];
   anyOf?: unknown[];
-  allOf?: unknown[];
+  allOf?: unknown[]; /** The property's whole schema, with every `$ref` inlined. */
+  schema: Record<string, unknown>;
 }>;
 /**
  * The value each server-managed body property pins, typed by its schema and
@@ -273,6 +309,39 @@ declare const extractPinnedBody: (args: {
   operationId: string;
 }) => Record<string, string | number | boolean>;
 //#endregion
+//#region src/fullSchema.d.ts
+/**
+ * Turns an already-dereferenced OpenAPI schema into the JSON Schema a tool
+ * argument carries, keeping every constraint it declares — `enum`, `format`,
+ * `pattern`, `minimum`, `default`, nested `properties` and `required`,
+ * `oneOf` — and changing only what JSON Schema cannot express: `allOf` is
+ * merged, `nullable` becomes a `'null'` type, and OpenAPI-only keywords and
+ * `x-` extensions are dropped. Descriptions are kept verbatim.
+ */
+declare const toToolSchema: (value: unknown) => unknown;
+type FullParam = {
+  argName: string;
+  required?: boolean;
+  description?: string;
+  schema?: unknown;
+  serverManaged?: boolean;
+};
+type FullBodyProp = {
+  argName: string;
+  required: boolean;
+  schema: Record<string, unknown>;
+};
+/**
+ * The `inputSchema` of a tool under `schemaDetail: 'full'`: every parameter
+ * and body property with its whole schema. `properties` is always present,
+ * even when empty, because some clients refuse an object schema without it.
+ */
+declare const buildFullInputSchema: (args: {
+  pathParams: FullParam[];
+  queryParams: FullParam[];
+  bodyProps: FullBodyProp[];
+}) => JsonObjectSchema;
+//#endregion
 //#region src/registerOpenApiTools.d.ts
 /** The resolved HTTP request a tool call maps to, before transport concerns. */
 interface ResolvedRequest {
@@ -360,6 +429,58 @@ declare const NO_CONTENT_TEXT = "Succeeded. The operation returned no content.";
  */
 declare const registerOpenApiTools: (args: RegisterOpenApiToolsArgs) => ToolDefinition[];
 //#endregion
+//#region src/inProcessCallApi.d.ts
+interface CreateInProcessCallApiArgs {
+  /**
+   * The Koa app serving the REST API the tools were generated from, or a
+   * function returning it — for an app that mounts the MCP router itself and
+   * so is not built yet when the tools are registered.
+   */
+  app: App | (() => App | Promise<App>);
+  /**
+   * Headers added to every dispatched request, after the ones the MCP request
+   * carried — e.g. a marker that tells a request log the call came from a tool.
+   */
+  headers?: (request: ResolvedRequest) => Record<string, string | undefined>;
+  /**
+   * Builds the error a non-2xx response throws. The default reads the message
+   * out of the common error envelopes (see {@link errorMessageOf}).
+   */
+  toError?: (response: InProcessResponse, request: ResolvedRequest) => Error;
+}
+/**
+ * The message an error response carries, read from the envelopes REST APIs
+ * commonly answer with: a plain string, `{ error: '…' }`,
+ * `{ error: { code, message } }` (as `code: message`) or `{ message: '…' }`.
+ * `null` when the body is none of them.
+ */
+declare const errorMessageOf: (body: unknown) => string | null;
+/**
+ * A `callApi` for {@link registerOpenApiTools} that serves each tool call
+ * against the REST app in this same process, with no socket: validation,
+ * authorization and error handling run once, in the routes, for both
+ * surfaces.
+ *
+ * The MCP request's headers (what `createMcpRouter`'s `getApiHeaders`
+ * produced — typically the caller's `Authorization`) are forwarded onto the
+ * dispatched request. A 2xx answers its body; anything else throws, so the
+ * client sees a tool error rather than an error body rendered as a result.
+ *
+ * @example
+ * ```typescript
+ * registerOpenApiTools({
+ *   server,
+ *   spec,
+ *   callApi: createInProcessCallApi({ app }),
+ * });
+ * ```
+ */
+declare const createInProcessCallApi: ({
+  app,
+  headers,
+  toError
+}: CreateInProcessCallApiArgs) => ((request: ResolvedRequest) => Promise<unknown>);
+//#endregion
 //#region src/schema.d.ts
 type ResolvedSchema = {
   type?: string;
@@ -498,4 +619,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, extractPinnedBody, extractQueryParams, getJsonSchemaType, openApiToToolDefinitions, operationIdToToolName, processOperation, processPath, registerOpenApiTools, resolveParameter, resolveSchema, snakeToCamel };
+export { type CreateInProcessCallApiArgs, 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, buildFullInputSchema, buildInputSchema, buildPathFn, buildQueryFn, createInProcessCallApi, dereferenceSchema, errorMessageOf, extractAcceptedBodyFields, extractBodyProps, extractPathParams, extractPinnedBody, extractQueryParams, getJsonSchemaType, openApiToToolDefinitions, operationIdToToolName, processOperation, processPath, registerOpenApiTools, resolveParameter, resolveSchema, snakeToCamel, toToolSchema };

package/dist/index.d.mts

@@ -1,4 +1,5 @@
 
+import { App, InProcessResponse } from "@ttoss/http-server";
 import { JsonObjectSchema, McpServer } from "@ttoss/http-server-mcp";
 
 //#region src/types.d.ts
@@ -121,6 +122,7 @@ type RequestBodySpec = {
 };
 interface OperationSpec {
   operationId?: string;
+  summary?: string;
   description?: string;
   parameters?: Array<{
     name?: string;
@@ -183,9 +185,39 @@ interface OpenApiToToolsOptions {
    * to an empty schema, which accepts any value.
    */
   documents?: OpenApiDocuments;
+  /**
+   * How much of each parameter's and body property's schema reaches the
+   * tool's `inputSchema`.
+   *
+   * - `'compact'` keeps the `type`, `items` and `description` of each
+   *   top-level argument, with descriptions flattened to one line.
+   * - `'full'` keeps the whole schema — `enum`, `format`, `pattern`,
+   *   `minimum`, `default`, nested `properties` and `required`, `oneOf` — and
+   *   changes only what JSON Schema cannot say: `allOf` is merged, `nullable`
+   *   becomes a `'null'` type (and joins an `enum`), and OpenAPI-only keywords
+   *   and `x-` extensions are dropped. Descriptions stay verbatim.
+   *
+   * @default 'compact'
+   */
+  schemaDetail?: 'compact' | 'full';
+  /**
+   * Builds each tool's description from its operation. The default is the
+   * operation's `description`, flattened to one line.
+   *
+   * @example
+   * ```typescript
+   * describe: ({ operation, method, pathTemplate }) =>
+   *   `${operation.summary}\n\n${operation.description}\n\n(${method} ${pathTemplate})`,
+   * ```
+   */
+  describe?: (args: {
+    operation: OperationSpec; /** Uppercase HTTP method. */
+    method: string;
+    pathTemplate: string;
+  }) => string;
 }
 /** {@link OpenApiToToolsOptions} with every default applied. */
-type ResolvedToolOptions = Required<Omit<OpenApiToToolsOptions, 'documents'>> & Pick<OpenApiToToolsOptions, 'documents'>;
+type ResolvedToolOptions = Required<Omit<OpenApiToToolsOptions, 'documents' | 'describe' | 'schemaDetail'>> & Pick<OpenApiToToolsOptions, 'documents' | 'describe' | 'schemaDetail'>;
 declare const DEFAULT_EXCLUDE_EXTENSION = "x-mcp-exclude";
 declare const DEFAULT_SERVER_MANAGED_EXTENSION = "x-mcp-server-managed";
 //#endregion
@@ -217,6 +249,8 @@ type ExtractParamsArgs = {
 declare const extractPathParams: (args: ExtractParamsArgs) => Array<{
   name: string;
   argName: string;
+  description?: string; /** The parameter's schema with every `$ref` inlined. */
+  schema?: Record<string, unknown>;
   serverManaged: boolean;
   pinnedValue?: string;
 }>;
@@ -225,7 +259,8 @@ declare const extractQueryParams: (args: ExtractParamsArgs) => Array<{
   argName: string;
   description: string;
   required: boolean;
-  type: string;
+  type: string; /** The parameter's schema with every `$ref` inlined. */
+  schema?: Record<string, unknown>;
   style?: string;
   explode?: boolean;
   serverManaged: boolean;
@@ -258,7 +293,8 @@ declare const extractBodyProps: (args: {
   nullable: boolean;
   oneOf?: unknown[];
   anyOf?: unknown[];
-  allOf?: unknown[];
+  allOf?: unknown[]; /** The property's whole schema, with every `$ref` inlined. */
+  schema: Record<string, unknown>;
 }>;
 /**
  * The value each server-managed body property pins, typed by its schema and
@@ -273,6 +309,39 @@ declare const extractPinnedBody: (args: {
   operationId: string;
 }) => Record<string, string | number | boolean>;
 //#endregion
+//#region src/fullSchema.d.ts
+/**
+ * Turns an already-dereferenced OpenAPI schema into the JSON Schema a tool
+ * argument carries, keeping every constraint it declares — `enum`, `format`,
+ * `pattern`, `minimum`, `default`, nested `properties` and `required`,
+ * `oneOf` — and changing only what JSON Schema cannot express: `allOf` is
+ * merged, `nullable` becomes a `'null'` type, and OpenAPI-only keywords and
+ * `x-` extensions are dropped. Descriptions are kept verbatim.
+ */
+declare const toToolSchema: (value: unknown) => unknown;
+type FullParam = {
+  argName: string;
+  required?: boolean;
+  description?: string;
+  schema?: unknown;
+  serverManaged?: boolean;
+};
+type FullBodyProp = {
+  argName: string;
+  required: boolean;
+  schema: Record<string, unknown>;
+};
+/**
+ * The `inputSchema` of a tool under `schemaDetail: 'full'`: every parameter
+ * and body property with its whole schema. `properties` is always present,
+ * even when empty, because some clients refuse an object schema without it.
+ */
+declare const buildFullInputSchema: (args: {
+  pathParams: FullParam[];
+  queryParams: FullParam[];
+  bodyProps: FullBodyProp[];
+}) => JsonObjectSchema;
+//#endregion
 //#region src/registerOpenApiTools.d.ts
 /** The resolved HTTP request a tool call maps to, before transport concerns. */
 interface ResolvedRequest {
@@ -360,6 +429,58 @@ declare const NO_CONTENT_TEXT = "Succeeded. The operation returned no content.";
  */
 declare const registerOpenApiTools: (args: RegisterOpenApiToolsArgs) => ToolDefinition[];
 //#endregion
+//#region src/inProcessCallApi.d.ts
+interface CreateInProcessCallApiArgs {
+  /**
+   * The Koa app serving the REST API the tools were generated from, or a
+   * function returning it — for an app that mounts the MCP router itself and
+   * so is not built yet when the tools are registered.
+   */
+  app: App | (() => App | Promise<App>);
+  /**
+   * Headers added to every dispatched request, after the ones the MCP request
+   * carried — e.g. a marker that tells a request log the call came from a tool.
+   */
+  headers?: (request: ResolvedRequest) => Record<string, string | undefined>;
+  /**
+   * Builds the error a non-2xx response throws. The default reads the message
+   * out of the common error envelopes (see {@link errorMessageOf}).
+   */
+  toError?: (response: InProcessResponse, request: ResolvedRequest) => Error;
+}
+/**
+ * The message an error response carries, read from the envelopes REST APIs
+ * commonly answer with: a plain string, `{ error: '…' }`,
+ * `{ error: { code, message } }` (as `code: message`) or `{ message: '…' }`.
+ * `null` when the body is none of them.
+ */
+declare const errorMessageOf: (body: unknown) => string | null;
+/**
+ * A `callApi` for {@link registerOpenApiTools} that serves each tool call
+ * against the REST app in this same process, with no socket: validation,
+ * authorization and error handling run once, in the routes, for both
+ * surfaces.
+ *
+ * The MCP request's headers (what `createMcpRouter`'s `getApiHeaders`
+ * produced — typically the caller's `Authorization`) are forwarded onto the
+ * dispatched request. A 2xx answers its body; anything else throws, so the
+ * client sees a tool error rather than an error body rendered as a result.
+ *
+ * @example
+ * ```typescript
+ * registerOpenApiTools({
+ *   server,
+ *   spec,
+ *   callApi: createInProcessCallApi({ app }),
+ * });
+ * ```
+ */
+declare const createInProcessCallApi: ({
+  app,
+  headers,
+  toError
+}: CreateInProcessCallApiArgs) => ((request: ResolvedRequest) => Promise<unknown>);
+//#endregion
 //#region src/schema.d.ts
 type ResolvedSchema = {
   type?: string;
@@ -498,4 +619,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, extractPinnedBody, extractQueryParams, getJsonSchemaType, openApiToToolDefinitions, operationIdToToolName, processOperation, processPath, registerOpenApiTools, resolveParameter, resolveSchema, snakeToCamel };
+export { type CreateInProcessCallApiArgs, 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, buildFullInputSchema, buildInputSchema, buildPathFn, buildQueryFn, createInProcessCallApi, dereferenceSchema, errorMessageOf, extractAcceptedBodyFields, extractBodyProps, extractPathParams, extractPinnedBody, extractQueryParams, getJsonSchemaType, openApiToToolDefinitions, operationIdToToolName, processOperation, processPath, registerOpenApiTools, resolveParameter, resolveSchema, snakeToCamel, toToolSchema };

package/dist/index.mjs

@@ -1,8 +1,9 @@
 /** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
+import { dispatchInProcess } from "@ttoss/http-server";
 import { getApiHeaders, registerToolFromSchema } from "@ttoss/http-server-mcp";
 
 //#region src/schema.ts
-var isRecord = value => {
+var isRecord$1 = value => {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 };
 var getAlternativeSchemas = schema => {
@@ -39,7 +40,7 @@ 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;
+    if (!isRecord$1(current) && !Array.isArray(current)) return void 0;
     const token = decodeURIComponent(rawToken).replace(/~1/g, "/").replace(/~0/g, "~");
     current = current[token];
   }
@@ -98,7 +99,7 @@ var dereferenceValue = args => {
       seenRefs
     });
   });
-  if (isRecord(value)) {
+  if (isRecord$1(value)) {
     if (typeof value.$ref === "string") {
       const target = resolveRef({
         ref: value.$ref,
@@ -178,7 +179,7 @@ var resolveParameter = (param, spec, documents) => {
         documents
       }
     });
-    return isRecord(target?.value) ? target.value : {};
+    return isRecord$1(target?.value) ? target.value : {};
   }
   return param;
 };
@@ -217,7 +218,7 @@ var appendDeepObject = args => {
     });
     return;
   }
-  if (isRecord(args.value)) {
+  if (isRecord$1(args.value)) {
     for (const [property, propertyValue] of Object.entries(args.value)) appendDeepObject({
       search: args.search,
       key: `${args.key}[${property}]`,
@@ -269,7 +270,7 @@ var appendQueryValue = args => {
     });
     return;
   }
-  if (isRecord(args.value)) {
+  if (isRecord$1(args.value)) {
     appendObjectValue({
       ...serialization,
       value: args.value
@@ -498,6 +499,8 @@ var extractPathParams = args => {
     return {
       name: p.name || "",
       argName: toArgName(p.name || ""),
+      description: p.description,
+      schema: dereferenceSchema(p.schema, args.spec, args.documents),
       ...managedFields(readServerManaged({
         node: p,
         extension: flag
@@ -519,6 +522,7 @@ var extractQueryParams = args => {
       description: p.description || "",
       required: p.required || false,
       type: p.schema?.type || "string",
+      schema: dereferenceSchema(p.schema, args.spec, args.documents),
       style: p.style,
       explode: p.explode,
       ...managedFields(readServerManaged({
@@ -611,7 +615,8 @@ var extractBodyProps = args => {
       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
+      allOf: Array.isArray(val.allOf) ? val.allOf : void 0,
+      schema: value
     };
   });
 };
@@ -641,6 +646,209 @@ var extractPinnedBody = args => {
   return pinned;
 };
 
+//#endregion
+//#region src/fullSchema.ts
+var isRecord = value => {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+};
+var OPENAPI_ONLY_KEYWORDS = new Set(["discriminator", "example", "externalDocs", "xml"]);
+var SCHEMA_MAPS = new Set(["$defs", "definitions", "dependentSchemas", "patternProperties", "properties"]);
+var SCHEMA_VALUES = new Set(["additionalProperties", "contains", "else", "if", "items", "not", "propertyNames", "then", "unevaluatedItems", "unevaluatedProperties"]);
+var SCHEMA_LISTS = new Set(["anyOf", "oneOf", "prefixItems"]);
+/**
+* OpenAPI 3.0's `nullable: true` in JSON Schema: `'null'` joins the `type`,
+* and `null` joins an `enum`, which would otherwise still refuse it.
+*/
+var withNull = schema => {
+  const result = {
+    ...schema
+  };
+  if (typeof result.type === "string") result.type = [result.type, "null"];else if (Array.isArray(result.type) && !result.type.includes("null")) result.type = [...result.type, "null"];
+  if (Array.isArray(result.enum) && !result.enum.includes(null)) result.enum = [...result.enum, null];
+  return result;
+};
+/**
+* Merges an `allOf` into one schema, the shape a tool argument needs.
+*
+* Members that declare `properties` are an object composition — a write body
+* that is a patch plus two fields — and merge their properties and `required`.
+* Otherwise the `allOf` only wraps a referenced scalar so it can carry its own
+* `description` (the one way OpenAPI 3.0 allows beside a `$ref`), and the
+* members are merged as they are. Sibling keys win in both, because the
+* wrapper exists to say something the referenced schema does not.
+*/
+var mergeAllOf = args => {
+  const {
+    members,
+    siblings
+  } = args;
+  if (!members.some(member => {
+    return member.properties !== void 0;
+  })) return Object.assign({}, ...members, siblings);
+  const properties = {};
+  const required = [];
+  for (const member of members) {
+    Object.assign(properties, member.properties);
+    if (Array.isArray(member.required)) required.push(...member.required);
+  }
+  return {
+    ...siblings,
+    type: "object",
+    properties,
+    ...(required.length > 0 ? {
+      required: [...new Set(required)]
+    } : {})
+  };
+};
+var normalizeChildren = args => {
+  const {
+    schema,
+    next
+  } = args;
+  const result = {};
+  for (const [key, value] of Object.entries(schema)) {
+    if (OPENAPI_ONLY_KEYWORDS.has(key) || key.startsWith("x-")) continue;
+    if (SCHEMA_MAPS.has(key) && isRecord(value)) result[key] = Object.fromEntries(Object.entries(value).map(([name, child]) => {
+      return [name, next(child)];
+    }));else if (SCHEMA_VALUES.has(key) && isRecord(value)) result[key] = next(value);else if (SCHEMA_LISTS.has(key) && Array.isArray(value)) result[key] = value.map(next);else result[key] = value;
+  }
+  return result;
+};
+/**
+* Turns an already-dereferenced OpenAPI schema into the JSON Schema a tool
+* argument carries, keeping every constraint it declares — `enum`, `format`,
+* `pattern`, `minimum`, `default`, nested `properties` and `required`,
+* `oneOf` — and changing only what JSON Schema cannot express: `allOf` is
+* merged, `nullable` becomes a `'null'` type, and OpenAPI-only keywords and
+* `x-` extensions are dropped. Descriptions are kept verbatim.
+*/
+var toToolSchema = value => {
+  if (!isRecord(value)) return value;
+  const {
+    allOf,
+    nullable,
+    ...rest
+  } = value;
+  const own = normalizeChildren({
+    schema: rest,
+    next: toToolSchema
+  });
+  const merged = Array.isArray(allOf) ? mergeAllOf({
+    members: allOf.filter(isRecord).map(member => {
+      return toToolSchema(member);
+    }),
+    siblings: own
+  }) : own;
+  return nullable === true ? withNull(merged) : merged;
+};
+/** A path or query parameter's schema, with the parameter's own description. */
+var paramProperty = param => {
+  return {
+    ...(toToolSchema(param.schema) ?? {}),
+    ...(param.description ? {
+      description: param.description
+    } : {})
+  };
+};
+/**
+* The `inputSchema` of a tool under `schemaDetail: 'full'`: every parameter
+* and body property with its whole schema. `properties` is always present,
+* even when empty, because some clients refuse an object schema without it.
+*/
+var buildFullInputSchema = args => {
+  const params = [...args.pathParams, ...args.queryParams].filter(param => {
+    return !param.serverManaged;
+  });
+  const properties = {};
+  const required = [];
+  for (const param of params) {
+    properties[param.argName] = paramProperty(param);
+    if (param.required) required.push(param.argName);
+  }
+  for (const prop of args.bodyProps) {
+    properties[prop.argName] = toToolSchema(prop.schema);
+    if (prop.required) required.push(prop.argName);
+  }
+  return {
+    type: "object",
+    properties,
+    ...(required.length > 0 ? {
+      required: [...new Set(required)]
+    } : {})
+  };
+};
+
+//#endregion
+//#region src/inProcessCallApi.ts
+var nestedMessageOf = error => {
+  if (!error || typeof error !== "object") return null;
+  const {
+    code,
+    message
+  } = error;
+  if (typeof message !== "string") return null;
+  return typeof code === "string" ? `${code}: ${message}` : message;
+};
+/**
+* The message an error response carries, read from the envelopes REST APIs
+* commonly answer with: a plain string, `{ error: '…' }`,
+* `{ error: { code, message } }` (as `code: message`) or `{ message: '…' }`.
+* `null` when the body is none of them.
+*/
+var errorMessageOf = body => {
+  if (typeof body === "string") return body || null;
+  if (!body || typeof body !== "object") return null;
+  const {
+    error,
+    message
+  } = body;
+  if (typeof error === "string") return error;
+  return nestedMessageOf(error) ?? (typeof message === "string" ? message : null);
+};
+var defaultToError = response => {
+  return new Error(errorMessageOf(response.body) ?? `HTTP ${response.status}`);
+};
+/**
+* A `callApi` for {@link registerOpenApiTools} that serves each tool call
+* against the REST app in this same process, with no socket: validation,
+* authorization and error handling run once, in the routes, for both
+* surfaces.
+*
+* The MCP request's headers (what `createMcpRouter`'s `getApiHeaders`
+* produced — typically the caller's `Authorization`) are forwarded onto the
+* dispatched request. A 2xx answers its body; anything else throws, so the
+* client sees a tool error rather than an error body rendered as a result.
+*
+* @example
+* ```typescript
+* registerOpenApiTools({
+*   server,
+*   spec,
+*   callApi: createInProcessCallApi({ app }),
+* });
+* ```
+*/
+var createInProcessCallApi = ({
+  app,
+  headers,
+  toError = defaultToError
+}) => {
+  return async request => {
+    const response = await dispatchInProcess({
+      app: typeof app === "function" ? await app() : app,
+      method: request.method,
+      path: request.url,
+      headers: {
+        ...request.headers,
+        ...headers?.(request)
+      },
+      body: request.body
+    });
+    if (response.status < 200 || response.status >= 300) throw toError(response, request);
+    return response.body;
+  };
+};
+
 //#endregion
 //#region src/toolDefinitions.ts
 /** Converts a camelCase `operationId` to a kebab-case tool name. */
@@ -657,6 +865,11 @@ var getJsonSchemaType = schemaType => {
 var sanitizeDescription = description => {
   return (description || "").replace(/'/g, "\\'").replace(/\n/g, " ").trim();
 };
+var defaultDescribe = ({
+  operation
+}) => {
+  return sanitizeDescription(operation.description);
+};
 /**
 * Forwards a property's `oneOf` / `anyOf` / multi-entry `allOf` verbatim, or
 * returns `undefined` when it declares none.
@@ -713,8 +926,7 @@ var buildInputSchema = (pathParams, queryParams, bodyProps) => {
   const modelQueryParams = queryParams.filter(p => {
     return !p.serverManaged;
   });
-  const allParams = [...modelPathParams, ...modelQueryParams, ...bodyProps];
-  if (allParams.length === 0) return {
+  if ([...modelPathParams, ...modelQueryParams, ...bodyProps].length === 0) return {
     type: "object"
   };
   const requiredFields = [...modelPathParams.map(p => {
@@ -729,10 +941,11 @@ var buildInputSchema = (pathParams, queryParams, bodyProps) => {
     return p.argName;
   })];
   const properties = {};
-  for (const param of allParams) properties[param.argName] = "description" in param ? normalizeNullable(buildTypedProperty(param)) : {
+  for (const param of modelPathParams) properties[param.argName] = {
     type: "string",
     description: ""
   };
+  for (const param of [...modelQueryParams, ...bodyProps]) properties[param.argName] = normalizeNullable(buildTypedProperty(param));
   return {
     type: "object",
     properties,
@@ -741,6 +954,35 @@ var buildInputSchema = (pathParams, queryParams, bodyProps) => {
     } : {})
   };
 };
+var SUPPORTED_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
+/** The tool description, from `options.describe` or the default. */
+var describeOperation = args => {
+  const {
+    options,
+    operation,
+    method,
+    pathTemplate
+  } = args;
+  return (options.describe ?? defaultDescribe)({
+    operation,
+    method,
+    pathTemplate
+  });
+};
+/** The `inputSchema` at the detail {@link OpenApiToToolsOptions.schemaDetail} asks for. */
+var selectInputSchema = args => {
+  if (args.schemaDetail !== "full") return buildInputSchema(args.pathParams, args.queryParams, args.bodyProps);
+  return buildFullInputSchema({
+    pathParams: args.pathParams.map(param => {
+      return {
+        ...param,
+        required: true
+      };
+    }),
+    queryParams: args.queryParams,
+    bodyProps: args.bodyProps
+  });
+};
 /** Collects every `x-` prefixed extension declared on the operation. */
 var extractExtensions = operation => {
   const extensions = {};
@@ -749,9 +991,7 @@ var extractExtensions = operation => {
 };
 var processOperation = args => {
   const httpMethod = args.method.toUpperCase();
-  if (!["GET", "POST", "PUT", "PATCH", "DELETE"].includes(httpMethod)) return null;
-  if (!args.operation.operationId) return null;
-  if (args.operation[args.options.excludeExtension]) return null;
+  if (!SUPPORTED_METHODS.includes(httpMethod) || !args.operation.operationId || args.operation[args.options.excludeExtension]) return null;
   const toolName = operationIdToToolName(args.operation.operationId);
   const parameters = [...(args.pathItemParameters ?? []), ...(args.operation.parameters ?? [])];
   const {
@@ -759,20 +999,15 @@ var processOperation = args => {
     serverManagedExtension
   } = args.options;
   const toArgName = argNameMapper(args.options.argumentNames);
-  const pathParams = extractPathParams({
-    parameters,
-    spec: args.spec,
-    documents,
-    toArgName,
-    serverManagedExtension
-  });
-  const queryParams = extractQueryParams({
+  const paramArgs = {
     parameters,
     spec: args.spec,
     documents,
     toArgName,
     serverManagedExtension
-  });
+  };
+  const pathParams = extractPathParams(paramArgs);
+  const queryParams = extractQueryParams(paramArgs);
   const bodyArgs = {
     requestBody: args.operation.requestBody,
     spec: args.spec,
@@ -783,7 +1018,12 @@ var processOperation = args => {
     ...bodyArgs,
     toArgName
   });
-  const inputSchema = buildInputSchema(pathParams, queryParams, bodyProps);
+  const inputSchema = selectInputSchema({
+    schemaDetail: args.options.schemaDetail,
+    pathParams,
+    queryParams,
+    bodyProps
+  });
   const serverManagedParameters = collectServerManagedParameters({
     pathParams,
     queryParams
@@ -791,7 +1031,10 @@ var processOperation = args => {
   const pinned = pinnedArgs(serverManagedParameters);
   return {
     name: toolName,
-    description: sanitizeDescription(args.operation.description),
+    description: describeOperation({
+      ...args,
+      method: httpMethod
+    }),
     inputSchema,
     method: httpMethod,
     pathTemplate: args.pathTemplate,
@@ -840,6 +1083,8 @@ var resolveOptions = (options = {}) => {
     excludeExtension: options.excludeExtension ?? "x-mcp-exclude",
     serverManagedExtension: options.serverManagedExtension ?? "x-mcp-server-managed",
     argumentNames: options.argumentNames ?? "camelCase",
+    schemaDetail: options.schemaDetail,
+    describe: options.describe,
     documents: options.documents
   };
 };
@@ -962,4 +1207,4 @@ var registerOpenApiTools = args => {
 };
 
 //#endregion
-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 };
+export { DEFAULT_EXCLUDE_EXTENSION, DEFAULT_SERVER_MANAGED_EXTENSION, NO_CONTENT_TEXT, buildBodyFn, buildFullInputSchema, buildInputSchema, buildPathFn, buildQueryFn, createInProcessCallApi, dereferenceSchema, errorMessageOf, extractAcceptedBodyFields, extractBodyProps, extractPathParams, extractPinnedBody, extractQueryParams, getJsonSchemaType, openApiToToolDefinitions, operationIdToToolName, processOperation, processPath, registerOpenApiTools, resolveParameter, resolveSchema, snakeToCamel, toToolSchema };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttoss/http-server-mcp-openapi",
-  "version": "0.5.6",
+  "version": "0.6.0",
   "description": "Generate Model Context Protocol (MCP) tools from an OpenAPI specification for @ttoss/http-server-mcp",
   "keywords": [
     "ai",
@@ -35,15 +35,15 @@
     "dist"
   ],
   "dependencies": {
-    "@ttoss/http-server-mcp": "^0.31.0"
+    "@ttoss/http-server": "^0.11.0",
+    "@ttoss/http-server-mcp": "^0.32.0"
   },
   "devDependencies": {
     "@modelcontextprotocol/server": "^2.0.0",
     "jest": "^30.4.2",
     "supertest": "^7.2.2",
     "tsdown": "^0.22.2",
-    "@ttoss/config": "^1.39.1",
-    "@ttoss/http-server": "^0.10.3"
+    "@ttoss/config": "^1.40.0"
   },
   "publishConfig": {
     "access": "public",