@ttoss/http-server-mcp 0.19.0 → 0.20.0

package/README.md

@@ -366,6 +366,56 @@ createMcpRouter(mcpServer, {
 
 The discovery endpoint (`/.well-known/oauth-protected-resource`) remains publicly accessible even when `aliases` includes `'/'`.
 
+## Gated Tool Registrar
+
+`createGatedToolRegistrar` wraps `server.registerTool` with a consistent authentication and authorization pipeline so you don't repeat the same boilerplate in every handler.
+
+Every registered tool automatically:
+
+1. Resolves the caller's identity (defaults to `getIdentity()` from the request context).
+2. Checks that the caller holds a required OAuth scope — returns an `isError` result (not a throw) when the scope is absent.
+3. Runs any extra `gates` in order; a throwing gate rejects the call.
+4. Merges `buildContext` output into the handler args.
+5. Wraps `null`/`undefined` results in a "Not found" error result.
+6. Calls `onError` on throw before rethrowing, for telemetry.
+
+```typescript
+import {
+  createGatedToolRegistrar,
+  getIdentity,
+  McpServer,
+} from '@ttoss/http-server-mcp';
+import { z } from 'zod';
+
+const { register } = createGatedToolRegistrar({
+  server,
+  resolveIdentity: () => {
+    const jwt = getIdentity<{ sub: string; scope: string }>();
+    const scopes = jwt?.scope?.split(' ') ?? [];
+    return { userId: jwt!.sub, scopes };
+  },
+  buildContext: ({ userId }) => ({ tenantId: lookupTenant(userId) }),
+  onError: (err, { handler, identity }) => {
+    logger.error({ err, handler, userId: identity.userId });
+  },
+});
+
+register({
+  name: 'list-campaigns',
+  description: 'List all ad campaigns for the caller.',
+  requiredScope: 'campaigns:read',
+  inputSchema: { limit: z.number().optional() },
+  method: async ({ userId, tenantId, limit }) =>
+    fetchCampaigns(tenantId, limit),
+});
+```
+
+**`resolveIdentity`** is called once per invocation. Omit it to use the default `getIdentity()` from the MCP request context.
+
+**`gates`** are async functions that receive the resolved identity and throw to reject. Use them for additional checks that span multiple tools (rate limiting, IP allowlists, etc.).
+
+**`buildContext`** injects request-scoped values (DB clients, tenant IDs) into every handler call without threading them through each individual tool.
+
 ## Issuing tokens for MCP clients
 
 The `auth` option above covers the **resource-server** half of MCP authorization — it verifies tokens issued by an external authorization server (Cognito, Auth0, …). To make your own first-party server _issue_ the tokens an MCP client runs the full OAuth flow against, add the [`@ttoss/http-server-auth`](https://ttoss.dev/docs/modules/packages/http-server-auth) plugin's `oauthServer()` and pair it with `createMcpRouter({ auth: { verifyToken } })` so one deployment both issues and verifies tokens. See the [OAuth Authorization Server](https://ttoss.dev/docs/engineering/guidelines/oauth-authorization-server) guideline.
@@ -446,6 +496,28 @@ Returns the `WWW-Authenticate` header value for a 401 response, formatted per th
 
 **Returns:** `string` — The full `WWW-Authenticate` header value
 
+### `createGatedToolRegistrar(options)`
+
+Factory that returns a `register` helper for tools that require authentication and a specific OAuth scope.
+
+**Parameters (`options`):**
+
+- `server` (`McpServer`) — The MCP server to register tools on.
+- `resolveIdentity` (`() => ToolIdentity`, optional) — Called once per invocation to resolve `{ userId, scopes? }`. Defaults to `getIdentity()` from the request context.
+- `gates` (`Array<(identity: ToolIdentity) => void | Promise<void>>`, optional) — Additional guards run after the scope check, in order. Throw to reject the call.
+- `buildContext` (`(identity: ToolIdentity) => Record<string, unknown>`, optional) — Produces extra key-value pairs merged into every handler's args.
+- `onError` (`(error, ctx) => void | Promise<void>`, optional) — Called when a handler throws, before the error is rethrown. Use for logging/telemetry.
+
+**Returns:** `{ register: (def: GatedToolDef) => void }`
+
+The `GatedToolDef` passed to `register` has:
+
+- `name` — Tool name.
+- `description` — Human-readable description.
+- `requiredScope` — Single scope that must appear in `identity.scopes`.
+- `inputSchema` — Zod field map or `ZodObject`, forwarded to `server.registerTool`.
+- `method` — Async handler. Receives merged call args + `buildContext` output.
+
 ### `registerToolFromSchema(server, params)`
 
 Registers a tool using a **plain JSON Schema** object for `inputSchema` instead of a Zod shape.

package/dist/index.cjs

@@ -2,14 +2,122 @@
 Object.defineProperty(exports, Symbol.toStringTag, {
   value: 'Module'
 });
-let node_async_hooks = require("node:async_hooks");
 let _modelcontextprotocol_sdk_server_streamableHttp_js = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
 let _ttoss_auth_core_amazon_cognito = require("@ttoss/auth-core/amazon-cognito");
 let _ttoss_http_server = require("@ttoss/http-server");
 let _ttoss_http_server_auth = require("@ttoss/http-server-auth");
 let zod = require("zod");
+let node_async_hooks = require("node:async_hooks");
 let _modelcontextprotocol_sdk_server_mcp_js = require("@modelcontextprotocol/sdk/server/mcp.js");
 
+//#region src/context.ts
+var requestContextStore = new node_async_hooks.AsyncLocalStorage();
+/**
+* Returns the verified JWT payload for the current MCP request.
+* Only available inside a tool handler when `auth` is configured on the router.
+*
+* Accepts an optional type parameter to avoid casting at call sites:
+* `getIdentity<{ sub: string; email: string }>()` returns `T | undefined`.
+* Omitting the type parameter keeps the return type as `unknown | undefined`.
+*/
+var getIdentity = () => {
+  return requestContextStore.getStore()?.identity;
+};
+
+//#endregion
+//#region src/createGatedToolRegistrar.ts
+var toolError = message => {
+  return {
+    content: [{
+      type: "text",
+      text: JSON.stringify({
+        error: message
+      })
+    }],
+    isError: true
+  };
+};
+/**
+* Factory that returns a `register` helper for MCP tools that require
+* authentication and a specific OAuth scope.
+*
+* Every registered tool automatically:
+* 1. Resolves the caller identity (default: `getIdentity()`). Returns an
+*    `isError` result when the identity is absent (unauthenticated request).
+* 2. Checks `requiredScope` — returns an `isError` result (not a throw) when
+*    the scope is absent, consistent with how MCP surfaces authorization errors.
+*    Scope semantics are intentionally simple (`Array.includes`). The package's
+*    `checkScopes` helper is not reused here because it throws rather than
+*    returning an `isError` result, and it reads identity from context itself.
+* 3. Runs any extra `gates` in order; a throwing gate rejects the call.
+*    Gates own their own error handling; `onError` covers the tool handler only.
+* 4. Merges `buildContext` output into the handler args.
+* 5. Wraps `null`/`undefined` results in a "Not found" error result.
+* 6. Calls `onError` on handler throw before rethrowing.
+*
+* @example
+* ```typescript
+* const { register } = createGatedToolRegistrar({
+*   server,
+*   resolveIdentity: () => {
+*     const jwt = getIdentity<{ sub: string; scopes: string[] }>();
+*     return { userId: jwt!.sub, scopes: jwt!.scopes };
+*   },
+* });
+*
+* register({
+*   name: 'list-campaigns',
+*   description: 'List all ad campaigns for the caller.',
+*   requiredScope: 'campaigns:read',
+*   inputSchema: { limit: z.number().optional() },
+*   method: async ({ userId, limit }) => fetchCampaigns(userId, limit),
+* });
+* ```
+*/
+var createGatedToolRegistrar = ({
+  server,
+  resolveIdentity = getIdentity,
+  gates = [],
+  onError,
+  buildContext
+}) => {
+  const register = def => {
+    server.registerTool(def.name, {
+      description: def.description,
+      inputSchema: def.inputSchema
+    }, async args => {
+      const identity = resolveIdentity();
+      if (!identity) return toolError("Unauthorized");
+      if (!(Array.isArray(identity.scopes) ? identity.scopes : []).includes(def.requiredScope)) return toolError(`This tool requires the "${def.requiredScope}" scope.`);
+      for (const gate of gates) await gate(identity);
+      const extra = buildContext ? buildContext(identity) : {};
+      try {
+        const result = await def.method({
+          ...args,
+          ...extra
+        });
+        if (result == null) return toolError("Not found");
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify(result)
+          }]
+        };
+      } catch (error) {
+        if (onError) await onError(error, {
+          handler: def.name,
+          identity
+        });
+        throw error;
+      }
+    });
+  };
+  return {
+    register
+  };
+};
+
+//#endregion
 //#region src/index.ts
 /** MCP lifecycle/discovery methods reachable before a client authenticates. */
 var DEFAULT_PUBLIC_METHODS = ["initialize", "tools/list"];
