fastmcp 3.12.0 → 3.14.0

package/README.md

@@ -18,6 +18,7 @@ A TypeScript framework for building [MCP](https://glama.ai/mcp) servers capable
 - [Logging](#logging)
 - [Error handling](#errors)
 - [HTTP Streaming](#http-streaming) (with SSE compatibility)
+- [Stateless mode](#stateless-mode) for serverless deployments
 - CORS (enabled by default)
 - [Progress notifications](#progress)
 - [Streaming output](#streaming-output)
@@ -178,6 +179,52 @@ const transport = new SSEClientTransport(new URL(`http://localhost:8080/sse`));
 await client.connect(transport);
 ```
 
+#### Stateless Mode
+
+FastMCP supports stateless operation for HTTP streaming, where each request is handled independently without maintaining persistent sessions. This is ideal for serverless environments, load-balanced deployments, or when session state isn't required.
+
+In stateless mode:
+
+- No sessions are tracked on the server
+- Each request creates a temporary session that's discarded after the response
+- Reduced memory usage and better scalability
+- Perfect for stateless deployment environments
+
+You can enable stateless mode by adding the `stateless: true` option:
+
+```ts
+server.start({
+  transportType: "httpStream",
+  httpStream: {
+    port: 8080,
+    stateless: true,
+  },
+});
+```
+
+> **Note:** Stateless mode is only available with HTTP streaming transport. Features that depend on persistent sessions (like session-specific state) will not be available in stateless mode.
+
+You can also enable stateless mode using CLI arguments or environment variables:
+
+```bash
+# Via CLI argument
+npx fastmcp dev src/server.ts --transport http-stream --port 8080 --stateless true
+
+# Via environment variable
+FASTMCP_STATELESS=true npx fastmcp dev src/server.ts
+```
+
+The `/ready` health check endpoint will indicate when the server is running in stateless mode:
+
+```json
+{
+  "mode": "stateless",
+  "ready": 1,
+  "status": "ready",
+  "total": 1
+}
+```
+
 ## Core Concepts
 
 ### Tools
@@ -649,6 +696,44 @@ server.addTool({
 });
 ```
 
+#### Custom Logger
+
+FastMCP allows you to provide a custom logger implementation to control how the server logs messages. This is useful for integrating with existing logging infrastructure or customizing log formatting.
+
+```ts
+import { FastMCP, Logger } from "fastmcp";
+
+class CustomLogger implements Logger {
+  debug(...args: unknown[]): void {
+    console.log("[DEBUG]", new Date().toISOString(), ...args);
+  }
+
+  error(...args: unknown[]): void {
+    console.error("[ERROR]", new Date().toISOString(), ...args);
+  }
+
+  info(...args: unknown[]): void {
+    console.info("[INFO]", new Date().toISOString(), ...args);
+  }
+
+  log(...args: unknown[]): void {
+    console.log("[LOG]", new Date().toISOString(), ...args);
+  }
+
+  warn(...args: unknown[]): void {
+    console.warn("[WARN]", new Date().toISOString(), ...args);
+  }
+}
+
+const server = new FastMCP({
+  name: "My Server",
+  version: "1.0.0",
+  logger: new CustomLogger(),
+});
+```
+
+See `src/examples/custom-logger.ts` for examples with Winston, Pino, and file-based logging.
+
 #### Logging
 
 Tools can log messages to the client using the `log` object in the context object:
@@ -1666,6 +1751,7 @@ Refer to this [issue](https://github.com/punkpeye/fastmcp/issues/25#issuecomment
 - [cswkim/discogs-mcp-server](https://github.com/cswkim/discogs-mcp-server) - connects to the Discogs API for interacting with your music collection
 - [Panzer-Jack/feuse-mcp](https://github.com/Panzer-Jack/feuse-mcp) - Frontend Useful MCP Tools - Essential utilities for web developers to automate API integration and code generation
 - [sunra-ai/sunra-clients](https://github.com/sunra-ai/sunra-clients/tree/main/mcp-server) - Sunra.ai is a generative media platform built for developers, providing high-performance AI model inference capabilities.
+- [foxtrottwist/shortcuts-mcp](https://github.com/foxtrottwist/shortcuts-mcp) - connects Claude to macOS Shortcuts for system automation, app integration, and interactive workflows
 
 ## Acknowledgements
 

package/dist/FastMCP.d.ts

@@ -10,6 +10,13 @@ import http from 'http';
 import { StrictEventEmitter } from 'strict-event-emitter-types';
 import { z } from 'zod';
 
+interface Logger {
+    debug(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    log(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+}
 type SSEServer = {
     close: () => Promise<void>;
 };
@@ -247,6 +254,11 @@ type ServerOptions<T extends FastMCPSessionAuth> = {
         status?: number;
     };
     instructions?: string;
+    /**
+     * Custom logger instance. If not provided, defaults to console.
+     * Use this to integrate with your own logging system.
+     */
+    logger?: Logger;
     name: string;
     /**
      * Configuration for OAuth well-known discovery endpoints that can be exposed
@@ -534,9 +546,10 @@ declare class FastMCPSession<T extends FastMCPSessionAuth = FastMCPSessionAuth>
     get loggingLevel(): LoggingLevel;
     get roots(): Root[];
     get server(): Server;
-    constructor({ auth, instructions, name, ping, prompts, resources, resourcesTemplates, roots, tools, transportType, utils, version, }: {
+    constructor({ auth, instructions, logger, name, ping, prompts, resources, resourcesTemplates, roots, tools, transportType, utils, version, }: {
         auth?: T;
         instructions?: string;
+        logger: Logger;
         name: string;
         ping?: ServerOptions<T>["ping"];
         prompts: Prompt<T>[];
@@ -606,6 +619,7 @@ declare class FastMCP<T extends FastMCPSessionAuth = FastMCPSessionAuth> extends
             endpoint?: `/${string}`;
             eventStore?: EventStore;
             port: number;
+            stateless?: boolean;
         };
         transportType: "httpStream" | "stdio";
     }>): Promise<void>;
@@ -615,4 +629,4 @@ declare class FastMCP<T extends FastMCPSessionAuth = FastMCPSessionAuth> extends
     stop(): Promise<void>;
 }
 
-export { type AudioContent, type Content, type ContentResult, type Context, FastMCP, type FastMCPEvents, FastMCPSession, type FastMCPSessionEvents, type ImageContent, type InputPrompt, type InputPromptArgument, type LoggingLevel, type Progress, type Prompt, type PromptArgument, type Resource, type ResourceContent, type ResourceResult, type ResourceTemplate, type ResourceTemplateArgument, type SSEServer, type SerializableValue, type ServerOptions, type TextContent, type Tool, type ToolParameters, UnexpectedStateError, UserError, audioContent, imageContent };
+export { type AudioContent, type Content, type ContentResult, type Context, FastMCP, type FastMCPEvents, FastMCPSession, type FastMCPSessionEvents, type ImageContent, type InputPrompt, type InputPromptArgument, type Logger, type LoggingLevel, type Progress, type Prompt, type PromptArgument, type Resource, type ResourceContent, type ResourceResult, type ResourceTemplate, type ResourceTemplateArgument, type SSEServer, type SerializableValue, type ServerOptions, type TextContent, type Tool, type ToolParameters, UnexpectedStateError, UserError, audioContent, imageContent };

package/dist/FastMCP.js

@@ -237,6 +237,7 @@ var FastMCPSession = class extends FastMCPSessionEventEmitter {
   #capabilities = {};
   #clientCapabilities;
   #connectionState = "connecting";
+  #logger;
   #loggingLevel = "info";
   #needsEventLoopFlush = false;
   #pingConfig;
@@ -251,6 +252,7 @@ var FastMCPSession = class extends FastMCPSessionEventEmitter {
   constructor({
     auth,
     instructions,
+    logger,
     name,
     ping,
     prompts,
@@ -264,6 +266,7 @@ var FastMCPSession = class extends FastMCPSessionEventEmitter {
   }) {
     super();
     this.#auth = auth;
+    this.#logger = logger;
     this.#pingConfig = ping;
     this.#rootsConfig = roots;
     this.#needsEventLoopFlush = transportType === "httpStream";
@@ -316,7 +319,7 @@ var FastMCPSession = class extends FastMCPSessionEventEmitter {
     try {
       await this.#server.close();
     } catch (error) {
-      console.error("[FastMCP error]", "could not close server", error);
+      this.#logger.error("[FastMCP error]", "could not close server", error);
     }
   }
   async connect(transport) {
@@ -338,7 +341,7 @@ var FastMCPSession = class extends FastMCPSessionEventEmitter {
         await delay(retryDelay);
       }
       if (!this.#clientCapabilities) {
-        console.warn(
+        this.#logger.warn(
           `[FastMCP warning] could not infer client capabilities after ${maxAttempts} attempts. Connection may be unstable.`
         );
       }
@@ -348,11 +351,11 @@ var FastMCPSession = class extends FastMCPSessionEventEmitter {
           this.#roots = roots?.roots || [];
         } catch (e) {
           if (e instanceof McpError && e.code === ErrorCode.MethodNotFound) {
-            console.debug(
+            this.#logger.debug(
               "[FastMCP debug] listRoots method not supported by client"
             );
           } else {
-            console.error(
+            this.#logger.error(
               `[FastMCP error] received error listing roots.
 
 ${e instanceof Error ? e.stack : JSON.stringify(e)}`
@@ -369,17 +372,17 @@ ${e instanceof Error ? e.stack : JSON.stringify(e)}`
             } catch {
               const logLevel = pingConfig.logLevel;
               if (logLevel === "debug") {
-                console.debug("[FastMCP debug] server ping failed");
+                this.#logger.debug("[FastMCP debug] server ping failed");
               } else if (logLevel === "warning") {
-                console.warn(
+                this.#logger.warn(
                   "[FastMCP warning] server is not responding to ping"
                 );
               } else if (logLevel === "error") {
-                console.error(
+                this.#logger.error(
                   "[FastMCP error] server is not responding to ping"
                 );
               } else {
-                console.info("[FastMCP info] server ping failed");
+                this.#logger.info("[FastMCP info] server ping failed");
               }
             }
           }, pingConfig.intervalMs);
@@ -565,7 +568,7 @@ ${e instanceof Error ? e.stack : JSON.stringify(e)}`
   }
   setupErrorHandling() {
     this.#server.onerror = (error) => {
-      console.error("[FastMCP error]", error);
+      this.#logger.error("[FastMCP error]", error);
     };
   }
   setupLoggingHandlers() {
@@ -731,7 +734,7 @@ ${e instanceof Error ? e.stack : JSON.stringify(e)}`
   }
   setupRootsHandlers() {
     if (this.#rootsConfig?.enabled === false) {
-      console.debug(
+      this.#logger.debug(
         "[FastMCP debug] roots capability explicitly disabled via config"
       );
       return;
@@ -747,11 +750,11 @@ ${e instanceof Error ? e.stack : JSON.stringify(e)}`
             });
           }).catch((error) => {
             if (error instanceof McpError && error.code === ErrorCode.MethodNotFound) {
-              console.debug(
+              this.#logger.debug(
                 "[FastMCP debug] listRoots method not supported by client"
               );
             } else {
-              console.error(
+              this.#logger.error(
                 `[FastMCP error] received error listing roots.
 
 ${error instanceof Error ? error.stack : JSON.stringify(error)}`
@@ -761,7 +764,7 @@ ${error instanceof Error ? error.stack : JSON.stringify(error)}`
         }
       );
     } else {
-      console.debug(
+      this.#logger.debug(
         "[FastMCP debug] roots capability not available, not setting up notification handler"
       );
     }
@@ -827,7 +830,7 @@ ${error instanceof Error ? error.stack : JSON.stringify(error)}`
               await new Promise((resolve) => setImmediate(resolve));
             }
           } catch (progressError) {
-            console.warn(
+            this.#logger.warn(
               `[FastMCP warning] Failed to report progress for tool '${request.params.name}':`,
               progressError instanceof Error ? progressError.message : String(progressError)
             );
@@ -885,7 +888,7 @@ ${error instanceof Error ? error.stack : JSON.stringify(error)}`
               await new Promise((resolve) => setImmediate(resolve));
             }
           } catch (streamError) {
-            console.warn(
+            this.#logger.warn(
               `[FastMCP warning] Failed to stream content for tool '${request.params.name}':`,
               streamError instanceof Error ? streamError.message : String(streamError)
             );
@@ -968,12 +971,14 @@ var FastMCP = class extends FastMCPEventEmitter {
     this.options = options;
     this.#options = options;
     this.#authenticate = options.authenticate;
+    this.#logger = options.logger || console;
   }
   get sessions() {
     return this.#sessions;
   }
   #authenticate;
   #httpStreamServer = null;
+  #logger;
   #options;
   #prompts = [];
   #resources = [];
@@ -1073,6 +1078,7 @@ var FastMCP = class extends FastMCPEventEmitter {
       const transport = new StdioServerTransport();
       const session = new FastMCPSession({
         instructions: this.#options.instructions,
+        logger: this.#logger,
         name: this.#options.name,
         ping: this.#options.ping,
         prompts: this.#prompts,
@@ -1091,109 +1097,71 @@ var FastMCP = class extends FastMCPEventEmitter {
       });
     } else if (config.transportType === "httpStream") {
       const httpConfig = config.httpStream;
-      this.#httpStreamServer = await startHTTPServer({
-        createServer: async (request) => {
-          let auth;
-          if (this.#authenticate) {
-            auth = await this.#authenticate(request);
-          }
-          const allowedTools = auth ? this.#tools.filter(
-            (tool) => tool.canAccess ? tool.canAccess(auth) : true
-          ) : this.#tools;
-          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: allowedTools,
-            transportType: "httpStream",
-            utils: this.#options.utils,
-            version: this.#options.version
-          });
-        },
-        enableJsonResponse: httpConfig.enableJsonResponse,
-        eventStore: httpConfig.eventStore,
-        onClose: async (session) => {
-          this.emit("disconnect", {
-            session
-          });
-        },
-        onConnect: async (session) => {
-          this.#sessions.push(session);
-          console.info(`[FastMCP info] HTTP Stream session established`);
-          this.emit("connect", {
-            session
-          });
-        },
-        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";
-            const url = new URL(req.url || "", "http://localhost");
-            try {
-              if (req.method === "GET" && url.pathname === path) {
-                res.writeHead(healthConfig.status ?? 200, {
-                  "Content-Type": "text/plain"
-                }).end(healthConfig.message ?? "\u2713 Ok");
-                return;
-              }
-              if (req.method === "GET" && url.pathname === "/ready") {
-                const readySessions = this.#sessions.filter(
-                  (s) => s.isReady
-                ).length;
-                const totalSessions = this.#sessions.length;
-                const allReady = readySessions === totalSessions && totalSessions > 0;
-                const response = {
-                  ready: readySessions,
-                  status: allReady ? "ready" : totalSessions === 0 ? "no_sessions" : "initializing",
-                  total: totalSessions
-                };
-                res.writeHead(allReady ? 200 : 503, {
-                  "Content-Type": "application/json"
-                }).end(JSON.stringify(response));
-                return;
-              }
-            } catch (error) {
-              console.error("[FastMCP error] health endpoint error", error);
-            }
-          }
-          const oauthConfig = this.#options.oauth;
-          if (oauthConfig?.enabled && req.method === "GET") {
-            const url = new URL(req.url || "", "http://localhost");
-            if (url.pathname === "/.well-known/oauth-authorization-server" && oauthConfig.authorizationServer) {
-              const metadata = convertObjectToSnakeCase(
-                oauthConfig.authorizationServer
-              );
-              res.writeHead(200, {
-                "Content-Type": "application/json"
-              }).end(JSON.stringify(metadata));
-              return;
+      if (httpConfig.stateless) {
+        this.#logger.info(
+          `[FastMCP info] Starting server in stateless mode on HTTP Stream at http://localhost:${httpConfig.port}${httpConfig.endpoint}`
+        );
+        this.#httpStreamServer = await startHTTPServer({
+          createServer: async (request) => {
+            let auth;
+            if (this.#authenticate) {
+              auth = await this.#authenticate(request);
             }
-            if (url.pathname === "/.well-known/oauth-protected-resource" && oauthConfig.protectedResource) {
-              const metadata = convertObjectToSnakeCase(
-                oauthConfig.protectedResource
-              );
-              res.writeHead(200, {
-                "Content-Type": "application/json"
-              }).end(JSON.stringify(metadata));
-              return;
+            return this.#createSession(auth);
+          },
+          enableJsonResponse: httpConfig.enableJsonResponse,
+          eventStore: httpConfig.eventStore,
+          // In stateless mode, we don't track sessions
+          onClose: async () => {
+          },
+          onConnect: async () => {
+            this.#logger.debug(
+              `[FastMCP debug] Stateless HTTP Stream request handled`
+            );
+          },
+          onUnhandledRequest: async (req, res) => {
+            await this.#handleUnhandledRequest(req, res, true);
+          },
+          port: httpConfig.port,
+          stateless: true,
+          streamEndpoint: httpConfig.endpoint
+        });
+      } else {
+        this.#httpStreamServer = await startHTTPServer({
+          createServer: async (request) => {
+            let auth;
+            if (this.#authenticate) {
+              auth = await this.#authenticate(request);
             }
-          }
-          res.writeHead(404).end();
-        },
-        port: httpConfig.port,
-        streamEndpoint: httpConfig.endpoint
-      });
-      console.info(
-        `[FastMCP info] server is running on HTTP Stream at http://localhost:${httpConfig.port}${httpConfig.endpoint}`
-      );
-      console.info(
-        `[FastMCP info] Transport type: httpStream (Streamable HTTP, not SSE)`
-      );
+            return this.#createSession(auth);
+          },
+          enableJsonResponse: httpConfig.enableJsonResponse,
+          eventStore: httpConfig.eventStore,
+          onClose: async (session) => {
+            this.emit("disconnect", {
+              session
+            });
+          },
+          onConnect: async (session) => {
+            this.#sessions.push(session);
+            this.#logger.info(`[FastMCP info] HTTP Stream session established`);
+            this.emit("connect", {
+              session
+            });
+          },
+          onUnhandledRequest: async (req, res) => {
+            await this.#handleUnhandledRequest(req, res, false);
+          },
+          port: httpConfig.port,
+          streamEndpoint: httpConfig.endpoint
+        });
+        this.#logger.info(
+          `[FastMCP info] server is running on HTTP Stream at http://localhost:${httpConfig.port}${httpConfig.endpoint}`
+        );
+        this.#logger.info(
+          `[FastMCP info] Transport type: httpStream (Streamable HTTP, not SSE)`
+        );
+      }
     } else {
       throw new Error("Invalid transport type");
     }
@@ -1206,6 +1174,101 @@ var FastMCP = class extends FastMCPEventEmitter {
       await this.#httpStreamServer.close();
     }
   }
+  /**
+   * Creates a new FastMCPSession instance with the current configuration.
+   * Used both for regular sessions and stateless requests.
+   */
+  #createSession(auth) {
+    const allowedTools = auth ? this.#tools.filter(
+      (tool) => tool.canAccess ? tool.canAccess(auth) : true
+    ) : this.#tools;
+    return new FastMCPSession({
+      auth,
+      logger: this.#logger,
+      name: this.#options.name,
+      ping: this.#options.ping,
+      prompts: this.#prompts,
+      resources: this.#resources,
+      resourcesTemplates: this.#resourcesTemplates,
+      roots: this.#options.roots,
+      tools: allowedTools,
+      transportType: "httpStream",
+      utils: this.#options.utils,
+      version: this.#options.version
+    });
+  }
+  /**
+   * Handles unhandled HTTP requests with health, readiness, and OAuth endpoints
+   */
+  #handleUnhandledRequest = async (req, res, isStateless = false) => {
+    const healthConfig = this.#options.health ?? {};
+    const enabled = healthConfig.enabled === void 0 ? true : healthConfig.enabled;
+    if (enabled) {
+      const path = healthConfig.path ?? "/health";
+      const url = new URL(req.url || "", "http://localhost");
+      try {
+        if (req.method === "GET" && url.pathname === path) {
+          res.writeHead(healthConfig.status ?? 200, {
+            "Content-Type": "text/plain"
+          }).end(healthConfig.message ?? "\u2713 Ok");
+          return;
+        }
+        if (req.method === "GET" && url.pathname === "/ready") {
+          if (isStateless) {
+            const response = {
+              mode: "stateless",
+              ready: 1,
+              status: "ready",
+              total: 1
+            };
+            res.writeHead(200, {
+              "Content-Type": "application/json"
+            }).end(JSON.stringify(response));
+          } else {
+            const readySessions = this.#sessions.filter(
+              (s) => s.isReady
+            ).length;
+            const totalSessions = this.#sessions.length;
+            const allReady = readySessions === totalSessions && totalSessions > 0;
+            const response = {
+              ready: readySessions,
+              status: allReady ? "ready" : totalSessions === 0 ? "no_sessions" : "initializing",
+              total: totalSessions
+            };
+            res.writeHead(allReady ? 200 : 503, {
+              "Content-Type": "application/json"
+            }).end(JSON.stringify(response));
+          }
+          return;
+        }
+      } catch (error) {
+        this.#logger.error("[FastMCP error] health endpoint error", error);
+      }
+    }
+    const oauthConfig = this.#options.oauth;
+    if (oauthConfig?.enabled && req.method === "GET") {
+      const url = new URL(req.url || "", "http://localhost");
+      if (url.pathname === "/.well-known/oauth-authorization-server" && oauthConfig.authorizationServer) {
+        const metadata = convertObjectToSnakeCase(
+          oauthConfig.authorizationServer
+        );
+        res.writeHead(200, {
+          "Content-Type": "application/json"
+        }).end(JSON.stringify(metadata));
+        return;
+      }
+      if (url.pathname === "/.well-known/oauth-protected-resource" && oauthConfig.protectedResource) {
+        const metadata = convertObjectToSnakeCase(
+          oauthConfig.protectedResource
+        );
+        res.writeHead(200, {
+          "Content-Type": "application/json"
+        }).end(JSON.stringify(metadata));
+        return;
+      }
+    }
+    res.writeHead(404).end();
+  };
   #parseRuntimeConfig(overrides) {
     const args = process.argv.slice(2);
     const getArg = (name) => {
@@ -1215,9 +1278,11 @@ var FastMCP = class extends FastMCPEventEmitter {
     const transportArg = getArg("transport");
     const portArg = getArg("port");
     const endpointArg = getArg("endpoint");
+    const statelessArg = getArg("stateless");
     const envTransport = process.env.FASTMCP_TRANSPORT;
     const envPort = process.env.FASTMCP_PORT;
     const envEndpoint = process.env.FASTMCP_ENDPOINT;
+    const envStateless = process.env.FASTMCP_STATELESS;
     const transportType = overrides?.transportType || (transportArg === "http-stream" ? "httpStream" : transportArg) || envTransport || "stdio";
     if (transportType === "httpStream") {
       const port = parseInt(
@@ -1225,11 +1290,13 @@ var FastMCP = class extends FastMCPEventEmitter {
       );
       const endpoint = overrides?.httpStream?.endpoint || endpointArg || envEndpoint || "/mcp";
       const enableJsonResponse = overrides?.httpStream?.enableJsonResponse || false;
+      const stateless = overrides?.httpStream?.stateless || statelessArg === "true" || envStateless === "true" || false;
       return {
         httpStream: {
           enableJsonResponse,
           endpoint,
-          port
+          port,
+          stateless
         },
         transportType: "httpStream"
       };