@ttoss/http-server-mcp 0.19.1 → 0.21.0

package/README.md

@@ -366,6 +366,74 @@ 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 global `gates` then per-tool `def.gates` in order; a throwing gate rejects the call. Both receive `ToolCallContext` (identity **and** the validated call args).
+4. Merges `buildContext` output into the handler args.
+5. Wraps `null`/`undefined` results in a configurable "Not found" error result.
+6. Calls `onError` on handler throw before rethrowing, for telemetry. Gate/scope failures do **not** trigger `onError`.
+
+```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: ({ identity }) => ({ tenantId: lookupTenant(identity.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`** (global and per-tool) are async functions that receive a `ToolCallContext` — both the resolved identity and the validated call args — and throw to reject. The full context lets gates vary their predicate based on what the caller is asking for, not just who they are.
+
+```typescript
+register({
+  name: 'activate-ad-account',
+  description: 'Activate or deactivate an ad account.',
+  requiredScope: 'accounts:write',
+  inputSchema: { accountId: z.number(), isActive: z.boolean() },
+  // arg-conditional gate: activating requires more checks than deactivating
+  gates: [
+    ({ args }) =>
+      args.isActive
+        ? checkSubscriptionGates(['mustNotExceedMaxActive', 'mustHaveBudget'])
+        : checkSubscriptionGates(['mustIncludeService']),
+  ],
+  method: async ({ userId, accountId, isActive }) =>
+    toggleAdAccount(userId, accountId, isActive),
+});
+```
+
+**`buildContext`** injects request-scoped values (DB clients, tenant IDs) into every handler call without threading them through each individual tool. It receives the full `ToolCallContext` so context can vary by identity or by call args.
+
 ## 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 +514,37 @@ 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<(ctx: ToolCallContext) => void | Promise<void>>`, optional) — Global guards run after the scope check, in order, before any per-tool gates. Each receives `{ identity, args, handler }`. Throw to reject the call.
+- `enforceScope` (`boolean`, optional, default `true`) — When `true`, checks `def.requiredScope` against `identity.scopes` and returns an `isError` result on mismatch. Set to `false` when all authorization is handled by `gates`.
+- `buildContext` (`(ctx: ToolCallContext) => Record<string, unknown>`, optional) — Produces extra key-value pairs merged into every handler's args. Receives the full `ToolCallContext` so context can vary by identity or by call args.
+- `onError` (`(error, ctx: ToolCallContext) => void | Promise<void>`, optional) — Called when the handler throws, before the error is rethrown. Gate/scope failures do **not** trigger this hook.
+- `notFoundMessage` (`string`, optional, default `"Not found"`) — `isError` message returned when the handler resolves to `null`/`undefined`.
+
+**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`.
+- `gates` (`Array<(ctx: ToolCallContext) => void | Promise<void>>`, optional) — Per-tool guards appended after the global `gates`. Receive the full `ToolCallContext` enabling arg-conditional authorization.
+- `method` — Async handler. Receives merged call args + `buildContext` output.
+
+**`ToolCallContext`** is the object passed to gates, `buildContext`, and `onError`:
+
+- `identity` (`ToolIdentity`) — The resolved caller identity (`{ userId, scopes? }`).
+- `args` (`Record<string, unknown>`) — The validated tool input (post SDK parse).
+- `handler` (`string`) — The tool name, for error attribution.
+
 ### `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,145 @@
 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. When `enforceScope` is `true` (default), checks `requiredScope` — returns
