@miragon/mcp-toolkit-core 2.5.0 → 2.7.0

package/dist/tools/register-widget-tool.js

@@ -1,51 +1,48 @@
 import { z } from "zod";
 import { appsSdkMeta, viewResourceUri } from "../types/meta.js";
 import { withToolErrors } from "./with-tool-errors.js";
-/**
- * Registrar for widget tools against mcp-use's native view binding.
- *
- * Model-visible tools are bound to a view named after the tool
- * (`view: { name: <tool name> }`); mcp-use derives the MCP Apps wire keys
- * (`_meta.ui.resourceUri`, flat `ui/resourceUri`) from that binding, and the
- * registrar adds the Apps SDK `openai/*` keys pointing at the same resource
- * (`viewResourceUri(<tool name>)`). App-only tools carry the native
- * `visibility: "app"` and no view — their results feed an already-rendered
- * widget via `callTool`.
- *
- * `createFrameworkApp` collects every `view` binding registered this way and
- * primes the view registry with the shared app bundle, so each bound name
- * resolves to the same compiled widget code.
- */
-export function createWidgetToolRegistrar(server, client, metaDefaults) {
-    return function register(config) {
+import { registrarInputSchema, } from "./registrar-shared.js";
+export function createWidgetToolRegistrar(server, client, metaDefaults, options = {}) {
+    // Registration is independent of the OAuth user type, which only shapes
+    // the callback ctx; the ctx is handed on typed by the registrar instead.
+    const target = server;
+    function register(config) {
         const model = config.visibility === "model";
+        // Every registrar-owned key is set explicitly in both branches — undefined
+        // included — so a cast or plain-JS `definition` cannot smuggle one in.
         const definition = {
+            ...config.definition,
             name: config.name,
             title: config.title,
             description: config.description,
-            inputSchema: config.inputSchema ? z.object(config.inputSchema) : undefined,
+            inputSchema: registrarInputSchema(config.inputSchema, config.strictInput ?? options.strictInput ?? false),
+            // mcp-use's alias: it reads `inputSchema ?? schema`.
+            schema: undefined,
             annotations: config.annotations,
         };
-        const callback = withToolErrors(async (looseParams) => {
-            // The SDK validates params against the schema above, so the loose
-            // callback param is safely the handler's precise `ToolArgs<TShape>`.
-            const result = await config.handler(client, looseParams);
+        // The SDK validates params against the schema above before the callback
+        // runs; the public `register` is generic over that shape, this
+        // implementation sees the erased `ToolArgs`.
+        const callback = withToolErrors(async (params, ctx) => {
+            const result = await config.handler(client, params, ctx);
             return {
                 content: [{ type: "text", text: result.text }],
                 structuredContent: result.structuredContent,
             };
         });
         if (!model) {
-            server.tool({
+            return target.tool({
                 ...definition,
                 visibility: "app",
+                view: undefined,
                 outputSchema: config.outputSchema,
-                ...(config.meta ? { _meta: config.meta } : {}),
+                _meta: config.meta,
             }, callback);
-            return;
         }
-        server.tool({
+        return target.tool({
             ...definition,
+            // Host default: callable by the model (no `_meta.ui.visibility`).
+            visibility: undefined,
             view: {
                 name: config.name,
                 description: config.description,
@@ -67,6 +64,7 @@ export function createWidgetToolRegistrar(server, client, metaDefaults) {
                 }),
             },
         }, callback);
-    };
+    }
+    return register;
 }
 //# sourceMappingURL=register-widget-tool.js.map

package/dist/tools/register-widget-tool.js.map

@@ -1 +1 @@
-{"version":3,"file":"register-widget-tool.js","sourceRoot":"","sources":["../../src/tools/register-widget-tool.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAAE,WAAW,EAAE,eAAe,EAA+B,MAAM,kBAAkB,CAAA;AAC5F,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AA+DtD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,yBAAyB,CACvC,MAAiB,EACjB,MAAe,EACf,YAAqC;IAErC,OAAO,SAAS,QAAQ,CACtB,MAAyC;QAEzC,MAAM,KAAK,GAAG,MAAM,CAAC,UAAU,KAAK,OAAO,CAAA;QAC3C,MAAM,UAAU,GAAG;YACjB,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,WAAW,EAAE,MAAM,CAAC,WAAW;YAC/B,WAAW,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,SAAS;YAC1E,WAAW,EAAE,MAAM,CAAC,WAAW;SAChC,CAAA;QAED,MAAM,QAAQ,GAAG,cAAc,CAAC,KAAK,EAAE,WAA0B,EAAE,EAAE;YACnE,kEAAkE;YAClE,qEAAqE;YACrE,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,WAA+B,CAAC,CAAA;YAC5E,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC;gBACvD,iBAAiB,EAAE,MAAM,CAAC,iBAAiB;aAC5C,CAAA;QACH,CAAC,CAAC,CAAA;QAEF,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,CAAC,IAAI,CACT;gBACE,GAAG,UAAU;gBACb,UAAU,EAAE,KAAK;gBACjB,YAAY,EAAE,MAAM,CAAC,YAAY;gBACjC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC/C,EACD,QAAQ,CACT,CAAA;YACD,OAAM;QACR,CAAC;QAED,MAAM,CAAC,IAAI,CACT;YACE,GAAG,UAAU;YACb,IAAI,EAAE;gBACJ,IAAI,EAAE,MAAM,CAAC,IAAI;gBACjB,WAAW,EAAE,MAAM,CAAC,WAAW;gBAC/B,GAAG,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,YAAY,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAChE;YACD,qEAAqE;YACrE,mEAAmE;YACnE,+BAA+B;YAC/B,YAAY,EAAE,MAAM,CAAC,YAAY,IAAI,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE;YAC/D,KAAK,EAAE;gBACL,GAAG,MAAM,CAAC,IAAI;gBACd,GAAG,WAAW,CAAC;oBACb,WAAW,EAAE,eAAe,CAAC,MAAM,CAAC,IAAI,CAAC;oBACzC,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,IAAI;oBAClC,QAAQ,EAAE,MAAM,CAAC,QAAQ;oBACzB,OAAO,EAAE,MAAM,CAAC,OAAO;oBACvB,iBAAiB,EAAE,MAAM,CAAC,WAAW;oBACrC,SAAS,EAAE,YAAY,EAAE,SAAS;iBACnC,CAAC;aACH;SACF,EACD,QAAQ,CACT,CAAA;IACH,CAAC,CAAA;AACH,CAAC"}
+{"version":3,"file":"register-widget-tool.js","sourceRoot":"","sources":["../../src/tools/register-widget-tool.ts"],"names":[],"mappings":"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"}

package/dist/tools/registrar-shared.d.ts

@@ -0,0 +1,74 @@
+import type { RequestContext, ToolDefinition } from "mcp-use";
+import { z } from "zod";
+/** Input shape both registrars accept: a raw zod shape, wrapped into an object schema. */
+export type ZodRawShape = Record<string, z.ZodTypeAny>;
+/**
+ * mcp-use's per-call context, handed to registrar handlers as their third
+ * argument: `signal` (aborts when the client cancels or the connection
+ * drops), `reportProgress`, `sendLog`, `sendNotification`, `client`
+ * (capability queries), the originating `request`, and `auth`.
+ *
+ * `auth` is typed optional on purpose: plugins receive their server as a
+ * plain `MCPServer` even when the composition root installed OAuth
+ * (`createFrameworkApp` erases the user type), and a tool whose
+ * `securitySchemes` accept `noauth` runs signed out. `TUser` is the server's
+ * OAuth user type when the registrar was created from an `MCPServer<TUser>`,
+ * `unknown` otherwise.
+ */
+export type ToolHandlerContext<TUser = unknown> = RequestContext<TUser, "optional">;
+/** The ctx user type a registrar created from an `MCPServer<TUser>` hands its handlers. */
+export type HandlerUser<TUser> = [TUser] extends [never] ? unknown : TUser;
+/** `ToolDefinition` keys every registrar derives itself from its config. */
+type RegistrarOwnedKey = "name" | "description" | "inputSchema" | "schema" | "outputSchema" | "annotations";
+/**
+ * The `ToolDefinition` fields `createToolRegistrar` forwards verbatim to
+ * `server.tool` (`definition`): `title`, `_meta`, `visibility`,
+ * `securitySchemes`, `view`, and any field a later mcp-use adds. The keys
+ * the registrar derives from its own config are excluded — they win.
+ */
+export type ToolDefinitionPassthrough = Omit<ToolDefinition, RegistrarOwnedKey>;
+/**
+ * The `ToolDefinition` fields `createWidgetToolRegistrar` forwards verbatim
+ * (`definition`) — e.g. `securitySchemes`. On top of the shared owned keys
+ * the widget registrar derives `title`, `visibility`, `view` and `_meta`
+ * from its config (`title`, `visibility`, `meta`), so those stay excluded.
+ */
+export type WidgetToolDefinitionPassthrough = Omit<ToolDefinition, RegistrarOwnedKey | "title" | "visibility" | "view" | "_meta">;
+/** Options shared by `createToolRegistrar` and `createWidgetToolRegistrar`. */
+export interface ToolRegistrarOptions {
+    /**
+     * Default for every tool's `strictInput` (a tool's own flag wins). Off by
+     * default in 2.x: a non-strict input silently strips unknown keys.
+     */
+    strictInput?: boolean;
+    /**
+     * Type `register()`'s return value as the tool's mcp-use `ToolRef` (name,
+     * input and output types — what `mcp-env.d.ts` / `useCallTool` infer from).
+     * The ref is returned at runtime either way; the static type is opt-in in
+     * 2.x because registrar wrappers typed as
+     * `ReturnType<typeof createToolRegistrar<C>>` may return `void` (a toolset
+     * filter registers nothing for a filtered tool).
+     */
+    toolRefs?: boolean;
+}
+/** The registrar options that select the `ToolRef`-typed registrar. */
+export type TypedToolRefOptions = ToolRegistrarOptions & {
+    toolRefs: true;
+};
+/**
+ * The message for unknown keys on a strict input: names every unknown key
+ * and every valid one, so a model can correct a typo in one retry instead of
+ * having the key silently dropped.
+ */
+export declare function unknownKeysMessage(unknown: readonly string[], valid: readonly string[]): string;
+/**
+ * A strict object schema for a raw input shape: advertised with
+ * `additionalProperties: false`, and an unknown key fails validation with
+ * {@link unknownKeysMessage}. mcp-use's SDK runs input validation before the
+ * callback and returns the failure as an `isError` tool result.
+ */
+export declare function strictInputSchema(shape: ZodRawShape): z.ZodObject<ZodRawShape, z.core.$strict>;
+/** The input schema a registrar advertises for a raw shape under its strictness setting. */
+export declare function registrarInputSchema(shape: ZodRawShape | undefined, strict: boolean): z.ZodObject<ZodRawShape> | undefined;
+export {};
+//# sourceMappingURL=registrar-shared.d.ts.map

package/dist/tools/registrar-shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registrar-shared.d.ts","sourceRoot":"","sources":["../../src/tools/registrar-shared.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAC7D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,0FAA0F;AAC1F,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,CAAC,CAAA;AAEtD;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,kBAAkB,CAAC,KAAK,GAAG,OAAO,IAAI,cAAc,CAAC,KAAK,EAAE,UAAU,CAAC,CAAA;AAEnF,2FAA2F;AAC3F,MAAM,MAAM,WAAW,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,OAAO,GAAG,KAAK,CAAA;AAE1E,4EAA4E;AAC5E,KAAK,iBAAiB,GACpB,MAAM,GAAG,aAAa,GAAG,aAAa,GAAG,QAAQ,GAAG,cAAc,GAAG,aAAa,CAAA;AAEpF;;;;;GAKG;AACH,MAAM,MAAM,yBAAyB,GAAG,IAAI,CAAC,cAAc,EAAE,iBAAiB,CAAC,CAAA;AAE/E;;;;;GAKG;AACH,MAAM,MAAM,+BAA+B,GAAG,IAAI,CAChD,cAAc,EACd,iBAAiB,GAAG,OAAO,GAAG,YAAY,GAAG,MAAM,GAAG,OAAO,CAC9D,CAAA;AAED,+EAA+E;AAC/E,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,uEAAuE;AACvE,MAAM,MAAM,mBAAmB,GAAG,oBAAoB,GAAG;IAAE,QAAQ,EAAE,IAAI,CAAA;CAAE,CAAA;AAE3E;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAM/F;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,WAAW,GAAG,CAAC,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAM9F;AAED,4FAA4F;AAC5F,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,WAAW,GAAG,SAAS,EAC9B,MAAM,EAAE,OAAO,GACd,CAAC,CAAC,SAAS,CAAC,WAAW,CAAC,GAAG,SAAS,CAGtC"}

package/dist/tools/registrar-shared.js

@@ -0,0 +1,32 @@
+import { z } from "zod";
+/**
+ * The message for unknown keys on a strict input: names every unknown key
+ * and every valid one, so a model can correct a typo in one retry instead of
+ * having the key silently dropped.
+ */
+export function unknownKeysMessage(unknown, valid) {
+    const quote = (keys) => keys.map((key) => JSON.stringify(key)).join(", ");
+    const head = `Unknown key${unknown.length === 1 ? "" : "s"} ${quote(unknown)}.`;
+    return valid.length === 0
+        ? `${head} This tool takes no arguments.`
+        : `${head} Valid keys: ${quote(valid)}.`;
+}
+/**
+ * A strict object schema for a raw input shape: advertised with
+ * `additionalProperties: false`, and an unknown key fails validation with
+ * {@link unknownKeysMessage}. mcp-use's SDK runs input validation before the
+ * callback and returns the failure as an `isError` tool result.
+ */
+export function strictInputSchema(shape) {
+    const valid = Object.keys(shape);
+    return z.strictObject(shape, {
+        error: (issue) => issue.code === "unrecognized_keys" ? unknownKeysMessage(issue.keys, valid) : undefined,
+    });
+}
+/** The input schema a registrar advertises for a raw shape under its strictness setting. */
+export function registrarInputSchema(shape, strict) {
+    if (strict)
+        return strictInputSchema(shape ?? {});
+    return shape ? z.object(shape) : undefined;
+}
+//# sourceMappingURL=registrar-shared.js.map

package/dist/tools/registrar-shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registrar-shared.js","sourceRoot":"","sources":["../../src/tools/registrar-shared.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAmEvB;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAA0B,EAAE,KAAwB;IACrF,MAAM,KAAK,GAAG,CAAC,IAAuB,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAC5F,MAAM,IAAI,GAAG,cAAc,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAA;IAC/E,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;QACvB,CAAC,CAAC,GAAG,IAAI,gCAAgC;QACzC,CAAC,CAAC,GAAG,IAAI,gBAAgB,KAAK,CAAC,KAAK,CAAC,GAAG,CAAA;AAC5C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAkB;IAClD,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IAChC,OAAO,CAAC,CAAC,YAAY,CAAC,KAAK,EAAE;QAC3B,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE,CACf,KAAK,CAAC,IAAI,KAAK,mBAAmB,CAAC,CAAC,CAAC,kBAAkB,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS;KACzF,CAAC,CAAA;AACJ,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,oBAAoB,CAClC,KAA8B,EAC9B,MAAe;IAEf,IAAI,MAAM;QAAE,OAAO,iBAAiB,CAAC,KAAK,IAAI,EAAE,CAAC,CAAA;IACjD,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;AAC5C,CAAC"}

package/dist/tools/tool-name-guard.d.ts

@@ -0,0 +1,37 @@
+import type { MCPServer } from "mcp-use";
+/**
+ * What `installToolkit` does when a tool name is registered twice on its
+ * server. `"warn"` (the 2.x default) logs both owners and lets mcp-use keep
+ * the later registration, exactly as before; `"throw"` refuses the second
+ * registration, failing the boot.
+ */
+export type DuplicateToolNamePolicy = "warn" | "throw";
+/** Owner label of the tools `installToolkit` itself registers. */
+export declare const FRAMEWORK_TOOL_OWNER = "the toolkit framework";
+/** Owner label of tools registered outside any toolkit-run hook. */
+export declare const APPLICATION_TOOL_OWNER = "application code";
+/** Owner label of the tools a module's `registerTools` / `registerWidgetTools` hook registers. */
+export declare function moduleToolOwner(moduleName: string): string;
+/** The diagnostic for a duplicate tool name, naming the tool and both owners. */
+export declare function duplicateToolNameMessage(name: string, existingOwner: string, newOwner: string, policy: DuplicateToolNamePolicy): string;
+/**
+ * Wrap `server.tool` so every registration is checked against the names
+ * already taken on this server. mcp-use's own `tool()` is a plain map set
+ * (last wins), so without this a module tool named like a framework tool —
+ * or like another module's — silently disappears.
+ *
+ * The wrapper stays installed, so registrations made by application code
+ * after `installToolkit` are guarded too. Tools registered on the server
+ * BEFORE the guard was installed are invisible to it (mcp-use has no public
+ * tool listing) — which is why the standard path registers its own tools
+ * after `installToolkit`. A registration mcp-use refuses claims no name.
+ * Installing twice keeps one wrapper; `"throw"` wins.
+ */
+export declare function installToolNameGuard(server: MCPServer, policy: DuplicateToolNamePolicy): void;
+/**
+ * Run `register` with `owner` as the label for every tool it registers on
+ * `server`. A no-op wrapper when the server has no guard (e.g.
+ * `registerFrameworkTools` called on a server `installToolkit` never saw).
+ */
+export declare function withToolOwner<T>(server: object, owner: string, register: () => T): T;
+//# sourceMappingURL=tool-name-guard.d.ts.map

package/dist/tools/tool-name-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-name-guard.d.ts","sourceRoot":"","sources":["../../src/tools/tool-name-guard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAkB,MAAM,SAAS,CAAA;AAExD;;;;;GAKG;AACH,MAAM,MAAM,uBAAuB,GAAG,MAAM,GAAG,OAAO,CAAA;AAEtD,kEAAkE;AAClE,eAAO,MAAM,oBAAoB,0BAA0B,CAAA;AAE3D,oEAAoE;AACpE,eAAO,MAAM,sBAAsB,qBAAqB,CAAA;AAExD,kGAAkG;AAClG,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,iFAAiF;AACjF,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,MAAM,EACZ,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,uBAAuB,GAC9B,MAAM,CASR;AAYD;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,uBAAuB,GAAG,IAAI,CA8B7F;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAC,CASpF"}

package/dist/tools/tool-name-guard.js

@@ -0,0 +1,81 @@
+/** Owner label of the tools `installToolkit` itself registers. */
+export const FRAMEWORK_TOOL_OWNER = "the toolkit framework";
+/** Owner label of tools registered outside any toolkit-run hook. */
+export const APPLICATION_TOOL_OWNER = "application code";
+/** Owner label of the tools a module's `registerTools` / `registerWidgetTools` hook registers. */
+export function moduleToolOwner(moduleName) {
+    return `module "${moduleName}"`;
+}
+/** The diagnostic for a duplicate tool name, naming the tool and both owners. */
+export function duplicateToolNameMessage(name, existingOwner, newOwner, policy) {
+    const head = `Duplicate tool name "${name}": already registered by ${existingOwner}, registered again by ${newOwner}.`;
+    if (policy === "throw")
+        return `${head} mcp-use keeps one tool per name — rename one of them.`;
+    return (`[mcp-toolkit] ${head} mcp-use keeps only the last registration, so the tool from ` +
+        `${newOwner} replaces the one from ${existingOwner} — rename one of them ` +
+        `(duplicateToolNames: "throw" in the installToolkit options, or in ` +
+        `createFrameworkApp's app options, makes this a boot error).`);
+}
+const guards = new WeakMap();
+/**
+ * Wrap `server.tool` so every registration is checked against the names
+ * already taken on this server. mcp-use's own `tool()` is a plain map set
+ * (last wins), so without this a module tool named like a framework tool —
+ * or like another module's — silently disappears.
+ *
+ * The wrapper stays installed, so registrations made by application code
+ * after `installToolkit` are guarded too. Tools registered on the server
+ * BEFORE the guard was installed are invisible to it (mcp-use has no public
+ * tool listing) — which is why the standard path registers its own tools
+ * after `installToolkit`. A registration mcp-use refuses claims no name.
+ * Installing twice keeps one wrapper; `"throw"` wins.
+ */
+export function installToolNameGuard(server, policy) {
+    const existing = guards.get(server);
+    if (existing) {
+        if (policy === "throw")
+            existing.policy = "throw";
+        return;
+    }
+    const guard = { policy, owners: new Map(), scopes: [] };
+    guards.set(server, guard);
+    // `never` keeps the checked assignment sound under parameter
+    // contravariance — the wrapper only forwards the callback.
+    const original = server.tool.bind(server);
+    const guarded = (definition, callback) => {
+        const owner = guard.scopes.at(-1) ?? APPLICATION_TOOL_OWNER;
+        const previous = guard.owners.get(definition.name);
+        if (previous !== undefined && guard.policy === "throw") {
+            throw new Error(duplicateToolNameMessage(definition.name, previous, owner, "throw"));
+        }
+        // Only what mcp-use accepted counts: its `tool()` can still refuse the
+        // definition (e.g. a `noauth` scheme without mixedAuth, a view without an
+        // outputSchema). A refused registration claims no name — a fallback under
+        // the same name stays legal — and replaces nothing, so it is not warned.
+        const ref = original(definition, callback);
+        if (previous !== undefined) {
+            console.warn(duplicateToolNameMessage(definition.name, previous, owner, "warn"));
+        }
+        guard.owners.set(definition.name, owner);
+        return ref;
+    };
+    server.tool = guarded;
+}
+/**
+ * Run `register` with `owner` as the label for every tool it registers on
+ * `server`. A no-op wrapper when the server has no guard (e.g.
+ * `registerFrameworkTools` called on a server `installToolkit` never saw).
+ */
+export function withToolOwner(server, owner, register) {
+    const guard = guards.get(server);
+    if (!guard)
+        return register();
+    guard.scopes.push(owner);
+    try {
+        return register();
+    }
+    finally {
+        guard.scopes.pop();
+    }
+}
+//# sourceMappingURL=tool-name-guard.js.map

package/dist/tools/tool-name-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-name-guard.js","sourceRoot":"","sources":["../../src/tools/tool-name-guard.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miragon/mcp-toolkit-core",
-  "version": "2.5.0",
+  "version": "2.7.0",
   "description": "Framework runtime for MCP servers: plugin contract, step/widget registries, pipeline executor, render-view helpers.",
   "repository": {
     "type": "git",
@@ -33,19 +33,19 @@
     "access": "public"
   },
   "peerDependencies": {
-    "mcp-use": "2.7.1",
+    "mcp-use": "2.7.3",
     "zod": "^4.4.0"
   },
   "devDependencies": {
-    "@modelcontextprotocol/server": "2.0.0",
+    "@modelcontextprotocol/server": "2.2.0",
     "@stryker-mutator/core": "10.0.0",
     "@stryker-mutator/vitest-runner": "10.0.0",
-    "@types/node": "26.6.2",
-    "@vitest/coverage-v8": "5.0.1",
+    "@types/node": "26.6.4",
+    "@vitest/coverage-v8": "4.1.11",
     "fast-check": "4.10.2",
-    "mcp-use": "2.7.1",
+    "mcp-use": "2.7.3",
     "typescript": "6.0.3",
-    "vitest": "5.0.1",
+    "vitest": "4.1.11",
     "zod": "4.6.5"
   },
   "engines": {