fastmcp 4.15.2 → 4.16.0

package/README.md

@@ -949,6 +949,50 @@ Limits worth knowing:
 - On `stdio` there is no proxy to keep alive, so enabling it there only adds
   notification traffic.
 
+#### Cancelling Long Tool Calls (`context.signal`)
+
+Every `execute` receives an `AbortSignal` that fires once its result can no
+longer reach anyone. Forward it to whatever does the real work so the work stops
+with the call instead of outliving it:
+
+```ts
+server.addTool({
+  name: "fetch_report",
+  parameters: z.object({ url: z.string() }),
+  timeoutMs: 30000,
+  execute: async (args, { signal }) => {
+    const response = await fetch(args.url, { signal });
+    return await response.text();
+  },
+});
+```
+
+It aborts on any of three events:
+
+- **The client cancelled the call** — it sent `notifications/cancelled`, which is
+  what the MCP SDK emits when a caller aborts its own request.
+- **The session ended** — the transport closed, or the session was closed
+  explicitly. No cancellation notification is involved here.
+- **`timeoutMs` elapsed** — `signal.reason` is the same `UserError` the caller
+  receives, so a tool can tell a timeout apart from a cancellation.
+
+The signal is never aborted after a call completes normally, so attaching
+cleanup to it is safe.
+
+Limits worth knowing:
+
+- **Nothing is killed for you.** FastMCP stops waiting for the tool, but the
+  promise `execute` returned keeps running until it settles. A tool that ignores
+  the signal still runs to completion — it just does so with nowhere to report.
+- **An HTTP client that vanishes mid-request is not detected.** The MCP SDK only
+  aborts a request's own signal for an explicit `notifications/cancelled`, and
+  `StreamableHTTPServerTransport` does not treat an abandoned response stream as
+  a session close. A caller that hangs up without terminating its session
+  (`DELETE`) leaves the tool running until it finishes or times out. Set
+  `timeoutMs` on anything expensive rather than relying on disconnect detection.
+- **`load` does not get one.** Resources, resource templates, and prompts
+  receive a smaller context without `signal`.
+
 ### 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 _chunkN6ZZF5YBcjs = require('./chunk-N6ZZF5YB.cjs');
+var _chunkRCOJI5RMcjs = require('./chunk-RCOJI5RM.cjs');
 
 
 
@@ -49,5 +49,5 @@ var _chunk5FVNY65Mcjs = require('./chunk-5FVNY65M.cjs');
 
 
 
-exports.AuthProvider = _chunk5FVNY65Mcjs.AuthProvider; exports.AzureProvider = _chunk5FVNY65Mcjs.AzureProvider; exports.DiscoveryDocumentCache = _chunkN6ZZF5YBcjs.DiscoveryDocumentCache; exports.FastMCP = _chunkN6ZZF5YBcjs.FastMCP; exports.FastMCPError = _chunkN6ZZF5YBcjs.FastMCPError; exports.FastMCPSession = _chunkN6ZZF5YBcjs.FastMCPSession; exports.GitHubProvider = _chunk5FVNY65Mcjs.GitHubProvider; exports.GoogleProvider = _chunk5FVNY65Mcjs.GoogleProvider; exports.MEDIA_FETCH_TIMEOUT_MS = _chunkN6ZZF5YBcjs.MEDIA_FETCH_TIMEOUT_MS; exports.OAuthProvider = _chunk5FVNY65Mcjs.OAuthProvider; exports.ServerState = _chunkN6ZZF5YBcjs.ServerState; exports.SessionError = _chunkN6ZZF5YBcjs.SessionError; exports.UnexpectedStateError = _chunkN6ZZF5YBcjs.UnexpectedStateError; exports.UserError = _chunkN6ZZF5YBcjs.UserError; exports.audioContent = _chunkN6ZZF5YBcjs.audioContent; exports.getAuthSession = _chunk5FVNY65Mcjs.getAuthSession; exports.imageContent = _chunkN6ZZF5YBcjs.imageContent; exports.jsonSchemaAdapter = _chunkN6ZZF5YBcjs.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 = _chunkRCOJI5RMcjs.DiscoveryDocumentCache; exports.FastMCP = _chunkRCOJI5RMcjs.FastMCP; exports.FastMCPError = _chunkRCOJI5RMcjs.FastMCPError; exports.FastMCPSession = _chunkRCOJI5RMcjs.FastMCPSession; exports.GitHubProvider = _chunk5FVNY65Mcjs.GitHubProvider; exports.GoogleProvider = _chunk5FVNY65Mcjs.GoogleProvider; exports.MEDIA_FETCH_TIMEOUT_MS = _chunkRCOJI5RMcjs.MEDIA_FETCH_TIMEOUT_MS; exports.OAuthProvider = _chunk5FVNY65Mcjs.OAuthProvider; exports.ServerState = _chunkRCOJI5RMcjs.ServerState; exports.SessionError = _chunkRCOJI5RMcjs.SessionError; exports.UnexpectedStateError = _chunkRCOJI5RMcjs.UnexpectedStateError; exports.UserError = _chunkRCOJI5RMcjs.UserError; exports.audioContent = _chunkRCOJI5RMcjs.audioContent; exports.getAuthSession = _chunk5FVNY65Mcjs.getAuthSession; exports.imageContent = _chunkRCOJI5RMcjs.imageContent; exports.jsonSchemaAdapter = _chunkRCOJI5RMcjs.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

