fastmcp 4.10.0 → 4.11.0

package/README.md

@@ -1228,15 +1228,32 @@ server.addTool({
 });
 ```
 
+`reportProgress` accepts an optional human-readable `message` alongside the numeric fields, which clients can display next to the progress indicator:
+
+```js
+await reportProgress({
+  progress: 40,
+  total: 100,
+  message: "Downloading chunk 4 of 10…",
+});
+```
+
+Progress notifications are only emitted when the client opts in by supplying a `progressToken` on the tool call; otherwise `reportProgress` is a no-op. Because `notifications/progress` is part of the MCP specification (the `message` field since revision 2025-03-26), this is the portable way to send incremental updates during a long-running tool call — see [Streaming Output](#streaming-output) below for the difference.
+
 #### Streaming Output
 
-FastMCP supports streaming partial results from tools while they're still executing, enabling responsive UIs and real-time feedback. This is particularly useful for:
+FastMCP can stream partial results from tools while they're still executing, enabling responsive UIs and real-time feedback. This is particularly useful for:
 
 - Long-running operations that generate content incrementally
 - Progressive generation of text, images, or other media
 - Operations where users benefit from seeing immediate partial results
 
-To enable streaming for a tool, add the `streamingHint` annotation and use the `streamContent` method:
+> [!IMPORTANT]
+> `streamContent` is a **FastMCP extension, not part of the MCP specification**. It emits a `notifications/tool/streamContent` notification, which the MCP specification does not define — as of revision `2025-11-25` there is no standard mechanism for streaming tool output ([SEP-2998](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2998) is the in-progress proposal to add one).
+>
+> Clients discard notifications they have no handler registered for, silently and without error. A client only sees streamed content if it registers a handler for the method (or sets a `fallbackNotificationHandler`), and **no client is known to render it as tool output** — MCP Inspector, for example, logs it in its notifications pane via a fallback handler, but the tool result itself still shows only what `execute` returned. Streaming is therefore mainly useful when you also control the client — see [Consuming streamed content](#consuming-streamed-content) below. If you need incremental updates that work on any client, use [`reportProgress`](#progress) with a `message` instead.
+
+To stream from a tool, use the `streamContent` method:
 
 ```js
 server.addTool({
@@ -1246,7 +1263,7 @@ server.addTool({
     prompt: z.string(),
   }),
   annotations: {
-    streamingHint: true, // Signals this tool uses streaming
+    streamingHint: true, // Advisory only; see below
     readOnlyHint: true,
   },
   execute: async (args, { streamContent }) => {
@@ -1260,19 +1277,45 @@ server.addTool({
       await new Promise((resolve) => setTimeout(resolve, 300)); // Simulate delay
     }
 
-    // When using streamContent, you can:
-    // 1. Return void (if all content was streamed)
-    // 2. Return a final result (which will be appended to streamed content)
+    // Always return a final result. Returning nothing sends an empty tool
+    // result, so clients that ignore the streamed notifications see no output
+    // at all.
+    return "The quick brown fox jumps over the lazy dog.";
+  },
+});
+```
 
-    // Option 1: All content was streamed, so return void
-    return;
+> [!WARNING]
+> Returning `undefined` from `execute` produces a tool result with empty `content`. If you stream everything and return nothing, the tool call resolves to an empty result with no indication that anything was lost — including on clients that do log the notification. Return the complete result as well, and treat streamed content purely as a progressive-rendering enhancement.
 
-    // Option 2: Return final content that will be appended
-    // return "Generation complete!";
-  },
+The `streamingHint` annotation is advisory metadata. It is forwarded verbatim to clients in `tools/list`, but it does not enable or gate `streamContent`, and FastMCP itself never reads it. No client is known to act on it today, though [SEP-2998](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2998) proposes standardizing the same annotation name.
+
+##### Consuming streamed content
+
+A client sees these notifications only if it registers a handler for the method (or sets a `fallbackNotificationHandler`):
+
+```ts
+import { z } from "zod";
+
+const StreamContentNotificationSchema = z.object({
+  method: z.literal("notifications/tool/streamContent"),
+  params: z.object({
+    content: z.array(z.any()),
+    toolName: z.string(),
+  }),
 });
+
+client.setNotificationHandler(
+  StreamContentNotificationSchema,
+  (notification) => {
+    const { content, toolName } = notification.params;
+    // Render the partial content however you like.
+  },
+);
 ```
 
+Note that notifications carry only `toolName`, not a request or progress token, so concurrent calls to the same tool on one session cannot be told apart.
+
 Streaming works with all content types (text, image, audio) and can be combined with progress reporting:
 
 ```js
@@ -1289,10 +1332,14 @@ server.addTool({
     const total = args.datasetSize;
 
     for (let i = 0; i < total; i++) {
-      // Report numeric progress
-      await reportProgress({ progress: i, total });
+      // Standard progress notification: reaches every spec-compliant client
+      await reportProgress({
+        progress: i,
+        total,
+        message: `Processed ${i} of ${total} items`,
+      });
 
-      // Stream intermediate results
+      // Richer partial content: only reaches clients that opt in
       if (i % 10 === 0) {
         await streamContent({
           type: "text",

package/dist/FastMCP.cjs

@@ -8,7 +8,7 @@
 
 
 
-var _chunkGF4ORBWZcjs = require('./chunk-GF4ORBWZ.cjs');
+var _chunkISO2WPB5cjs = require('./chunk-ISO2WPB5.cjs');
 
 
 
@@ -43,5 +43,5 @@ var _chunkDZYT6QAHcjs = require('./chunk-DZYT6QAH.cjs');
 
 
 
-exports.AuthProvider = _chunkDZYT6QAHcjs.AuthProvider; exports.AzureProvider = _chunkDZYT6QAHcjs.AzureProvider; exports.DiscoveryDocumentCache = _chunkGF4ORBWZcjs.DiscoveryDocumentCache; exports.FastMCP = _chunkGF4ORBWZcjs.FastMCP; exports.FastMCPSession = _chunkGF4ORBWZcjs.FastMCPSession; exports.GitHubProvider = _chunkDZYT6QAHcjs.GitHubProvider; exports.GoogleProvider = _chunkDZYT6QAHcjs.GoogleProvider; exports.OAuthProvider = _chunkDZYT6QAHcjs.OAuthProvider; exports.ServerState = _chunkGF4ORBWZcjs.ServerState; exports.UnexpectedStateError = _chunkGF4ORBWZcjs.UnexpectedStateError; exports.UserError = _chunkGF4ORBWZcjs.UserError; exports.audioContent = _chunkGF4ORBWZcjs.audioContent; exports.getAuthSession = _chunkDZYT6QAHcjs.getAuthSession; exports.imageContent = _chunkGF4ORBWZcjs.imageContent; exports.jsonSchemaAdapter = _chunkGF4ORBWZcjs.jsonSchemaAdapter; exports.requireAll = _chunkDZYT6QAHcjs.requireAll; exports.requireAny = _chunkDZYT6QAHcjs.requireAny; exports.requireAuth = _chunkDZYT6QAHcjs.requireAuth; exports.requireRole = _chunkDZYT6QAHcjs.requireRole; exports.requireScopes = _chunkDZYT6QAHcjs.requireScopes;
+exports.AuthProvider = _chunkDZYT6QAHcjs.AuthProvider; exports.AzureProvider = _chunkDZYT6QAHcjs.AzureProvider; exports.DiscoveryDocumentCache = _chunkISO2WPB5cjs.DiscoveryDocumentCache; exports.FastMCP = _chunkISO2WPB5cjs.FastMCP; exports.FastMCPSession = _chunkISO2WPB5cjs.FastMCPSession; exports.GitHubProvider = _chunkDZYT6QAHcjs.GitHubProvider; exports.GoogleProvider = _chunkDZYT6QAHcjs.GoogleProvider; exports.OAuthProvider = _chunkDZYT6QAHcjs.OAuthProvider; exports.ServerState = _chunkISO2WPB5cjs.ServerState; exports.UnexpectedStateError = _chunkISO2WPB5cjs.UnexpectedStateError; exports.UserError = _chunkISO2WPB5cjs.UserError; exports.audioContent = _chunkISO2WPB5cjs.audioContent; exports.getAuthSession = _chunkDZYT6QAHcjs.getAuthSession; exports.imageContent = _chunkISO2WPB5cjs.imageContent; exports.jsonSchemaAdapter = _chunkISO2WPB5cjs.jsonSchemaAdapter; exports.requireAll = _chunkDZYT6QAHcjs.requireAll; exports.requireAny = _chunkDZYT6QAHcjs.requireAny; exports.requireAuth = _chunkDZYT6QAHcjs.requireAuth; exports.requireRole = _chunkDZYT6QAHcjs.requireRole; exports.requireScopes = _chunkDZYT6QAHcjs.requireScopes;
 //# sourceMappingURL=FastMCP.cjs.map

package/dist/FastMCP.d.cts

@@ -185,6 +185,22 @@ type Context<T extends FastMCPSessionAuth> = {
      * counters, or maintain user-specific data across multiple requests.
      */
     sessionId?: string;
+    /**
+     * Streams incremental content while the tool is still executing, by emitting
+     * a `notifications/tool/streamContent` notification.
+     *
+     * NOTE: this is a FastMCP extension, not part of the MCP specification. As of
+     * revision 2025-11-25 the spec has no streaming tool output primitive (see
+     * SEP-2998 for the in-progress proposal). A client only receives these
+     * notifications if it registers a handler for the method or sets a
+     * `fallbackNotificationHandler`; otherwise the SDK drops them silently. No
+     * client is known to render them as tool output.
+     *
+     * Always return a final result from `execute` rather than relying on streamed
+     * content alone, otherwise clients that ignore the notification see an empty
+     * tool result. For incremental status that works everywhere, prefer
+     * {@link Context.reportProgress} with a `message`.
+     */
     streamContent: (content: Content | Content[]) => Promise<void>;
 };
 type Extra = unknown;
@@ -199,6 +215,13 @@ type Literal = boolean | null | number | string | undefined;
  */
 type LoadContext<T extends FastMCPSessionAuth> = Omit<Context<T>, "reportProgress" | "streamContent">;
 type Progress = {
+    /**
+     * An optional human-readable message describing the current progress.
+     *
+     * Part of `notifications/progress` since MCP revision 2025-03-26, so unlike
+     * `streamContent` this reaches any spec-compliant client.
+     */
+    message?: string;
     /**
      * The progress thus far. This should increase every time progress is made, even if the total is unknown.
      */
@@ -681,8 +704,11 @@ type Tool<T extends FastMCPSessionAuth, Params extends ToolParameters = ToolPara
     };
     annotations?: {
         /**
-         * When true, the tool leverages incremental content streaming
-         * Return void for tools that handle all their output via streaming
+         * Advisory metadata signalling that the tool streams incremental content
+         * via {@link Context.streamContent}. Forwarded verbatim in `tools/list`.
+         *
+         * This has no effect on FastMCP's behavior: it neither enables nor is
+         * required by `streamContent`. No known client interprets it today.
          */
         streamingHint?: boolean;
     } & ToolAnnotations;

package/dist/FastMCP.d.ts

@@ -185,6 +185,22 @@ type Context<T extends FastMCPSessionAuth> = {
      * counters, or maintain user-specific data across multiple requests.
      */
     sessionId?: string;
+    /**
+     * Streams incremental content while the tool is still executing, by emitting
+     * a `notifications/tool/streamContent` notification.
+     *
+     * NOTE: this is a FastMCP extension, not part of the MCP specification. As of
+     * revision 2025-11-25 the spec has no streaming tool output primitive (see
+     * SEP-2998 for the in-progress proposal). A client only receives these
+     * notifications if it registers a handler for the method or sets a
+     * `fallbackNotificationHandler`; otherwise the SDK drops them silently. No
+     * client is known to render them as tool output.
+     *
+     * Always return a final result from `execute` rather than relying on streamed
+     * content alone, otherwise clients that ignore the notification see an empty
+     * tool result. For incremental status that works everywhere, prefer
+     * {@link Context.reportProgress} with a `message`.
+     */
     streamContent: (content: Content | Content[]) => Promise<void>;
 };
 type Extra = unknown;
@@ -199,6 +215,13 @@ type Literal = boolean | null | number | string | undefined;
  */
 type LoadContext<T extends FastMCPSessionAuth> = Omit<Context<T>, "reportProgress" | "streamContent">;
 type Progress = {
+    /**
+     * An optional human-readable message describing the current progress.
+     *
+     * Part of `notifications/progress` since MCP revision 2025-03-26, so unlike
+     * `streamContent` this reaches any spec-compliant client.
+     */
+    message?: string;
     /**
      * The progress thus far. This should increase every time progress is made, even if the total is unknown.
      */
@@ -681,8 +704,11 @@ type Tool<T extends FastMCPSessionAuth, Params extends ToolParameters = ToolPara
     };
     annotations?: {
         /**
-         * When true, the tool leverages incremental content streaming
-         * Return void for tools that handle all their output via streaming
+         * Advisory metadata signalling that the tool streams incremental content
+         * via {@link Context.streamContent}. Forwarded verbatim in `tools/list`.
+         *
+         * This has no effect on FastMCP's behavior: it neither enables nor is
+         * required by `streamContent`. No known client interprets it today.
          */
         streamingHint?: boolean;
     } & ToolAnnotations;

package/dist/FastMCP.js

@@ -8,7 +8,7 @@ import {
   audioContent,
   imageContent,
   jsonSchemaAdapter
-} from "./chunk-MGP2FVUH.js";
+} from "./chunk-JOZJUFKE.js";
 import {
   AuthProvider,
   AzureProvider,

package/dist/{chunk-GF4ORBWZ.cjs → chunk-ISO2WPB5.cjs}

@@ -2445,4 +2445,4 @@ var FastMCP = class extends FastMCPEventEmitter {
 
 
 exports.DiscoveryDocumentCache = DiscoveryDocumentCache; exports.jsonSchemaAdapter = jsonSchemaAdapter; exports.imageContent = imageContent; exports.audioContent = audioContent; exports.UnexpectedStateError = UnexpectedStateError; exports.UserError = UserError; exports.ServerState = ServerState; exports.FastMCPSession = FastMCPSession; exports.FastMCP = FastMCP;
-//# sourceMappingURL=chunk-GF4ORBWZ.cjs.map
+//# sourceMappingURL=chunk-ISO2WPB5.cjs.map