mcp-use 2.0.0-beta.8 → 2.0.0

package/dist/internal/node-http-unavailable.js

@@ -0,0 +1 @@
+var createServer=()=>{throw new Error("MCPServer.listen() requires a Node.js runtime")};export{createServer};

package/dist/internal/node-http.js

@@ -0,0 +1 @@
+import{createServer}from"http";export{createServer};

package/dist/internal/resource-completion.js

@@ -1,7 +1 @@
-import {
-  normalizeCompletions
-} from "../chunk-KIZ72TIK.js";
-export {
-  normalizeCompletions
-};
-//# sourceMappingURL=resource-completion.js.map
+import{normalizeCompletions}from"../chunk-OJF6B5EU.js";export{normalizeCompletions};

package/dist/internal/usage.js

@@ -0,0 +1 @@
+import{flushUsage,isUsageDisabled,recordUsage}from"../chunk-273ZVKJJ.js";export{flushUsage,isUsageDisabled,recordUsage};

package/dist/landing-handler-TG6LVQBI.js

@@ -0,0 +1 @@
+import{generateLandingPage}from"./chunk-GX6PGIEO.js";import{resolveServerOrigin}from"./chunk-PSKSL567.js";function createLandingPageResponse(request,basePath,config,branding,tools,prompts,resources){let origin=resolveServerOrigin(request),url=new URL(basePath,`${origin}/`).href,html=generateLandingPage({...config,url,...branding.favicon!==void 0&&{iconUrl:new URL("/favicon.ico",`${origin}/`).href,...branding.faviconMimeType!==void 0&&{iconType:branding.faviconMimeType}},tools:Array.from(tools,entry=>entry.definition),prompts:Array.from(prompts,entry=>entry.definition),resources:Array.from(resources,entry=>entry.definition)});return new Response(request.method==="HEAD"?null:html,{status:200,headers:{"cache-control":"no-store","content-type":"text/html; charset=utf-8","x-content-type-options":"nosniff"}})}export{createLandingPageResponse};

package/dist/landing-handler.d.ts

@@ -1,10 +1,12 @@
 import { type LandingPageOptions, type LandingPagePrompt, type LandingPageResource, type LandingPageTool } from "./landing.js";
+import type { ServerBranding } from "./branding.js";
 /**
  * Render a landing-page response without loading the renderer on MCP requests.
  *
  * @param request - Classified HTML GET or HEAD request.
  * @param basePath - Exact MCP endpoint path.
  * @param config - Server identity and description.
+ * @param branding - Normalized browser and MCP identity branding.
  * @param tools - Frozen tool registry values.
  * @param prompts - Frozen prompt registry values.
  * @param resources - Frozen static-resource registry values.
@@ -12,11 +14,10 @@ import { type LandingPageOptions, type LandingPagePrompt, type LandingPageResour
  *
  * @internal
  */
