refactor: drop type assertions in v2 port

events.ts: convert property-override arrow functions to method overrides
with declared overload signatures. The overrides now expose only the
ZodSchema form (the only one this package uses); a guard skips tracking
during super() construction (Protocol's ctor registers built-in handlers
before our fields initialize). Adds _methodOf() helper, removes the
MethodSchema local type and the eslint-disable directives.

server/index.ts: split registerAppTool into two public overloads
(StandardSchemaWithJSON and ZodRawShape forms) matching registerTool's,
removing the union-args casts. The impl signature still loses the
overload pairing, so the forwarding call into registerTool uses one
@ts-expect-error in place of three casts. Re-export LegacyToolCallback
alongside ToolCallback.

Author: felixweinberger

src/events.ts

@@ -5,12 +5,10 @@ import {
   Result,
   type BaseContext,
   type LegacyContextFields,
+  type ZodLikeRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
 
 type AppContext = BaseContext & LegacyContextFields;
-import { ZodLiteral, ZodObject } from "zod/v4";
-
-type MethodSchema = ZodObject<{ method: ZodLiteral<string> }>;
 
 /**
  * Per-event state: a singular `on*` handler (replace semantics) plus a
@@ -78,7 +76,7 @@ export abstract class ProtocolWithEvents<
    * schema on first use.
    */
   protected abstract readonly eventSchemas: {
-    [K in keyof EventMap]: MethodSchema;
+    [K in keyof EventMap]: ZodLikeRequestSchema;
   };
 
   /**
@@ -202,12 +200,15 @@ export abstract class ProtocolWithEvents<
 
   // ── Handler registration with double-set protection ─────────────────
 
-  // The two overrides below are arrow-function class fields rather than
-  // prototype methods so that Protocol's constructor — which registers its
-  // own ping/cancelled/progress handlers via `this.setRequestHandler`
-  // before our fields initialize — hits the base implementation and skips
-  // tracking. Converting these to proper methods would crash with
-  // `_registeredMethods` undefined during super().
+  // These overrides are prototype methods, so Protocol's constructor (which
+  // registers built-in ping/cancelled/progress handlers via
+  // `this.setRequestHandler` during super()) dispatches here before our own
+  // fields have initialized. The `_registeredMethods === undefined` guard
+  // skips tracking during that window.
+  //
+  // The base method has four overloads in v2; we expose only the Zod-schema
+  // form here since that is all this package uses. Subclasses retain the
+  // typed (request, ctx) handler signature.
 
   /**
    * Registers a request handler. Throws if a handler for the same method
@@ -216,11 +217,24 @@ export abstract class ProtocolWithEvents<
    *
    * @throws {Error} if a handler for this method is already registered.
    */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  override setRequestHandler = ((...args: any) => {
-    this._assertMethodNotRegistered(args[0], "setRequestHandler");
-    super.setRequestHandler(...(args as [MethodSchema, () => Result]));
-  }) as Protocol<AppContext>["setRequestHandler"];
+  override setRequestHandler<T extends ZodLikeRequestSchema>(
+    requestSchema: T,
+    handler: (
+      request: ReturnType<T["parse"]>,
+      ctx: AppContext,
+    ) => Result | Promise<Result>,
+  ): void;
+  override setRequestHandler(
+    schema: ZodLikeRequestSchema,
+    handler: (request: unknown, ctx: AppContext) => Result | Promise<Result>,
+  ): void {
+    if (this._registeredMethods === undefined) {
+      super.setRequestHandler(schema, handler);
+      return;
+    }
+    this._assertMethodNotRegistered(schema, "setRequestHandler");
+    super.setRequestHandler(schema, handler);
+  }
 
   /**
    * Registers a notification handler. Throws if a handler for the same
@@ -229,11 +243,21 @@ export abstract class ProtocolWithEvents<
    *
    * @throws {Error} if a handler for this method is already registered.
    */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  override setNotificationHandler = ((...args: any) => {
-    this._assertMethodNotRegistered(args[0], "setNotificationHandler");
-    super.setNotificationHandler(...(args as [MethodSchema, () => void]));
-  }) as Protocol<AppContext>["setNotificationHandler"];
+  override setNotificationHandler<T extends ZodLikeRequestSchema>(
+    notificationSchema: T,
+    handler: (notification: ReturnType<T["parse"]>) => void | Promise<void>,
+  ): void;
+  override setNotificationHandler(
+    schema: ZodLikeRequestSchema,
+    handler: (notification: unknown) => void | Promise<void>,
+  ): void {
+    if (this._registeredMethods === undefined) {
+      super.setNotificationHandler(schema, handler);
+      return;
+    }
+    this._assertMethodNotRegistered(schema, "setNotificationHandler");
+    super.setNotificationHandler(schema, handler);
+  }
 
   /**
    * Warn if a request handler `on*` setter is replacing a previously-set
@@ -256,15 +280,30 @@ export abstract class ProtocolWithEvents<
    * Replace a request handler, bypassing double-set protection. Used by
    * `on*` request-handler setters that need replace semantics.
    */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  protected replaceRequestHandler = ((...args: any) => {
-    const method = (args[0] as MethodSchema).shape.method.value;
-    this._registeredMethods.add(method);
-    super.setRequestHandler(...(args as [MethodSchema, () => Result]));
-  }) as Protocol<AppContext>["setRequestHandler"];
+  protected replaceRequestHandler<T extends ZodLikeRequestSchema>(
+    requestSchema: T,
+    handler: (
+      request: ReturnType<T["parse"]>,
+      ctx: AppContext,
+    ) => Result | Promise<Result>,
+  ): void;
+  protected replaceRequestHandler(
+    schema: ZodLikeRequestSchema,
+    handler: (request: unknown, ctx: AppContext) => Result | Promise<Result>,
+  ): void {
+    this._registeredMethods.add(this._methodOf(schema));
+    super.setRequestHandler(schema, handler);
+  }
 
-  private _assertMethodNotRegistered(schema: unknown, via: string): void {
-    const method = (schema as MethodSchema).shape.method.value;
+  private _methodOf(arg: ZodLikeRequestSchema | string): string {
+    return typeof arg === "string" ? arg : arg.shape.method.value;
+  }
+
+  private _assertMethodNotRegistered(
+    schema: ZodLikeRequestSchema | string,
+    via: string,
+  ): void {
+    const method = this._methodOf(schema);
     if (this._registeredMethods.has(method)) {
       throw new Error(
         `Handler for "${method}" already registered (via ${via}). ` +

src/server/index.ts

@@ -45,7 +45,7 @@ import type {
   McpServer,
   RegisteredTool,
   ResourceMetadata,
-  ToolCallback as SchemaToolCallback,
+  ToolCallback,
   ReadResourceCallback as _ReadResourceCallback,
   RegisteredResource,
 } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -55,13 +55,6 @@ import type {
   StandardSchemaWithJSON,
 } from "@modelcontextprotocol/sdk/server/zod-compat.js";
 import type { ZodRawShape } from "@modelcontextprotocol/sdk";
-
-type ToolCallback<Args extends ZodRawShapeCompat | AnySchema | undefined> =
-  Args extends ZodRawShape
-    ? LegacyToolCallback<Args>
-    : Args extends StandardSchemaWithJSON
-      ? SchemaToolCallback<Args>
-      : SchemaToolCallback<undefined>;
 import type {
   ClientCapabilities,
   ReadResourceResult,
@@ -70,7 +63,7 @@ import type {
 
 // Re-exports for convenience
 export { RESOURCE_URI_META_KEY, RESOURCE_MIME_TYPE };
-export type { ResourceMetadata, ToolCallback };
+export type { ResourceMetadata, ToolCallback, LegacyToolCallback };
 
 /**
  * Base tool configuration matching the standard MCP server tool options.
@@ -224,8 +217,8 @@ export interface McpUiAppResourceConfig extends ResourceMetadata {
  * @see {@link registerAppResource `registerAppResource`} to register the HTML resource referenced by the tool
  */
 export function registerAppTool<
-  OutputArgs extends ZodRawShapeCompat | AnySchema,
-  InputArgs extends undefined | ZodRawShapeCompat | AnySchema = undefined,
+  OutputArgs extends StandardSchemaWithJSON,
+  InputArgs extends StandardSchemaWithJSON | undefined = undefined,
 >(
   server: Pick<McpServer, "registerTool">,
   name: string,
@@ -234,6 +227,25 @@ export function registerAppTool<
     outputSchema?: OutputArgs;
   },
   cb: ToolCallback<InputArgs>,
+): RegisteredTool;
+/** Raw-shape form: `inputSchema` may be a plain `{ field: z.string() }` record. */
+export function registerAppTool<
+  InputArgs extends ZodRawShape,
+  OutputArgs extends ZodRawShape | StandardSchemaWithJSON | undefined = undefined,
+>(
+  server: Pick<McpServer, "registerTool">,
+  name: string,
+  config: McpUiAppToolConfig & {
+    inputSchema: InputArgs;
+    outputSchema?: OutputArgs;
+  },
+  cb: LegacyToolCallback<InputArgs>,
+): RegisteredTool;
+export function registerAppTool(
+  server: Pick<McpServer, "registerTool">,
+  name: string,
+  config: McpUiAppToolConfig,
+  cb: (...args: never) => ReturnType<ToolCallback<undefined>>,
 ): RegisteredTool {
   // Normalize metadata for backward compatibility:
   // - If _meta.ui.resourceUri is set, also set the legacy flat key
@@ -251,12 +263,11 @@ export function registerAppTool<
     normalizedMeta = { ...meta, ui: { ...uiMeta, resourceUri: legacyUri } };
   }
 
-  return (server.registerTool as McpServer["registerTool"])(
-    name,
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    { ...config, _meta: normalizedMeta } as any,
-    cb as SchemaToolCallback<undefined>,
-  );
+  // The two public overloads above guarantee (config.inputSchema, cb) match one
+  // of registerTool's overloads. The impl signature loses that pairing, so this
+  // forward needs a single suppression rather than three casts.
+  // @ts-expect-error -- forwarding overload-paired args through one impl signature
+  return server.registerTool(name, { ...config, _meta: normalizedMeta }, cb);
 }
 
 export type McpUiReadResourceResult = ReadResourceResult & {