@ttoss/http-server-mcp-openapi 0.7.2 → 0.8.0

package/MIGRATIONS.md

@@ -0,0 +1,35 @@
+# Migrations
+
+## `openApiToTools` replaces `registerOpenApiTools`
+
+The package now derives tools and leaves registering them to `registerTools`
+from `@ttoss/http-server-mcp`, which can also
+[defer](./README.md#deferring-the-tools-of-a-large-api) them behind
+`search` / `describe` / `call`.
+
+```diff
+-import { registerOpenApiTools } from '@ttoss/http-server-mcp-openapi';
++import { registerTools } from '@ttoss/http-server-mcp';
++import { openApiToTools } from '@ttoss/http-server-mcp-openapi';
+
+-registerOpenApiTools({ server, spec, callApi, serverParameters });
++registerTools({
++  server,
++  tools: openApiToTools({ spec, callApi, serverParameters }),
++});
+```
+
+Every other argument keeps its name and meaning; only `server` moves to
+`registerTools`. `RegisterOpenApiToolsArgs` is now `OpenApiToToolsArgs`,
+without `server`.
+
+The return value changed: `registerOpenApiTools` answered the
+`ToolDefinition`s, `openApiToTools` answers `OpenApiTool`s, each carrying its
+`ToolDefinition` as `definition`. Replace `tool.method` with
+`tool.definition.method`, and so on, wherever you read the result.
+
+`ToolDefinition` gained `tags`, copied from the operation. A consumer that
+builds `ToolDefinition` objects by hand must add it.
+
+**What you will observe if you miss this.** The build fails on the missing
+`registerOpenApiTools` import. Generated tools answer exactly as before.

package/README.md

@@ -1,9 +1,9 @@
 # @ttoss/http-server-mcp-openapi
 
 Generate [Model Context Protocol (MCP)](https://modelcontextprotocol.io) tools
-from an [OpenAPI](https://www.openapis.org/) specification and register them on
-a [@ttoss/http-server-mcp](https://ttoss.dev/docs/modules/packages/http-server-mcp)
-server.
+from an [OpenAPI](https://www.openapis.org/) specification, ready for
+[@ttoss/http-server-mcp](https://ttoss.dev/docs/modules/packages/http-server-mcp)'s
+`registerTools`.
 
 Point it at your existing OpenAPI document and every operation becomes an MCP
 tool whose handler resolves the incoming arguments into an HTTP request against
@@ -20,15 +20,18 @@ pnpm add @ttoss/http-server-mcp-openapi @ttoss/http-server-mcp
 
 ```typescript
 import { App, bodyParser } from '@ttoss/http-server';
-import { createMcpRouter, McpServer } from '@ttoss/http-server-mcp';
-import { registerOpenApiTools } from '@ttoss/http-server-mcp-openapi';
+import {
+  createMcpRouter,
+  McpServer,
+  registerTools,
+} from '@ttoss/http-server-mcp';
+import { openApiToTools } from '@ttoss/http-server-mcp-openapi';
 
 import openApiDocument from './openapi.json' with { type: 'json' };
 
 const server = new McpServer({ name: 'my-api', version: '1.0.0' });
 
-registerOpenApiTools({
-  server,
+const tools = openApiToTools({
   spec: openApiDocument,
   // You own how the request is executed — base URL, auth, fetch impl.
   // `headers` is what createMcpRouter's `getApiHeaders` produced for this
@@ -44,6 +47,8 @@ registerOpenApiTools({
   },
 });
 
+registerTools({ server, tools });
+
 const app = new App();
 app.use(bodyParser());
 app.use(createMcpRouter(server).routes());
@@ -55,13 +60,14 @@ app.listen(3000);
 Each OpenAPI operation with an `operationId` and a supported HTTP method
 (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`) becomes one tool:
 
-| OpenAPI                   | MCP tool                                     |
-| ------------------------- | -------------------------------------------- |
-| `operationId: listAgents` | tool name `list-agents` (kebab-case)         |
-| path/query/body params    | a single `inputSchema` object                |
-| `$ref`, `oneOf`, `anyOf`  | dereferenced and merged into a flat schema   |
-| snake_case names          | camelCase tool inputs, mapped back on call   |
-| operation `description`   | tool description (quotes/newlines sanitised) |
+| OpenAPI                   | MCP tool                                      |
+| ------------------------- | --------------------------------------------- |
+| `operationId: listAgents` | tool name `list-agents` (kebab-case)          |
+| path/query/body params    | a single `inputSchema` object                 |
+| `$ref`, `oneOf`, `anyOf`  | dereferenced and merged into a flat schema    |
+| snake_case names          | camelCase tool inputs, mapped back on call    |
+| operation `description`   | tool description (quotes/newlines sanitised)  |
+| operation `tags`          | tool `tags`, for the deferred `search` filter |
 
 Path params are always required strings. Query and body params carry their
 declared type and `required` flag. Array params keep their `items` schema. A
@@ -87,24 +93,63 @@ repeats array values, `spaceDelimited`/`pipeDelimited` join them, and
 `deepObject` emits bracketed keys — including nested objects and arrays, so
 `{ documentId: { $eq: 'doc_1' } }` becomes `filters[documentId][$eq]=doc_1`.
 
-## `registerOpenApiTools`
+## `openApiToTools`
 
 | Field                  | Description                                                                                                   |
 | ---------------------- | ------------------------------------------------------------------------------------------------------------- |
-| `server`               | The `McpServer` to register tools on.                                                                         |
 | `spec`                 | One OpenAPI document, or an array of them (tools are flattened).                                              |
 | `callApi`              | Runs the resolved `{ method, url, body, tool, headers }` request and returns the raw data.                    |
 | `toText?`              | Serialises the raw data into the tool's text payload. Defaults to pretty JSON; strings pass through verbatim. |
 | `serverParameters?`    | Supplies server-managed path/query parameter values. See [Server-managed values](#server-managed-values).     |
 | `toStructuredContent?` | `({ data, tool })` → the result's `structuredContent`, sent beside the text. `undefined` keeps it text-only.  |
 | `toolMeta?`            | `({ tool })` → the tool's `_meta` on `tools/list`. See [MCP Apps views](#mcp-apps-views).                     |
+| `validateArguments?`   | Enforce each generated `inputSchema` before `callApi` runs. Default `false`; see the caveat below.            |
 | `options?`             | See [Options](#options).                                                                                      |
 
 The default `toText` answers `NO_CONTENT_TEXT` (`Succeeded. The operation
 returned no content.`) when `callApi` resolves `undefined` or `''`, so a `204`
 reaches the client as a success.
 
-Returns the list of `ToolDefinition`s that were registered.
+Returns one `OpenApiTool` per operation: a `Tool` with the operation's `tags`,
+a `summary` of `METHOD /path — description`, and the `definition` it was
+derived from. Enable `validateArguments` only when the spec describes every
+value the API accepts: a generated schema is easily narrower than the API, and
+validating against it rejects calls the API would have taken.
+
+### Deferring the tools of a large API
+
+Every tool definition ships to the model on every turn, so a large API
+overflows the client's context. [Defer](https://github.com/ttoss/ttoss/tree/main/packages/http-server-mcp#deferring-tools-for-large-tool-sets)
+the same tools behind `search` / `describe` / `call`, for example on a second
+endpoint next to the full one:
+
+```typescript
+registerTools({ server: fullServer, tools });
+registerTools({ server: deferredServer, tools, defer: true });
+```
+
+`search` filters by the operations' tags and shows each tool's route; tools
+linked to an MCP Apps view stay registered directly.
+
+### Gating generated tools
+
+A generated tool is an ordinary `Tool`, so a gate wraps it like any other.
+`definition` carries what the operation declares, such as a custom extension
+naming the scope:
+
+```typescript
+const gate = createToolGate({ gates: [subscriptionGate] });
+
+registerTools({
+  server,
+  tools: tools.map((tool) => {
+    return gate({
+      tool,
+      requiredScope: tool.definition.extensions['x-required-scope'] as string,
+    });
+  }),
+});
+```
 
 ### MCP Apps views
 
@@ -112,7 +157,7 @@ A generated tool links to a view through `toolMeta`, and the view reads the
 result from `structuredContent`:
 
 ```typescript
-import { registerAppResource } from '@ttoss/http-server-mcp';
+import { registerAppResource, registerTools } from '@ttoss/http-server-mcp';
 
 const agentCard = registerAppResource({
   server,
@@ -121,8 +166,7 @@ const agentCard = registerAppResource({
   html: agentCardHtml,
 });
 
-registerOpenApiTools({
-  server,
+const tools = openApiToTools({
   spec,
   callApi,
   toolMeta: ({ tool }) => {
@@ -134,6 +178,8 @@ registerOpenApiTools({
       : undefined;
   },
 });
+
+registerTools({ server, tools });
 ```
 
 Keep the text payload: a host without MCP Apps support renders only that.
@@ -151,11 +197,10 @@ forwarded onto the dispatched request.
 ```typescript
 import {
   createInProcessCallApi,
-  registerOpenApiTools,
+  openApiToTools,
 } from '@ttoss/http-server-mcp-openapi';
 
-registerOpenApiTools({
-  server,
+const tools = openApiToTools({
   spec,
   callApi: createInProcessCallApi({
     app, // or () => app, when the app is built after the tools
@@ -163,6 +208,8 @@ registerOpenApiTools({
   }),
 });
 
+registerTools({ server, tools });
+
 const router = createMcpRouter(server, {
   getApiHeaders: (ctx) => ({ authorization: ctx.headers.authorization ?? '' }),
 });
@@ -178,7 +225,7 @@ back to `HTTP <status>`. Pass `toError` to build the error yourself.
 ## `openApiToToolDefinitions`
 
 Use the lower-level function when you want the tool definitions without
-registering them — to inspect, filter, or wire handlers yourself:
+handlers — to inspect, filter, or wire handlers yourself:
 
 ```typescript
 import { openApiToToolDefinitions } from '@ttoss/http-server-mcp-openapi';
@@ -193,14 +240,13 @@ for (const tool of tools) {
 ```
 
 Each `ToolDefinition` exposes `name`, `description`, `inputSchema`, `method`,
-`pathTemplate`, `operationId`, the `path`/`query`/`body` builders,
+`pathTemplate`, `operationId`, `tags`, the `path`/`query`/`body` builders,
 `acceptedBodyFields`, `extensions`, and `serverManagedParameters`.
 
 ## Options
 
 ```typescript
-registerOpenApiTools({
-  server,
+openApiToTools({
   spec,
   callApi,
   options: {
@@ -259,12 +305,11 @@ A value flagged with `serverManagedExtension` is never offered to the model:
   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
+  `tool.serverManagedParameters`. `openApiToTools` discards anything the
   model sent for it and fills it from `serverParameters`, keyed by spec name:
 
 ```typescript
-registerOpenApiTools({
-  server,
+openApiToTools({
   spec,
   callApi,
   serverParameters: ({ tool, headers }) => ({
@@ -299,6 +344,12 @@ const tools = openApiToToolDefinitions({ spec: openApiDocument });
 const iamAction = tools[0].extensions['x-iam-action'];
 ```
 
+## Migrations
+
+Breaking changes and what they require of consumers are listed in
+[MIGRATIONS.md](https://github.com/ttoss/ttoss/blob/main/packages/http-server-mcp-openapi/MIGRATIONS.md),
+newest first.
+
 ## Related Packages
 
 - [@ttoss/http-server-mcp](https://ttoss.dev/docs/modules/packages/http-server-mcp) - MCP server integration for @ttoss/http-server

package/dist/index.cjs

@@ -354,7 +354,7 @@ var pinnedArgs = parameters => {
 /**
 * 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`.
+* definition sends them, not only `openApiToTools`.
 */
 var withPinned = args => {
   const {
@@ -812,7 +812,7 @@ var defaultToError = response => {
   return new Error(errorMessageOf(response.body) ?? `HTTP ${response.status}`);
 };
 /**
-* A `callApi` for {@link registerOpenApiTools} that serves each tool call
+* A `callApi` for {@link openApiToTools} 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.
@@ -824,10 +824,9 @@ var defaultToError = response => {
 *
 * @example
 * ```typescript
-* registerOpenApiTools({
+* registerTools({
 *   server,
-*   spec,
-*   callApi: createInProcessCallApi({ app }),
+*   tools: openApiToTools({ spec, callApi: createInProcessCallApi({ app }) }),
 * });
 * ```
 */
@@ -992,6 +991,12 @@ var extractExtensions = operation => {
   for (const [key, value] of Object.entries(operation)) if (key.startsWith("x-")) extensions[key] = value;
   return extensions;
 };
+/** The operation's tags, ignoring entries a malformed spec typed otherwise. */
+var operationTags = operation => {
+  return (operation.tags ?? []).filter(tag => {
+    return typeof tag === "string";
+  });
+};
 var processOperation = args => {
   const httpMethod = args.method.toUpperCase();
   if (!SUPPORTED_METHODS.includes(httpMethod) || !args.operation.operationId || args.operation[args.options.excludeExtension]) return null;
@@ -1042,6 +1047,7 @@ var processOperation = args => {
     method: httpMethod,
     pathTemplate: args.pathTemplate,
     operationId: args.operation.operationId,
+    tags: operationTags(args.operation),
     path: withPinned({
       build: buildPathFn(args.pathTemplate, pathParams),
       pinned
@@ -1120,7 +1126,7 @@ var openApiToToolDefinitions = args => {
 };
 
 //#endregion
-//#region src/registerOpenApiTools.ts
+//#region src/openApiToTools.ts
 /** The text the default `toText` answers when the API returned no body. */
 var NO_CONTENT_TEXT = "Succeeded. The operation returned no content.";
 var defaultToText = data => {
@@ -1146,21 +1152,21 @@ var applyServerParameters = async args => {
   return result;
 };
 /**
-* Derives MCP tools from OpenAPI document(s) and registers each on the given
-* MCP server. Every tool's handler resolves the incoming args into a concrete
-* HTTP request and delegates execution to `callApi`.
+* Derives MCP tools from OpenAPI document(s). Each tool's handler resolves
+* the incoming args into a concrete HTTP request and delegates execution to
+* `callApi`. Register the result with `registerTools` from
+* `@ttoss/http-server-mcp` — one MCP tool each, or deferred.
 *
-* @returns The list of {@link ToolDefinition} that were registered.
+* @returns One {@link OpenApiTool} per translatable operation.
 *
 * @example
 * ```typescript
-* import { McpServer } from '@ttoss/http-server-mcp';
-* import { registerOpenApiTools } from '@ttoss/http-server-mcp-openapi';
+* import { McpServer, registerTools } from '@ttoss/http-server-mcp';
+* import { openApiToTools } from '@ttoss/http-server-mcp-openapi';
 *
 * const server = new McpServer({ name: 'my-api', version: '1.0.0' });
 *
-* registerOpenApiTools({
-*   server,
+* const tools = openApiToTools({
 *   spec: myOpenApiDocument,
 *   callApi: async ({ method, url, body, headers }) => {
 *     const res = await fetch(`https://api.example.com${url}`, {
@@ -1171,53 +1177,62 @@ var applyServerParameters = async args => {
 *     return res.json();
 *   },
 * });
+*
+* registerTools({ server, tools });
 * ```
 */
-var registerOpenApiTools = args => {
+var openApiToTools = args => {
   const toText = args.toText ?? defaultToText;
-  const tools = openApiToToolDefinitions({
+  return openApiToToolDefinitions({
     spec: args.spec,
     options: args.options
+  }).map(definition => {
+    const route = `${definition.method} ${definition.pathTemplate}`;
+    return {
+      name: definition.name,
+      description: definition.description,
+      inputSchema: definition.inputSchema,
+      validateArguments: args.validateArguments ?? false,
+      ...(definition.tags.length > 0 ? {
+        tags: definition.tags
+      } : {}),
+      summary: definition.description ? `${route} — ${definition.description}` : route,
+      _meta: args.toolMeta?.({
+        tool: definition
+      }),
+      definition,
+      handler: async rawArgs => {
+        const headers = (0, _ttoss_http_server_mcp.getApiHeaders)();
+        const handlerArgs = await applyServerParameters({
+          tool: definition,
+          handlerArgs: rawArgs,
+          headers,
+          serverParameters: args.serverParameters
+        });
+        const url = definition.path(handlerArgs) + (definition.query ? definition.query(handlerArgs) : "");
+        const data = await args.callApi({
+          method: definition.method,
+          url,
+          body: definition.body ? definition.body(handlerArgs) : void 0,
+          tool: definition,
+          headers
+        });
+        const structuredContent = args.toStructuredContent?.({
+          data,
+          tool: definition
+        });
+        return {
+          content: [{
+            type: "text",
+            text: toText(data)
+          }],
+          ...(structuredContent === void 0 ? {} : {
+            structuredContent
+          })
+        };
+      }
+    };
   });
-  for (const tool of tools) (0, _ttoss_http_server_mcp.registerToolFromSchema)(args.server, {
-    name: tool.name,
-    description: tool.description,
-    inputSchema: tool.inputSchema,
-    _meta: args.toolMeta?.({
-      tool
-    }),
-    handler: async rawArgs => {
-      const headers = (0, _ttoss_http_server_mcp.getApiHeaders)();
-      const handlerArgs = await applyServerParameters({
-        tool,
-        handlerArgs: rawArgs,
-        headers,
-        serverParameters: args.serverParameters
-      });
-      const url = tool.path(handlerArgs) + (tool.query ? tool.query(handlerArgs) : "");
-      const data = await args.callApi({
-        method: tool.method,
-        url,
-        body: tool.body ? tool.body(handlerArgs) : void 0,
-        tool,
-        headers
-      });
-      const structuredContent = args.toStructuredContent?.({
-        data,
-        tool
-      });
-      return {
-        content: [{
-          type: "text",
-          text: toText(data)
-        }],
-        ...(structuredContent === void 0 ? {} : {
-          structuredContent
-        })
-      };
-    }
-  });
-  return tools;
 };
 
 //#endregion
@@ -1239,10 +1254,10 @@ exports.extractPinnedBody = extractPinnedBody;
 exports.extractQueryParams = extractQueryParams;
 exports.getJsonSchemaType = getJsonSchemaType;
 exports.openApiToToolDefinitions = openApiToToolDefinitions;
+exports.openApiToTools = openApiToTools;
 exports.operationIdToToolName = operationIdToToolName;
 exports.processOperation = processOperation;
 exports.processPath = processPath;
-exports.registerOpenApiTools = registerOpenApiTools;
 exports.resolveParameter = resolveParameter;
 exports.resolveSchema = resolveSchema;
 exports.snakeToCamel = snakeToCamel;

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 
-import { JsonObjectSchema, McpServer } from "@ttoss/http-server-mcp";
+import { JsonObjectSchema, Tool } from "@ttoss/http-server-mcp";
 import { App, InProcessResponse } from "@ttoss/http-server";
 
 //#region src/types.d.ts
@@ -49,6 +49,8 @@ interface ToolDefinition {
   pathTemplate: string;
   /** The operation's `operationId`. */
   operationId: string;
+  /** The operation's `tags`, e.g. to filter the deferred `search` by module. */
+  tags: string[];
   /** Builds the request path, substituting path params from the args. */
   path: (args: Record<string, unknown>) => string;
   /** Builds the query string (including leading `?`), or `undefined` if none. */
@@ -73,7 +75,7 @@ interface ToolDefinition {
    * Path and query parameters flagged with the server-managed extension. They
    * are absent from `inputSchema`, but `path` / `query` still read them from
    * the args under `argName`, so the consumer fills them before building the
-   * request — `registerOpenApiTools` does it through `serverParameters`.
+   * request — `openApiToTools` does it through `serverParameters`.
    */
   serverManagedParameters: ServerManagedParameter[];
 }
@@ -122,6 +124,7 @@ type RequestBodySpec = {
 };
 interface OperationSpec {
   operationId?: string;
+  tags?: string[];
   summary?: string;
   description?: string;
   parameters?: Array<{
@@ -342,7 +345,7 @@ declare const buildFullInputSchema: (args: {
   bodyProps: FullBodyProp[];
 }) => JsonObjectSchema;
 //#endregion
-//#region src/registerOpenApiTools.d.ts
+//#region src/openApiToTools.d.ts
 /** The resolved HTTP request a tool call maps to, before transport concerns. */
 interface ResolvedRequest {
   /** Uppercase HTTP method. */
@@ -360,9 +363,7 @@ interface ResolvedRequest {
    */
   headers: Record<string, string>;
 }
-interface RegisterOpenApiToolsArgs {
-  /** The MCP server the generated tools are registered on. */
-  server: McpServer;
+interface OpenApiToToolsArgs {
   /** One or more OpenAPI documents to derive tools from. */
   spec: OpenApiSpec | OpenApiSpec[];
   /** Tuning options forwarded to {@link openApiToToolDefinitions}. */
@@ -399,7 +400,7 @@ interface RegisterOpenApiToolsArgs {
   /**
    * Builds each tool's `_meta`, advertised on `tools/list`. This is how a
    * generated tool links to an MCP Apps view: return the bag from
-   * `registerAppResource(...).toolMeta()`. `undefined` registers no `_meta`.
+   * `registerAppResource(...).toolMeta()`. `undefined` sets no `_meta`.
    *
    * @example
    * ```typescript
@@ -427,25 +428,41 @@ interface RegisterOpenApiToolsArgs {
     tool: ToolDefinition;
     headers: Record<string, string>;
   }) => Record<string, unknown> | Promise<Record<string, unknown>>;
+  /**
+   * Sets every tool's `validateArguments`: enforce the generated
+   * `inputSchema` before `callApi` runs. Leave it off unless the spec
+   * describes every value the API accepts — see `Tool.validateArguments`.
+   * @default false
+   */
+  validateArguments?: boolean;
+}
+/** A {@link Tool} derived from one OpenAPI operation. */
+interface OpenApiTool extends Tool {
+  /**
+   * The operation it was derived from — method, path, extensions — for
+   * decisions that key on the API rather than the tool name, such as which
+   * scope a gate requires.
+   */
+  definition: ToolDefinition;
 }
 /** The text the default `toText` answers when the API returned no body. */
 declare const NO_CONTENT_TEXT = "Succeeded. The operation returned no content.";
 /**
- * Derives MCP tools from OpenAPI document(s) and registers each on the given
- * MCP server. Every tool's handler resolves the incoming args into a concrete
- * HTTP request and delegates execution to `callApi`.
+ * Derives MCP tools from OpenAPI document(s). Each tool's handler resolves
+ * the incoming args into a concrete HTTP request and delegates execution to
+ * `callApi`. Register the result with `registerTools` from
+ * `@ttoss/http-server-mcp` — one MCP tool each, or deferred.
  *
- * @returns The list of {@link ToolDefinition} that were registered.
+ * @returns One {@link OpenApiTool} per translatable operation.
  *
  * @example
  * ```typescript
- * import { McpServer } from '@ttoss/http-server-mcp';
- * import { registerOpenApiTools } from '@ttoss/http-server-mcp-openapi';
+ * import { McpServer, registerTools } from '@ttoss/http-server-mcp';
+ * import { openApiToTools } from '@ttoss/http-server-mcp-openapi';
  *
  * const server = new McpServer({ name: 'my-api', version: '1.0.0' });
  *
- * registerOpenApiTools({
- *   server,
+ * const tools = openApiToTools({
  *   spec: myOpenApiDocument,
  *   callApi: async ({ method, url, body, headers }) => {
  *     const res = await fetch(`https://api.example.com${url}`, {
@@ -456,9 +473,11 @@ declare const NO_CONTENT_TEXT = "Succeeded. The operation returned no content.";
  *     return res.json();
  *   },
  * });
+ *
+ * registerTools({ server, tools });
  * ```
  */
-declare const registerOpenApiTools: (args: RegisterOpenApiToolsArgs) => ToolDefinition[];
+declare const openApiToTools: (args: OpenApiToToolsArgs) => OpenApiTool[];
 //#endregion
 //#region src/inProcessCallApi.d.ts
 interface CreateInProcessCallApiArgs {
@@ -487,7 +506,7 @@ interface CreateInProcessCallApiArgs {
  */
 declare const errorMessageOf: (body: unknown) => string | null;
 /**
- * A `callApi` for {@link registerOpenApiTools} that serves each tool call
+ * A `callApi` for {@link openApiToTools} 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.
@@ -499,10 +518,9 @@ declare const errorMessageOf: (body: unknown) => string | null;
  *
  * @example
  * ```typescript
- * registerOpenApiTools({
+ * registerTools({
  *   server,
- *   spec,
- *   callApi: createInProcessCallApi({ app }),
+ *   tools: openApiToTools({ spec, callApi: createInProcessCallApi({ app }) }),
  * });
  * ```
  */
@@ -650,4 +668,4 @@ declare const openApiToToolDefinitions: (args: {
   options?: OpenApiToToolsOptions;
 }) => ToolDefinition[];
 //#endregion
-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 };
+export { type CreateInProcessCallApiArgs, DEFAULT_EXCLUDE_EXTENSION, DEFAULT_SERVER_MANAGED_EXTENSION, type JsonSchemaProperty, NO_CONTENT_TEXT, type OpenApiDocuments, type OpenApiSpec, type OpenApiToToolsArgs, type OpenApiToToolsOptions, type OpenApiTool, type OperationSpec, type QueryParamSerialization, 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, openApiToTools, operationIdToToolName, processOperation, processPath, resolveParameter, resolveSchema, snakeToCamel, toToolSchema };

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 
 import { App, InProcessResponse } from "@ttoss/http-server";
-import { JsonObjectSchema, McpServer } from "@ttoss/http-server-mcp";
+import { JsonObjectSchema, Tool } from "@ttoss/http-server-mcp";
 
 //#region src/types.d.ts
 /** The JSON Schema primitive types this generator can derive from an OpenAPI `type`. */
@@ -49,6 +49,8 @@ interface ToolDefinition {
   pathTemplate: string;
   /** The operation's `operationId`. */
   operationId: string;
+  /** The operation's `tags`, e.g. to filter the deferred `search` by module. */
+  tags: string[];
   /** Builds the request path, substituting path params from the args. */
   path: (args: Record<string, unknown>) => string;
   /** Builds the query string (including leading `?`), or `undefined` if none. */
@@ -73,7 +75,7 @@ interface ToolDefinition {
    * Path and query parameters flagged with the server-managed extension. They
    * are absent from `inputSchema`, but `path` / `query` still read them from
    * the args under `argName`, so the consumer fills them before building the
-   * request — `registerOpenApiTools` does it through `serverParameters`.
+   * request — `openApiToTools` does it through `serverParameters`.
    */
   serverManagedParameters: ServerManagedParameter[];
 }
@@ -122,6 +124,7 @@ type RequestBodySpec = {
 };
 interface OperationSpec {
   operationId?: string;
+  tags?: string[];
   summary?: string;
   description?: string;
   parameters?: Array<{
@@ -342,7 +345,7 @@ declare const buildFullInputSchema: (args: {
   bodyProps: FullBodyProp[];
 }) => JsonObjectSchema;
 //#endregion
-//#region src/registerOpenApiTools.d.ts
+//#region src/openApiToTools.d.ts
 /** The resolved HTTP request a tool call maps to, before transport concerns. */
 interface ResolvedRequest {
   /** Uppercase HTTP method. */
@@ -360,9 +363,7 @@ interface ResolvedRequest {
    */
   headers: Record<string, string>;
 }
-interface RegisterOpenApiToolsArgs {
-  /** The MCP server the generated tools are registered on. */
-  server: McpServer;
+interface OpenApiToToolsArgs {
   /** One or more OpenAPI documents to derive tools from. */
   spec: OpenApiSpec | OpenApiSpec[];
   /** Tuning options forwarded to {@link openApiToToolDefinitions}. */
@@ -399,7 +400,7 @@ interface RegisterOpenApiToolsArgs {
   /**
    * Builds each tool's `_meta`, advertised on `tools/list`. This is how a
    * generated tool links to an MCP Apps view: return the bag from
-   * `registerAppResource(...).toolMeta()`. `undefined` registers no `_meta`.
+   * `registerAppResource(...).toolMeta()`. `undefined` sets no `_meta`.
    *
    * @example
    * ```typescript
@@ -427,25 +428,41 @@ interface RegisterOpenApiToolsArgs {
     tool: ToolDefinition;
     headers: Record<string, string>;
   }) => Record<string, unknown> | Promise<Record<string, unknown>>;
+  /**
+   * Sets every tool's `validateArguments`: enforce the generated
+   * `inputSchema` before `callApi` runs. Leave it off unless the spec
+   * describes every value the API accepts — see `Tool.validateArguments`.
+   * @default false
+   */
+  validateArguments?: boolean;
+}
+/** A {@link Tool} derived from one OpenAPI operation. */
+interface OpenApiTool extends Tool {
+  /**
+   * The operation it was derived from — method, path, extensions — for
+   * decisions that key on the API rather than the tool name, such as which
+   * scope a gate requires.
+   */
+  definition: ToolDefinition;
 }
 /** The text the default `toText` answers when the API returned no body. */
 declare const NO_CONTENT_TEXT = "Succeeded. The operation returned no content.";
 /**
- * Derives MCP tools from OpenAPI document(s) and registers each on the given
- * MCP server. Every tool's handler resolves the incoming args into a concrete
- * HTTP request and delegates execution to `callApi`.
+ * Derives MCP tools from OpenAPI document(s). Each tool's handler resolves
+ * the incoming args into a concrete HTTP request and delegates execution to
+ * `callApi`. Register the result with `registerTools` from
+ * `@ttoss/http-server-mcp` — one MCP tool each, or deferred.
  *
- * @returns The list of {@link ToolDefinition} that were registered.
+ * @returns One {@link OpenApiTool} per translatable operation.
  *
  * @example
  * ```typescript
- * import { McpServer } from '@ttoss/http-server-mcp';
- * import { registerOpenApiTools } from '@ttoss/http-server-mcp-openapi';
+ * import { McpServer, registerTools } from '@ttoss/http-server-mcp';
+ * import { openApiToTools } from '@ttoss/http-server-mcp-openapi';
  *
  * const server = new McpServer({ name: 'my-api', version: '1.0.0' });
  *
- * registerOpenApiTools({
- *   server,
+ * const tools = openApiToTools({
  *   spec: myOpenApiDocument,
  *   callApi: async ({ method, url, body, headers }) => {
  *     const res = await fetch(`https://api.example.com${url}`, {
@@ -456,9 +473,11 @@ declare const NO_CONTENT_TEXT = "Succeeded. The operation returned no content.";
  *     return res.json();
  *   },
  * });
+ *
+ * registerTools({ server, tools });
  * ```
  */
-declare const registerOpenApiTools: (args: RegisterOpenApiToolsArgs) => ToolDefinition[];
+declare const openApiToTools: (args: OpenApiToToolsArgs) => OpenApiTool[];
 //#endregion
 //#region src/inProcessCallApi.d.ts
 interface CreateInProcessCallApiArgs {
@@ -487,7 +506,7 @@ interface CreateInProcessCallApiArgs {
  */
 declare const errorMessageOf: (body: unknown) => string | null;
 /**
- * A `callApi` for {@link registerOpenApiTools} that serves each tool call
+ * A `callApi` for {@link openApiToTools} 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.
@@ -499,10 +518,9 @@ declare const errorMessageOf: (body: unknown) => string | null;
  *
  * @example
  * ```typescript
- * registerOpenApiTools({
+ * registerTools({
  *   server,
- *   spec,
- *   callApi: createInProcessCallApi({ app }),
+ *   tools: openApiToTools({ spec, callApi: createInProcessCallApi({ app }) }),
  * });
  * ```
  */
@@ -650,4 +668,4 @@ declare const openApiToToolDefinitions: (args: {
   options?: OpenApiToToolsOptions;
 }) => ToolDefinition[];
 //#endregion
-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 };
+export { type CreateInProcessCallApiArgs, DEFAULT_EXCLUDE_EXTENSION, DEFAULT_SERVER_MANAGED_EXTENSION, type JsonSchemaProperty, NO_CONTENT_TEXT, type OpenApiDocuments, type OpenApiSpec, type OpenApiToToolsArgs, type OpenApiToToolsOptions, type OpenApiTool, type OperationSpec, type QueryParamSerialization, 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, openApiToTools, operationIdToToolName, processOperation, processPath, resolveParameter, resolveSchema, snakeToCamel, toToolSchema };

package/dist/index.mjs

@@ -1,6 +1,6 @@
 /** 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";
+import { getApiHeaders } from "@ttoss/http-server-mcp";
 
 //#region src/schema.ts
 var isRecord$1 = value => {
@@ -351,7 +351,7 @@ var pinnedArgs = parameters => {
 /**
 * 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`.
+* definition sends them, not only `openApiToTools`.
 */
 var withPinned = args => {
   const {
@@ -809,7 +809,7 @@ var defaultToError = response => {
   return new Error(errorMessageOf(response.body) ?? `HTTP ${response.status}`);
 };
 /**
-* A `callApi` for {@link registerOpenApiTools} that serves each tool call
+* A `callApi` for {@link openApiToTools} 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.
@@ -821,10 +821,9 @@ var defaultToError = response => {
 *
 * @example
 * ```typescript
-* registerOpenApiTools({
+* registerTools({
 *   server,
-*   spec,
-*   callApi: createInProcessCallApi({ app }),
+*   tools: openApiToTools({ spec, callApi: createInProcessCallApi({ app }) }),
 * });
 * ```
 */
@@ -989,6 +988,12 @@ var extractExtensions = operation => {
   for (const [key, value] of Object.entries(operation)) if (key.startsWith("x-")) extensions[key] = value;
   return extensions;
 };
+/** The operation's tags, ignoring entries a malformed spec typed otherwise. */
+var operationTags = operation => {
+  return (operation.tags ?? []).filter(tag => {
+    return typeof tag === "string";
+  });
+};
 var processOperation = args => {
   const httpMethod = args.method.toUpperCase();
   if (!SUPPORTED_METHODS.includes(httpMethod) || !args.operation.operationId || args.operation[args.options.excludeExtension]) return null;
@@ -1039,6 +1044,7 @@ var processOperation = args => {
     method: httpMethod,
     pathTemplate: args.pathTemplate,
     operationId: args.operation.operationId,
+    tags: operationTags(args.operation),
     path: withPinned({
       build: buildPathFn(args.pathTemplate, pathParams),
       pinned
@@ -1117,7 +1123,7 @@ var openApiToToolDefinitions = args => {
 };
 
 //#endregion
-//#region src/registerOpenApiTools.ts
+//#region src/openApiToTools.ts
 /** The text the default `toText` answers when the API returned no body. */
 var NO_CONTENT_TEXT = "Succeeded. The operation returned no content.";
 var defaultToText = data => {
@@ -1143,21 +1149,21 @@ var applyServerParameters = async args => {
   return result;
 };
 /**
-* Derives MCP tools from OpenAPI document(s) and registers each on the given
-* MCP server. Every tool's handler resolves the incoming args into a concrete
-* HTTP request and delegates execution to `callApi`.
+* Derives MCP tools from OpenAPI document(s). Each tool's handler resolves
+* the incoming args into a concrete HTTP request and delegates execution to
+* `callApi`. Register the result with `registerTools` from
+* `@ttoss/http-server-mcp` — one MCP tool each, or deferred.
 *
-* @returns The list of {@link ToolDefinition} that were registered.
+* @returns One {@link OpenApiTool} per translatable operation.
 *
 * @example
 * ```typescript
-* import { McpServer } from '@ttoss/http-server-mcp';
-* import { registerOpenApiTools } from '@ttoss/http-server-mcp-openapi';
+* import { McpServer, registerTools } from '@ttoss/http-server-mcp';
+* import { openApiToTools } from '@ttoss/http-server-mcp-openapi';
 *
 * const server = new McpServer({ name: 'my-api', version: '1.0.0' });
 *
-* registerOpenApiTools({
-*   server,
+* const tools = openApiToTools({
 *   spec: myOpenApiDocument,
 *   callApi: async ({ method, url, body, headers }) => {
 *     const res = await fetch(`https://api.example.com${url}`, {
@@ -1168,54 +1174,63 @@ var applyServerParameters = async args => {
 *     return res.json();
 *   },
 * });
+*
+* registerTools({ server, tools });
 * ```
 */
-var registerOpenApiTools = args => {
+var openApiToTools = args => {
   const toText = args.toText ?? defaultToText;
-  const tools = openApiToToolDefinitions({
+  return openApiToToolDefinitions({
     spec: args.spec,
     options: args.options
+  }).map(definition => {
+    const route = `${definition.method} ${definition.pathTemplate}`;
+    return {
+      name: definition.name,
+      description: definition.description,
+      inputSchema: definition.inputSchema,
+      validateArguments: args.validateArguments ?? false,
+      ...(definition.tags.length > 0 ? {
+        tags: definition.tags
+      } : {}),
+      summary: definition.description ? `${route} — ${definition.description}` : route,
+      _meta: args.toolMeta?.({
+        tool: definition
+      }),
+      definition,
+      handler: async rawArgs => {
+        const headers = getApiHeaders();
+        const handlerArgs = await applyServerParameters({
+          tool: definition,
+          handlerArgs: rawArgs,
+          headers,
+          serverParameters: args.serverParameters
+        });
+        const url = definition.path(handlerArgs) + (definition.query ? definition.query(handlerArgs) : "");
+        const data = await args.callApi({
+          method: definition.method,
+          url,
+          body: definition.body ? definition.body(handlerArgs) : void 0,
+          tool: definition,
+          headers
+        });
+        const structuredContent = args.toStructuredContent?.({
+          data,
+          tool: definition
+        });
+        return {
+          content: [{
+            type: "text",
+            text: toText(data)
+          }],
+          ...(structuredContent === void 0 ? {} : {
+            structuredContent
+          })
+        };
+      }
+    };
   });
-  for (const tool of tools) registerToolFromSchema(args.server, {
-    name: tool.name,
-    description: tool.description,
-    inputSchema: tool.inputSchema,
-    _meta: args.toolMeta?.({
-      tool
-    }),
-    handler: async rawArgs => {
-      const headers = getApiHeaders();
-      const handlerArgs = await applyServerParameters({
-        tool,
-        handlerArgs: rawArgs,
-        headers,
-        serverParameters: args.serverParameters
-      });
-      const url = tool.path(handlerArgs) + (tool.query ? tool.query(handlerArgs) : "");
-      const data = await args.callApi({
-        method: tool.method,
-        url,
-        body: tool.body ? tool.body(handlerArgs) : void 0,
-        tool,
-        headers
-      });
-      const structuredContent = args.toStructuredContent?.({
-        data,
-        tool
-      });
-      return {
-        content: [{
-          type: "text",
-          text: toText(data)
-        }],
-        ...(structuredContent === void 0 ? {} : {
-          structuredContent
-        })
-      };
-    }
-  });
-  return tools;
 };
 
 //#endregion
-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 };
+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, openApiToTools, operationIdToToolName, processOperation, processPath, resolveParameter, resolveSchema, snakeToCamel, toToolSchema };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttoss/http-server-mcp-openapi",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "Generate Model Context Protocol (MCP) tools from an OpenAPI specification for @ttoss/http-server-mcp",
   "keywords": [
     "ai",
@@ -32,18 +32,19 @@
     }
   },
   "files": [
+    "MIGRATIONS.md",
     "dist"
   ],
   "dependencies": {
-    "@ttoss/http-server": "^0.11.0",
-    "@ttoss/http-server-mcp": "^0.33.1"
+    "@ttoss/http-server-mcp": "^0.34.0",
+    "@ttoss/http-server": "^0.11.1"
   },
   "devDependencies": {
     "@modelcontextprotocol/server": "^2.0.0",
     "jest": "^30.4.2",
     "supertest": "^7.2.2",
     "tsdown": "^0.22.2",
-    "@ttoss/config": "^1.40.0"
+    "@ttoss/config": "^1.41.0"
   },
   "publishConfig": {
     "access": "public",