@ttoss/http-server-mcp 0.32.0 → 0.33.0

package/README.md

@@ -716,6 +716,9 @@ The `GatedToolDef` passed to `register` has:
 - `inputSchema` — Zod field map or `ZodObject`, forwarded to `server.registerTool`.
 - `gates` (`Array<(ctx: ToolCallContext) => void | Promise<void>>`, optional) — Per-tool guards appended after the global `gates`. Receive the full `ToolCallContext` enabling arg-conditional authorization.
 - `_meta` (`Record<string, unknown>`, optional) — Tool metadata forwarded verbatim on `tools/list`; how a gated tool links to an [MCP Apps](#mcp-apps-interactive-uis) view.
+- `title` (`string`, optional) — Display name forwarded on `tools/list`.
+- `annotations` (`ToolAnnotations`, optional) — Behaviour hints forwarded on `tools/list`: `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`. Clients use them to decide when to ask for confirmation; they never replace `requiredScope` or `gates`.
+- `outputSchema` (Zod field map or `ZodObject`, optional) — Result schema forwarded on `tools/list`. When set, a successful result is returned as `structuredContent` **and** as the same JSON in a `TextContent` block, and the SDK validates it against the schema. Without it, the result is a single `TextContent`, as before.
 - `method` — Async handler. Receives merged call args + `buildContext` output.
 
 **`ToolCallContext`** is the object passed to gates, `buildContext`, and `onError`:

package/dist/index.cjs

@@ -576,11 +576,15 @@ var createGatedToolRegistrar = ({
         ...extra
       });
       if (result == null) return toolError(notFoundMessage);
-      return {
-        content: [{
-          type: "text",
-          text: JSON.stringify(result)
-        }]
+      const content = [{
+        type: "text",
+        text: JSON.stringify(result)
+      }];
+      return def.outputSchema === void 0 ? {
+        content
+      } : {
+        content,
+        structuredContent: result
       };
     } catch (error) {
       if (onError) await onError(error, ctx);
@@ -608,8 +612,11 @@ var createGatedToolRegistrar = ({
       return runMethod(def, ctx);
     };
     server.registerTool(def.name, {
+      title: def.title,
       description: def.description,
       inputSchema: def.inputSchema,
+      outputSchema: def.outputSchema,
+      annotations: def.annotations,
       _meta: def._meta
     }, handler);
   };

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 
 /// <reference types="node" />
-import { CallToolResult, InMemoryServerEventBus, McpServer, McpServer as McpServer$1, McpServerFactory, RegisteredResource, ServerEvent, ServerEventBus, ServerEventBus as ServerEventBus$1, ServerNotifier, ServerNotifier as ServerNotifier$1 } from "@modelcontextprotocol/server";
+import { CallToolResult, InMemoryServerEventBus, McpServer, McpServer as McpServer$1, McpServerFactory, RegisteredResource, ServerEvent, ServerEventBus, ServerEventBus as ServerEventBus$1, ServerNotifier, ServerNotifier as ServerNotifier$1, ToolAnnotations } from "@modelcontextprotocol/server";
 import { Router } from "@ttoss/http-server";
 import accepts from "accepts";
 import { AsyncLocalStorage } from "async_hooks";
@@ -1012,7 +1012,21 @@ type ToolCallContext = {
 /** Definition for a single gated tool. */
 type GatedToolDef = {
   /** Tool name as registered with the MCP server. */name: string; /** Human-readable tool description. */
-  description: string; /** The single scope that must be present on the caller's token. */
+  description: string; /** Display name shown by clients instead of `name`. */
+  title?: string;
+  /**
+   * Behaviour hints forwarded on `tools/list` (`readOnlyHint`,
+   * `destructiveHint`, `idempotentHint`, `openWorldHint`). Clients use them to
+   * decide when to ask the user for confirmation; they are hints, never
+   * enforcement — scope and gates still decide what may run.
+   */
+  annotations?: ToolAnnotations;
+  /**
+   * Zod field map or ZodObject describing the result. When set, a successful
+   * result is also returned as `structuredContent`, and the SDK validates it
+   * against this schema.
+   */
+  outputSchema?: unknown; /** The single scope that must be present on the caller's token. */
   requiredScope: string; /** Zod field map or ZodObject — passed through to `server.registerTool`. */
   inputSchema: unknown;
   /**

package/dist/index.d.mts

@@ -2,7 +2,7 @@
 /// <reference types="node" />
 import { Router } from "@ttoss/http-server";
 import { AsyncLocalStorage } from "node:async_hooks";
-import { CallToolResult, InMemoryServerEventBus, McpServer, McpServer as McpServer$1, McpServerFactory, RegisteredResource, ServerEvent, ServerEventBus, ServerEventBus as ServerEventBus$1, ServerNotifier, ServerNotifier as ServerNotifier$1 } from "@modelcontextprotocol/server";
+import { CallToolResult, InMemoryServerEventBus, McpServer, McpServer as McpServer$1, McpServerFactory, RegisteredResource, ServerEvent, ServerEventBus, ServerEventBus as ServerEventBus$1, ServerNotifier, ServerNotifier as ServerNotifier$1, ToolAnnotations } from "@modelcontextprotocol/server";
 import { z } from "zod";
 import accepts from "accepts";
 import { AsyncLocalStorage as AsyncLocalStorage$1 } from "async_hooks";
@@ -1013,7 +1013,21 @@ type ToolCallContext = {
 /** Definition for a single gated tool. */
 type GatedToolDef = {
   /** Tool name as registered with the MCP server. */name: string; /** Human-readable tool description. */
-  description: string; /** The single scope that must be present on the caller's token. */
+  description: string; /** Display name shown by clients instead of `name`. */
+  title?: string;
+  /**
+   * Behaviour hints forwarded on `tools/list` (`readOnlyHint`,
+   * `destructiveHint`, `idempotentHint`, `openWorldHint`). Clients use them to
+   * decide when to ask the user for confirmation; they are hints, never
+   * enforcement — scope and gates still decide what may run.
+   */
+  annotations?: ToolAnnotations;
+  /**
+   * Zod field map or ZodObject describing the result. When set, a successful
+   * result is also returned as `structuredContent`, and the SDK validates it
+   * against this schema.
+   */
+  outputSchema?: unknown; /** The single scope that must be present on the caller's token. */
   requiredScope: string; /** Zod field map or ZodObject — passed through to `server.registerTool`. */
   inputSchema: unknown;
   /**

package/dist/index.mjs

@@ -573,11 +573,15 @@ var createGatedToolRegistrar = ({
         ...extra
       });
       if (result == null) return toolError(notFoundMessage);
-      return {
-        content: [{
-          type: "text",
-          text: JSON.stringify(result)
-        }]
+      const content = [{
+        type: "text",
+        text: JSON.stringify(result)
+      }];
+      return def.outputSchema === void 0 ? {
+        content
+      } : {
+        content,
+        structuredContent: result
       };
     } catch (error) {
       if (onError) await onError(error, ctx);
@@ -605,8 +609,11 @@ var createGatedToolRegistrar = ({
       return runMethod(def, ctx);
     };
     server.registerTool(def.name, {
+      title: def.title,
       description: def.description,
       inputSchema: def.inputSchema,
+      outputSchema: def.outputSchema,
+      annotations: def.annotations,
       _meta: def._meta
     }, handler);
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttoss/http-server-mcp",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "description": "Model Context Protocol (MCP) server integration for @ttoss/http-server",
   "keywords": [
     "ai",
@@ -37,10 +37,10 @@
     "@modelcontextprotocol/node": "^2.0.0",
     "@modelcontextprotocol/server": "^2.0.0",
     "zod": "^4.4.3",
-    "@ttoss/auth-core": "^0.16.0",
+    "@ttoss/http-server": "^0.11.0",
     "@ttoss/http-server-auth": "^0.8.0",
-    "@ttoss/i18n-core": "^0.6.0",
-    "@ttoss/http-server": "^0.11.0"
+    "@ttoss/auth-core": "^0.16.0",
+    "@ttoss/i18n-core": "^0.6.0"
   },
   "devDependencies": {
     "@modelcontextprotocol/client": "^2.0.0",