fastmcp 4.13.1 → 4.14.1

package/README.md

@@ -903,6 +903,52 @@ By default, ping behavior is optimized for each transport type:
 
 This configurable approach helps reduce log verbosity and optimize performance for different usage scenarios.
 
+#### Keeping Long Tool Calls Alive (`streamKeepalive`)
+
+Pings travel on the standalone server-to-client stream, so they never keep an
+individual tool call's connection open — and in `stateless` mode that stream does
+not exist at all. A tool that runs for minutes without producing output leaves
+its response connection silent, and an idle-connection timeout in front of the
+server (AWS ALB defaults to 60 seconds) closes it before the result is written.
+
+This applies to **both** session modes. A stateful deployment keeps its
+standalone stream warm with pings while the connection carrying the tool call
+goes idle and is closed anyway; stateless has no standalone stream to begin
+with.
+
+`streamKeepalive` writes periodically to the in-flight tool call's own response
+stream, which is the connection that would otherwise be closed. It is opt-in:
+
+```ts
+const server = new FastMCP({
+  name: "My Server",
+  version: "1.0.0",
+  streamKeepalive: {
+    // Opt in; disabled by default
+    enabled: true,
+    // Keep comfortably below the shortest idle timeout on the path
+    intervalMs: 20000,
+  },
+});
+```
+
+Each keepalive is a `notifications/message` (level configurable via `logLevel`,
+default `debug`) tagged with the logger `fastmcp-keepalive`, related to the tool
+call being served. Keepalives start when a tool begins executing and stop when
+the request stops waiting for it — on success, error, timeout, or client
+cancellation — so idle connections stay quiet. Because the messages are related
+to the request, this works in stateful and `stateless` mode alike, and needs no
+client support beyond the standard logging notification.
+
+Limits worth knowing:
+
+- It has no effect with `httpStream.enableJsonResponse`, which buffers a single
+  JSON reply instead of streaming, so there is no open stream to write to.
+- It only covers tool calls. Other long-running requests (`resources/read`,
+  `prompts/get`) still write nothing until they finish.
+- On `stdio` there is no proxy to keep alive, so enabling it there only adds
+  notification traffic.
+
 ### Health-check Endpoint
 
 When you run FastMCP with the `httpStream` transport you can optionally expose a

package/dist/FastMCP.cjs

@@ -11,7 +11,7 @@
 
 
 
-var _chunkO72VCMGVcjs = require('./chunk-O72VCMGV.cjs');
+var _chunkB5WJ5VRVcjs = require('./chunk-B5WJ5VRV.cjs');
 
 
 
@@ -49,5 +49,5 @@ var _chunk5FVNY65Mcjs = require('./chunk-5FVNY65M.cjs');
 
 
 
