fastmcp 1.27.7 → 2.1.0

package/README.md

@@ -15,14 +15,15 @@ A TypeScript framework for building [MCP](https://glama.ai/mcp) servers capable
 - [Audio content](#returning-an-audio)
 - [Logging](#logging)
 - [Error handling](#errors)
-- [SSE](#sse)
-- [HTTP Streaming](#http-streaming)
+- [HTTP Streaming](#http-streaming) (with SSE compatibility)
 - CORS (enabled by default)
 - [Progress notifications](#progress)
+- [Streaming output](#streaming-output)
 - [Typed server events](#typed-server-events)
 - [Prompt argument auto-completion](#prompt-argument-auto-completion)
 - [Sampling](#requestsampling)
 - [Configurable ping behavior](#configurable-ping-behavior)
+- [Health-check endpoint](#health-check-endpoint)
 - [Roots](#roots-management)
 - CLI for [testing](#test-with-mcp-cli) and [debugging](#inspect-with-mcp-inspector)
 
@@ -87,24 +88,6 @@ If you are looking for a boilerplate repository to build your own MCP server, ch
 
 FastMCP supports multiple transport options for remote communication, allowing an MCP hosted on a remote machine to be accessed over the network.
 
-#### SSE
-
-[Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) (SSE) provide a mechanism for servers to send real-time updates to clients over an HTTPS connection.
-
-You can run the server with SSE support:
-
-```ts
-server.start({
-  transportType: "sse",
-  sse: {
-    endpoint: "/sse",
-    port: 8080,
-  },
-});
-```
-
-This will start the server and listen for SSE connections on `http://localhost:8080/sse`.
-
 #### HTTP Streaming
 
 [HTTP streaming](https://www.cloudflare.com/learning/video/what-is-http-live-streaming/) provides a more efficient alternative to SSE in environments that support it, with potentially better performance for larger payloads.
@@ -115,7 +98,6 @@ You can run the server with HTTP streaming support:
 server.start({
   transportType: "httpStream",
   httpStream: {
-    endpoint: "/stream",
     port: 8080,
   },
 });
@@ -125,10 +107,10 @@ This will start the server and listen for HTTP streaming connections on `http://
 
 You can connect to these servers using the appropriate client transport.
 
-For SSE connections:
+For HTTP streaming connections:
 
 ```ts
-import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 
 const client = new Client(
   {
@@ -140,15 +122,17 @@ const client = new Client(
   },
 );
 
-const transport = new SSEClientTransport(new URL(`http://localhost:8080/sse`));
+const transport = new StreamableHTTPClientTransport(
+  new URL(`http://localhost:8080/stream`),
+);
 
 await client.connect(transport);
 ```
 
-For HTTP streaming connections:
+For SSE connections:
 
 ```ts
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 
 const client = new Client(
   {
@@ -160,9 +144,7 @@ const client = new Client(
   },
 );
 
-const transport = new StreamableHTTPClientTransport(
-  new URL(`http://localhost:8080/stream`),
-);
+const transport = new SSEClientTransport(new URL(`http://localhost:8080/sse`));
 
 await client.connect(transport);
 ```
@@ -420,6 +402,47 @@ By default, ping behavior is optimized for each transport type:
 
 This configurable approach helps reduce log verbosity and optimize performance for different usage scenarios.
 
+### Health-check Endpoint
+
+When you run FastMCP with the `httpStream` transport you can optionally expose a
+simple HTTP endpoint that returns a plain-text response useful for load-balancer
+or container orchestration liveness checks.
+
+Enable (or customise) the endpoint via the `health` key in the server options:
+
+```ts
+const server = new FastMCP({
+  name: "My Server",
+  version: "1.0.0",
+  health: {
+    // Enable / disable (default: true)
+    enabled: true,
+    // Body returned by the endpoint (default: 'ok')
+    message: "healthy",
+    // Path that should respond (default: '/health')
+    path: "/healthz",
+    // HTTP status code to return (default: 200)
+    status: 200,
+  },
+});
+
+await server.start({
+  transportType: "httpStream",
+  httpStream: { port: 8080 },
+});
+```
+
+Now a request to `http://localhost:8080/healthz` will return:
+
+```
+HTTP/1.1 200 OK
+content-type: text/plain
+
+healthy
+```
+
+The endpoint is ignored when the server is started with the `stdio` transport.
+
 #### Roots Management
 
 FastMCP supports [Roots](https://modelcontextprotocol.io/docs/concepts/roots) - Feature that allows clients to provide a set of filesystem-like root locations that can be listed and dynamically updated. The Roots feature can be configured or disabled in server options:
@@ -668,6 +691,86 @@ server.addTool({
 });
 ```
 
+#### 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:
+
+- 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:
+
+```js
+server.addTool({
+  name: "generateText",
+  description: "Generate text incrementally",
+  parameters: z.object({
+    prompt: z.string(),
+  }),
+  annotations: {
+    streamingHint: true, // Signals this tool uses streaming
+    readOnlyHint: true,
+  },
+  execute: async (args, { streamContent }) => {
+    // Send initial content immediately
+    await streamContent({ type: "text", text: "Starting generation...\n" });
+
+    // Simulate incremental content generation
+    const words = "The quick brown fox jumps over the lazy dog.".split(" ");
+    for (const word of words) {
+      await streamContent({ type: "text", text: word + " " });
+      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)
+
+    // Option 1: All content was streamed, so return void
+    return;
+
+    // Option 2: Return final content that will be appended
+    // return "Generation complete!";
+  },
+});
+```
+
+Streaming works with all content types (text, image, audio) and can be combined with progress reporting:
+
+```js
+server.addTool({
+  name: "processData",
+  description: "Process data with streaming updates",
+  parameters: z.object({
+    datasetSize: z.number(),
+  }),
+  annotations: {
+    streamingHint: true,
+  },
+  execute: async (args, { streamContent, reportProgress }) => {
+    const total = args.datasetSize;
+
+    for (let i = 0; i < total; i++) {
+      // Report numeric progress
+      await reportProgress({ progress: i, total });
+
+      // Stream intermediate results
+      if (i % 10 === 0) {
+        await streamContent({
+          type: "text",
+          text: `Processed ${i} of ${total} items...\n`,
+        });
+      }
+
+      await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+
+    return "Processing complete!";
+  },
+});
+```
+
 #### Tool Annotations
 
 As of the MCP Specification (2025-03-26), tools can include annotations that provide richer context and control by adding metadata about a tool's behavior:
@@ -892,8 +995,6 @@ server.addPrompt({
 FastMCP allows you to `authenticate` clients using a custom function:
 
 ```ts
-import { AuthError } from "fastmcp";
-
 const server = new FastMCP({
   name: "My Server",
   version: "1.0.0",

package/dist/FastMCP.d.ts

@@ -49,6 +49,7 @@ type Context<T extends FastMCPSessionAuth> = {
     };
     reportProgress: (progress: Progress) => Promise<void>;
     session: T | undefined;
+    streamContent: (content: Content | Content[]) => Promise<void>;
 };
 type Extra = unknown;
 type Extras = Record<string, Extra>;
@@ -187,6 +188,38 @@ type ResourceTemplateArgumentsToObject<T extends {
 };
 type ServerOptions<T extends FastMCPSessionAuth> = {
     authenticate?: Authenticate<T>;
+    /**
+     * Configuration for the health-check endpoint that can be exposed when the
+     * server is running using the HTTP Stream transport. When enabled, the
+     * server will respond to an HTTP GET request with the configured path (by
+     * default "/health") rendering a plain-text response (by default "ok") and
+     * the configured status code (by default 200).
+     *
+     * The endpoint is only added when the server is started with
+     * `transportType: "httpStream"` – it is ignored for the stdio transport.
+     */
+    health?: {
+        /**
+         * When set to `false` the health-check endpoint is disabled.
+         * @default true
+         */
+        enabled?: boolean;
+        /**
+         * Plain-text body returned by the endpoint.
+         * @default "ok"
+         */
+        message?: string;
+        /**
+         * HTTP path that should be handled.
+         * @default "/health"
+         */
+        path?: string;
+        /**
+         * HTTP response status that will be returned.
+         * @default 200
+         */
+        status?: number;
+    };
     instructions?: string;
     name: string;
     ping?: {
@@ -221,9 +254,15 @@ type ServerOptions<T extends FastMCPSessionAuth> = {
     version: `${number}.${number}.${number}`;
 };
 type Tool<T extends FastMCPSessionAuth, Params extends ToolParameters = ToolParameters> = {
-    annotations?: ToolAnnotations;
+    annotations?: {
+        /**
+         * When true, the tool leverages incremental content streaming
+         * Return void for tools that handle all their output via streaming
+         */
+        streamingHint?: boolean;
+    } & ToolAnnotations;
     description?: string;
-    execute: (args: StandardSchemaV1.InferOutput<Params>, context: Context<T>) => Promise<AudioContent | ContentResult | ImageContent | string | TextContent>;
+    execute: (args: StandardSchemaV1.InferOutput<Params>, context: Context<T>) => Promise<AudioContent | ContentResult | ImageContent | string | TextContent | void>;
     name: string;
     parameters?: Params;
     timeoutMs?: number;
@@ -337,16 +376,9 @@ declare class FastMCP<T extends Record<string, unknown> | undefined = undefined>
      */
     start(options?: {
         httpStream: {
-            endpoint: `/${string}`;
             port: number;
         };
         transportType: "httpStream";
-    } | {
-        sse: {
-            endpoint: `/${string}`;
-            port: number;
-        };
-        transportType: "sse";
     } | {
         transportType: "stdio";
     }): Promise<void>;

package/dist/FastMCP.js

@@ -19,7 +19,7 @@ import { EventEmitter } from "events";
 import { fileTypeFromBuffer } from "file-type";
 import { readFile } from "fs/promises";
 import Fuse from "fuse.js";
-import { startHTTPStreamServer, startSSEServer } from "mcp-proxy";
+import { startHTTPServer } from "mcp-proxy";
 import { setTimeout as delay } from "timers/promises";
 import { fetch } from "undici";
 import parseURITemplate from "uri-templates";
@@ -354,7 +354,7 @@ ${e instanceof Error ? e.stack : JSON.stringify(e)}`
     const pingConfig = this.#pingConfig || {};
     let defaultEnabled = false;
     if ("type" in transport) {
-      if (transport.type === "sse" || transport.type === "httpStream") {
+      if (transport.type === "httpStream") {
         defaultEnabled = true;
       }
     }
@@ -773,10 +773,21 @@ ${e instanceof Error ? e.stack : JSON.stringify(e)}`
             });
           }
         };
+        const streamContent = async (content) => {
+          const contentArray = Array.isArray(content) ? content : [content];
+          await this.#server.notification({
+            method: "notifications/tool/streamContent",
+            params: {
+              content: contentArray,
+              toolName: request.params.name
+            }
+          });
+        };
         const executeToolPromise = tool.execute(args, {
           log,
           reportProgress,
-          session: this.#auth
+          session: this.#auth,
+          streamContent
         });
         const maybeStringResult = await (tool.timeoutMs ? Promise.race([
           executeToolPromise,
@@ -790,7 +801,11 @@ ${e instanceof Error ? e.stack : JSON.stringify(e)}`
             }, tool.timeoutMs);
           })
         ]) : executeToolPromise);
-        if (typeof maybeStringResult === "string") {
+        if (maybeStringResult === void 0 || maybeStringResult === null) {
+          result = ContentResultZodSchema.parse({
+            content: []
+          });
+        } else if (typeof maybeStringResult === "string") {
           result = ContentResultZodSchema.parse({
             content: [{ text: maybeStringResult, type: "text" }]
           });
@@ -837,7 +852,6 @@ var FastMCP = class extends FastMCPEventEmitter {
   #resources = [];
   #resourcesTemplates = [];
   #sessions = [];
-  #sseServer = null;
   #tools = [];
   /**
    * Adds a prompt to the server.
@@ -887,8 +901,8 @@ var FastMCP = class extends FastMCPEventEmitter {
       this.emit("connect", {
         session
       });
-    } else if (options.transportType === "sse") {
-      this.#sseServer = await startSSEServer({
+    } else if (options.transportType === "httpStream") {
+      this.#httpStreamServer = await startHTTPServer({
         createServer: async (request) => {
           let auth;
           if (this.#authenticate) {
@@ -906,7 +920,6 @@ var FastMCP = class extends FastMCPEventEmitter {
             version: this.#options.version
           });
         },
-        endpoint: options.sse.endpoint,
         onClose: (session) => {
           this.emit("disconnect", {
             session
@@ -918,46 +931,28 @@ var FastMCP = class extends FastMCPEventEmitter {
             session
           });
         },
-        port: options.sse.port
-      });
-      console.info(
-        `[FastMCP info] server is running on SSE at http://localhost:${options.sse.port}${options.sse.endpoint}`
-      );
-    } else if (options.transportType === "httpStream") {
-      this.#httpStreamServer = await startHTTPStreamServer({
-        createServer: async (request) => {
-          let auth;
-          if (this.#authenticate) {
-            auth = await this.#authenticate(request);
+        onUnhandledRequest: async (req, res) => {
+          const healthConfig = this.#options.health ?? {};
+          const enabled = healthConfig.enabled === void 0 ? true : healthConfig.enabled;
+          if (enabled) {
+            const path = healthConfig.path ?? "/health";
+            try {
+              if (req.method === "GET" && new URL(req.url || "", "http://localhost").pathname === path) {
+                res.writeHead(healthConfig.status ?? 200, {
+                  "Content-Type": "text/plain"
+                }).end(healthConfig.message ?? "ok");
+                return;
+              }
+            } catch (error) {
+              console.error("[FastMCP error] health endpoint error", error);
+            }
           }
-          return new FastMCPSession({
-            auth,
-            name: this.#options.name,
-            ping: this.#options.ping,
-            prompts: this.#prompts,
-            resources: this.#resources,
-            resourcesTemplates: this.#resourcesTemplates,
-            roots: this.#options.roots,
-            tools: this.#tools,
-            version: this.#options.version
-          });
-        },
-        endpoint: options.httpStream.endpoint,
-        onClose: (session) => {
-          this.emit("disconnect", {
-            session
-          });
-        },
-        onConnect: async (session) => {
-          this.#sessions.push(session);
-          this.emit("connect", {
-            session
-          });
+          res.writeHead(404).end();
         },
         port: options.httpStream.port
       });
       console.info(
-        `[FastMCP info] server is running on HTTP Stream at http://localhost:${options.httpStream.port}${options.httpStream.endpoint}`
+        `[FastMCP info] server is running on HTTP Stream at http://localhost:${options.httpStream.port}/stream`
       );
     } else {
       throw new Error("Invalid transport type");
@@ -967,9 +962,6 @@ var FastMCP = class extends FastMCPEventEmitter {
    * Stops the server.
    */
   async stop() {
-    if (this.#sseServer) {
-      await this.#sseServer.close();
-    }
     if (this.#httpStreamServer) {
       await this.#httpStreamServer.close();
     }