fastmcp 1.27.7 → 2.1.0

package/src/FastMCP.ts

@@ -25,7 +25,7 @@ import { fileTypeFromBuffer } from "file-type";
 import { readFile } from "fs/promises";
 import Fuse from "fuse.js";
 import http from "http";
-import { startHTTPStreamServer, startSSEServer } from "mcp-proxy";
+import { startHTTPServer } from "mcp-proxy";
 import { StrictEventEmitter } from "strict-event-emitter-types";
 import { setTimeout as delay } from "timers/promises";
 import { fetch } from "undici";
@@ -180,6 +180,7 @@ type Context<T extends FastMCPSessionAuth> = {
   };
   reportProgress: (progress: Progress) => Promise<void>;
   session: T | undefined;
+  streamContent: (content: Content | Content[]) => Promise<void>;
 };
 
 type Extra = unknown;
@@ -445,8 +446,44 @@ type ResourceTemplateArgumentsToObject<T extends { name: string }[]> = {
 
 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?: {
     /**
      * Whether ping should be enabled by default.
@@ -483,13 +520,19 @@ 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
+    AudioContent | ContentResult | ImageContent | string | TextContent | void
   >;
   name: string;
   parameters?: Params;
@@ -767,7 +810,7 @@ export class FastMCPSession<
 
     if ("type" in transport) {
       // Enable by default for SSE and HTTP streaming
-      if (transport.type === "sse" || transport.type === "httpStream") {
+      if (transport.type === "httpStream") {
         defaultEnabled = true;
       }
     }
@@ -1266,14 +1309,29 @@ export class FastMCPSession<
         };
 
         // Create a promise for tool execution
+        // Streams partial results while a tool is still executing
+        // Enables progressive rendering and real-time feedback
+        const streamContent = async (content: Content | 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,
+          streamContent,
         });
 
         // Handle timeout if specified
-        const maybeStringResult = await (tool.timeoutMs
+        const maybeStringResult = (await (tool.timeoutMs
           ? Promise.race([
               executeToolPromise,
               new Promise<never>((_, reject) => {
@@ -1286,9 +1344,20 @@ export class FastMCPSession<
                 }, tool.timeoutMs);
               }),
             ])
-          : executeToolPromise);
-
-        if (typeof maybeStringResult === "string") {
+          : executeToolPromise)) as
+          | AudioContent
+          | ContentResult
+          | ImageContent
+          | null
+          | string
+          | TextContent
+          | undefined;
+
+        if (maybeStringResult === undefined || maybeStringResult === null) {
+          result = ContentResultZodSchema.parse({
+            content: [],
+          });
+        } else if (typeof maybeStringResult === "string") {
           result = ContentResultZodSchema.parse({
             content: [{ text: maybeStringResult, type: "text" }],
           });
@@ -1339,7 +1408,6 @@ export class FastMCP<
   #resources: Resource[] = [];
   #resourcesTemplates: InputResourceTemplate[] = [];
   #sessions: FastMCPSession<T>[] = [];
-  #sseServer: null | SSEServer = null;
 
   #tools: Tool<T>[] = [];
 
@@ -1388,13 +1456,9 @@ export class FastMCP<
   public async start(
     options:
       | {
-          httpStream: { endpoint: `/${string}`; port: number };
+          httpStream: { port: number };
           transportType: "httpStream";
         }
-      | {
-          sse: { endpoint: `/${string}`; port: number };
-          transportType: "sse";
-        }
       | { transportType: "stdio" } = {
       transportType: "stdio",
     },
@@ -1421,8 +1485,8 @@ export class FastMCP<
       this.emit("connect", {
         session,
       });
-    } else if (options.transportType === "sse") {
-      this.#sseServer = await startSSEServer<FastMCPSession<T>>({
+    } else if (options.transportType === "httpStream") {
+      this.#httpStreamServer = await startHTTPServer<FastMCPSession<T>>({
         createServer: async (request) => {
           let auth: T | undefined;
 
@@ -1442,7 +1506,6 @@ export class FastMCP<
             version: this.#options.version,
           });
         },
-        endpoint: options.sse.endpoint as `/${string}`,
         onClose: (session) => {
           this.emit("disconnect", {
             session,
@@ -1455,51 +1518,41 @@ export class FastMCP<
             session,
           });
         },
-        port: options.sse.port,
-      });
+        onUnhandledRequest: async (req, res) => {
+          const healthConfig = this.#options.health ?? {};
 
-      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<FastMCPSession<T>>({
-        createServer: async (request) => {
-          let auth: T | undefined;
+          const enabled =
+            healthConfig.enabled === undefined ? true : healthConfig.enabled;
 
-          if (this.#authenticate) {
-            auth = await this.#authenticate(request);
-          }
+          if (enabled) {
+            const path = healthConfig.path ?? "/health";
 
-          return new FastMCPSession<T>({
-            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 as `/${string}`,
-        onClose: (session) => {
-          this.emit("disconnect", {
-            session,
-          });
-        },
-        onConnect: async (session) => {
-          this.#sessions.push(session);
+            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");
 
-          this.emit("connect", {
-            session,
-          });
+                return;
+              }
+            } catch (error) {
+              console.error("[FastMCP error] health endpoint error", error);
+            }
+          }
+
+          // If the request was not handled above, return 404
+          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");
@@ -1510,9 +1563,6 @@ export class FastMCP<
    * Stops the server.
    */
   public async stop() {
-    if (this.#sseServer) {
-      await this.#sseServer.close();
-    }
     if (this.#httpStreamServer) {
       await this.#httpStreamServer.close();
     }

package/src/examples/addition.ts

@@ -1,8 +1,12 @@
 /**
- * This is an example of a FastMCP server that adds two numbers.
+ * Example FastMCP server demonstrating core functionality plus streaming output.
  *
- * If you are looking for a complete example of an MCP server repository,
- * see https://github.com/punkpeye/fastmcp-boilerplate
+ * Features demonstrated:
+ * - Basic tool with type-safe parameters
+ * - Streaming-enabled tool for incremental output
+ * - Advanced tool annotations
+ *
+ * For a complete project template, see https://github.com/punkpeye/fastmcp-boilerplate
  */
 import { type } from "arktype";
 import * as v from "valibot";
@@ -118,6 +122,39 @@ server.addResource({
   uri: "file:///logs/app.log",
 });
 
+server.addTool({
+  annotations: {
+    openWorldHint: false,
+    readOnlyHint: true,
+    streamingHint: true,
+  },
+  description: "Generate a poem line by line with streaming output",
+  execute: async (args, context) => {
+    const { theme } = args;
+    const lines = [
+      `Poem about ${theme} - line 1`,
+      `Poem about ${theme} - line 2`,
+      `Poem about ${theme} - line 3`,
+      `Poem about ${theme} - line 4`,
+    ];
+
+    for (const line of lines) {
+      await context.streamContent({
+        text: line,
+        type: "text",
+      });
+
+      await new Promise((resolve) => setTimeout(resolve, 1000));
+    }
+
+    return;
+  },
+  name: "stream-poem",
+  parameters: z.object({
+    theme: z.string().describe("Theme for the poem"),
+  }),
+});
+
 server.addPrompt({
   arguments: [
     {
@@ -144,7 +181,6 @@ if (transportType === "httpStream") {
 
   server.start({
     httpStream: {
-      endpoint: "/stream",
       port: PORT,
     },
     transportType: "httpStream",