fastmcp 3.12.0 → 3.14.0

package/src/FastMCP.ts

@@ -38,6 +38,14 @@ import parseURITemplate from "uri-templates";
 import { toJsonSchema } from "xsschema";
 import { z } from "zod";
 
+export interface Logger {
+  debug(...args: unknown[]): void;
+  error(...args: unknown[]): void;
+  info(...args: unknown[]): void;
+  log(...args: unknown[]): void;
+  warn(...args: unknown[]): void;
+}
+
 export type SSEServer = {
   close: () => Promise<void>;
 };
@@ -570,6 +578,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;
 
   /**
@@ -924,6 +937,7 @@ export class FastMCPSession<
   #capabilities: ServerCapabilities = {};
   #clientCapabilities?: ClientCapabilities;
   #connectionState: "closed" | "connecting" | "error" | "ready" = "connecting";
+  #logger: Logger;
   #loggingLevel: LoggingLevel = "info";
   #needsEventLoopFlush: boolean = false;
   #pingConfig?: ServerOptions<T>["ping"];
@@ -947,6 +961,7 @@ export class FastMCPSession<
   constructor({
     auth,
     instructions,
+    logger,
     name,
     ping,
     prompts,
@@ -960,6 +975,7 @@ export class FastMCPSession<
   }: {
     auth?: T;
     instructions?: string;
+    logger: Logger;
     name: string;
     ping?: ServerOptions<T>["ping"];
     prompts: Prompt<T>[];
@@ -974,6 +990,7 @@ export class FastMCPSession<
     super();
 
     this.#auth = auth;
+    this.#logger = logger;
     this.#pingConfig = ping;
     this.#rootsConfig = roots;
     this.#needsEventLoopFlush = transportType === "httpStream";
@@ -1043,7 +1060,7 @@ export class FastMCPSession<
     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);
     }
   }
 
@@ -1073,7 +1090,7 @@ export class FastMCPSession<
       }
 
       if (!this.#clientCapabilities) {
-        console.warn(
+        this.#logger.warn(
           `[FastMCP warning] could not infer client capabilities after ${maxAttempts} attempts. Connection may be unstable.`,
         );
       }
@@ -1087,11 +1104,11 @@ export class FastMCPSession<
           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.\n\n${
                 e instanceof Error ? e.stack : JSON.stringify(e)
               }`,
@@ -1114,17 +1131,17 @@ export class FastMCPSession<
               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);
@@ -1360,7 +1377,7 @@ export class FastMCPSession<
 
   private setupErrorHandling() {
     this.#server.onerror = (error) => {
-      console.error("[FastMCP error]", error);
+      this.#logger.error("[FastMCP error]", error);
     };
   }
 
@@ -1564,7 +1581,7 @@ export class FastMCPSession<
 
   private setupRootsHandlers() {
     if (this.#rootsConfig?.enabled === false) {
-      console.debug(
+      this.#logger.debug(
         "[FastMCP debug] roots capability explicitly disabled via config",
       );
       return;
@@ -1589,11 +1606,11 @@ export class FastMCPSession<
                 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.\n\n${
                     error instanceof Error ? error.stack : JSON.stringify(error)
                   }`,
@@ -1603,7 +1620,7 @@ export class FastMCPSession<
         },
       );
     } else {
-      console.debug(
+      this.#logger.debug(
         "[FastMCP debug] roots capability not available, not setting up notification handler",
       );
     }
@@ -1686,7 +1703,7 @@ export class FastMCPSession<
               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
@@ -1753,7 +1770,7 @@ export class FastMCPSession<
               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
@@ -1879,6 +1896,7 @@ export class FastMCP<
   }
   #authenticate: Authenticate<T> | undefined;
   #httpStreamServer: null | SSEServer = null;
+  #logger: Logger;
   #options: ServerOptions<T>;
   #prompts: InputPrompt<T>[] = [];
   #resources: Resource<T>[] = [];
@@ -1892,6 +1910,7 @@ export class FastMCP<
 
     this.#options = options;
     this.#authenticate = options.authenticate;
+    this.#logger = options.logger || console;
   }
 
   /**
@@ -2018,6 +2037,7 @@ export class FastMCP<
         endpoint?: `/${string}`;
         eventStore?: EventStore;
         port: number;
+        stateless?: boolean;
       };
       transportType: "httpStream" | "stdio";
     }>,
@@ -2028,6 +2048,7 @@ export class FastMCP<
       const transport = new StdioServerTransport();
       const session = new FastMCPSession<T>({
         instructions: this.#options.instructions,
+        logger: this.#logger,
         name: this.#options.name,
         ping: this.#options.ping,
         prompts: this.#prompts,
@@ -2050,151 +2071,86 @@ export class FastMCP<
     } else if (config.transportType === "httpStream") {
       const httpConfig = config.httpStream;
 
-      this.#httpStreamServer = await startHTTPServer<FastMCPSession<T>>({
-        createServer: async (request) => {
-          let auth: T | undefined;
-
-          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<T>({
-            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: session as FastMCPSession<FastMCPSessionAuth>,
-          });
-        },
-        onConnect: async (session) => {
-          this.#sessions.push(session);
-
-          console.info(`[FastMCP info] HTTP Stream session established`);
-
-          this.emit("connect", {
-            session: session as FastMCPSession<FastMCPSessionAuth>,
-          });
-        },
-
-        onUnhandledRequest: async (req, res) => {
-          const healthConfig = this.#options.health ?? {};
+      if (httpConfig.stateless) {
+        // Stateless mode - create new server instance for each request
+        this.#logger.info(
+          `[FastMCP info] Starting server in stateless mode on HTTP Stream at http://localhost:${httpConfig.port}${httpConfig.endpoint}`,
+        );
 
-          const enabled =
-            healthConfig.enabled === undefined ? true : healthConfig.enabled;
+        this.#httpStreamServer = await startHTTPServer<FastMCPSession<T>>({
+          createServer: async (request) => {
+            let auth: T | undefined;
 
-          if (enabled) {
-            const path = healthConfig.path ?? "/health";
-            const url = new URL(req.url || "", "http://localhost");
+            if (this.#authenticate) {
+              auth = await this.#authenticate(request);
+            }
 
-            try {
-              if (req.method === "GET" && url.pathname === path) {
-                res
-                  .writeHead(healthConfig.status ?? 200, {
-                    "Content-Type": "text/plain",
-                  })
-                  .end(healthConfig.message ?? "✓ Ok");
-
-                return;
-              }
+            // In stateless mode, create a new session for each request
+            // without persisting it in the sessions array
+            return this.#createSession(auth);
+          },
+          enableJsonResponse: httpConfig.enableJsonResponse,
+          eventStore: httpConfig.eventStore,
+          // In stateless mode, we don't track sessions
+          onClose: async () => {
+            // No session tracking in stateless mode
+          },
+          onConnect: async () => {
+            // No persistent session tracking in stateless mode
+            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 {
+        // Regular mode with session management
+        this.#httpStreamServer = await startHTTPServer<FastMCPSession<T>>({
+          createServer: async (request) => {
+            let auth: T | undefined;
 
-              // Enhanced readiness check endpoint
-              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);
+            if (this.#authenticate) {
+              auth = await this.#authenticate(request);
             }
-          }
 
-          // Handle OAuth well-known endpoints
-          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;
-            }
+            return this.#createSession(auth);
+          },
+          enableJsonResponse: httpConfig.enableJsonResponse,
+          eventStore: httpConfig.eventStore,
+          onClose: async (session) => {
+            this.emit("disconnect", {
+              session: session as FastMCPSession<FastMCPSessionAuth>,
+            });
+          },
+          onConnect: async (session) => {
+            this.#sessions.push(session);
 
-            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;
-            }
-          }
+            this.#logger.info(`[FastMCP info] HTTP Stream session established`);
 
-          // If the request was not handled above, return 404
-          res.writeHead(404).end();
-        },
-        port: httpConfig.port,
-        streamEndpoint: httpConfig.endpoint,
-      });
+            this.emit("connect", {
+              session: session as FastMCPSession<FastMCPSessionAuth>,
+            });
+          },
 
-      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)`,
-      );
+          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");
     }
@@ -2209,12 +2165,154 @@ export class FastMCP<
     }
   }
 
+  /**
+   * Creates a new FastMCPSession instance with the current configuration.
+   * Used both for regular sessions and stateless requests.
+   */
+  #createSession(auth?: T): FastMCPSession<T> {
+    const allowedTools = auth
+      ? this.#tools.filter((tool) =>
+          tool.canAccess ? tool.canAccess(auth) : true,
+        )
+      : this.#tools;
+    return new FastMCPSession<T>({
+      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: http.IncomingMessage,
+    res: http.ServerResponse,
+    isStateless = false,
+  ) => {
+    const healthConfig = this.#options.health ?? {};
+
+    const enabled =
+      healthConfig.enabled === undefined ? 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 ?? "✓ Ok");
+
+          return;
+        }
+
+        // Enhanced readiness check endpoint
+        if (req.method === "GET" && url.pathname === "/ready") {
+          if (isStateless) {
+            // In stateless mode, we're always ready if the server is running
+            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);
+      }
+    }
+
+    // Handle OAuth well-known endpoints
+    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;
+      }
+    }
+
+    // If the request was not handled above, return 404
+    res.writeHead(404).end();
+  };
   #parseRuntimeConfig(
     overrides?: Partial<{
       httpStream: {
         enableJsonResponse?: boolean;
         endpoint?: `/${string}`;
         port: number;
+        stateless?: boolean;
       };
       transportType: "httpStream" | "stdio";
     }>,
@@ -2225,6 +2323,7 @@ export class FastMCP<
           endpoint: `/${string}`;
           eventStore?: EventStore;
           port: number;
+          stateless?: boolean;
         };
         transportType: "httpStream";
       }
@@ -2241,10 +2340,12 @@ export class FastMCP<
     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;
 
     // Overrides > CLI > env > defaults
     const transportType =
@@ -2261,12 +2362,18 @@ export class FastMCP<
         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: endpoint as `/${string}`,
           port,
+          stateless,
         },
         transportType: "httpStream" as const,
       };