@@ -190,6 +190,19 @@ type Context<T extends FastMCPSessionAuth> = {
      * counters, or maintain user-specific data across multiple requests.
      */
     sessionId?: string;
+    /**
+     * Aborted once the tool's result can no longer reach anyone: the client
+     * cancelled the call, the session went away, or `timeoutMs` elapsed.
+     *
+     * Nothing is killed on your behalf — FastMCP stops waiting, but the promise
+     * `execute` returned keeps running until it settles. Forward this signal to
+     * whatever does the real work (`fetch`, a database driver, a subprocess) so
+     * the work stops with the call instead of outliving it.
+     *
+     * It is never aborted after a call completes normally, so it is safe to
+     * attach cleanup to it.
+     */
+    signal: AbortSignal;
     /**
      * Streams incremental content while the tool is still executing, by emitting
      * a `notifications/tool/streamContent` notification.
@@ -216,9 +229,11 @@ type Literal = boolean | null | number | string | undefined;
  *
  * This is a subset of the tool execution {@link Context}. `reportProgress`
  * and `streamContent` are tied to a tool call's progress token / streaming
- * notification and are not available outside of `tool.execute`.
+ * notification and are not available outside of `tool.execute`. `signal` is
+ * omitted too: its timeout leg comes from `tool.timeoutMs`, which `load` has
+ * no equivalent of.
  */
-type LoadContext<T extends FastMCPSessionAuth> = Omit<Context<T>, "reportProgress" | "streamContent">;
+type LoadContext<T extends FastMCPSessionAuth> = Omit<Context<T>, "reportProgress" | "signal" | "streamContent">;
 type Progress = {
     /**
      * An optional human-readable message describing the current progress.
@@ -887,10 +902,16 @@ declare class FastMCPSession<T extends FastMCPSessionAuth = FastMCPSessionAuth>
     /**
      * The HTTP session ID, or `undefined` for transports that do not have one.
      *
-     * Resolved from the transport on every read rather than captured when the
-     * session connects: `StreamableHTTPServerTransport` assigns its `sessionId`
-     * while it handles `initialize`, which happens after `connect()` resolves.
-     * A value read at connect time is therefore still `undefined`.
+     * Resolved from the transport rather than captured when the session
+     * connects: `StreamableHTTPServerTransport` assigns its `sessionId` while it
+     * handles `initialize`, which happens after `connect()` resolves. A value
+     * read at connect time is therefore still `undefined`.
+     *
+     * The first ID seen is latched, so the session keeps reporting it once the
+     * transport detaches — `Protocol` drops its transport reference on close,
+     * which would otherwise make the ID vanish mid-teardown. Latching is safe
+     * because {@link connect} refuses a second transport, so a session never
+     * sees two IDs.
      */
     get sessionId(): string | undefined;
     set sessionId(value: string | undefined);

package/dist/FastMCP.d.ts

@@ -190,6 +190,19 @@ type Context<T extends FastMCPSessionAuth> = {
      * counters, or maintain user-specific data across multiple requests.
      */
     sessionId?: string;
+    /**
+     * Aborted once the tool's result can no longer reach anyone: the client
+     * cancelled the call, the session went away, or `timeoutMs` elapsed.
+     *
+     * Nothing is killed on your behalf — FastMCP stops waiting, but the promise
+     * `execute` returned keeps running until it settles. Forward this signal to
+     * whatever does the real work (`fetch`, a database driver, a subprocess) so
+     * the work stops with the call instead of outliving it.
+     *
+     * It is never aborted after a call completes normally, so it is safe to
+     * attach cleanup to it.
+     */
+    signal: AbortSignal;
     /**
      * Streams incremental content while the tool is still executing, by emitting
      * a `notifications/tool/streamContent` notification.
@@ -216,9 +229,11 @@ type Literal = boolean | null | number | string | undefined;
  *
  * This is a subset of the tool execution {@link Context}. `reportProgress`
  * and `streamContent` are tied to a tool call's progress token / streaming
- * notification and are not available outside of `tool.execute`.
+ * notification and are not available outside of `tool.execute`. `signal` is
+ * omitted too: its timeout leg comes from `tool.timeoutMs`, which `load` has
+ * no equivalent of.
  */
-type LoadContext<T extends FastMCPSessionAuth> = Omit<Context<T>, "reportProgress" | "streamContent">;
+type LoadContext<T extends FastMCPSessionAuth> = Omit<Context<T>, "reportProgress" | "signal" | "streamContent">;
 type Progress = {
     /**
      * An optional human-readable message describing the current progress.
@@ -887,10 +902,16 @@ declare class FastMCPSession<T extends FastMCPSessionAuth = FastMCPSessionAuth>
     /**
      * The HTTP session ID, or `undefined` for transports that do not have one.
      *
-     * Resolved from the transport on every read rather than captured when the
-     * session connects: `StreamableHTTPServerTransport` assigns its `sessionId`
-     * while it handles `initialize`, which happens after `connect()` resolves.
-     * A value read at connect time is therefore still `undefined`.
+     * Resolved from the transport rather than captured when the session
+     * connects: `StreamableHTTPServerTransport` assigns its `sessionId` while it
+     * handles `initialize`, which happens after `connect()` resolves. A value
+     * read at connect time is therefore still `undefined`.
+     *
+     * The first ID seen is latched, so the session keeps reporting it once the
+     * transport detaches — `Protocol` drops its transport reference on close,
+     * which would otherwise make the ID vanish mid-teardown. Latching is safe
+     * because {@link connect} refuses a second transport, so a session never
+     * sees two IDs.
      */
     get sessionId(): string | undefined;
     set sessionId(value: string | undefined);

package/dist/FastMCP.js

@@ -11,7 +11,7 @@ import {
   audioContent,
   imageContent,
   jsonSchemaAdapter
-} from "./chunk-4VIPI4GU.js";
+} from "./chunk-EL6BTW4Y.js";
 import {
   AuthProvider,
   AzureProvider,

package/dist/{chunk-4VIPI4GU.js → chunk-EL6BTW4Y.js}

@@ -467,21 +467,38 @@ var FastMCPSession = class extends FastMCPSessionEventEmitter {
   /**
    * The HTTP session ID, or `undefined` for transports that do not have one.
    *
-   * Resolved from the transport on every read rather than captured when the
-   * session connects: `StreamableHTTPServerTransport` assigns its `sessionId`
-   * while it handles `initialize`, which happens after `connect()` resolves.
-   * A value read at connect time is therefore still `undefined`.
+   * Resolved from the transport rather than captured when the session
+   * connects: `StreamableHTTPServerTransport` assigns its `sessionId` while it
+   * handles `initialize`, which happens after `connect()` resolves. A value
+   * read at connect time is therefore still `undefined`.
+   *
+   * The first ID seen is latched, so the session keeps reporting it once the
+   * transport detaches — `Protocol` drops its transport reference on close,
+   * which would otherwise make the ID vanish mid-teardown. Latching is safe
+   * because {@link connect} refuses a second transport, so a session never
+   * sees two IDs.
    */
   get sessionId() {
-    if (this.#sessionId !== void 0) {
-      return this.#sessionId;
+    if (this.#sessionId === void 0) {
+      const transportSessionId = this.#server.transport?.sessionId;
+      if (typeof transportSessionId === "string") {
+        this.#sessionId = transportSessionId;
+      }
     }
-    const transport = this.#server.transport;
-    return typeof transport?.sessionId === "string" ? transport.sessionId : void 0;
+    return this.#sessionId;
   }
   set sessionId(value) {
     this.#sessionId = value;
   }
+  /**
+   * Aborted once the session ends, and folded into the `signal` every tool
+   * call receives. The MCP SDK only aborts a request's own signal for an
+   * explicit `notifications/cancelled`, and neither `Protocol` nor
+   * `StreamableHTTPServerTransport` touches it when the transport simply goes
+   * away — so without this a tool keeps running after the client that asked
+   * for it has hung up.
+   */
+  #abortController = new AbortController();
   #auth;
   #capabilities = {};
   #clientCapabilities;
@@ -603,6 +620,7 @@ var FastMCPSession = class extends FastMCPSessionEventEmitter {
     if (this.#pingInterval) {
       clearInterval(this.#pingInterval);
     }
+    this.#abortSession();
     try {
       await this.#server.close();
     } catch (error) {
@@ -793,6 +811,16 @@ ${error instanceof Error ? error.stack : JSON.stringify(error)}`
       });
     });
   }
+  /**
+   * Cancels the `signal` held by every tool still executing on this session.
+   * Idempotent, so the close path and the transport's own close handler can
+   * both call it.
+   */
+  #abortSession() {
+    if (!this.#abortController.signal.aborted) {
+      this.#abortController.abort(new SessionError("Session closed"));
+    }
+  }
   /**
    * Builds the context object passed as the third argument to
    * `resource.load` / `resourceTemplate.load` / `prompt.load`.
@@ -1062,6 +1090,9 @@ ${error instanceof Error ? error.stack : JSON.stringify(error)}`
     this.#server.onerror = (error) => {
       this.#logger.error("[FastMCP error]", error);
     };
+    this.#server.onclose = () => {
+      this.#abortSession();
+    };
   }
   setupLoggingHandlers() {
     this.#server.setRequestHandler(SetLevelRequestSchema, (request) => {
@@ -1410,6 +1441,14 @@ ${error instanceof Error ? error.stack : JSON.stringify(error)}`
               toolName: request.params.name
             });
           }
+          const timeoutAbort = new AbortController();
+          const signal = AbortSignal.any([
+            timeoutAbort.signal,
+            this.#abortController.signal,
+            // Only ever aborted for an explicit `notifications/cancelled`; the
+            // session signal above is what covers a client that simply left.
+            ...extra.signal ? [extra.signal] : []
+          ]);
           const executeToolPromise = Promise.resolve(
             tool.execute(args, {
               client: {
@@ -1421,6 +1460,7 @@ ${error instanceof Error ? error.stack : JSON.stringify(error)}`
               requestId: typeof request.params?._meta?.requestId === "string" ? request.params._meta.requestId : void 0,
               session: this.#auth,
               sessionId: this.sessionId,
+              signal,
               streamContent
             })
           );
@@ -1432,11 +1472,11 @@ ${error instanceof Error ? error.stack : JSON.stringify(error)}`
             executeToolPromise,
             new Promise((_, reject) => {
               const timeoutId = setTimeout(() => {
-                reject(
-                  new UserError(
-                    `Tool '${request.params.name}' timed out after ${tool.timeoutMs}ms. Consider increasing timeoutMs or optimizing the tool implementation.`
-                  )
+                const timedOut = new UserError(
+                  `Tool '${request.params.name}' timed out after ${tool.timeoutMs}ms. Consider increasing timeoutMs or optimizing the tool implementation.`
                 );
+                timeoutAbort.abort(timedOut);
+                reject(timedOut);
               }, tool.timeoutMs);
               executeToolPromise.then(
                 () => clearTimeout(timeoutId),
@@ -2767,4 +2807,4 @@ export {
   FastMCPSession,
   FastMCP
 };
-//# sourceMappingURL=chunk-4VIPI4GU.js.map
+//# sourceMappingURL=chunk-EL6BTW4Y.js.map