-exports.AuthProvider = _chunk5FVNY65Mcjs.AuthProvider; exports.AzureProvider = _chunk5FVNY65Mcjs.AzureProvider; exports.DiscoveryDocumentCache = _chunkO72VCMGVcjs.DiscoveryDocumentCache; exports.FastMCP = _chunkO72VCMGVcjs.FastMCP; exports.FastMCPError = _chunkO72VCMGVcjs.FastMCPError; exports.FastMCPSession = _chunkO72VCMGVcjs.FastMCPSession; exports.GitHubProvider = _chunk5FVNY65Mcjs.GitHubProvider; exports.GoogleProvider = _chunk5FVNY65Mcjs.GoogleProvider; exports.MEDIA_FETCH_TIMEOUT_MS = _chunkO72VCMGVcjs.MEDIA_FETCH_TIMEOUT_MS; exports.OAuthProvider = _chunk5FVNY65Mcjs.OAuthProvider; exports.ServerState = _chunkO72VCMGVcjs.ServerState; exports.SessionError = _chunkO72VCMGVcjs.SessionError; exports.UnexpectedStateError = _chunkO72VCMGVcjs.UnexpectedStateError; exports.UserError = _chunkO72VCMGVcjs.UserError; exports.audioContent = _chunkO72VCMGVcjs.audioContent; exports.getAuthSession = _chunk5FVNY65Mcjs.getAuthSession; exports.imageContent = _chunkO72VCMGVcjs.imageContent; exports.jsonSchemaAdapter = _chunkO72VCMGVcjs.jsonSchemaAdapter; exports.requireAll = _chunk5FVNY65Mcjs.requireAll; exports.requireAny = _chunk5FVNY65Mcjs.requireAny; exports.requireAuth = _chunk5FVNY65Mcjs.requireAuth; exports.requireRole = _chunk5FVNY65Mcjs.requireRole; exports.requireScopes = _chunk5FVNY65Mcjs.requireScopes;
+exports.AuthProvider = _chunk5FVNY65Mcjs.AuthProvider; exports.AzureProvider = _chunk5FVNY65Mcjs.AzureProvider; exports.DiscoveryDocumentCache = _chunkB5WJ5VRVcjs.DiscoveryDocumentCache; exports.FastMCP = _chunkB5WJ5VRVcjs.FastMCP; exports.FastMCPError = _chunkB5WJ5VRVcjs.FastMCPError; exports.FastMCPSession = _chunkB5WJ5VRVcjs.FastMCPSession; exports.GitHubProvider = _chunk5FVNY65Mcjs.GitHubProvider; exports.GoogleProvider = _chunk5FVNY65Mcjs.GoogleProvider; exports.MEDIA_FETCH_TIMEOUT_MS = _chunkB5WJ5VRVcjs.MEDIA_FETCH_TIMEOUT_MS; exports.OAuthProvider = _chunk5FVNY65Mcjs.OAuthProvider; exports.ServerState = _chunkB5WJ5VRVcjs.ServerState; exports.SessionError = _chunkB5WJ5VRVcjs.SessionError; exports.UnexpectedStateError = _chunkB5WJ5VRVcjs.UnexpectedStateError; exports.UserError = _chunkB5WJ5VRVcjs.UserError; exports.audioContent = _chunkB5WJ5VRVcjs.audioContent; exports.getAuthSession = _chunk5FVNY65Mcjs.getAuthSession; exports.imageContent = _chunkB5WJ5VRVcjs.imageContent; exports.jsonSchemaAdapter = _chunkB5WJ5VRVcjs.jsonSchemaAdapter; exports.requireAll = _chunk5FVNY65Mcjs.requireAll; exports.requireAny = _chunk5FVNY65Mcjs.requireAny; exports.requireAuth = _chunk5FVNY65Mcjs.requireAuth; exports.requireRole = _chunk5FVNY65Mcjs.requireRole; exports.requireScopes = _chunk5FVNY65Mcjs.requireScopes;
 //# sourceMappingURL=FastMCP.cjs.map

package/dist/FastMCP.d.cts

@@ -697,6 +697,36 @@ type ServerOptions<T extends FastMCPSessionAuth> = {
          */
         enabled?: boolean;
     };
+    /**
+     * Writes periodically to an in-flight tool call's own response stream, so a
+     * proxy or load balancer does not close the connection as idle while a
+     * long-running tool produces no output.
+     *
+     * Unlike {@link ServerOptions.ping}, these messages are related to the
+     * request being served, so they travel on that request's stream instead of
+     * the standalone server-to-client stream. That makes them the only option
+     * that works with `httpStream.stateless`, where no standing server-to-client
+     * stream exists.
+     */
+    streamKeepalive?: {
+        /**
+         * Whether to write keepalives. Opt-in.
+         * @default false
+         */
+        enabled?: boolean;
+        /**
+         * Interval between keepalives. Keep it comfortably below the shortest idle
+         * timeout on the path (AWS ALB defaults to 60s). Values below 1ms fall back
+         * to the default.
+         * @default 20000 (20s)
+         */
+        intervalMs?: number;
+        /**
+         * Level reported on the keepalive notification.
+         * @default 'debug'
+         */
+        logLevel?: LoggingLevel;
+    };
     /**
      * General utilities
      */