+*    an `isError` result when the scope is absent, consistent with how MCP
+*    surfaces authorization errors. 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 global `gates` then per-`register` `def.gates` in order; a throwing
+*    gate rejects the call. Every gate receives the full {@link ToolCallContext}
+*    (identity **and** the validated call args), enabling arg-conditional gates.
+*    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 configurable "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: 'activate-campaign',
+*   description: 'Activate or deactivate a campaign.',
+*   requiredScope: 'campaigns:write',
+*   inputSchema: { isActive: z.boolean() },
+*   // arg-conditional gate: active vs. inactive have different restrictions
+*   gates: [
+*     ({ args }) =>
+*       args.isActive
+*         ? subscriptionGate(['mustNotExceedMaxActive', 'mustHaveBudget'])
+*         : subscriptionGate(['mustIncludeService']),
+*   ],
+*   method: async ({ userId, isActive }) => toggleCampaign(userId, isActive),
+* });
+* ```
+*/
+var checkScope = (identity, requiredScope) => {
+  if (!(Array.isArray(identity.scopes) ? identity.scopes : []).includes(requiredScope)) return toolError(`This tool requires the "${requiredScope}" scope.`);
+  return null;
+};
+var runGates = async (allGates, ctx) => {
+  for (const gate of allGates) await gate(ctx);
+};
+var createGatedToolRegistrar = ({
+  server,
+  resolveIdentity = getIdentity,
+  gates = [],
+  enforceScope = true,
+  onError,
+  buildContext,
+  notFoundMessage = "Not found"
+}) => {
+  const register = def => {
+    server.registerTool(def.name, {
+      description: def.description,
+      inputSchema: def.inputSchema
+    }, async args => {
+      const identity = resolveIdentity();
+      if (!identity) return toolError("Unauthorized");
+      const ctx = {
+        identity,
+        args,
+        handler: def.name
+      };
+      if (enforceScope) {
+        const scopeError = checkScope(identity, def.requiredScope);
+        if (scopeError) return scopeError;
+      }
+      await runGates([...gates, ...(def.gates ?? [])], ctx);
+      const extra = buildContext ? buildContext(ctx) : {};
+      try {
+        const result = await def.method({
+          ...args,
+          ...extra
+        });
+        if (result == null) return toolError(notFoundMessage);
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify(result)
+          }]
+        };
+      } catch (error) {
+        if (onError) await onError(error, ctx);
+        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 +158,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 +245,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 +533,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,106 @@ 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[];
+};
+/**
+ * Full context passed to gates, `buildContext`, and `onError` on every tool
+ * invocation. Having all three fields in one object means gate callbacks can
+ * be both identity-aware and args-aware without multiple parameters.
+ */
+type ToolCallContext = {
+  /** The resolved caller identity. */identity: ToolIdentity;
+  /**
+   * The validated tool input (post SDK parse). Present for gates and
+   * `buildContext`. Arg-conditional gates read this to vary their predicate
+   * per call.
+   */
+  args: Record<string, unknown>; /** Tool name, for error attribution and gate labelling. */
+  handler: 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;
+  /**
+   * Per-tool gates merged after the global `gates`. Useful for arg-conditional
+   * authorization (e.g. different subscription tiers based on call args).
+   * Each gate receives the full {@link ToolCallContext} (identity + args).
+   * Throw to reject the call; return (or resolve) to continue.
+   */
+  gates?: Array<(ctx: ToolCallContext) => void | Promise<void>>; /** 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;
+  /**
+   * Global authorization gates run after the scope check, in order, before
+   * per-tool gates. Each receives the full {@link ToolCallContext} — both
+   * identity and the validated call args — so gate predicates may be
+   * conditional on either.
+   * Throw to reject the call; return (or resolve) to continue.
+   * Gates own their own error handling — `onError` covers the tool handler only.
+   */
+  gates?: Array<(ctx: ToolCallContext) => void | Promise<void>>;
+  /**
+   * When `true` (default), checks `def.requiredScope` against `identity.scopes`
+   * and returns an `isError` result when the scope is absent. Set to `false`
+   * to skip the scope check (e.g. when all scopes are enforced by `gates`).
+   */
+  enforceScope?: boolean;
+  /**
+   * 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: ToolCallContext) => void | Promise<void>;
+  /**
+   * Called once per invocation to produce extra key-value pairs that are
+   * merged into the handler args. Receives the full {@link ToolCallContext}
+   * so context can vary by identity or by call args.
+   */
+  buildContext?: (ctx: ToolCallContext) => Record<string, unknown>;
+  /**
+   * Message returned as an `isError` result when the handler resolves to
+   * `null` or `undefined`. Defaults to `"Not found"`.
+   */
+  notFoundMessage?: string;
+};
+declare const createGatedToolRegistrar: ({
+  server,
+  resolveIdentity,
+  gates,
+  enforceScope,
+  onError,
+  buildContext,
+  notFoundMessage
+}: 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 +887,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 +1116,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 ToolCallContext, 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,106 @@ 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[];
+};
+/**
+ * Full context passed to gates, `buildContext`, and `onError` on every tool
+ * invocation. Having all three fields in one object means gate callbacks can
+ * be both identity-aware and args-aware without multiple parameters.
+ */
+type ToolCallContext = {
+  /** The resolved caller identity. */identity: ToolIdentity;
+  /**
+   * The validated tool input (post SDK parse). Present for gates and
+   * `buildContext`. Arg-conditional gates read this to vary their predicate
+   * per call.
+   */
+  args: Record<string, unknown>; /** Tool name, for error attribution and gate labelling. */
+  handler: 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;
+  /**
+   * Per-tool gates merged after the global `gates`. Useful for arg-conditional
+   * authorization (e.g. different subscription tiers based on call args).
+   * Each gate receives the full {@link ToolCallContext} (identity + args).
+   * Throw to reject the call; return (or resolve) to continue.
+   */
+  gates?: Array<(ctx: ToolCallContext) => void | Promise<void>>; /** 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;
+  /**
+   * Global authorization gates run after the scope check, in order, before
+   * per-tool gates. Each receives the full {@link ToolCallContext} — both
+   * identity and the validated call args — so gate predicates may be
+   * conditional on either.
+   * Throw to reject the call; return (or resolve) to continue.
+   * Gates own their own error handling — `onError` covers the tool handler only.
+   */
+  gates?: Array<(ctx: ToolCallContext) => void | Promise<void>>;
+  /**
+   * When `true` (default), checks `def.requiredScope` against `identity.scopes`
+   * and returns an `isError` result when the scope is absent. Set to `false`
+   * to skip the scope check (e.g. when all scopes are enforced by `gates`).
+   */
+  enforceScope?: boolean;
+  /**
+   * 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: ToolCallContext) => void | Promise<void>;
+  /**
+   * Called once per invocation to produce extra key-value pairs that are
+   * merged into the handler args. Receives the full {@link ToolCallContext}
+   * so context can vary by identity or by call args.
+   */
+  buildContext?: (ctx: ToolCallContext) => Record<string, unknown>;
+  /**
+   * Message returned as an `isError` result when the handler resolves to
+   * `null` or `undefined`. Defaults to `"Not found"`.
+   */
+  notFoundMessage?: string;
+};
+declare const createGatedToolRegistrar: ({
+  server,
+  resolveIdentity,
+  gates,
+  enforceScope,
+  onError,
+  buildContext,
+  notFoundMessage
+}: 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 +888,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 +1117,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 ToolCallContext, type ToolIdentity, apiCall, checkScopes, createGatedToolRegistrar, createMcpRouter, getIdentity, registerToolFromSchema, z };

package/dist/index.mjs

@@ -1,12 +1,143 @@
 /** 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. When `enforceScope` is `true` (default), checks `requiredScope` — returns
+*    an `isError` result when the scope is absent, consistent with how MCP
+*    surfaces authorization errors. 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 global `gates` then per-`register` `def.gates` in order; a throwing
+*    gate rejects the call. Every gate receives the full {@link ToolCallContext}
+*    (identity **and** the validated call args), enabling arg-conditional gates.
+*    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 configurable "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: 'activate-campaign',
+*   description: 'Activate or deactivate a campaign.',
+*   requiredScope: 'campaigns:write',
+*   inputSchema: { isActive: z.boolean() },
+*   // arg-conditional gate: active vs. inactive have different restrictions
+*   gates: [
+*     ({ args }) =>
+*       args.isActive
+*         ? subscriptionGate(['mustNotExceedMaxActive', 'mustHaveBudget'])
+*         : subscriptionGate(['mustIncludeService']),
+*   ],
+*   method: async ({ userId, isActive }) => toggleCampaign(userId, isActive),
+* });
+* ```
+*/
+var checkScope = (identity, requiredScope) => {
+  if (!(Array.isArray(identity.scopes) ? identity.scopes : []).includes(requiredScope)) return toolError(`This tool requires the "${requiredScope}" scope.`);
+  return null;
+};
+var runGates = async (allGates, ctx) => {
+  for (const gate of allGates) await gate(ctx);
+};
+var createGatedToolRegistrar = ({
+  server,
+  resolveIdentity = getIdentity,
+  gates = [],
+  enforceScope = true,
+  onError,
+  buildContext,
+  notFoundMessage = "Not found"
+}) => {
+  const register = def => {
+    server.registerTool(def.name, {
+      description: def.description,
+      inputSchema: def.inputSchema
+    }, async args => {
+      const identity = resolveIdentity();
+      if (!identity) return toolError("Unauthorized");
+      const ctx = {
+        identity,
+        args,
+        handler: def.name
+      };
+      if (enforceScope) {
+        const scopeError = checkScope(identity, def.requiredScope);
+        if (scopeError) return scopeError;
+      }
+      await runGates([...gates, ...(def.gates ?? [])], ctx);
+      const extra = buildContext ? buildContext(ctx) : {};
+      try {
+        const result = await def.method({
+          ...args,
+          ...extra
+        });
+        if (result == null) return toolError(notFoundMessage);
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify(result)
+          }]
+        };
+      } catch (error) {
+        if (onError) await onError(error, ctx);
+        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 +155,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 +242,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 +522,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.1",
+  "version": "0.21.0",
   "description": "Model Context Protocol (MCP) server integration for @ttoss/http-server",
   "keywords": [
     "ai",
@@ -36,8 +36,8 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.4.3",
     "@ttoss/http-server": "^0.7.1",
-    "@ttoss/http-server-auth": "^0.3.6",
-    "@ttoss/auth-core": "^0.9.0"
+    "@ttoss/auth-core": "^0.10.0",
+    "@ttoss/http-server-auth": "^0.3.7"
   },
   "devDependencies": {
     "@types/koa": "^3.0.3",