fastmcp 1.27.6 → 2.0.0

package/README.md

@@ -15,10 +15,10 @@ 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)
@@ -87,24 +87,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 +97,6 @@ You can run the server with HTTP streaming support:
 server.start({
   transportType: "httpStream",
   httpStream: {
-    endpoint: "/stream",
     port: 8080,
   },
 });
@@ -125,10 +106,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 +121,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 +143,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);
 ```
@@ -668,6 +649,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 +953,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

@@ -1,6 +1,6 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
-import { AudioContent, Root, ClientCapabilities, CreateMessageRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { Root, ClientCapabilities, CreateMessageRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { EventEmitter } from 'events';
 import http from 'http';
@@ -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>;
@@ -88,7 +89,12 @@ type ImageContent = {
     mimeType: string;
     type: "image";
 };
-type Content = ImageContent | TextContent;
+type AudioContent = {
+    data: string;
+    mimeType: string;
+    type: "audio";
+};
+type Content = AudioContent | ImageContent | TextContent;
 type ContentResult = {
     content: Content[];
     isError?: boolean;
@@ -216,9 +222,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;
@@ -332,16 +344,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";
@@ -163,9 +163,18 @@ var ImageContentZodSchema = z.object({
   mimeType: z.string(),
   type: z.literal("image")
 }).strict();
+var AudioContentZodSchema = z.object({
+  /**
+   * The base64-encoded audio data.
+   */
+  data: z.string().base64(),
+  mimeType: z.string(),
+  type: z.literal("audio")
+}).strict();
 var ContentZodSchema = z.discriminatedUnion("type", [
   TextContentZodSchema,
-  ImageContentZodSchema
+  ImageContentZodSchema,
+  AudioContentZodSchema
 ]);
 var ContentResultZodSchema = z.object({
   content: ContentZodSchema.array(),
@@ -345,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;
       }
     }
@@ -764,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,
@@ -781,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" }]
           });
@@ -828,7 +852,6 @@ var FastMCP = class extends FastMCPEventEmitter {
   #resources = [];
   #resourcesTemplates = [];
   #sessions = [];
-  #sseServer = null;
   #tools = [];
   /**
    * Adds a prompt to the server.
@@ -878,44 +901,8 @@ var FastMCP = class extends FastMCPEventEmitter {
       this.emit("connect", {
         session
       });
-    } else if (options.transportType === "sse") {
-      this.#sseServer = await startSSEServer({
-        createServer: async (request) => {
-          let auth;
-          if (this.#authenticate) {
-            auth = await this.#authenticate(request);
-          }
-          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.sse.endpoint,
-        onClose: (session) => {
-          this.emit("disconnect", {
-            session
-          });
-        },
-        onConnect: async (session) => {
-          this.#sessions.push(session);
-          this.emit("connect", {
-            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({
+      this.#httpStreamServer = await startHTTPServer({
         createServer: async (request) => {
           let auth;
           if (this.#authenticate) {
@@ -933,7 +920,6 @@ var FastMCP = class extends FastMCPEventEmitter {
             version: this.#options.version
           });
         },
-        endpoint: options.httpStream.endpoint,
         onClose: (session) => {
           this.emit("disconnect", {
             session
@@ -948,7 +934,7 @@ var FastMCP = class extends FastMCPEventEmitter {
         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");
@@ -958,9 +944,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();
     }