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

package/README.md

@@ -89,14 +89,16 @@ repeats array values, `spaceDelimited`/`pipeDelimited` join them, and
 
 ## `registerOpenApiTools`
 
-| 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).     |
-| `options?`          | See [Options](#options).                                                                                      |
+| 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).                     |
+| `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`
@@ -104,6 +106,38 @@ reaches the client as a success.
 
 Returns the list of `ToolDefinition`s that were registered.
 
+### MCP Apps views
+
+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';
+
+const agentCard = registerAppResource({
+  server,
+  name: 'agent_card',
+  uri: 'ui://agents/card',
+  html: agentCardHtml,
+});
+
+registerOpenApiTools({
+  server,
+  spec,
+  callApi,
+  toolMeta: ({ tool }) => {
+    return tool.name === 'get-agent' ? agentCard.toolMeta() : undefined;
+  },
+  toStructuredContent: ({ data, tool }) => {
+    return tool.name === 'get-agent'
+      ? (data as Record<string, unknown>)
+      : undefined;
+  },
+});
+```
+
+Keep the text payload: a host without MCP Apps support renders only that.
+
 ## Calling the API In-Process
 
 When the REST API runs in the same process as the MCP server,

package/dist/index.cjs

@@ -1183,6 +1183,9 @@ var registerOpenApiTools = args => {
     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({
@@ -1192,17 +1195,25 @@ var registerOpenApiTools = args => {
         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(await args.callApi({
-            method: tool.method,
-            url,
-            body: tool.body ? tool.body(handlerArgs) : void 0,
-            tool,
-            headers
-          }))
-        }]
+          text: toText(data)
+        }],
+        ...(structuredContent === void 0 ? {} : {
+          structuredContent
+        })
       };
     }
   });

package/dist/index.d.cts

@@ -379,6 +379,37 @@ interface RegisterOpenApiToolsArgs {
    * {@link NO_CONTENT_TEXT} for an empty body (e.g. a `204`).
    */
   toText?: (data: unknown) => string;
+  /**
+   * Builds the tool result's `structuredContent` from the raw API data, sent
+   * beside the text payload. Return `undefined` to keep a result text-only,
+   * which is every result when this is unset.
+   *
+   * @example
+   * ```typescript
+   * toStructuredContent: ({ data }) =>
+   *   typeof data === 'object' && data !== null && !Array.isArray(data)
+   *     ? (data as Record<string, unknown>)
+   *     : undefined,
+   * ```
+   */
+  toStructuredContent?: (args: {
+    data: unknown;
+    tool: ToolDefinition;
+  }) => Record<string, unknown> | undefined;
+  /**
+   * 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`.
+   *
+   * @example
+   * ```typescript
+   * toolMeta: ({ tool }) =>
+   *   tool.name === 'get-agent' ? agentCard.toolMeta() : undefined,
+   * ```
+   */
+  toolMeta?: (args: {
+    tool: ToolDefinition;
+  }) => Record<string, unknown> | undefined;
   /**
    * Supplies the values of the tool's server-managed path and query
    * parameters (`tool.serverManagedParameters`), keyed by their spec name.

package/dist/index.d.mts

@@ -379,6 +379,37 @@ interface RegisterOpenApiToolsArgs {
    * {@link NO_CONTENT_TEXT} for an empty body (e.g. a `204`).
    */
   toText?: (data: unknown) => string;
+  /**
+   * Builds the tool result's `structuredContent` from the raw API data, sent
+   * beside the text payload. Return `undefined` to keep a result text-only,
+   * which is every result when this is unset.
+   *
+   * @example
+   * ```typescript
+   * toStructuredContent: ({ data }) =>
+   *   typeof data === 'object' && data !== null && !Array.isArray(data)
+   *     ? (data as Record<string, unknown>)
+   *     : undefined,
+   * ```
+   */
+  toStructuredContent?: (args: {
+    data: unknown;
+    tool: ToolDefinition;
+  }) => Record<string, unknown> | undefined;
+  /**
+   * 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`.
+   *
+   * @example
+   * ```typescript
+   * toolMeta: ({ tool }) =>
+   *   tool.name === 'get-agent' ? agentCard.toolMeta() : undefined,
+   * ```
+   */
+  toolMeta?: (args: {
+    tool: ToolDefinition;
+  }) => Record<string, unknown> | undefined;
   /**
    * Supplies the values of the tool's server-managed path and query
    * parameters (`tool.serverManagedParameters`), keyed by their spec name.

package/dist/index.mjs

@@ -1180,6 +1180,9 @@ var registerOpenApiTools = args => {
     name: tool.name,
     description: tool.description,
     inputSchema: tool.inputSchema,
+    _meta: args.toolMeta?.({
+      tool
+    }),
     handler: async rawArgs => {
       const headers = getApiHeaders();
       const handlerArgs = await applyServerParameters({
@@ -1189,17 +1192,25 @@ var registerOpenApiTools = args => {
         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(await args.callApi({
-            method: tool.method,
-            url,
-            body: tool.body ? tool.body(handlerArgs) : void 0,
-            tool,
-            headers
-          }))
-        }]
+          text: toText(data)
+        }],
+        ...(structuredContent === void 0 ? {} : {
+          structuredContent
+        })
       };
     }
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttoss/http-server-mcp-openapi",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Generate Model Context Protocol (MCP) tools from an OpenAPI specification for @ttoss/http-server-mcp",
   "keywords": [
     "ai",
@@ -36,7 +36,7 @@
   ],
   "dependencies": {
     "@ttoss/http-server": "^0.11.0",
-    "@ttoss/http-server-mcp": "^0.32.0"
+    "@ttoss/http-server-mcp": "^0.33.0"
   },
   "devDependencies": {
     "@modelcontextprotocol/server": "^2.0.0",