mcp-use 2.0.0-beta.28 → 2.0.0-beta.30

package/dist/{mcp-proxy-QYZQ6LNV.js → mcp-proxy-JK7IC5CR.js}

@@ -214,7 +214,7 @@ function mountPlan(host, plan) {
 async function mountProxyConnection(host, connection) {
   if (host.isStarted()) {
     throw new Error(
-      "Cannot call proxy() after the server has started: register upstream servers before listen()/getHandler()."
+      "Cannot call proxy() after the server has started: register upstream servers before listen()/server.fetch."
     );
   }
   const namespace = connection.info.server.name;
@@ -237,7 +237,7 @@ function toClientConfig(config) {
 async function mountProxyServers(host, servers) {
   if (host.isStarted()) {
     throw new Error(
-      "Cannot call proxy() after the server has started: register upstream servers before listen()/getHandler()."
+      "Cannot call proxy() after the server has started: register upstream servers before listen()/server.fetch."
     );
   }
   const { MCPClient } = await loadProxyClient();

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

@@ -1,4 +1,5 @@
 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];
@@ -49,9 +50,15 @@ export type McpMiddlewareResult<M extends McpMiddlewareMethod> = McpMiddlewareOp
  * @internal
  */
 export declare function withMcpMiddlewareParams<M extends McpMiddlewareMethod>(request: unknown, params: McpMiddlewareOperationMap[M]["params"]): RequestTypeMap[M];
-interface MiddlewareContextCommon {
-    /** The originating HTTP request, when this operation is served over HTTP. */
-    request?: Request;
+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;
@@ -60,19 +67,19 @@ interface MiddlewareContextCommon {
     auth?: AuthInfo;
     /** Shared state for middleware participating in this request. */
     state: Map<string, unknown>;
-}
+};
 /**
  * Context passed to MCP middleware.
  *
  * The conditional form preserves the correlation between `method` and
  * `params` when more than one method is represented.
  */
-export type MiddlewareContext<M extends McpMiddlewareMethod = McpMiddlewareMethod> = M extends McpMiddlewareMethod ? MiddlewareContextCommon & {
+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> = MiddlewareContext<M>;
+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`. */
@@ -86,13 +93,13 @@ 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 = {
-    [M in McpMiddlewareMethod]: MiddlewareContext<M>;
+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> = (ctx: MiddlewareContext<M>, next: McpMiddlewareNext<M>) => Promise<McpMiddlewareResult<M>>;
+export type McpExactMiddlewareFn<M extends McpMiddlewareMethod, TEnv extends Env = Env> = (ctx: MiddlewareContext<M, TEnv>, next: McpMiddlewareNext<M>) => Promise<McpMiddlewareResult<M>>;
 /**
  * Type-preserving middleware over every wrapped MCP method.
  *
@@ -100,19 +107,19 @@ export type McpExactMiddlewareFn<M extends McpMiddlewareMethod> = (ctx: Middlewa
  * resolves after downstream middleware, and the composer propagates that
  * downstream result unchanged. It must call `next()` or throw.
  */
-export type McpMiddlewareFn<Methods extends McpMiddlewareMethod = McpMiddlewareMethod> = (ctx: MiddlewareContext<Methods>, next: () => Promise<void>) => Promise<void>;
+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:` patterns plus prefixless compatibility forms. */
-export type McpMiddlewarePattern = McpMiddlewarePatternBody | `mcp:${McpMiddlewarePatternBody}`;
+/** 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 = McpEventPatternBody | `mcp:${McpEventPatternBody}`;
+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> = StripMcpPrefix<P> extends infer Body ? Body extends McpMiddlewareMethod ? McpExactMiddlewareFn<Body> : McpMiddlewareFn<McpMiddlewareMethodsForPattern<P>> : never;
+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;
 /**
  * Type-erased middleware adapter stored after registration.
  *
@@ -131,27 +138,25 @@ export interface McpMiddlewareEntry {
  * implementation signature is the deliberate erasure boundary, like the
  * official SDK's `setRequestHandler` implementation.
  */
-export declare function createMcpMiddlewareEntry<P extends McpMiddlewarePattern>(pattern: P, handler: McpMiddlewareFnFor<P>): McpMiddlewareEntry;
+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> = M extends McpMiddlewareMethod ? Omit<MiddlewareContext<M>, "params" | "request" | "state"> & {
+export type ReadonlyMiddlewareContext<M extends McpMiddlewareMethod = McpMiddlewareMethod, TEnv extends Env = Env> = M extends McpMiddlewareMethod ? Omit<MiddlewareContext<M, TEnv>, "params" | "state"> & {
     readonly params: Readonly<McpMiddlewareOperationMap[M]["params"]>;
-    /** The originating HTTP request, when this operation is served over HTTP. */
-    readonly request?: Request;
     readonly state: ReadonlyMap<string, unknown>;
 } : never;
 /** Read-only observer invoked before an MCP handler runs. */
-export type McpEventListenerFn<Methods extends McpMiddlewareMethod = McpMiddlewareMethod> = <M extends Methods>(ctx: ReadonlyMiddlewareContext<M>) => void;
+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> = <M extends Methods>(ctx: ReadonlyMiddlewareContext<M>, result: McpMiddlewareResult<M>) => void;
-type McpExactEventListenerFn<M extends McpMiddlewareMethod> = (ctx: ReadonlyMiddlewareContext<M>) => void;
-type McpExactCompleteEventListenerFn<M extends McpMiddlewareMethod> = (ctx: ReadonlyMiddlewareContext<M>, result: McpMiddlewareResult<M>) => void;
+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> = StripCompleteSuffix<StripMcpPrefix<P>> extends infer Body ? Body extends McpMiddlewareMethod ? P extends `${string}:complete` ? McpExactCompleteEventListenerFn<Body> : McpExactEventListenerFn<Body> : P extends `${string}:complete` ? McpCompleteEventListenerFn<McpMiddlewareMethodsForPattern<StripCompleteSuffix<P>>> : McpEventListenerFn<McpMiddlewareMethodsForPattern<StripCompleteSuffix<P>>> : never;
+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;
@@ -159,15 +164,15 @@ export interface McpEventListenerEntry {
     handler: (ctx: ReadonlyMiddlewareContext, result?: unknown) => void;
 }
 /** Adapt a public method-correlated observer for type-erased storage. */
-export declare function createMcpEventListenerEntry<P extends McpEventPattern>(pattern: P, handler: McpEventListenerFnFor<P>): McpEventListenerEntry;
+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 matching middleware in FIFO registration order. */
-export declare function composeMiddleware<M extends McpMiddlewareMethod>(entries: McpMiddlewareEntry[], method: M, innerFn: () => Promise<McpMiddlewareResult<M>>): (ctx: MiddlewareContext<M>) => Promise<McpMiddlewareResult<M>>;
+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<M extends McpMiddlewareMethod>(ctx: MiddlewareContext<M>): ReadonlyMiddlewareContext<M>;
+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>(middlewares: McpMiddlewareEntry[], events: McpEventListenerEntry[], method: M, ctx: MiddlewareContext<M>, innerFn: () => Promise<McpMiddlewareResult<M>>): Promise<McpMiddlewareResult<M>>;
+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;

package/dist/next/index.js

@@ -50,7 +50,7 @@ function createNextHandler(server) {
     server.__primeViews(parseBuildManifest(raw, manifestPath), {
       projectRoot
     });
-    return server.getHandler();
+    return async (request) => server.fetch(request);
   };
   const handle = async (request) => {
     handlerPromise ??= initialize();

package/dist/oauth/index.js

@@ -8,7 +8,7 @@ import {
   oauthMetadataResponse,
   requireBearerAuth,
   verifyBearerToken
-} from "../chunk-26JBVQUY.js";
+} from "../chunk-QKJJ6DWK.js";
 import {
   oauthCustomProvider
 } from "../chunk-YF5X7FYF.js";

package/dist/prompts.d.ts

@@ -1,4 +1,5 @@
-import type { GetPromptResult, StandardSchemaWithJSON } from "@modelcontextprotocol/server";
+import type { CallToolResult, GetPromptResult, StandardSchemaWithJSON } from "@modelcontextprotocol/server";
+import type { Env } from "hono";
 import type { RequestContext } from "./context.js";
 /** Declares a prompt's identity and argument schema. First argument to {@link MCPServer.prompt}. */
 export interface PromptDefinition {
@@ -20,7 +21,10 @@ export type InferPromptInput<T> = T extends {
     schema: infer S extends StandardSchemaWithJSON;
 } ? StandardSchemaWithJSON.InferOutput<S> : Record<string, unknown>;
 /**
- * Prompt execution callback. Returns the SDK's raw {@link GetPromptResult}.
+ * Prompt execution callback. Prefer the SDK's raw {@link GetPromptResult}.
+ *
+ * Deprecated response helpers that return a {@link CallToolResult} are still
+ * accepted and converted at registration time.
  *
  * @example
  * ```ts
@@ -31,4 +35,4 @@ export type InferPromptInput<T> = T extends {
  * })
  * ```
  */
-export type PromptCallback<TInput = Record<string, unknown>, TUser = never, HasOAuth extends boolean = false> = (params: TInput, ctx: RequestContext<TUser, HasOAuth>) => GetPromptResult | Promise<GetPromptResult>;
+export type PromptCallback<TInput = Record<string, unknown>, TUser = never, HasOAuth extends boolean = false, TEnv extends Env = Env> = (params: TInput, ctx: RequestContext<TUser, HasOAuth, TEnv>) => GetPromptResult | CallToolResult | Promise<GetPromptResult | CallToolResult>;

package/dist/react/hooks/use-call-tool.d.ts

@@ -4,7 +4,8 @@ import { type CallToolSuccess } from "../types/result-types.js";
 export type { CallToolSuccess } from "../types/result-types.js";
 export { ToolError } from "../types/result-types.js";
 /**
- * Typed server-tool call handle returned by {@link useCallTool}.
+ * Typed server-tool call handle returned by {@link useCallTool} and
+ * {@link useDynamicTool}.
  *
  * @typeParam Args - Tool argument object type.
  * @typeParam Result - Expected `structuredContent` type for a successful result.
@@ -39,6 +40,15 @@ export interface CallToolHandle<Args, Result> {
     /** Whether a call is in flight. */
     isPending: boolean;
 }
+type ToolNameParameter<Name extends string> = string extends keyof RegisteredTools ? Name : Name extends keyof RegisteredTools ? Name : `Tool "${Name}" is not exported from the server entry. Export the ToolRef returned by server.tool().`;
+type RegisteredToolInput<Name extends string> = Name extends keyof RegisteredTools ? RegisteredTools[Name]["input"] : Record<string, unknown>;
+type RegisteredToolOutput<Name extends string> = Name extends keyof RegisteredTools ? RegisteredTools[Name]["output"] : unknown;
+/**
+ * Call a server tool using a {@link ToolRef} value (inline-JSX stretch path).
+ *
+ * @typeParam R - Tool ref carrying name, input, and output types.
+ */
+export declare function useCallTool<R extends ToolRef<string, unknown, unknown>>(ref: R): CallToolHandle<R extends ToolRef<string, infer I, unknown> ? I : never, R extends ToolRef<string, unknown, infer O> ? O : never>;
 /**
  * Call a registered server tool from the view with inferred types.
  *
@@ -66,17 +76,25 @@ export interface CallToolHandle<Args, Result> {
  * }
  * ```
  */
-export declare function useCallTool<Name extends keyof RegisteredTools>(name: Name): CallToolHandle<RegisteredTools[Name]["input"], RegisteredTools[Name]["output"]>;
+export declare function useCallTool<const Name extends string>(name: ToolNameParameter<Name>): CallToolHandle<RegisteredToolInput<Name>, RegisteredToolOutput<Name>>;
 /**
- * Call a server tool using a {@link ToolRef} value (inline-JSX stretch path).
+ * Call a tool whose registration cannot be represented by an exported
+ * {@link ToolRef}, such as a tool created from a loop, runtime configuration,
+ * or an OpenAPI document.
  *
- * @typeParam R - Tool ref carrying name, input, and output types.
- */
-export declare function useCallTool<R extends ToolRef<string, unknown, unknown>>(ref: R): CallToolHandle<R extends ToolRef<string, infer I, unknown> ? I : never, R extends ToolRef<string, unknown, infer O> ? O : never>;
-/**
- * Call a server tool with explicit argument/result types (escape hatch).
+ * Prefer {@link useCallTool} for statically declared tools. This explicit
+ * escape hatch requires callers to supply the contract because TypeScript
+ * cannot infer runtime-only registrations.
+ *
+ * @example
+ * ```tsx
+ * const lookup = useDynamicTool<{ id: string }, { value: string }>("lookup");
+ * const result = await lookup.callTool({ id: "item-1" });
+ * ```
  *
- * @typeParam Args - Explicit argument object type.
- * @typeParam Result - Explicit `structuredContent` type.
+ * @typeParam Args - Explicit tool argument object type.
+ * @typeParam Result - Expected `structuredContent` type for a successful result.
+ * @param name - Runtime-registered tool name.
+ * @returns A call handle using the explicitly supplied contract.
  */
-export declare function useCallTool<Args extends Record<string, unknown>, Result = unknown>(name: string): CallToolHandle<Args, Result>;
+export declare function useDynamicTool<Args extends Record<string, unknown>, Result = unknown>(name: string): CallToolHandle<Args, Result>;

package/dist/react/index.d.ts

@@ -14,7 +14,7 @@ export { Image } from "./components/image.js";
 export { ModelContext, modelContext } from "./components/model-context.js";
 export { ThemeProvider } from "./components/theme-provider.js";
 export { ViewControls } from "./components/view-controls.js";
-export { useCallTool, type CallToolHandle } from "./hooks/use-call-tool.js";
+export { useCallTool, useDynamicTool, type CallToolHandle, } from "./hooks/use-call-tool.js";
 export { useDisplayMode } from "./hooks/use-display-mode.js";
 export { useFiles } from "./hooks/use-files.js";
 export { useHostContext, type HostContextHandle, } from "./hooks/use-host-context.js";

package/dist/react/index.js

@@ -1318,6 +1318,12 @@ function ViewControls({
 // src/react/hooks/use-call-tool.ts
 import { useCallback, useRef as useRef2, useState as useState3 } from "react";
 function useCallTool(nameOrRef) {
+  return useToolCall(nameOrRef);
+}
+function useDynamicTool(name) {
+  return useToolCall(name);
+}
+function useToolCall(nameOrRef) {
   const toolName = typeof nameOrRef === "string" ? nameOrRef : nameOrRef.name;
   const runtime = useViewRuntime();
   const [data, setData] = useState3(
@@ -1526,6 +1532,7 @@ export {
   toolResultText,
   useCallTool,
   useDisplayMode,
+  useDynamicTool,
   useFiles,
   useHostContext,
   useOpenExternal,

package/dist/react/types/register.d.ts

@@ -4,7 +4,7 @@ export interface Register {
 }
 type RegisteredToolsModule = Register extends {
     tools: infer M;
-} ? M : Record<never, never>;
+} ? M : undefined;
 type ToolsFromModule<M> = {
     [K in keyof M as M[K] extends ToolRef<infer N, any, any> ? N : never]: M[K] extends ToolRef<any, infer I, infer O> ? {
         input: I;
@@ -14,8 +14,16 @@ type ToolsFromModule<M> = {
 /**
  * Map of registered tool names to their inferred input/output types, derived
  * from exported {@link ToolRef} values in the augmented {@link Register} module.
+ *
+ * Projects without an `mcp-env.d.ts` registration retain a loose string map so
+ * existing non-scaffolded applications keep compiling. Once the module is
+ * registered, only exported tool refs are accepted by typed React hooks; an
+ * empty registered module therefore exposes no tool names.
  */
-export type RegisteredTools = ToolsFromModule<RegisteredToolsModule>;
+export type RegisteredTools = RegisteredToolsModule extends undefined ? Record<string, {
+    input: Record<string, unknown>;
+    output: unknown;
+}> : ToolsFromModule<RegisteredToolsModule>;
 /**
  * Recursive partial for streamed JSON: every field optional at every depth.
  *

package/dist/resources.d.ts

@@ -1,4 +1,5 @@
-import type { Annotations, CompleteResourceTemplateCallback, MetaObject, ReadResourceResult } from "@modelcontextprotocol/server";
+import type { Annotations, CallToolResult, CompleteResourceTemplateCallback, MetaObject, ReadResourceResult } from "@modelcontextprotocol/server";
+import type { Env } from "hono";
 import type { RequestContext } from "./context.js";
 /** Declares a static resource at a fixed URI. First argument to {@link MCPServer.resource}. */
 export interface ResourceDefinition {
@@ -27,9 +28,12 @@ export interface ResourceDefinition {
     _meta?: MetaObject;
 }
 /**
- * Resource read callback. Returns the SDK's raw {@link ReadResourceResult};
+ * Resource read callback. Prefer the SDK's raw {@link ReadResourceResult};
  * each `contents` entry addresses itself with the read `uri`.
  *
+ * Deprecated response helpers that return a {@link CallToolResult} are still
+ * accepted and converted at registration time.
+ *
  * @example
  * ```ts
  * async (uri) => ({
@@ -37,7 +41,7 @@ export interface ResourceDefinition {
  * })
  * ```
  */
-export type ResourceCallback<TUser = never, HasOAuth extends boolean = false> = (uri: URL, ctx: RequestContext<TUser, HasOAuth>) => ReadResourceResult | Promise<ReadResourceResult>;
+export type ResourceCallback<TUser = never, HasOAuth extends boolean = false, TEnv extends Env = Env> = (uri: URL, ctx: RequestContext<TUser, HasOAuth, TEnv>) => ReadResourceResult | CallToolResult | Promise<ReadResourceResult | CallToolResult>;
 /**
  * A resource-template variable completer accepted by
  * {@link MCPServer.resourceTemplate}.
@@ -115,6 +119,11 @@ export type InferTemplateParams<T> = T extends {
 } ? string extends U ? Record<string, TemplateVariableValue> : {
     [K in ExtractTemplateVariables<U>]: TemplateVariableValue;
 } : Record<string, TemplateVariableValue>;
-/** Resource template read callback; receives the matched URI and variables. */
-export type ResourceTemplateCallback<TParams = Record<string, TemplateVariableValue>, TUser = never, HasOAuth extends boolean = false> = (uri: URL, params: TParams, ctx: RequestContext<TUser, HasOAuth>) => ReadResourceResult | Promise<ReadResourceResult>;
+/**
+ * Resource template read callback; receives the matched URI and variables.
+ *
+ * Prefer {@link ReadResourceResult}. Deprecated helper-shaped
+ * {@link CallToolResult} returns are still accepted and converted.
+ */
+export type ResourceTemplateCallback<TParams = Record<string, TemplateVariableValue>, TUser = never, HasOAuth extends boolean = false, TEnv extends Env = Env> = (uri: URL, params: TParams, ctx: RequestContext<TUser, HasOAuth, TEnv>) => ReadResourceResult | CallToolResult | Promise<ReadResourceResult | CallToolResult>;
 export {};

package/dist/response-conversion.d.ts

@@ -0,0 +1,25 @@
+import type { CallToolResult, GetPromptResult, ReadResourceResult } from "@modelcontextprotocol/server";
+/**
+ * Convert a helper/`CallToolResult` (or pass through a raw resource result) to
+ * {@link ReadResourceResult}.
+ *
+ * Maps official {@link ContentBlock}s: `text` → text contents, `image`/`audio`
+ * `data` → `blob`, embedded `resource` → unwrap, `resource_link` skipped.
+ * Empty `content` with `structuredContent` becomes a JSON text entry.
+ *
+ * @param result - Tool-shaped or resource result from a resource callback.
+ * @param uri - URI of the resource being read (used for synthesized entries).
+ * @returns Official resource read envelope.
+ */
+export declare function toResourceResult(result: CallToolResult | ReadResourceResult, uri: string): ReadResourceResult;
+/**
+ * Convert a helper/`CallToolResult` (or pass through a raw prompt result) to
+ * {@link GetPromptResult}.
+ *
+ * Each tool {@link ContentBlock} becomes a `user` {@link PromptMessage}
+ * (prompt messages already accept the same content-block union).
+ *
+ * @param result - Tool-shaped or prompt result from a prompt callback.
+ * @returns Official prompt get envelope.
+ */
+export declare function toPromptResult(result: CallToolResult | GetPromptResult): GetPromptResult;

package/dist/response-helpers.d.ts

@@ -0,0 +1,223 @@
+import type { CallToolResult } from "@modelcontextprotocol/server";
+/**
+ * Typed {@link CallToolResult} that constrains `structuredContent` to `T`.
+ *
+ * @deprecated Prefer returning a raw {@link CallToolResult} from tool
+ * callbacks. Example: `{ content: [{ type: "text", text: JSON.stringify(data) }], structuredContent: data }`.
+ *
+ * @typeParam T - Structured payload type (typically an object).
+ */
+export interface TypedCallToolResult<T extends Record<string, unknown> = Record<string, unknown>> {
+    [x: string]: unknown;
+    content: CallToolResult["content"];
+    isError?: CallToolResult["isError"];
+    _meta?: CallToolResult["_meta"];
+    structuredContent?: T;
+}
+/**
+ * Content-only tool result (`structuredContent` pinned to `never`).
+ *
+ * @deprecated Prefer returning a raw {@link CallToolResult}:
+ * `{ content: [{ type: "text", text }] }`.
+ */
+export interface ToolContentResult {
+    [x: string]: unknown;
+    content: CallToolResult["content"];
+    isError?: CallToolResult["isError"];
+    _meta?: CallToolResult["_meta"];
+    structuredContent?: never;
+}
+/**
+ * Create a plain-text tool result.
+ *
+ * @deprecated Prefer `{ content: [{ type: "text", text: content }] }`.
+ *
+ * @param content - Text to return.
+ * @returns Tool result with a single text content block.
+ *
+ * @example
+ * ```ts
+ * // Preferred:
+ * return { content: [{ type: "text", text: `Hello, ${name}!` }] };
+ * // Deprecated:
+ * return text(`Hello, ${name}!`);
+ * ```
+ */
+export declare function text(content: string): ToolContentResult;
+/**
+ * Create a Markdown text tool result.
+ *
+ * @deprecated Prefer `{ content: [{ type: "text", text: content }] }`.
+ *
+ * @param content - Markdown text.
+ * @returns Tool result with `text/markdown` MIME metadata.
+ */
+export declare function markdown(content: string): ToolContentResult;
+/**
+ * Create an HTML text tool result.
+ *
+ * @deprecated Prefer `{ content: [{ type: "text", text: content }] }`.
+ *
+ * @param content - HTML text.
+ * @returns Tool result with `text/html` MIME metadata.
+ */
+export declare function html(content: string): ToolContentResult;
+/**
+ * Create an XML text tool result.
+ *
+ * @deprecated Prefer `{ content: [{ type: "text", text: content }] }`.
+ *
+ * @param content - XML text.
+ * @returns Tool result with `text/xml` MIME metadata.
+ */
+export declare function xml(content: string): ToolContentResult;
+/**
+ * Create a CSS text tool result.
+ *
+ * @deprecated Prefer `{ content: [{ type: "text", text: content }] }`.
+ *
+ * @param content - CSS text.
+ * @returns Tool result with `text/css` MIME metadata.
+ */
+export declare function css(content: string): ToolContentResult;
+/**
+ * Create a JavaScript text tool result.
+ *
+ * @deprecated Prefer `{ content: [{ type: "text", text: content }] }`.
+ *
+ * @param content - JavaScript source text.
+ * @returns Tool result with `text/javascript` MIME metadata.
+ */
+export declare function javascript(content: string): ToolContentResult;
+/**
+ * Create an image content tool result.
+ *
+ * @deprecated Prefer
+ * `{ content: [{ type: "image", data, mimeType }] }`.
+ *
+ * @param data - Base64 image data (or data URL payload).
+ * @param mimeType - Image MIME type.
+ * @returns Tool result with an image content block.
+ *
+ * @defaultValue mimeType - `"image/png"`
+ */
+export declare function image(data: string, mimeType?: string): ToolContentResult;
+/**
+ * Create an audio content tool result from base64 data.
+ *
+ * @deprecated Prefer
+ * `{ content: [{ type: "audio", data, mimeType }] }`.
+ *
+ * @param data - Base64-encoded audio.
+ * @param mimeType - Audio MIME type.
+ * @returns Tool result with an audio content block.
+ *
+ * @defaultValue mimeType - `"audio/wav"`
+ */
+export declare function audio(data: string, mimeType?: string): ToolContentResult;
+/**
+ * Create a binary payload carried as base64 text.
+ *
+ * @deprecated Prefer a raw {@link CallToolResult} with an appropriate content
+ * block, or a resource `{ contents: [{ uri, mimeType, blob }] }`.
+ *
+ * @param base64Data - Base64-encoded bytes.
+ * @param mimeType - MIME type of the binary payload.
+ * @returns Tool result with base64 text and binary MIME metadata.
+ */
+export declare function binary(base64Data: string, mimeType: string): ToolContentResult;
+/**
+ * Create an embedded-resource content block for a tool result.
+ *
+ * Supports `resource(uri, mimeType, text?)` or `resource(uri, callToolResult)`.
+ *
+ * @deprecated Prefer
+ * `{ content: [{ type: "resource", resource: { uri, mimeType, text } }] }`.
+ *
+ * @param uri - Resource URI.
+ * @param mimeTypeOrContent - MIME type string, or a helper/`CallToolResult` to extract from.
+ * @param text - Optional text body (3-arg form).
+ * @returns Tool result with an embedded resource content block.
+ */
+export declare function resource(uri: string, mimeTypeOrContent: string | CallToolResult | TypedCallToolResult, text?: string): ToolContentResult;
+/**
+ * Create a failed tool result.
+ *
+ * @deprecated Prefer
+ * `{ isError: true, content: [{ type: "text", text: message }] }`.
+ *
+ * @param message - Error message shown to the model.
+ * @returns Tool result with `isError: true`.
+ */
+export declare function error(message: string): TypedCallToolResult<never>;
+/**
+ * Create a structured JSON object tool result.
+ *
+ * @deprecated Prefer
+ * `{ content: [{ type: "text", text: JSON.stringify(data) }], structuredContent: data }`.
+ *
+ * @typeParam T - Object payload type.
+ * @param data - Object (or array — forwarded to {@link array}) to return.
+ * @returns Tool result with JSON text and `structuredContent`.
+ */
+export declare function object<T extends Record<string, unknown>>(data: T): TypedCallToolResult<T>;
+/**
+ * Create a structured array tool result (2026 any-JSON root — no `{ data }` wrap).
+ *
+ * @deprecated Prefer
+ * `{ content: [{ type: "text", text: JSON.stringify(data) }], structuredContent: data }`
+ * or `{ content: [], structuredContent: data }` (SDK may auto-append JSON text for
+ * non-object roots).
+ *
+ * @typeParam T - Array payload type.
+ * @param data - Array to return as `structuredContent`.
+ * @returns Tool result with JSON text and the array as `structuredContent`.
+ */
+export declare function array<T extends unknown[]>(data: T): CallToolResult;
+/**
+ * Runtime data for a view-bound tool result (legacy widget helper).
+ *
+ * @deprecated Prefer returning a plain {@link CallToolResult} from a tool
+ * registered with `view: { name }`. Put view props in `structuredContent` and
+ * model-facing text in `content`.
+ *
+ * @typeParam TProps - Props object placed in `structuredContent`.
+ */
+export interface WidgetResponseConfig<TProps extends Record<string, unknown> = Record<string, unknown>> {
+    /** View-facing data sent as `structuredContent`. */
+    props?: TProps;
+    /**
+     * Legacy alias for {@link WidgetResponseConfig.props}.
+     *
+     * @deprecated Use `props` instead.
+     */
+    data?: TProps;
+    /** Model-facing helper/`CallToolResult` whose `content` is forwarded. */
+    output?: CallToolResult | TypedCallToolResult;
+    /** Extra result `_meta` for the view. */
+    metadata?: Record<string, unknown>;
+    /** Override text when `output` is omitted or should be replaced. */
+    message?: string;
+}
+/**
+ * Create a view/widget tool result (`props` → `structuredContent`).
+ *
+ * @deprecated Prefer a plain {@link CallToolResult} with `view:` on the tool
+ * definition:
+ * `{ content: [{ type: "text", text }], structuredContent: props }`.
+ *
+ * @typeParam TProps - Props object type.
+ * @param config - Runtime view data.
+ * @returns Tool result with props in `structuredContent`.
+ */
+export declare function widget<TProps extends Record<string, unknown> = Record<string, unknown>>(config: WidgetResponseConfig<TProps>): TypedCallToolResult<TProps>;
+/**
+ * Merge several tool results into one (`content` concatenated; objects shallow-merged).
+ *
+ * @deprecated Prefer building a single raw {@link CallToolResult} with the
+ * desired `content` array.
+ *
+ * @param results - Results to merge.
+ * @returns Combined tool result.
+ */
+export declare function mix(...results: CallToolResult[]): CallToolResult;