fastmcp 3.13.0 → 3.14.1

package/README.md

@@ -696,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:
@@ -1713,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>[];
@@ -616,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,
@@ -1092,7 +1098,7 @@ var FastMCP = class extends FastMCPEventEmitter {
     } else if (config.transportType === "httpStream") {
       const httpConfig = config.httpStream;
       if (httpConfig.stateless) {
-        console.info(
+        this.#logger.info(
           `[FastMCP info] Starting server in stateless mode on HTTP Stream at http://localhost:${httpConfig.port}${httpConfig.endpoint}`
         );
         this.#httpStreamServer = await startHTTPServer({
@@ -1109,7 +1115,7 @@ var FastMCP = class extends FastMCPEventEmitter {
           onClose: async () => {
           },
           onConnect: async () => {
-            console.debug(
+            this.#logger.debug(
               `[FastMCP debug] Stateless HTTP Stream request handled`
             );
           },
@@ -1138,7 +1144,7 @@ var FastMCP = class extends FastMCPEventEmitter {
           },
           onConnect: async (session) => {
             this.#sessions.push(session);
-            console.info(`[FastMCP info] HTTP Stream session established`);
+            this.#logger.info(`[FastMCP info] HTTP Stream session established`);
             this.emit("connect", {
               session
             });
@@ -1149,10 +1155,10 @@ var FastMCP = class extends FastMCPEventEmitter {
           port: httpConfig.port,
           streamEndpoint: httpConfig.endpoint
         });
-        console.info(
+        this.#logger.info(
           `[FastMCP info] server is running on HTTP Stream at http://localhost:${httpConfig.port}${httpConfig.endpoint}`
         );
-        console.info(
+        this.#logger.info(
           `[FastMCP info] Transport type: httpStream (Streamable HTTP, not SSE)`
         );
       }
@@ -1178,6 +1184,7 @@ var FastMCP = class extends FastMCPEventEmitter {
     ) : this.#tools;
     return new FastMCPSession({
       auth,
+      logger: this.#logger,
       name: this.#options.name,
       ping: this.#options.ping,
       prompts: this.#prompts,
@@ -1235,7 +1242,7 @@ var FastMCP = class extends FastMCPEventEmitter {
           return;
         }
       } catch (error) {
-        console.error("[FastMCP error] health endpoint error", error);
+        this.#logger.error("[FastMCP error] health endpoint error", error);
       }
     }
     const oauthConfig = this.#options.oauth;