fastmcp 4.10.0 → 4.12.0

package/README.md

@@ -33,6 +33,7 @@ A TypeScript framework for building [MCP](https://glama.ai/mcp) servers capable
 - [Configurable ping behavior](#configurable-ping-behavior)
 - [Health-check endpoint](#health-check-endpoint)
 - [Roots](#roots-management)
+- [In-memory transport](#unit-testing-with-an-in-memory-transport) for unit testing without binding a port
 - CLI for [testing](#test-with-mcp-cli) and [debugging](#inspect-with-mcp-inspector)
 
 ## When to use FastMCP over the official SDK?
@@ -1228,15 +1229,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 +1264,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 +1278,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 +1333,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",
@@ -2478,6 +2526,51 @@ session.on("error", (event) => {
 
 ## Running Your Server
 
+### Unit testing with an in-memory transport
+
+`server.connect(transport)` attaches the server to a transport you construct yourself, instead of letting `start()` create one. Paired with the SDK's `InMemoryTransport`, this lets you drive a server in-process — no port to bind, no subprocess to spawn — which is usually what you want for testing a `stdio` server:
+
+```ts
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+
+async function createTestClient(server: FastMCP) {
+  const [clientTransport, serverTransport] =
+    InMemoryTransport.createLinkedPair();
+
+  const client = new Client({ name: "test-client", version: "0.0.0" });
+
+  const [session] = await Promise.all([
+    server.connect(serverTransport),
+    client.connect(clientTransport),
+  ]);
+
+  return { client, session };
+}
+
+test("adds two numbers", async () => {
+  const { client } = await createTestClient(server);
+
+  expect(
+    await client.callTool({ arguments: { a: 2, b: 3 }, name: "add" }),
+  ).toEqual({
+    content: [{ text: "5", type: "text" }],
+  });
+
+  await client.close();
+});
+```
+
+The session is built from the tools, resources and prompts registered on the instance, exactly as `start()` builds it, so your tests exercise the same wiring the real server uses — including `canAccess` filtering and the `connect`/`disconnect` events.
+
+Pass session auth as the second argument, equivalent to what your `authenticate` function would return:
+
+```ts
+await server.connect(serverTransport, { id: 7, role: "admin" });
+```
+
+`connect` returns the [`FastMCPSession`](#fastmcpsession), so you can assert on `session.clientCapabilities`, `session.roots`, and the rest. The transport's lifecycle belongs to you: `stop()` does not close transports passed to `connect`, so close the client (and the session, if you need `disconnect` to fire) when the test finishes.
+
 ### Test with `mcp-cli`
 
 The fastest way to test and debug your server is with `fastmcp dev`:

package/dist/FastMCP.cjs

@@ -8,7 +8,7 @@
 
 
 
-var _chunkGF4ORBWZcjs = require('./chunk-GF4ORBWZ.cjs');
+var _chunkPGTM33AUcjs = require('./chunk-PGTM33AU.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 = _chunkPGTM33AUcjs.DiscoveryDocumentCache; exports.FastMCP = _chunkPGTM33AUcjs.FastMCP; exports.FastMCPSession = _chunkPGTM33AUcjs.FastMCPSession; exports.GitHubProvider = _chunkDZYT6QAHcjs.GitHubProvider; exports.GoogleProvider = _chunkDZYT6QAHcjs.GoogleProvider; exports.OAuthProvider = _chunkDZYT6QAHcjs.OAuthProvider; exports.ServerState = _chunkPGTM33AUcjs.ServerState; exports.UnexpectedStateError = _chunkPGTM33AUcjs.UnexpectedStateError; exports.UserError = _chunkPGTM33AUcjs.UserError; exports.audioContent = _chunkPGTM33AUcjs.audioContent; exports.getAuthSession = _chunkDZYT6QAHcjs.getAuthSession; exports.imageContent = _chunkPGTM33AUcjs.imageContent; exports.jsonSchemaAdapter = _chunkPGTM33AUcjs.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;
@@ -888,6 +914,34 @@ declare class FastMCP<T extends FastMCPSessionAuth = FastMCPSessionAuth> extends
      * Adds tools to the server.
      */
     addTools<Params extends ToolParameters>(tools: Tool<T, Params>[]): void;
+    /**
+     * Connects the server to a transport you constructed yourself, instead of
+     * letting {@link FastMCP.start} create one.
+     *
+     * The session is built from the tools, resources and prompts registered on
+     * this instance — exactly as `start()` does — so tests exercise the same
+     * wiring the real server uses. The main use case is driving a server
+     * in-process over `InMemoryTransport` without binding a port:
+     *
+     * ```ts
+     * const [clientTransport, serverTransport] =
+     *   InMemoryTransport.createLinkedPair();
+     *
+     * await Promise.all([
+     *   server.connect(serverTransport),
+     *   client.connect(clientTransport),
+     * ]);
+     * ```
+     *
+     * The transport's lifecycle belongs to the caller: `stop()` does not close
+     * transports passed here. Close the returned session (or the transport) when
+     * you are done with it.
+     *
+     * @param transport - An already-constructed MCP server transport.
+     * @param auth - Session auth, equivalent to what `authenticate` would return.
+     * @returns The session bound to the transport.
+     */
+    connect(transport: Transport, auth?: T): Promise<FastMCPSession<T>>;
     /**
      * Embeds a resource by URI, making it easy to include resources in tool responses.
      *

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;
@@ -888,6 +914,34 @@ declare class FastMCP<T extends FastMCPSessionAuth = FastMCPSessionAuth> extends
      * Adds tools to the server.
      */
     addTools<Params extends ToolParameters>(tools: Tool<T, Params>[]): void;
+    /**
+     * Connects the server to a transport you constructed yourself, instead of
+     * letting {@link FastMCP.start} create one.
+     *
+     * The session is built from the tools, resources and prompts registered on
+     * this instance — exactly as `start()` does — so tests exercise the same
+     * wiring the real server uses. The main use case is driving a server
+     * in-process over `InMemoryTransport` without binding a port:
+     *
+     * ```ts
+     * const [clientTransport, serverTransport] =
+     *   InMemoryTransport.createLinkedPair();
+     *
+     * await Promise.all([
+     *   server.connect(serverTransport),
+     *   client.connect(clientTransport),
+     * ]);
+     * ```
+     *
+     * The transport's lifecycle belongs to the caller: `stop()` does not close
+     * transports passed here. Close the returned session (or the transport) when
+     * you are done with it.
+     *
+     * @param transport - An already-constructed MCP server transport.
+     * @param auth - Session auth, equivalent to what `authenticate` would return.
+     * @returns The session bound to the transport.
+     */
+    connect(transport: Transport, auth?: T): Promise<FastMCPSession<T>>;
     /**
      * Embeds a resource by URI, making it easy to include resources in tool responses.
      *

package/dist/FastMCP.js

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

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

@@ -1559,6 +1559,53 @@ var FastMCP = class extends FastMCPEventEmitter {
       this.#toolsListChanged(this.#tools);
     }
   }
+  /**
+   * Connects the server to a transport you constructed yourself, instead of
+   * letting {@link FastMCP.start} create one.
+   *
+   * The session is built from the tools, resources and prompts registered on
+   * this instance — exactly as `start()` does — so tests exercise the same
+   * wiring the real server uses. The main use case is driving a server
+   * in-process over `InMemoryTransport` without binding a port:
+   *
+   * ```ts
+   * const [clientTransport, serverTransport] =
+   *   InMemoryTransport.createLinkedPair();
+   *
+   * await Promise.all([
+   *   server.connect(serverTransport),
+   *   client.connect(clientTransport),
+   * ]);
+   * ```
+   *
+   * The transport's lifecycle belongs to the caller: `stop()` does not close
+   * transports passed here. Close the returned session (or the transport) when
+   * you are done with it.
+   *
+   * @param transport - An already-constructed MCP server transport.
+   * @param auth - Session auth, equivalent to what `authenticate` would return.
+   * @returns The session bound to the transport.
+   */
+  async connect(transport, auth) {
+    const session = this.#createSession(auth);
+    await session.connect(transport);
+    this.#sessions.push(session);
+    session.once("error", () => {
+      this.#removeSession(session);
+    });
+    const originalOnClose = transport.onclose;
+    transport.onclose = () => {
+      this.#removeSession(session);
+      if (originalOnClose) {
+        originalOnClose();
+      }
+    };
+    this.emit("connect", {
+      session
+    });
+    this.#serverState = "running" /* Running */;
+    return session;
+  }
   /**
    * Embeds a resource by URI, making it easy to include resources in tool responses.
    *
@@ -2445,4 +2492,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-PGTM33AU.cjs.map