-export declare function createLandingPageResponse(request: Request, basePath: string, config: Pick<LandingPageOptions, "name" | "title" | "version" | "description">, tools: Iterable<{
+export declare function createLandingPageResponse(request: Request, basePath: string, config: Pick<LandingPageOptions, "name" | "title" | "version" | "description">, branding: Pick<ServerBranding, "favicon" | "faviconMimeType">, tools: Iterable<{
     definition: LandingPageTool;
 }>, prompts: Iterable<{
     definition: LandingPagePrompt;
 }>, resources: Iterable<{
     definition: LandingPageResource;
 }>): Response;
-//# sourceMappingURL=landing-handler.d.ts.map

package/dist/landing.d.ts

@@ -1,8 +1,10 @@
 /**
- * Landing page generator for MCP server endpoints
+ * Generate an HTML landing page for an MCP server endpoint.
  *
- * Generates SEO-friendly HTML with connection instructions for MCP servers
- * from Claude Code, Cursor, VS Code, ChatGPT, and Manufact Inspector (hosted).
+ * The rendered page includes server metadata and connection instructions for
+ * supported MCP clients.
+ *
+ * @packageDocumentation
  */
 /** A tool shown in the landing page's primitives list. */
 export interface LandingPageTool {
@@ -53,13 +55,25 @@ export interface LandingPageOptions {
     resources?: readonly LandingPageResource[];
     /** Optional absolute URL for the icon displayed above the server heading. */
     iconUrl?: string;
+    /** MIME type for the favicon link tag when known. */
+    iconType?: string;
 }
 /**
  * Generates an HTML landing page with connection instructions
  * for Claude Code, Cursor, VS Code, ChatGPT, and Manufact Inspector.
  *
  * @param options - Server identity, endpoint, icon, and primitive metadata.
- * @returns HTML landing page with connection instructions
+ * @returns HTML landing page with connection instructions.
+ *
+ * @example
+ * ```ts
+ * import { generateLandingPage } from "mcp-use/landing";
+ *
+ * const html = generateLandingPage({
+ *   name: "weather",
+ *   version: "1.0.0",
+ *   url: "https://example.com/mcp",
+ * });
+ * ```
  */
 export declare function generateLandingPage(options: LandingPageOptions): string;
-//# sourceMappingURL=landing.d.ts.map

package/dist/landing.js

@@ -1,7 +1 @@
-import {
-  generateLandingPage
-} from "./chunk-FCGJJVL2.js";
-export {
-  generateLandingPage
-};
-//# sourceMappingURL=landing.js.map
+import{generateLandingPage}from"./chunk-GX6PGIEO.js";export{generateLandingPage};

package/dist/listen-address.d.ts

@@ -0,0 +1,8 @@
+/** Default bind address for Node listeners. */
+export declare const DEFAULT_LISTEN_HOST = "127.0.0.1";
+/** Default TCP port for Node listeners. */
+export declare const DEFAULT_LISTEN_PORT = 3000;
+/** Resolve an explicit value, then `HOST`, then configured value, then default. */
+export declare function resolveListenHost(explicitHost: string | undefined, configuredHost: string | undefined, env?: Readonly<Record<string, string | undefined>>): string;
+/** Resolve an explicit value, then `PORT`, then configured value, then default. */
+export declare function resolveListenPort(explicitPort: number | undefined, configuredPort: number | undefined, env?: Readonly<Record<string, string | undefined>>): number;

package/dist/logging.d.ts

@@ -28,4 +28,3 @@ export declare function resolveLogLevel(configured?: LogLevel): LogLevel;
  * `config.logging.enabled` is `false`.
  */
 export declare function requestLogger(options?: LoggingOptions): FetchMiddleware;
-//# sourceMappingURL=logging.d.ts.map

package/dist/mcp-proxy-NETCUGUD.js

@@ -0,0 +1,2 @@
+var PROXY_CLIENT_INSTALL_HINT=["[mcp-use] server.proxy() requires the optional @mcp-use/client package.","Install it in your project:","","  npm install @mcp-use/client"].join(`
+`);function passthroughJsonSchema(schema){return{"~standard":{version:1,vendor:"mcp-use-proxy",validate(value){return{value}},jsonSchema:{input:()=>schema,output:()=>schema}}}}function promptArgsToJsonSchema(args){let properties=Object.create(null),required=[];for(let arg of args??[])properties[arg.name]={type:"string",...arg.description!==void 0&&{description:arg.description}},arg.required===!0&&required.push(arg.name);return{type:"object",properties,...required.length>0&&{required}}}function prefixedName(namespace,name){return`${namespace}_${name}`}function proxiedResourceUri(namespace,uri){return`mcp-use-proxy:///${encodeURIComponent(namespace)}/${encodeURIComponent(uri)}`}function isConnection(value){if(value===null||typeof value!="object")return!1;let candidate=value;return typeof candidate.listTools=="function"&&typeof candidate.callTool=="function"&&typeof candidate.readResource=="function"&&typeof candidate.listPrompts=="function"&&typeof candidate.getPrompt=="function"}function isClientPackageMissing(error){if(!(error instanceof Error))return!1;let code=error.code;return(code==="ERR_MODULE_NOT_FOUND"||code==="MODULE_NOT_FOUND")&&error.message.includes("@mcp-use/client")}function proxyDiagnostic(message,error){if(error===void 0){console.error(`[mcp-use] ${message}`);return}let detail=error instanceof Error?error.message:String(error);console.error(`[mcp-use] ${message}: ${detail}`)}function proxyClientInstallError(error){return isClientPackageMissing(error)?new Error(PROXY_CLIENT_INSTALL_HINT,{cause:error}):void 0}async function loadProxyClient(importer=()=>import("@mcp-use/client")){try{return await importer()}catch(error){let installError=proxyClientInstallError(error);throw installError!==void 0?installError:error}}function supports(connection,capability){return connection.supports?.(capability)!==!1}async function introspect(namespace,connection){let tools=[];if(supports(connection,"tools"))try{tools=await connection.listTools()}catch(error){proxyDiagnostic(`Failed to introspect tools from upstream MCP server "${namespace}"`,error)}let resources=[];if(supports(connection,"resources"))try{connection.listAllResources!==void 0?resources=(await connection.listAllResources()).resources:connection.listResources!==void 0&&(resources=(await connection.listResources()).resources)}catch(error){proxyDiagnostic(`Failed to introspect resources from upstream MCP server "${namespace}"`,error)}let prompts=[];if(supports(connection,"prompts"))try{prompts=(await connection.listPrompts()).prompts}catch(error){proxyDiagnostic(`Failed to introspect prompts from upstream MCP server "${namespace}"`,error)}return{namespace,connection,tools,resources,prompts}}function mountPlan(host,plan){host.trackNamespace?.({tools:plan.tools.length,resources:plan.resources.length,prompts:plan.prompts.length});for(let tool of plan.tools){let name=prefixedName(plan.namespace,tool.name);if(host.hasTool(name)){proxyDiagnostic(`Skipping proxied tool "${name}" from upstream "${plan.namespace}" because that name is already registered`);continue}let definition={name,...tool.title!==void 0&&{title:tool.title},...tool.description!==void 0&&{description:tool.description},...tool.annotations!==void 0&&{annotations:tool.annotations},...tool.inputSchema!==void 0&&{inputSchema:passthroughJsonSchema(tool.inputSchema)},...tool.outputSchema!==void 0&&{outputSchema:passthroughJsonSchema(tool.outputSchema)}},upstreamName=tool.name,callback=async(params,ctx)=>{let progressForwarding=Promise.resolve();try{return await plan.connection.callTool(upstreamName,params,{signal:ctx.signal,onprogress:progress=>{progressForwarding=progressForwarding.then(async()=>{try{await ctx.reportProgress(progress.progress,progress.total,progress.message)}catch(error){proxyDiagnostic(`Failed to forward progress for proxied tool "${definition.name}"`,error)}})}})}finally{await progressForwarding}};host.registerTool(definition,callback)}for(let resource of plan.resources){let name=prefixedName(plan.namespace,resource.name);if(host.hasResource(name)){proxyDiagnostic(`Skipping proxied resource "${name}" from upstream "${plan.namespace}" because that name is already registered`);continue}let upstreamUri=resource.uri;host.registerResource({name,uri:proxiedResourceUri(plan.namespace,upstreamUri),...resource.title!==void 0&&{title:resource.title},...resource.description!==void 0&&{description:resource.description},...resource.mimeType!==void 0&&{mimeType:resource.mimeType}},async(_uri,ctx)=>plan.connection.readResource(upstreamUri,{signal:ctx.signal}))}for(let prompt of plan.prompts){let name=prefixedName(plan.namespace,prompt.name);if(host.hasPrompt(name)){proxyDiagnostic(`Skipping proxied prompt "${name}" from upstream "${plan.namespace}" because that name is already registered`);continue}let upstreamName=prompt.name;host.registerPrompt({name,...prompt.title!==void 0&&{title:prompt.title},...prompt.description!==void 0&&{description:prompt.description},schema:passthroughJsonSchema(promptArgsToJsonSchema(prompt.arguments))},async params=>plan.connection.getPrompt(upstreamName,params))}}async function mountProxyConnection(host,connection){if(host.isStarted())throw new Error("Cannot call proxy() after the server has started: register upstream servers before listen()/server.fetch.");let namespace=connection.info.server.name,plan=await introspect(namespace,connection);mountPlan(host,plan)}function toClientConfig(config){return{url:config.url,...config.headers!==void 0&&{headers:config.headers},...config.authToken!==void 0&&{authToken:config.authToken},...config.timeout!==void 0&&{timeout:config.timeout},...config.fetch!==void 0&&{fetch:config.fetch},...config.protocolNegotiation!==void 0&&{protocolNegotiation:config.protocolNegotiation},oauth:!1}}async function mountProxyServers(host,servers){if(host.isStarted())throw new Error("Cannot call proxy() after the server has started: register upstream servers before listen()/server.fetch.");let{MCPClient}=await loadProxyClient(),clientServers=Object.fromEntries(Object.entries(servers).map(([name,config])=>[name,toClientConfig(config)])),owner=new MCPClient({mcpServers:clientServers});try{let plans=[];for(let namespace of Object.keys(clientServers)){let connection;try{connection=await owner.connect(namespace)}catch(error){proxyDiagnostic(`Failed to connect to upstream MCP server "${namespace}"`,error);continue}plans.push(await introspect(namespace,connection))}for(let plan of plans)mountPlan(host,plan);host.trackOwner(owner)}catch(error){throw await owner.close().catch(()=>{}),error}}function isProxyConnection(value){return isConnection(value)}export{isProxyConnection,mountProxyConnection,mountProxyServers,proxyClientInstallError};

package/dist/mcp-proxy.d.ts

@@ -0,0 +1,158 @@
+import type { CallToolResult, GetPromptResult, InputRequiredResult, PromptArgument, ReadResourceResult, ToolAnnotations } from "@modelcontextprotocol/server";
+import type { PromptCallback, PromptDefinition } from "./prompts.js";
+import type { ResourceCallback, ResourceDefinition } from "./resources.js";
+import type { ToolCallback, ToolDefinition } from "./tools.js";
+/** HTTP connection settings accepted by {@link MCPServer.proxy}. */
+export interface ProxyHttpConfig {
+    /** Upstream MCP endpoint URL. */
+    url: string;
+    /** Extra headers sent on every upstream request. */
+    headers?: Record<string, string>;
+    /** Bearer token sent to the upstream server. */
+    authToken?: string;
+    /** Connection timeout in milliseconds. */
+    timeout?: number;
+    /** Fetch implementation used for upstream HTTP requests. */
+    fetch?: typeof fetch;
+    /** Protocol negotiation mode forwarded to `@mcp-use/client`. */
+    protocolNegotiation?: "auto" | "legacy" | {
+        pin: string;
+    };
+}
+/** Connection settings for one upstream server. */
+export type ProxyServerConfig = ProxyHttpConfig;
+/** Progress payload received while a proxied tool is running. */
+export interface ProxyProgress {
+    /** Completed work units. */
+    progress: number;
+    /** Total work units, when known. */
+    total?: number | undefined;
+    /** Human-readable progress detail. */
+    message?: string | undefined;
+}
+/** Request controls used when forwarding calls to an upstream connection. */
+export interface ProxyRequestOptions {
+    /** Aborts the upstream request when the downstream request is cancelled. */
+    signal?: AbortSignal;
+    /** Receives upstream progress notifications. */
+    onprogress?: (progress: ProxyProgress) => void;
+}
+/** Structural connection contract accepted by the low-level proxy overload. */
+export interface ProxyConnection {
+    /** Negotiated metadata used to derive the automatic capability namespace. */
+    readonly info: {
+        server: {
+            name: string;
+        };
+    };
+    /** Whether the upstream advertised a named MCP capability. */
+    supports?(capability: string): boolean;
+    /** List upstream tools. */
+    listTools(): Promise<ProxyTool[]>;
+    /** Forward a tool call. */
+    callTool(name: string, args?: Record<string, unknown>, options?: ProxyRequestOptions): Promise<CallToolResult | InputRequiredResult>;
+    /** List upstream resources, including pagination when supported. */
+    listAllResources?(): Promise<{
+        resources: ProxyResource[];
+    }>;
+    /** List one page of upstream resources. */
+    listResources?(): Promise<{
+        resources: ProxyResource[];
+    }>;
+    /** Read an upstream resource. */
+    readResource(uri: string, options?: ProxyRequestOptions): Promise<ReadResourceResult>;
+    /** List upstream prompts. */
+    listPrompts(): Promise<{
+        prompts: ProxyPrompt[];
+    }>;
+    /** Render an upstream prompt. */
+    getPrompt(name: string, args: Record<string, unknown>): Promise<GetPromptResult>;
+}
+/** Tool metadata consumed while introspecting an upstream connection. */
+export interface ProxyTool {
+    /** Upstream tool name. */
+    name: string;
+    /** Human-readable tool title. */
+    title?: string | undefined;
+    /** LLM-facing tool description. */
+    description?: string | undefined;
+    /** Upstream input JSON Schema. */
+    inputSchema?: Record<string, unknown> | undefined;
+    /** Upstream output JSON Schema. */
+    outputSchema?: Record<string, unknown> | undefined;
+    /** Upstream behavioral hints. */
+    annotations?: ToolAnnotations | undefined;
+}
+/** Resource metadata consumed while introspecting an upstream connection. */
+export interface ProxyResource {
+    /** Upstream resource name. */
+    name: string;
+    /** Original upstream resource URI. */
+    uri: string;
+    /** Human-readable resource title. */
+    title?: string | undefined;
+    /** Human-readable resource description. */
+    description?: string | undefined;
+    /** Resource media type. */
+    mimeType?: string | undefined;
+}
+/** Prompt metadata consumed while introspecting an upstream connection. */
+export interface ProxyPrompt {
+    /** Upstream prompt name. */
+    name: string;
+    /** Human-readable prompt title. */
+    title?: string | undefined;
+    /** Human-readable prompt description. */
+    description?: string | undefined;
+    /** String arguments accepted by the prompt. */
+    arguments?: PromptArgument[] | undefined;
+}
+/** Registration surface used while mounting proxied capabilities. @internal */
+export interface ProxyMountHost {
+    /** Whether the parent server has mounted its handler. */
+    isStarted(): boolean;
+    /** Whether a tool name is already registered. */
+    hasTool(name: string): boolean;
+    /** Whether a resource name is already registered. */
+    hasResource(name: string): boolean;
+    /** Whether a prompt name is already registered. */
+    hasPrompt(name: string): boolean;
+    /** Register a proxied tool. */
+    registerTool(definition: ToolDefinition, callback: ToolCallback): void;
+    /** Register a proxied resource. */
+    registerResource(definition: ResourceDefinition, callback: ResourceCallback): void;
+    /** Register a proxied prompt. */
+    registerPrompt(definition: PromptDefinition, callback: PromptCallback): void;
+    /** Track a proxy client owned by the parent server. */
+    trackOwner(owner: {
+        close(): Promise<void>;
+    }): void;
+    /** Record one successfully introspected upstream namespace. */
+    trackNamespace?(counts: {
+        tools: number;
+        resources: number;
+        prompts: number;
+    }): void;
+}
+/** Convert a missing optional-client import into the proxy install error. @internal */
+export declare function proxyClientInstallError(error: unknown): Error | undefined;
+/**
+ * Mount one existing upstream connection on a parent server.
+ *
+ * @param host - Parent server registration surface.
+ * @param connection - Ready `@mcp-use/client` v2 connection.
+ * @internal
+ */
+export declare function mountProxyConnection(host: ProxyMountHost, connection: ProxyConnection): Promise<void>;
+/**
+ * Connect and mount namespace-keyed upstream servers through
+ * `@mcp-use/client` v2.
+ *
+ * @param host - Parent server registration surface.
+ * @param servers - Namespace-keyed upstream client configuration.
+ *
+ * @internal
+ */
+export declare function mountProxyServers(host: ProxyMountHost, servers: Record<string, ProxyServerConfig>): Promise<void>;
+/** Determine whether a proxy argument is an existing connection. @internal */
+export declare function isProxyConnection(value: unknown): value is ProxyConnection;

package/dist/middleware/cors.d.ts

@@ -8,4 +8,3 @@ import type { FetchMiddleware } from "../fetch-app.js";
 export declare function corsFetchMiddleware(options: CorsOptions): FetchMiddleware;
 /** Whether global CORS middleware owns response headers for view assets. */
 export declare function isGlobalCorsEnabled(cors: CorsOptions | undefined): boolean;
-//# sourceMappingURL=cors.d.ts.map

package/dist/middleware/mcp-middleware.d.ts

@@ -1,135 +1,209 @@
-import type { AuthInfo } from "@modelcontextprotocol/server";
+import type { AuthInfo, HandlerResultTypeMap, RequestTypeMap, ResultTypeMap } from "@modelcontextprotocol/server";
+import type { Context, Env, HonoRequest } from "hono";
+declare const MCP_MIDDLEWARE_METHODS: readonly ["tools/call", "tools/list", "resources/read", "resources/list", "prompts/get", "prompts/list"];
+/** MCP methods currently intercepted by {@link MCPServer.use}. */
+export type McpMiddlewareMethod = (typeof MCP_MIDDLEWARE_METHODS)[number];
+/** Params exposed by the SDK for a particular MCP request method. */
+export type McpMiddlewareParams<M extends McpMiddlewareMethod> = RequestTypeMap[M] extends {
+    params?: infer P;
+} ? NonNullable<P> : Record<string, never>;
 /**
- * Context passed to every MCP middleware handler.
+ * Method-specific params and middleware result types.
  *
- * `params` is mutable — middleware can modify params before calling `next()`
- * and those changes will be visible to downstream middleware and the handler.
- *
- * `state` is a shared Map for passing arbitrary data across middleware in
- * the same chain.
+ * List middleware intentionally operates on item arrays rather than protocol
+ * result envelopes. The server wrapper preserves the envelope around the
+ * transformed array.
  */
-export interface MiddlewareContext {
-    /** MCP method name, e.g. "tools/call", "tools/list", "resources/read" */
-    method: string;
-    /** JSON-RPC request params (mutable — mutations are passed downstream) */
-    params: Record<string, unknown>;
-    /** OAuth info extracted from JWT, present when OAuth is configured */
-    auth?: AuthInfo;
-    /** Shared state Map for passing data across middleware in the same request */
-    state: Map<string, unknown>;
-}
-/** Params shape for `tools/call` method */
-interface ToolsCallParams {
-    name: string;
-    arguments?: Record<string, unknown>;
-    _meta?: Record<string, unknown>;
-}
-/** Params shape for `resources/read` method */
-interface ResourcesReadParams {
-    uri: string;
-    _meta?: Record<string, unknown>;
-}
-/** Params shape for `prompts/get` method */
-interface PromptsGetParams {
-    name: string;
-    arguments?: Record<string, string>;
-    _meta?: Record<string, unknown>;
-}
-/** Context with narrowed `params` for `tools/call` */
-export interface ToolsCallMiddlewareContext extends MiddlewareContext {
-    method: "tools/call";
-    params: ToolsCallParams & Record<string, unknown>;
-}
-/** Context with narrowed `params` for `resources/read` */
-export interface ResourcesReadMiddlewareContext extends MiddlewareContext {
-    method: "resources/read";
-    params: ResourcesReadParams & Record<string, unknown>;
-}
-/** Context with narrowed `params` for `prompts/get` */
-export interface PromptsGetMiddlewareContext extends MiddlewareContext {
-    method: "prompts/get";
-    params: PromptsGetParams & Record<string, unknown>;
+export interface McpMiddlewareOperationMap {
+    /** Tool invocation parameters and handler result. */
+    "tools/call": {
+        /** Parameters for the tool invocation. */
+        params: McpMiddlewareParams<"tools/call">;
+        /** Tool invocation result passed through the middleware chain. */
+        result: HandlerResultTypeMap["tools/call"];
+    };
+    /** Tool-list parameters and list items. */
+    "tools/list": {
+        /** Parameters for the tool-list request. */
+        params: McpMiddlewareParams<"tools/list">;
+        /** Tool descriptors returned by the list request. */
+        result: ResultTypeMap["tools/list"]["tools"];
+    };
+    /** Resource-read parameters and handler result. */
+    "resources/read": {
+        /** Parameters identifying the resource to read. */
+        params: McpMiddlewareParams<"resources/read">;
+        /** Resource contents returned by the handler. */
+        result: HandlerResultTypeMap["resources/read"];
+    };
+    /** Resource-list parameters and list items. */
+    "resources/list": {
+        /** Parameters for the resource-list request. */
+        params: McpMiddlewareParams<"resources/list">;
+        /** Resource descriptors returned by the list request. */
+        result: ResultTypeMap["resources/list"]["resources"];
+    };
+    /** Prompt-read parameters and handler result. */
+    "prompts/get": {
+        /** Parameters identifying the prompt and its arguments. */
+        params: McpMiddlewareParams<"prompts/get">;
+        /** Prompt messages returned by the handler. */
+        result: HandlerResultTypeMap["prompts/get"];
+    };
+    /** Prompt-list parameters and list items. */
+    "prompts/list": {
+        /** Parameters for the prompt-list request. */
+        params: McpMiddlewareParams<"prompts/list">;
+        /** Prompt descriptors returned by the list request. */
+        result: ResultTypeMap["prompts/list"]["prompts"];
+    };
 }
+/** Result exposed to middleware for a particular MCP method. */
+export type McpMiddlewareResult<M extends McpMiddlewareMethod> = McpMiddlewareOperationMap[M]["result"];
 /**
- * Map from MCP middleware pattern strings to their narrowed context type.
- * Used by `McpMiddlewareFnFor<P>` to infer the correct `ctx` parameter.
+ * Rebuild an SDK request with the params currently held by middleware.
+ *
+ * Middleware may replace `ctx.params`, so forwarding the request object that
+ * was captured before the chain ran would silently discard that replacement.
+ * @internal
  */
-export interface McpMiddlewarePatternMap {
-    "tools/call": ToolsCallMiddlewareContext;
-    "resources/read": ResourcesReadMiddlewareContext;
-    "prompts/get": PromptsGetMiddlewareContext;
-}
+export declare function withMcpMiddlewareParams<M extends McpMiddlewareMethod>(request: unknown, params: McpMiddlewareOperationMap[M]["params"]): RequestTypeMap[M];
+type MiddlewareContextCommon<TEnv extends Env = Env> = Omit<Context<TEnv>, "req"> & {
+    /** Hono request for the originating HTTP exchange. */
+    request?: HonoRequest;
+    /**
+     * Deprecated v1-compatible alias for {@link MiddlewareContext.request}.
+     *
+     * @deprecated Use `request` instead.
+     */
+    req?: HonoRequest;
+    /** Session info when the underlying transport provides a session ID. */
+    session?: {
+        sessionId: string;
+    };
+    /** OAuth info extracted from the validated access token. */
+    auth?: AuthInfo;
+    /** Shared state for middleware participating in this request. */
+    state: Map<string, unknown>;
+};
 /**
- * A typed MCP middleware function whose `ctx` is narrowed based on the
- * pattern string `P`. Falls back to the base `MiddlewareContext` for
- * wildcard or unrecognized patterns.
+ * Context passed to MCP middleware.
+ *
+ * The conditional form preserves the correlation between `method` and
+ * `params` when more than one method is represented.
  */
-export type McpMiddlewareFnFor<P extends string> = P extends keyof McpMiddlewarePatternMap ? (ctx: McpMiddlewarePatternMap[P], next: () => Promise<unknown>) => Promise<unknown> : McpMiddlewareFn;
+export type MiddlewareContext<M extends McpMiddlewareMethod = McpMiddlewareMethod, TEnv extends Env = Env> = M extends McpMiddlewareMethod ? MiddlewareContextCommon<TEnv> & {
+    method: M;
+    params: McpMiddlewareOperationMap[M]["params"];
+} : never;
+/** Preferred explicit name for the method-correlated middleware context. */
+export type McpMiddlewareContext<M extends McpMiddlewareMethod = McpMiddlewareMethod, TEnv extends Env = Env> = MiddlewareContext<M, TEnv>;
+/** Context with narrowed params for `tools/call`. */
+export type ToolsCallMiddlewareContext = MiddlewareContext<"tools/call">;
+/** Context with narrowed params for `tools/list`. */
+export type ToolsListMiddlewareContext = MiddlewareContext<"tools/list">;
+/** Context with narrowed params for `resources/read`. */
+export type ResourcesReadMiddlewareContext = MiddlewareContext<"resources/read">;
+/** Context with narrowed params for `resources/list`. */
+export type ResourcesListMiddlewareContext = MiddlewareContext<"resources/list">;
+/** Context with narrowed params for `prompts/get`. */
+export type PromptsGetMiddlewareContext = MiddlewareContext<"prompts/get">;
+/** Context with narrowed params for `prompts/list`. */
+export type PromptsListMiddlewareContext = MiddlewareContext<"prompts/list">;
+/** Map retained for compatibility and convenient indexed lookup. */
+export type McpMiddlewarePatternMap<TEnv extends Env = Env> = {
+    [M in McpMiddlewareMethod]: MiddlewareContext<M, TEnv>;
+};
+/** Continue the middleware chain with the result type for method `M`. */
+export type McpMiddlewareNext<M extends McpMiddlewareMethod> = () => Promise<McpMiddlewareResult<M>>;
+/** Middleware for one exact MCP method. */
+export type McpExactMiddlewareFn<M extends McpMiddlewareMethod, TEnv extends Env = Env> = (ctx: MiddlewareContext<M, TEnv>, next: McpMiddlewareNext<M>) => Promise<McpMiddlewareResult<M>>;
 /**
- * A single MCP middleware function.
+ * Type-preserving middleware over every wrapped MCP method.
  *
- * Call `next()` to pass control to the next middleware (or handler).
- * Return its result, or return a different value to override the response.
- * Throw an error to reject the request.
+ * The global wildcard cannot inspect or replace a method-specific result. Its `next`
+ * resolves after downstream middleware, and the composer propagates that
+ * downstream result unchanged. It must call `next()` or throw.
  */
-export type McpMiddlewareFn = (ctx: MiddlewareContext, next: () => Promise<unknown>) => Promise<unknown>;
+export type McpMiddlewareFn<Methods extends McpMiddlewareMethod = McpMiddlewareMethod, TEnv extends Env = Env> = (ctx: MiddlewareContext<Methods, TEnv>, next: () => Promise<void>) => Promise<void>;
+/** Exact MCP middleware methods plus the global pass-through wildcard. */
+export type McpMiddlewarePatternBody = McpMiddlewareMethod | "*";
+/** Canonical `mcp:` middleware patterns. */
+export type McpMiddlewarePattern = `mcp:${McpMiddlewarePatternBody}`;
+/** Observer patterns additionally support grouping related MCP methods. */
+export type McpEventPatternBody = McpMiddlewarePatternBody | "tools/*" | "resources/*" | "prompts/*";
+type McpEventBasePattern = `mcp:${McpEventPatternBody}`;
+type StripMcpPrefix<P extends string> = P extends `mcp:${infer Body}` ? Body : P;
+/** Methods selected by an MCP middleware or observer pattern. */
+export type McpMiddlewareMethodsForPattern<P extends string> = StripMcpPrefix<P> extends infer Body ? Body extends McpMiddlewareMethod ? Body : Body extends "tools/*" ? Extract<McpMiddlewareMethod, `tools/${string}`> : Body extends "resources/*" ? Extract<McpMiddlewareMethod, `resources/${string}`> : Body extends "prompts/*" ? Extract<McpMiddlewareMethod, `prompts/${string}`> : Body extends "*" ? McpMiddlewareMethod : never : never;
+/** Infer an exact or type-preserving wildcard handler from pattern `P`. */
+export type McpMiddlewareFnFor<P extends McpMiddlewarePattern, TEnv extends Env = Env> = StripMcpPrefix<P> extends infer Body ? Body extends McpMiddlewareMethod ? McpExactMiddlewareFn<Body, TEnv> : McpMiddlewareFn<McpMiddlewareMethodsForPattern<P>, TEnv> : never;
 /**
- * Internal storage entry for a registered MCP middleware.
- * The pattern is stored with the `mcp:` prefix already stripped.
+ * Type-erased middleware adapter stored after registration.
+ *
+ * Exact handlers and the global wildcard are adapted to this common callable
+ * shape before insertion, following the SDK's request-handler storage model.
  * @internal
  */
 export interface McpMiddlewareEntry {
-    /** Pattern after stripping "mcp:" — e.g. "tools/call", "tools/*", "*" */
     pattern: string;
-    handler: McpMiddlewareFn;
+    handler: (ctx: MiddlewareContext, next: () => Promise<unknown>) => Promise<unknown>;
 }
-/** Phase for MCP observer event listeners registered via `server.on()`. */
-export type McpEventPhase = "before" | "complete";
 /**
- * Internal storage entry for a registered MCP observer event listener.
- * @internal
+ * Adapt a public method-correlated handler for type-erased internal storage.
+ *
+ * The overload retains the public pattern/handler correlation. The broad
+ * implementation signature is the deliberate erasure boundary, like the
+ * official SDK's `setRequestHandler` implementation.
  */
+export declare function createMcpMiddlewareEntry<P extends McpMiddlewarePattern, TEnv extends Env = Env>(pattern: P, handler: McpMiddlewareFnFor<P, TEnv>): McpMiddlewareEntry;
+/** Phase for MCP observer event listeners registered via `server.on()`. */
+export type McpEventPhase = "before" | "complete";
+/** Read-only observer context correlated by MCP method. */
+export type ReadonlyMiddlewareContext<M extends McpMiddlewareMethod = McpMiddlewareMethod, TEnv extends Env = Env> = TEnv extends Env ? M extends McpMiddlewareMethod ? {
+    readonly method: M;
+    readonly params: Readonly<McpMiddlewareOperationMap[M]["params"]>;
+    readonly request?: HonoRequest;
+    /** @deprecated Use `request` instead. */
+    readonly req?: HonoRequest;
+    readonly session?: Readonly<{
+        sessionId: string;
+    }>;
+    readonly auth?: Readonly<AuthInfo>;
+    readonly state: ReadonlyMap<string, unknown>;
+} : never : never;
+/** Read-only observer invoked before an MCP handler runs. */
+export type McpEventListenerFn<Methods extends McpMiddlewareMethod = McpMiddlewareMethod, TEnv extends Env = Env> = <M extends Methods>(ctx: ReadonlyMiddlewareContext<M, TEnv>) => void;
+/** Read-only observer invoked after an MCP handler completes. */
+export type McpCompleteEventListenerFn<Methods extends McpMiddlewareMethod = McpMiddlewareMethod, TEnv extends Env = Env> = <M extends Methods>(ctx: ReadonlyMiddlewareContext<M, TEnv>, result: McpMiddlewareResult<M>) => void;
+type McpExactEventListenerFn<M extends McpMiddlewareMethod, TEnv extends Env = Env> = (ctx: ReadonlyMiddlewareContext<M, TEnv>) => void;
+type McpExactCompleteEventListenerFn<M extends McpMiddlewareMethod, TEnv extends Env = Env> = (ctx: ReadonlyMiddlewareContext<M, TEnv>, result: McpMiddlewareResult<M>) => void;
+/** MCP observer pattern, optionally targeting the completion phase. */
+export type McpEventPattern = McpEventBasePattern | `${McpEventBasePattern}:complete`;
+type StripCompleteSuffix<P extends string> = P extends `${infer Body}:complete` ? Body : P;
+/** Infer a typed before/complete observer from event pattern `P`. */
+export type McpEventListenerFnFor<P extends McpEventPattern, TEnv extends Env = Env> = StripCompleteSuffix<StripMcpPrefix<P>> extends infer Body ? Body extends McpMiddlewareMethod ? P extends `${string}:complete` ? McpExactCompleteEventListenerFn<Body, TEnv> : McpExactEventListenerFn<Body, TEnv> : P extends `${string}:complete` ? McpCompleteEventListenerFn<McpMiddlewareMethodsForPattern<StripCompleteSuffix<P>>, TEnv> : McpEventListenerFn<McpMiddlewareMethodsForPattern<StripCompleteSuffix<P>>, TEnv> : never;
+/** Internal type-erased observer entry. @internal */
 export interface McpEventListenerEntry {
     pattern: string;
     phase: McpEventPhase;
-    handler: McpEventListenerFn | McpCompleteEventListenerFn;
+    handler: (ctx: ReadonlyMiddlewareContext, result?: unknown) => void;
 }
-/** Read-only observer invoked before the MCP handler runs. */
-export type McpEventListenerFn = (ctx: Readonly<MiddlewareContext>) => void;
-/** Read-only observer invoked after the MCP handler completes. */
-export type McpCompleteEventListenerFn = (ctx: Readonly<MiddlewareContext>, result: unknown) => void;
-/**
- * Test whether a registered middleware pattern matches a given MCP method.
- *
- * Matching rules:
- * - `"*"` matches any method
- * - `"tools/*"` prefix-matches any method starting with `"tools/"`
- * - `"tools/call"` exact-matches only `"tools/call"`
- */
+/** Adapt a public method-correlated observer for type-erased storage. */
+export declare function createMcpEventListenerEntry<P extends McpEventPattern, TEnv extends Env = Env>(pattern: P, handler: McpEventListenerFnFor<P, TEnv>): McpEventListenerEntry;
+/** Test whether a registered middleware or observer pattern matches a method. */
 export declare function matchesPattern(pattern: string, method: string): boolean;
-/**
- * Compose a middleware chain for a given MCP method invocation.
- *
- * Filters `entries` to those matching `method`, then builds a `next()` chain
- * with `innerFn` at the center. Returns the outermost callable.
- *
- * Middleware executes in FIFO registration order (first registered = outermost).
- */
-export declare function composeMiddleware(entries: McpMiddlewareEntry[], method: string, innerFn: () => Promise<unknown>): (ctx: MiddlewareContext) => Promise<unknown>;
+/** Compose matching middleware in FIFO registration order. */
+export declare function composeMiddleware<M extends McpMiddlewareMethod, TEnv extends Env = Env>(entries: McpMiddlewareEntry[], method: M, innerFn: () => Promise<McpMiddlewareResult<M>>): (ctx: MiddlewareContext<M, TEnv>) => Promise<McpMiddlewareResult<M>>;
 /** Build a read-only snapshot of middleware context for observer events. */
-export declare function freezeMiddlewareContext(ctx: MiddlewareContext): Readonly<MiddlewareContext>;
-/**
- * Run before/complete observer listeners around a middleware chain.
- *
- * Listener throws are logged and do not fail the MCP request.
- */
-export declare function runMcpOperation(middlewares: McpMiddlewareEntry[], events: McpEventListenerEntry[], method: string, ctx: MiddlewareContext, innerFn: () => Promise<unknown>): Promise<unknown>;
-/** Strip `mcp:` prefix and optional `:complete` suffix from observer patterns. */
+export declare function freezeMiddlewareContext<M extends McpMiddlewareMethod, TEnv extends Env = Env>(ctx: MiddlewareContext<M, TEnv>): ReadonlyMiddlewareContext<M, TEnv>;
+/** Run before/complete observers around a method-correlated middleware chain. */
+export declare function runMcpOperation<M extends McpMiddlewareMethod, TEnv extends Env = Env>(middlewares: McpMiddlewareEntry[], events: McpEventListenerEntry[], method: M, ctx: MiddlewareContext<M, TEnv>, innerFn: () => Promise<McpMiddlewareResult<M>>): Promise<McpMiddlewareResult<M>>;
+/** Strip `mcp:` prefix and optional `:complete` suffix from event patterns. */
 export declare function parseMcpPattern(raw: string): {
     pattern: string;
     phase: McpEventPhase;
 };
-/** Normalize middleware pattern strings (strip `mcp:` prefix). */
+/** Normalize middleware pattern strings by stripping the `mcp:` prefix. */
 export declare function normalizeMcpMiddlewarePattern(raw: string): string;
 export {};
-//# sourceMappingURL=mcp-middleware.d.ts.map

package/dist/mount-mcp.d.ts

@@ -44,4 +44,3 @@ export interface McpMount {
  * ```
  */
 export declare function createMcpMount(factory: McpServerFactory, options?: MountMcpOptions): McpMount;
-//# sourceMappingURL=mount-mcp.d.ts.map