@@ -27,7 +135,6 @@ var buildVerifyToken = auth => {
   if (auth.verifyToken) return auth.verifyToken;
   throw new Error("McpAuthOptions requires either cognitoUserPool or verifyToken");
 };
-var requestContextStore = new node_async_hooks.AsyncLocalStorage();
 /**
 * Generic HTTP helper for use inside MCP tool handlers.
 *
@@ -115,17 +222,6 @@ var apiCall = async (method, url, options) => {
   return response.text();
 };
 /**
-* Returns the verified JWT payload for the current MCP request.
-* Only available inside a tool handler when `auth` is configured on the router.
-*
-* Accepts an optional type parameter to avoid casting at call sites:
-* `getIdentity<{ sub: string; email: string }>()` returns `T | undefined`.
-* Omitting the type parameter keeps the return type as `unknown | undefined`.
-*/
-var getIdentity = () => {
-  return requestContextStore.getStore()?.identity;
-};
-/**
 * Asserts that the current request's token contains all required scopes.
 * Throws if any scope is missing — the MCP SDK catches this and returns a
 * tool error to the client. Use inside tool handlers for per-tool authorization.
@@ -414,6 +510,7 @@ Object.defineProperty(exports, 'McpServer', {
 });
 exports.apiCall = apiCall;
 exports.checkScopes = checkScopes;
+exports.createGatedToolRegistrar = createGatedToolRegistrar;
 exports.createMcpRouter = createMcpRouter;
 exports.getIdentity = getIdentity;
 exports.registerToolFromSchema = registerToolFromSchema;

package/dist/index.d.cts

@@ -665,6 +665,108 @@ declare namespace Application {
   const HttpError: typeof HttpErrors.HttpError;
 }
 //#endregion
+//#region src/context.d.ts
+/**
+ * Returns the verified JWT payload for the current MCP request.
+ * Only available inside a tool handler when `auth` is configured on the router.
+ *
+ * Accepts an optional type parameter to avoid casting at call sites:
+ * `getIdentity<{ sub: string; email: string }>()` returns `T | undefined`.
+ * Omitting the type parameter keeps the return type as `unknown | undefined`.
+ */
+declare const getIdentity: <T = unknown>() => T | undefined;
+//#endregion
+//#region src/createGatedToolRegistrar.d.ts
+/** Resolved identity for a gated tool call. */
+type ToolIdentity = {
+  userId: string;
+  scopes?: string[];
+};
+/** 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. */
+  requiredScope: string; /** Zod field map or ZodObject — passed through to `server.registerTool`. */
+  inputSchema: unknown; /** The tool handler. Receives merged call args + `buildContext` output. */
+  method: (args: Record<string, unknown>) => Promise<unknown>;
+};
+/** Options for {@link createGatedToolRegistrar}. */
+type CreateGatedToolRegistrarOptions = {
+  /** The MCP server instance to register tools on. */server: McpServer$1;
+  /**
+   * Called once per tool invocation to resolve the caller's identity.
+   * Defaults to `getIdentity()` from the request context.
+   */
+  resolveIdentity?: () => ToolIdentity;
+  /**
+   * Additional authorization gates run after the scope check, in order.
+   * Throw to reject the call; return (or resolve) to continue.
+   * Gates own their own error handling — `onError` covers the tool handler only.
+   */
+  gates?: Array<(identity: ToolIdentity) => void | Promise<void>>;
+  /**
+   * Called when the tool **handler** throws. Use for error reporting/telemetry.
+   * The error is always rethrown after this hook completes.
+   * Note: scope-check failures and gate rejections do not trigger `onError`.
+   */
+  onError?: (error: unknown, ctx: {
+    handler: string;
+    identity: ToolIdentity;
+  }) => void | Promise<void>;
+  /**
+   * Called once per invocation to produce extra key-value pairs that are
+   * merged into the handler args. Use to inject request-scoped context
+   * (e.g. a database client keyed to the caller's tenant).
+   */
+  buildContext?: (identity: ToolIdentity) => Record<string, unknown>;
+};
+/**
+ * Factory that returns a `register` helper for MCP tools that require
+ * authentication and a specific OAuth scope.
+ *
+ * Every registered tool automatically:
+ * 1. Resolves the caller identity (default: `getIdentity()`). Returns an
+ *    `isError` result when the identity is absent (unauthenticated request).
+ * 2. Checks `requiredScope` — returns an `isError` result (not a throw) when
+ *    the scope is absent, consistent with how MCP surfaces authorization errors.
+ *    Scope semantics are intentionally simple (`Array.includes`). The package's
+ *    `checkScopes` helper is not reused here because it throws rather than
+ *    returning an `isError` result, and it reads identity from context itself.
+ * 3. Runs any extra `gates` in order; a throwing gate rejects the call.
+ *    Gates own their own error handling; `onError` covers the tool handler only.
+ * 4. Merges `buildContext` output into the handler args.
+ * 5. Wraps `null`/`undefined` results in a "Not found" error result.
+ * 6. Calls `onError` on handler throw before rethrowing.
+ *
+ * @example
+ * ```typescript
+ * const { register } = createGatedToolRegistrar({
+ *   server,
+ *   resolveIdentity: () => {
+ *     const jwt = getIdentity<{ sub: string; scopes: string[] }>();
+ *     return { userId: jwt!.sub, scopes: jwt!.scopes };
+ *   },
+ * });
+ *
+ * register({
+ *   name: 'list-campaigns',
+ *   description: 'List all ad campaigns for the caller.',
+ *   requiredScope: 'campaigns:read',
+ *   inputSchema: { limit: z.number().optional() },
+ *   method: async ({ userId, limit }) => fetchCampaigns(userId, limit),
+ * });
+ * ```
+ */
+declare const createGatedToolRegistrar: ({
+  server,
+  resolveIdentity,
+  gates,
+  onError,
+  buildContext
+}: CreateGatedToolRegistrarOptions) => {
+  register: (def: GatedToolDef) => void;
+};
+//#endregion
 //#region src/index.d.ts
 type Context$1 = Application.Context;
 /** Amazon Cognito user pool configuration for JWT verification. */
