@ttoss/http-server-mcp 0.33.2 → 0.34.1

package/dist/index.mjs

@@ -37,7 +37,7 @@ var getApiHeaders = () => {
 /**
 * The `Accept-Language` header of the current MCP request, or `undefined`
 * outside a request or when the client sent none. The default locale source
-* for `createGatedToolRegistrar`'s `i18n` option.
+* for `createToolGate`'s `i18n` option.
 */
 var getRequestLocale = () => {
   return requestContextStore.getStore()?.acceptLanguage;
@@ -364,24 +364,33 @@ var registerAppResource = ({
 };
 
 //#endregion
-//#region src/registerToolFromSchema.ts
+//#region src/tool.ts
+var EMPTY_OBJECT_SCHEMA = {
+  type: "object",
+  properties: {}
+};
+/** The JSON Schema dialect the MCP SDK converts Standard Schemas to. */
+var JSON_SCHEMA_TARGET = "draft-2020-12";
+var isStandardSchema = schema => {
+  return "~standard" in schema;
+};
 /**
-* Converts a plain JSON Schema into the Standard Schema `registerTool` accepts.
+* Converts a JSON Schema into the Standard Schema `registerTool` accepts.
 *
 * A Standard Schema keeps advertisement and enforcement in separate fields:
 * `~standard.jsonSchema` is what `tools/list` publishes, `~standard.validate`
 * is what `tools/call` runs. Replacing only `validate` therefore keeps the
 * schema fully visible to clients while leaving arguments unchecked.
 */
-var toStandardSchema = ({
-  inputSchema,
-  validateArguments
+var fromJsonObjectSchema = ({
+  schema,
+  validate
 }) => {
-  const schema = fromJsonSchema(inputSchema);
-  if (validateArguments) return schema;
+  const standard = fromJsonSchema(schema);
+  if (validate) return standard;
   return {
     "~standard": {
-      ...schema["~standard"],
+      ...standard["~standard"],
       validate: value => {
         return {
           value
@@ -390,71 +399,53 @@ var toStandardSchema = ({
     }
   };
 };
+var resolved = /* @__PURE__ */new WeakMap();
 /**
-* Registers a tool on an MCP server using a **plain JSON Schema** object for
-* `inputSchema` instead of a Zod shape.
-*
-* This is useful when tool definitions are shared between the MCP server and
-* an AI SDK agent (e.g. Vercel AI SDK's `tool()` helper), because both consume
-* a plain JSON Schema at runtime. Using this helper eliminates the lossy
-* JSON-Schema→Zod conversion that would otherwise be required.
-*
-* Thin wrapper over `@modelcontextprotocol/server`'s `fromJsonSchema`, which
-* converts a JSON Schema into a Standard Schema that `registerTool` accepts
-* directly, so the schema round-trips verbatim over `tools/list`. Arguments
-* reach the handler unchecked unless `validateArguments` is enabled.
-*
-* @param server - The `McpServer` instance to register the tool on.
-* @param params - Tool configuration including name, description, inputSchema,
-*   validateArguments, `_meta`, and handler.
-*
-* @example
-* ```typescript
-* import { registerToolFromSchema, McpServer } from '@ttoss/http-server-mcp';
-*
-* const server = new McpServer({ name: 'my-server', version: '1.0.0' });
-*
-* registerToolFromSchema(server, {
-*   name: 'get-project',
-*   description: 'Get a project by ID',
-*   inputSchema: {
-*     type: 'object',
-*     properties: { id: { type: 'string', description: 'Project public ID' } },
-*     required: ['id'],
-*   },
-*   handler: async ({ id }) => ({
-*     content: [{ type: 'text', text: `Project: ${id}` }],
-*   }),
-* });
-* ```
+* Resolves a tool's schemas once, so the direct registration and a deferred
+* `call` enforce exactly the same thing.
 */
-var registerToolFromSchema = (server, params) => {
-  const {
-    name,
-    description,
-    inputSchema = {
-      type: "object",
-      properties: {}
-    },
-    validateArguments = false,
-    handler,
-    _meta
-  } = params;
-  server.registerTool(name, {
-    description,
-    inputSchema: toStandardSchema({
-      inputSchema,
-      validateArguments
+var resolveToolSchemas = tool => {
+  const cached = resolved.get(tool);
+  if (cached) return cached;
+  const inputSchema = tool.inputSchema ?? EMPTY_OBJECT_SCHEMA;
+  const result = {
+    input: isStandardSchema(inputSchema) ? inputSchema : fromJsonObjectSchema({
+      schema: inputSchema,
+      validate: tool.validateArguments ?? false
     }),
-    _meta
+    inputJson: isStandardSchema(inputSchema) ? inputSchema["~standard"].jsonSchema.input({
+      target: JSON_SCHEMA_TARGET
+    }) : inputSchema,
+    output: tool.outputSchema === void 0 || isStandardSchema(tool.outputSchema) ? tool.outputSchema : fromJsonObjectSchema({
+      schema: tool.outputSchema,
+      validate: true
+    })
+  };
+  resolved.set(tool, result);
+  return result;
+};
+/** Registers one tool as one MCP tool. */
+var registerDirectTool = ({
+  server,
+  tool
+}) => {
+  const schemas = resolveToolSchemas(tool);
+  server.registerTool(tool.name, {
+    title: tool.title,
+    description: tool.description,
+    inputSchema: schemas.input,
+    outputSchema: schemas.output,
+    annotations: tool.annotations,
+    _meta: tool._meta
   }, async args => {
-    return handler(args);
+    return tool.handler(args);
   });
 };
-
-//#endregion
-//#region src/createGatedToolRegistrar.ts
-var toolError = (message, code) => {
+/** An `isError` result whose text is `{ error, code? }` as JSON. */
+var toolError = ({
+  message,
+  code
+}) => {
   return {
     content: [{
       type: "text",
@@ -469,6 +460,591 @@ var toolError = (message, code) => {
   };
 };
 /**
+* Builds a {@link Tool} from a `method` that returns data instead of a
+* `CallToolResult`, which is what most hand-written tools want.
+*
+* @example
+* ```typescript
+* const getCampaign = defineTool({
+*   name: 'get-campaign',
+*   description: 'Get a campaign by id.',
+*   inputSchema: z.object({ campaignId: z.string() }),
+*   method: ({ campaignId }) => findCampaign(campaignId as string),
+*   notFoundMessage: 'Campaign not found',
+* });
+* ```
+*/
+var defineTool = ({
+  method,
+  notFoundMessage = "Not found",
+  ...tool
+}) => {
+  return {
+    ...tool,
+    handler: async args => {
+      const result = await method(args);
+      if (result == null) return toolError({
+        message: notFoundMessage
+      });
+      const content = [{
+        type: "text",
+        text: JSON.stringify(result)
+      }];
+      return tool.outputSchema === void 0 ? {
+        content
+      } : {
+        content,
+        structuredContent: result
+      };
+    }
+  };
+};
+
+//#endregion
+//#region src/toolSearch.ts
+var SUMMARY_MAX_LENGTH = 160;
+var SUGGESTION_COUNT = 3;
+var MIN_RELATED_SCORE = 1;
+/** Plural and singular forms rank alike: `agents` finds `get-agent`. */
+var stem = term => {
+  if (term.length > 4 && term.endsWith("ies")) return `${term.slice(0, -3)}y`;
+  if (term.length > 3 && term.endsWith("s") && !term.endsWith("ss")) return term.slice(0, -1);
+  return term;
+};
+/** Splits kebab-case, snake_case, camelCase and prose into lowercase terms. */
+var termsOf = text => {
+  return text.replace(/([\p{Ll}\p{N}])(\p{Lu})/gu, "$1 $2").toLowerCase().split(/[^\p{L}\p{N}]+/u).filter(term => {
+    return term.length > 0;
+  }).map(stem);
+};
+/** The fields a query term is matched against, most telling first. */
+var FIELDS = [{
+  weight: 4,
+  text: tool => {
+    return tool.name;
+  }
+}, {
+  weight: 3,
+  text: tool => {
+    return tool.summary ?? "";
+  }
+}, {
+  weight: 2,
+  text: tool => {
+    return (tool.tags ?? []).join(" ");
+  }
+}, {
+  weight: 1,
+  text: tool => {
+    return tool.description;
+  }
+}];
+var fieldTerms = /* @__PURE__ */new WeakMap();
+var termsByField = tool => {
+  const cached = fieldTerms.get(tool);
+  if (cached) return cached;
+  const terms = FIELDS.map(field => {
+    return new Set(termsOf(field.text(tool)));
+  });
+  fieldTerms.set(tool, terms);
+  return terms;
+};
+/**
+* A term scores the weight of the best field holding it, half that when it
+* is only a prefix of a word there (`proj` → `project`).
+*/
+var scoreOf = ({
+  tool,
+  terms
+}) => {
+  const fields = termsByField(tool);
+  let score = 0;
+  for (const term of terms) {
+    let best = 0;
+    for (const [index, words] of fields.entries()) {
+      const weight = FIELDS[index].weight;
+      if (words.has(term)) best = Math.max(best, weight);else if (term.length >= 3 && [...words].some(word => {
+        return word.startsWith(term);
+      })) best = Math.max(best, weight / 2);
+    }
+    score += best;
+  }
+  return score;
+};
+var withTag = ({
+  tag,
+  tools
+}) => {
+  return tag === void 0 ? tools : tools.filter(tool => {
+    return tool.tags?.includes(tag) ?? false;
+  });
+};
+/**
+* The tools `query` matches, best first, ties in the tools' order; `undefined`
+* when the query has no words.
+*/
+var scoreTools = ({
+  query,
+  tag,
+  tools
+}) => {
+  const terms = [...new Set(termsOf(query))];
+  if (terms.length === 0) return void 0;
+  return withTag({
+    tag,
+    tools
+  }).map((tool, index) => {
+    return {
+      tool,
+      index,
+      score: scoreOf({
+        tool,
+        terms
+      })
+    };
+  }).filter(({
+    score
+  }) => {
+    return score > 0;
+  }).sort((a, b) => {
+    return b.score - a.score || a.index - b.index;
+  });
+};
+/**
+* The deferred tools' default search: scores each tool by the query's terms,
+* weighted name > summary > tags > description, and breaks ties by the
+* tools' order. No index — a few hundred tools need none.
+*/
+var rankTools = ({
+  query,
+  tag,
+  limit,
+  tools
+}) => {
+  const scored = scoreTools({
+    query,
+    tag,
+    tools
+  });
+  if (!scored) return withTag({
+    tag,
+    tools
+  }).slice(0, limit);
+  return scored.slice(0, limit).map(({
+    tool
+  }) => {
+    return tool;
+  });
+};
+var summaryOf = tool => {
+  const [line] = (tool.summary ?? tool.description).trim().split("\n", 1);
+  return line.length > SUMMARY_MAX_LENGTH ? `${line.slice(0, SUMMARY_MAX_LENGTH - 1).trimEnd()}…` : line;
+};
+var editDistance = (a, b) => {
+  const row = Array.from({
+    length: b.length + 1
+  }, (_, index) => {
+    return index;
+  });
+  for (let i = 1; i <= a.length; i++) {
+    let diagonal = row[0];
+    row[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const above = row[j];
+      row[j] = Math.min(row[j] + 1, row[j - 1] + 1, diagonal + (a[i - 1] === b[j - 1] ? 0 : 1));
+      diagonal = above;
+    }
+  }
+  return row[b.length];
+};
+/** Names a model probably meant: near-misses first, then related tools. */
+var suggestionsFor = ({
+  name,
+  tools
+}) => {
+  const tolerance = Math.max(2, Math.floor(name.length / 3));
+  const nearMisses = tools.map(tool => {
+    return {
+      name: tool.name,
+      distance: editDistance(name, tool.name)
+    };
+  }).filter(({
+    distance
+  }) => {
+    return distance <= tolerance;
+  }).sort((a, b) => {
+    return a.distance - b.distance;
+  }).map(candidate => {
+    return candidate.name;
+  });
+  const related = (scoreTools({
+    query: name,
+    tools
+  }) ?? []).filter(({
+    score
+  }) => {
+    return score >= MIN_RELATED_SCORE;
+  }).slice(0, SUGGESTION_COUNT).map(({
+    tool
+  }) => {
+    return tool.name;
+  });
+  return [...new Set([...nearMisses, ...related])].slice(0, SUGGESTION_COUNT);
+};
+
+//#endregion
+//#region src/deferTools.ts
+var DEFAULT_SEARCH_LIMIT = 10;
+var DEFAULT_SEARCH_MAX_LIMIT = 50;
+var jsonResult = ({
+  data,
+  isError = false
+}) => {
+  return {
+    content: [{
+      type: "text",
+      text: JSON.stringify(data)
+    }],
+    structuredContent: data,
+    ...(isError ? {
+      isError: true
+    } : {})
+  };
+};
+var errorMessageOf = error => {
+  return error instanceof Error ? error.message : String(error);
+};
+var formatIssue = issue => {
+  const path = (issue.path ?? []).map(segment => {
+    return String(typeof segment === "object" ? segment.key : segment);
+  }).join(".");
+  return path ? `${path}: ${issue.message}` : issue.message;
+};
+var linksAppView = ({
+  tool
+}) => {
+  const ui = tool._meta?.ui;
+  return typeof ui === "object" && ui !== null && "resourceUri" in ui || tool._meta?.["ui/resourceUri"] !== void 0;
+};
+var deferredToolsOf = ({
+  tools,
+  options
+}) => {
+  const byName = /* @__PURE__ */new Map();
+  for (const tool of tools) {
+    if (byName.has(tool.name)) throw new Error(`Two tools are named "${tool.name}".`);
+    byName.set(tool.name, tool);
+  }
+  const isVisible = tool => {
+    return options.visible ? options.visible({
+      tool
+    }) : true;
+  };
+  const searchLimit = options.searchLimit ?? DEFAULT_SEARCH_LIMIT;
+  return {
+    names: {
+      search: "search",
+      describe: "describe",
+      call: "call",
+      ...options.names
+    },
+    tools,
+    searchLimit,
+    searchMaxLimit: options.searchMaxLimit ?? Math.max(DEFAULT_SEARCH_MAX_LIMIT, searchLimit),
+    searchTools: options.search ?? rankTools,
+    visibleTools: () => {
+      return tools.filter(isVisible);
+    },
+    find: name => {
+      const tool = byName.get(name);
+      return tool && isVisible(tool) ? tool : void 0;
+    }
+  };
+};
+var searchToolOf = ({
+  names,
+  tools,
+  searchLimit,
+  searchMaxLimit,
+  searchTools,
+  visibleTools
+}) => {
+  const tags = [...new Set(tools.flatMap(tool => {
+    return tool.tags ?? [];
+  }))].sort();
+  return {
+    name: names.search,
+    description: `Find tools by keyword among the ${tools.length} this server offers. Returns each match's name and summary; get input schemas with "${names.describe}", then run one with "${names.call}".` + (tags.length > 0 ? ` Tags: ${tags.join(", ")}.` : ""),
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: "Words describing the action, e.g. \"create agent\". Empty lists the tools in order."
+        },
+        tag: {
+          type: "string",
+          description: "Only tools with this tag.",
+          ...(tags.length > 0 ? {
+            enum: tags
+          } : {})
+        },
+        limit: {
+          type: "integer",
+          minimum: 1,
+          maximum: searchMaxLimit,
+          description: `Maximum number of results. Defaults to ${searchLimit}.`
+        }
+      },
+      required: ["query"]
+    },
+    validateArguments: true,
+    annotations: {
+      readOnlyHint: true
+    },
+    handler: async args => {
+      const limit = args.limit ?? searchLimit;
+      return jsonResult({
+        data: {
+          tools: (await searchTools({
+            query: args.query,
+            tag: args.tag,
+            limit,
+            tools: visibleTools()
+          })).slice(0, limit).map(tool => {
+            return {
+              name: tool.name,
+              summary: summaryOf(tool),
+              ...(tool.tags ? {
+                tags: tool.tags
+              } : {})
+            };
+          })
+        }
+      });
+    }
+  };
+};
+var describeToolOf = ({
+  names,
+  find,
+  visibleTools
+}) => {
+  return {
+    name: names.describe,
+    description: `Get the full definition of tools found with "${names.search}", including the input schema "${names.call}" expects.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        names: {
+          type: "array",
+          items: {
+            type: "string"
+          },
+          minItems: 1,
+          description: "Tool names, as search returned them."
+        }
+      },
+      required: ["names"]
+    },
+    validateArguments: true,
+    annotations: {
+      readOnlyHint: true
+    },
+    handler: args => {
+      const described = [];
+      const unknown = [];
+      for (const name of args.names) {
+        const tool = find(name);
+        if (!tool) {
+          unknown.push({
+            name,
+            suggestions: suggestionsFor({
+              name,
+              tools: visibleTools()
+            })
+          });
+          continue;
+        }
+        described.push({
+          name: tool.name,
+          ...(tool.title ? {
+            title: tool.title
+          } : {}),
+          description: tool.description,
+          inputSchema: resolveToolSchemas(tool).inputJson,
+          ...(tool.annotations ? {
+            annotations: tool.annotations
+          } : {})
+        });
+      }
+      return jsonResult({
+        data: {
+          tools: described,
+          ...(unknown.length > 0 ? {
+            unknown
+          } : {})
+        },
+        isError: described.length === 0
+      });
+    }
+  };
+};
+/** Runs one tool the way a direct call would, with errors that help a retry. */
+var runTool = async ({
+  tool,
+  args
+}) => {
+  const schemas = resolveToolSchemas(tool);
+  const validated = await schemas.input["~standard"].validate(args);
+  if (validated.issues) return jsonResult({
+    data: {
+      error: `Invalid arguments for "${tool.name}".`,
+      issues: validated.issues.map(formatIssue),
+      inputSchema: schemas.inputJson
+    },
+    isError: true
+  });
+  const schemaHint = {
+    type: "text",
+    text: JSON.stringify({
+      inputSchema: schemas.inputJson
+    })
+  };
+  try {
+    const result = await tool.handler(validated.value);
+    return result.isError ? {
+      ...result,
+      content: [...result.content, schemaHint]
+    } : result;
+  } catch (error) {
+    return {
+      content: [{
+        type: "text",
+        text: errorMessageOf(error)
+      }, schemaHint],
+      isError: true
+    };
+  }
+};
+var callToolOf = ({
+  names,
+  find,
+  visibleTools
+}) => {
+  return {
+    name: names.call,
+    description: `Run a tool found with "${names.search}". Pass its arguments as "${names.describe}" defined them.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: {
+          type: "string",
+          description: "The tool to run."
+        },
+        arguments: {
+          type: "object",
+          description: "The tool's arguments, matching its input schema."
+        }
+      },
+      required: ["name"]
+    },
+    validateArguments: true,
+    handler: args => {
+      const name = args.name;
+      const tool = find(name);
+      if (!tool) return jsonResult({
+        data: {
+          error: `Unknown tool "${name}".`,
+          suggestions: suggestionsFor({
+            name,
+            tools: visibleTools()
+          })
+        },
+        isError: true
+      });
+      return runTool({
+        tool,
+        args: args.arguments ?? {}
+      });
+    }
+  };
+};
+/**
+* Defers `tools` behind three tools — `search`, `describe`, `call` — so a
+* client's context holds three small definitions instead of every schema,
+* and a schema enters it only for the tools the model is about to use.
+*/
+var registerDeferredTools = ({
+  server,
+  tools,
+  ...options
+}) => {
+  const deferred = deferredToolsOf({
+    tools,
+    options
+  });
+  for (const tool of [searchToolOf(deferred), describeToolOf(deferred), callToolOf(deferred)]) registerDirectTool({
+    server,
+    tool
+  });
+  const except = options.except ?? linksAppView;
+  for (const tool of tools) if (except({
+    tool
+  })) registerDirectTool({
+    server,
+    tool
+  });
+};
+
+//#endregion
+//#region src/registerTools.ts
+/**
+* Registers tools on an MCP server, either one MCP tool each (the default)
+* or deferred behind `search` / `describe` / `call`. The same `tools` can feed
+* both, so two endpoints over one API cannot drift apart.
+*
+* @example
+* ```typescript
+* import { McpServer, registerTools, z } from '@ttoss/http-server-mcp';
+*
+* const tools = [
+*   {
+*     name: 'get-project',
+*     description: 'Get a project by ID',
+*     inputSchema: z.object({ id: z.string() }),
+*     handler: async ({ id }) => ({
+*       content: [{ type: 'text', text: `Project: ${id}` }],
+*     }),
+*   },
+* ];
+*
+* registerTools({ server: fullServer, tools });
+* registerTools({ server: deferredServer, tools, defer: true });
+* ```
+*/
+var registerTools = ({
+  server,
+  tools,
+  defer = false
+}) => {
+  if (defer === false) {
+    for (const tool of tools) registerDirectTool({
+      server,
+      tool
+    });
+    return;
+  }
+  registerDeferredTools({
+    server,
+    tools,
+    ...(defer === true ? {} : defer)
+  });
+};
+
+//#endregion
+//#region src/toolGate.ts
+/**
 * The localized `isError` result for `error`, or `undefined` when it is not
 * a `LocalizedError` or rendering fails — the caller then keeps its usual path.
 */
@@ -486,76 +1062,84 @@ var localizedToolError = async ({
       error,
       i18n: await i18n.catalog.getI18n(requested)
     });
-    return rendered ? toolError(rendered.message, rendered.code) : void 0;
+    return rendered ? toolError({
+      message: rendered.message,
+      code: rendered.code
+    }) : void 0;
   } catch {
     return;
   }
 };
 /**
-* Factory that returns a `register` helper for MCP tools that require
-* authentication and a specific OAuth scope.
+* 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.
+*/
+var hasScope = ({
+  identity,
+  requiredScope
+}) => {
+  return (Array.isArray(identity.scopes) ? identity.scopes : []).includes(requiredScope);
+};
+/**
+* Factory for a gate: a function that wraps a {@link Tool} so every call
+* passes the same authentication and authorization pipeline before its
+* handler runs. The gated tool is an ordinary `Tool`, so it registers
+* directly or joins a catalog like any other.
 *
-* Every registered tool automatically:
+* Every gated call:
 * 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.
+*    surfaces authorization errors.
+* 3. Runs global `gates` then the tool's `gates` in order; a throwing gate
+*    rejects the call. Every gate receives the full {@link ToolCallContext}.
 * 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.
-* 7. With `i18n`, renders a `LocalizedError` from a gate or the handler as an
+* 5. Calls `onError` on handler throw before rethrowing.
+* 6. With `i18n`, renders a `LocalizedError` from a gate or the handler as an
 *    `isError` result in the caller's locale instead of rethrowing it.
 *
 * @example
 * ```typescript
-* const { register } = createGatedToolRegistrar({
-*   server,
+* const gate = createToolGate({
 *   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']),
+* registerTools({
+*   server,
+*   tools: [
+*     gate({
+*       requiredScope: 'campaigns:write',
+*       // arg-conditional gate: active vs. inactive have different restrictions
+*       gates: [
+*         ({ args }) =>
+*           args.isActive
+*             ? subscriptionGate(['mustNotExceedMaxActive', 'mustHaveBudget'])
+*             : subscriptionGate(['mustIncludeService']),
+*       ],
+*       tool: defineTool({
+*         name: 'activate-campaign',
+*         description: 'Activate or deactivate a campaign.',
+*         inputSchema: z.object({ isActive: z.boolean() }),
+*         method: ({ userId, isActive }) => toggleCampaign(userId, isActive),
+*       }),
+*     }),
 *   ],
-*   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,
+var createToolGate = ({
   resolveIdentity = getIdentity,
   gates = [],
   enforceScope = true,
   onError,
   buildContext,
-  notFoundMessage = "Not found",
   i18n
-}) => {
+} = {}) => {
   const renderOrRethrow = async (error, ctx) => {
     const localized = i18n ? await localizedToolError({
       error,
@@ -565,60 +1149,46 @@ var createGatedToolRegistrar = ({
     if (localized) return localized;
     throw error;
   };
-  const runMethod = async (def, ctx) => {
-    const extra = buildContext ? buildContext(ctx) : {};
-    try {
-      const result = await def.method({
-        ...ctx.args,
-        ...extra
-      });
-      if (result == null) return toolError(notFoundMessage);
-      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);
-      return renderOrRethrow(error, ctx);
-    }
-  };
-  const register = def => {
-    const handler = 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;
-      }
-      try {
-        await runGates([...gates, ...(def.gates ?? [])], ctx);
-      } catch (error) {
-        return renderOrRethrow(error, ctx);
+  return ({
+    tool,
+    requiredScope,
+    gates: toolGates = []
+  }) => {
+    return {
+      ...tool,
+      handler: async args => {
+        const identity = resolveIdentity();
+        if (!identity) return toolError({
+          message: "Unauthorized"
+        });
+        const ctx = {
+          identity,
+          args,
+          handler: tool.name
+        };
+        if (enforceScope && !hasScope({
+          identity,
+          requiredScope
+        })) return toolError({
+          message: `This tool requires the "${requiredScope}" scope.`
+        });
+        try {
+          for (const gate of [...gates, ...toolGates]) await gate(ctx);
+        } catch (error) {
+          return renderOrRethrow(error, ctx);
+        }
+        const extra = buildContext ? buildContext(ctx) : {};
+        try {
+          return await tool.handler({
+            ...args,
+            ...extra
+          });
+        } catch (error) {
+          if (onError) await onError(error, ctx);
+          return renderOrRethrow(error, ctx);
+        }
       }
-      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);
-  };
-  return {
-    register
   };
 };
 
@@ -991,4 +1561,4 @@ var createMcpRouter = (server, options = {}) => {
 };
 
 //#endregion
-export { InMemoryServerEventBus, McpServer, UI_EXTENSION_ID, UI_RESOURCE_MIME_TYPE, apiCall, checkScopes, createGatedToolRegistrar, createMcpRouter, errorBodyMessage, getApiHeaders, getIdentity, getRequestLocale, registerAppResource, registerToolFromSchema, z };
+export { InMemoryServerEventBus, McpServer, UI_EXTENSION_ID, UI_RESOURCE_MIME_TYPE, apiCall, checkScopes, createMcpRouter, createToolGate, defineTool, errorBodyMessage, getApiHeaders, getIdentity, getRequestLocale, rankTools, registerAppResource, registerTools, z };