@@ -840,7 +870,7 @@ declare class FastMCPSession<T extends FastMCPSessionAuth = FastMCPSessionAuth>
     get server(): Server;
     get sessionId(): string | undefined;
     set sessionId(value: string | undefined);
-    constructor({ auth, instructions, logger, name, onToolCall, ping, prompts, resources, resourcesTemplates, roots, sessionId, stateless, tools, transportType, utils, version, }: {
+    constructor({ auth, instructions, logger, name, onToolCall, ping, prompts, resources, resourcesTemplates, roots, sessionId, stateless, streamKeepalive, tools, transportType, utils, version, }: {
         auth?: T;
         instructions?: string;
         logger: Logger;
@@ -853,6 +883,7 @@ declare class FastMCPSession<T extends FastMCPSessionAuth = FastMCPSessionAuth>
         roots?: ServerOptions<T>["roots"];
         sessionId?: string;
         stateless?: boolean;
+        streamKeepalive?: ServerOptions<T>["streamKeepalive"];
         tools: Tool<T>[];
         transportType?: "httpStream" | "stdio";
         utils?: ServerOptions<T>["utils"];

package/dist/FastMCP.d.ts

@@ -697,6 +697,36 @@ type ServerOptions<T extends FastMCPSessionAuth> = {
          */
         enabled?: boolean;
     };
+    /**
+     * Writes periodically to an in-flight tool call's own response stream, so a
+     * proxy or load balancer does not close the connection as idle while a
+     * long-running tool produces no output.
+     *
+     * Unlike {@link ServerOptions.ping}, these messages are related to the
+     * request being served, so they travel on that request's stream instead of
+     * the standalone server-to-client stream. That makes them the only option
+     * that works with `httpStream.stateless`, where no standing server-to-client
+     * stream exists.
+     */
+    streamKeepalive?: {
+        /**
+         * Whether to write keepalives. Opt-in.
+         * @default false
+         */
+        enabled?: boolean;
+        /**
+         * Interval between keepalives. Keep it comfortably below the shortest idle
+         * timeout on the path (AWS ALB defaults to 60s). Values below 1ms fall back
+         * to the default.
+         * @default 20000 (20s)
+         */
+        intervalMs?: number;
+        /**
+         * Level reported on the keepalive notification.
+         * @default 'debug'
+         */
+        logLevel?: LoggingLevel;
+    };
     /**
      * General utilities
      */
@@ -840,7 +870,7 @@ declare class FastMCPSession<T extends FastMCPSessionAuth = FastMCPSessionAuth>
     get server(): Server;
     get sessionId(): string | undefined;
     set sessionId(value: string | undefined);
-    constructor({ auth, instructions, logger, name, onToolCall, ping, prompts, resources, resourcesTemplates, roots, sessionId, stateless, tools, transportType, utils, version, }: {
+    constructor({ auth, instructions, logger, name, onToolCall, ping, prompts, resources, resourcesTemplates, roots, sessionId, stateless, streamKeepalive, tools, transportType, utils, version, }: {
         auth?: T;
         instructions?: string;
         logger: Logger;
@@ -853,6 +883,7 @@ declare class FastMCPSession<T extends FastMCPSessionAuth = FastMCPSessionAuth>
         roots?: ServerOptions<T>["roots"];
         sessionId?: string;
         stateless?: boolean;
+        streamKeepalive?: ServerOptions<T>["streamKeepalive"];
         tools: Tool<T>[];
         transportType?: "httpStream" | "stdio";
         utils?: ServerOptions<T>["utils"];

package/dist/FastMCP.js

@@ -11,7 +11,7 @@ import {
   audioContent,
   imageContent,
   jsonSchemaAdapter
-} from "./chunk-3BMGHXXY.js";
+} from "./chunk-SGCRCQNU.js";
 import {
   AuthProvider,
   AzureProvider,