@@ -787,15 +889,6 @@ interface ApiCallOptions {
  * ```
  */
 declare const apiCall: (method: string, url: string, options?: ApiCallOptions) => Promise<unknown>;
-/**
- * Returns the verified JWT payload for the current MCP request.
- * Only available inside a tool handler when `auth` is configured on the router.
- *
- * Accepts an optional type parameter to avoid casting at call sites:
- * `getIdentity<{ sub: string; email: string }>()` returns `T | undefined`.
- * Omitting the type parameter keeps the return type as `unknown | undefined`.
- */
-declare const getIdentity: <T = unknown>() => T | undefined;
 /**
  * Asserts that the current request's token contains all required scopes.
  * Throws if any scope is missing — the MCP SDK catches this and returns a
@@ -1025,4 +1118,4 @@ interface RegisterToolFromSchemaParams {
  */
 declare const registerToolFromSchema: (server: McpServer$1, params: RegisterToolFromSchemaParams) => void;
 //#endregion
-export { ApiCallOptions, CognitoUserPoolConfig, JsonObjectSchema, McpAuthOptions, McpRouterOptions, McpServer, RegisterToolFromSchemaParams, apiCall, checkScopes, createMcpRouter, getIdentity, registerToolFromSchema, z };
+export { ApiCallOptions, CognitoUserPoolConfig, type CreateGatedToolRegistrarOptions, type GatedToolDef, JsonObjectSchema, McpAuthOptions, McpRouterOptions, McpServer, RegisterToolFromSchemaParams, type ToolIdentity, apiCall, checkScopes, createGatedToolRegistrar, createMcpRouter, getIdentity, registerToolFromSchema, z };

package/dist/index.d.mts

@@ -2,10 +2,11 @@
 /// <reference types="node" />
 import { Router } from "@ttoss/http-server";
 import { z } from "zod";
+import { AsyncLocalStorage } from "node:async_hooks";
 import { McpServer, McpServer as McpServer$1 } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import accepts from "accepts";
-import { AsyncLocalStorage } from "async_hooks";
+import { AsyncLocalStorage as AsyncLocalStorage$1 } from "async_hooks";
 import Cookies from "cookies";
 import { EventEmitter } from "events";
 import { IncomingHttpHeaders, IncomingMessage, OutgoingHttpHeaders, Server, ServerResponse } from "http";
@@ -403,7 +404,7 @@ declare class Application<StateT = Application.DefaultState, ContextT = Applicat
   response: Application.BaseResponse;
   silent: boolean;
   keys: Keygrip | string[];
-  ctxStorage: AsyncLocalStorage<ContextT> | undefined;
+  ctxStorage: AsyncLocalStorage$1<ContextT> | undefined;
   /**
    * @param {object} [options] Application options
    * @param {string} [options.env='development'] Environment
@@ -421,7 +422,7 @@ declare class Application<StateT = Application.DefaultState, ContextT = Applicat
     subdomainOffset?: number | undefined;
     proxyIpHeader?: string | undefined;
     maxIpsCount?: number | undefined;
-    asyncLocalStorage?: boolean | AsyncLocalStorage<ContextT> | undefined;
+    asyncLocalStorage?: boolean | AsyncLocalStorage$1<ContextT> | undefined;
   });
   /**
    * Shorthand for:
@@ -665,6 +666,108 @@ declare namespace Application {
   const HttpError: typeof HttpErrors.HttpError;
 }
 //#endregion
+//#region src/context.d.ts
+/**
+ * Returns the verified JWT payload for the current MCP request.
+ * Only available inside a tool handler when `auth` is configured on the router.
+ *
+ * Accepts an optional type parameter to avoid casting at call sites:
+ * `getIdentity<{ sub: string; email: string }>()` returns `T | undefined`.
+ * Omitting the type parameter keeps the return type as `unknown | undefined`.
+ */
+declare const getIdentity: <T = unknown>() => T | undefined;
+//#endregion
+//#region src/createGatedToolRegistrar.d.ts
+/** Resolved identity for a gated tool call. */
+type ToolIdentity = {
+  userId: string;
+  scopes?: string[];
+};
+/** 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. */
+  requiredScope: string; /** Zod field map or ZodObject — passed through to `server.registerTool`. */
+  inputSchema: unknown; /** The tool handler. Receives merged call args + `buildContext` output. */
+  method: (args: Record<string, unknown>) => Promise<unknown>;
+};
+/** Options for {@link createGatedToolRegistrar}. */
+type CreateGatedToolRegistrarOptions = {
+  /** The MCP server instance to register tools on. */server: McpServer$1;
+  /**
+   * Called once per tool invocation to resolve the caller's identity.
+   * Defaults to `getIdentity()` from the request context.
+   */
+  resolveIdentity?: () => ToolIdentity;
+  /**
+   * Additional authorization gates run after the scope check, in order.
+   * Throw to reject the call; return (or resolve) to continue.
+   * Gates own their own error handling — `onError` covers the tool handler only.
+   */
+  gates?: Array<(identity: ToolIdentity) => void | Promise<void>>;
+  /**
+   * Called when the tool **handler** throws. Use for error reporting/telemetry.
+   * The error is always rethrown after this hook completes.
+   * Note: scope-check failures and gate rejections do not trigger `onError`.
+   */
+  onError?: (error: unknown, ctx: {
+    handler: string;
+    identity: ToolIdentity;
+  }) => void | Promise<void>;
+  /**
+   * Called once per invocation to produce extra key-value pairs that are
+   * merged into the handler args. Use to inject request-scoped context
+   * (e.g. a database client keyed to the caller's tenant).
+   */
+  buildContext?: (identity: ToolIdentity) => Record<string, unknown>;
+};
+/**
+ * Factory that returns a `register` helper for MCP tools that require
+ * authentication and a specific OAuth scope.
+ *
+ * Every registered tool automatically:
+ * 1. Resolves the caller identity (default: `getIdentity()`). Returns an
+ *    `isError` result when the identity is absent (unauthenticated request).
+ * 2. Checks `requiredScope` — returns an `isError` result (not a throw) when
+ *    the scope is absent, consistent with how MCP surfaces authorization errors.
+ *    Scope semantics are intentionally simple (`Array.includes`). The package's
+ *    `checkScopes` helper is not reused here because it throws rather than
+ *    returning an `isError` result, and it reads identity from context itself.
+ * 3. Runs any extra `gates` in order; a throwing gate rejects the call.
+ *    Gates own their own error handling; `onError` covers the tool handler only.
+ * 4. Merges `buildContext` output into the handler args.
+ * 5. Wraps `null`/`undefined` results in a "Not found" error result.
+ * 6. Calls `onError` on handler throw before rethrowing.
+ *
+ * @example
+ * ```typescript
+ * const { register } = createGatedToolRegistrar({
+ *   server,
+ *   resolveIdentity: () => {
+ *     const jwt = getIdentity<{ sub: string; scopes: string[] }>();
+ *     return { userId: jwt!.sub, scopes: jwt!.scopes };
+ *   },
+ * });
+ *
+ * register({
+ *   name: 'list-campaigns',
+ *   description: 'List all ad campaigns for the caller.',
+ *   requiredScope: 'campaigns:read',
+ *   inputSchema: { limit: z.number().optional() },
+ *   method: async ({ userId, limit }) => fetchCampaigns(userId, limit),
+ * });
+ * ```
+ */
+declare const createGatedToolRegistrar: ({
+  server,
+  resolveIdentity,
+  gates,
+  onError,
+  buildContext
+}: CreateGatedToolRegistrarOptions) => {
+  register: (def: GatedToolDef) => void;
+};
+//#endregion
 //#region src/index.d.ts
 type Context$1 = Application.Context;
 /** Amazon Cognito user pool configuration for JWT verification. */
@@ -787,15 +890,6 @@ interface ApiCallOptions {
  * ```
  */
 declare const apiCall: (method: string, url: string, options?: ApiCallOptions) => Promise<unknown>;
-/**
- * Returns the verified JWT payload for the current MCP request.
- * Only available inside a tool handler when `auth` is configured on the router.
- *
- * Accepts an optional type parameter to avoid casting at call sites:
- * `getIdentity<{ sub: string; email: string }>()` returns `T | undefined`.
- * Omitting the type parameter keeps the return type as `unknown | undefined`.
- */
-declare const getIdentity: <T = unknown>() => T | undefined;
 /**
  * Asserts that the current request's token contains all required scopes.
  * Throws if any scope is missing — the MCP SDK catches this and returns a
@@ -1025,4 +1119,4 @@ interface RegisterToolFromSchemaParams {
  */
 declare const registerToolFromSchema: (server: McpServer$1, params: RegisterToolFromSchemaParams) => void;
 //#endregion
-export { ApiCallOptions, CognitoUserPoolConfig, JsonObjectSchema, McpAuthOptions, McpRouterOptions, McpServer, RegisterToolFromSchemaParams, apiCall, checkScopes, createMcpRouter, getIdentity, registerToolFromSchema, z };
+export { ApiCallOptions, CognitoUserPoolConfig, type CreateGatedToolRegistrarOptions, type GatedToolDef, JsonObjectSchema, McpAuthOptions, McpRouterOptions, McpServer, RegisterToolFromSchemaParams, type ToolIdentity, apiCall, checkScopes, createGatedToolRegistrar, createMcpRouter, getIdentity, registerToolFromSchema, z };

package/dist/index.mjs

@@ -1,12 +1,120 @@
 /** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
-import { AsyncLocalStorage } from "node:async_hooks";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { CognitoJwtVerifier } from "@ttoss/auth-core/amazon-cognito";
 import { Router } from "@ttoss/http-server";
 import { authMiddleware } from "@ttoss/http-server-auth";
 import { z, z as z$1 } from "zod";
+import { AsyncLocalStorage } from "node:async_hooks";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
+//#region src/context.ts
+var requestContextStore = new AsyncLocalStorage();
+/**
+* Returns the verified JWT payload for the current MCP request.
+* Only available inside a tool handler when `auth` is configured on the router.
+*
+* Accepts an optional type parameter to avoid casting at call sites:
+* `getIdentity<{ sub: string; email: string }>()` returns `T | undefined`.
+* Omitting the type parameter keeps the return type as `unknown | undefined`.
+*/
+var getIdentity = () => {
+  return requestContextStore.getStore()?.identity;
+};
+
+//#endregion
+//#region src/createGatedToolRegistrar.ts
+var toolError = message => {
+  return {
+    content: [{
+      type: "text",
+      text: JSON.stringify({
+        error: message
+      })
+    }],
+    isError: true
+  };
+};
+/**
+* Factory that returns a `register` helper for MCP tools that require
+* authentication and a specific OAuth scope.
+*
+* Every registered tool automatically:
+* 1. Resolves the caller identity (default: `getIdentity()`). Returns an
+*    `isError` result when the identity is absent (unauthenticated request).
+* 2. Checks `requiredScope` — returns an `isError` result (not a throw) when
+*    the scope is absent, consistent with how MCP surfaces authorization errors.
+*    Scope semantics are intentionally simple (`Array.includes`). The package's
+*    `checkScopes` helper is not reused here because it throws rather than
+*    returning an `isError` result, and it reads identity from context itself.
+* 3. Runs any extra `gates` in order; a throwing gate rejects the call.
+*    Gates own their own error handling; `onError` covers the tool handler only.
+* 4. Merges `buildContext` output into the handler args.
+* 5. Wraps `null`/`undefined` results in a "Not found" error result.
+* 6. Calls `onError` on handler throw before rethrowing.
+*
+* @example
+* ```typescript
+* const { register } = createGatedToolRegistrar({
+*   server,
+*   resolveIdentity: () => {
+*     const jwt = getIdentity<{ sub: string; scopes: string[] }>();
+*     return { userId: jwt!.sub, scopes: jwt!.scopes };
+*   },
+* });
+*
+* register({
+*   name: 'list-campaigns',
+*   description: 'List all ad campaigns for the caller.',
+*   requiredScope: 'campaigns:read',
+*   inputSchema: { limit: z.number().optional() },
+*   method: async ({ userId, limit }) => fetchCampaigns(userId, limit),
+* });
+* ```
+*/
+var createGatedToolRegistrar = ({
+  server,
+  resolveIdentity = getIdentity,
+  gates = [],
+  onError,
+  buildContext
+}) => {
+  const register = def => {
+    server.registerTool(def.name, {
+      description: def.description,
+      inputSchema: def.inputSchema
+    }, async args => {
+      const identity = resolveIdentity();
+      if (!identity) return toolError("Unauthorized");
+      if (!(Array.isArray(identity.scopes) ? identity.scopes : []).includes(def.requiredScope)) return toolError(`This tool requires the "${def.requiredScope}" scope.`);
+      for (const gate of gates) await gate(identity);
+      const extra = buildContext ? buildContext(identity) : {};
+      try {
+        const result = await def.method({
+          ...args,
+          ...extra
+        });
+        if (result == null) return toolError("Not found");
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify(result)
+          }]
+        };
+      } catch (error) {
+        if (onError) await onError(error, {
+          handler: def.name,
+          identity
+        });
+        throw error;
+      }
+    });
+  };
+  return {
+    register
+  };
+};
+
+//#endregion
 //#region src/index.ts
 /** MCP lifecycle/discovery methods reachable before a client authenticates. */
 var DEFAULT_PUBLIC_METHODS = ["initialize", "tools/list"];
@@ -24,7 +132,6 @@ var buildVerifyToken = auth => {
   if (auth.verifyToken) return auth.verifyToken;
   throw new Error("McpAuthOptions requires either cognitoUserPool or verifyToken");
 };
-var requestContextStore = new AsyncLocalStorage();
 /**
 * Generic HTTP helper for use inside MCP tool handlers.
 *
@@ -112,17 +219,6 @@ var apiCall = async (method, url, options) => {
   return response.text();
 };
 /**
-* Returns the verified JWT payload for the current MCP request.
-* Only available inside a tool handler when `auth` is configured on the router.
-*
-* Accepts an optional type parameter to avoid casting at call sites:
-* `getIdentity<{ sub: string; email: string }>()` returns `T | undefined`.
-* Omitting the type parameter keeps the return type as `unknown | undefined`.
-*/
-var getIdentity = () => {
-  return requestContextStore.getStore()?.identity;
-};
-/**
 * Asserts that the current request's token contains all required scopes.
 * Throws if any scope is missing — the MCP SDK catches this and returns a
 * tool error to the client. Use inside tool handlers for per-tool authorization.
@@ -403,4 +499,4 @@ var registerToolFromSchema = (server, params) => {
 };
 
 //#endregion
-export { McpServer, apiCall, checkScopes, createMcpRouter, getIdentity, registerToolFromSchema, z };
+export { McpServer, apiCall, checkScopes, createGatedToolRegistrar, createMcpRouter, getIdentity, registerToolFromSchema, z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttoss/http-server-mcp",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Model Context Protocol (MCP) server integration for @ttoss/http-server",
   "keywords": [
     "ai",
@@ -35,9 +35,9 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.4.3",
-    "@ttoss/auth-core": "^0.8.0",
-    "@ttoss/http-server-auth": "^0.3.5",
-    "@ttoss/http-server": "^0.7.1"
+    "@ttoss/auth-core": "^0.10.0",
+    "@ttoss/http-server": "^0.7.1",
+    "@ttoss/http-server-auth": "^0.3.7"
   },
   "devDependencies": {
     "@types/koa": "^3.0.3",