fastmcp 4.15.3 → 4.16.1

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 _chunkIXYHFFR6cjs = require('./chunk-IXYHFFR6.cjs');
+var _chunkGTUJ3UXAcjs = require('./chunk-GTUJ3UXA.cjs');
 
 
 
@@ -49,5 +49,5 @@ var _chunk5FVNY65Mcjs = require('./chunk-5FVNY65M.cjs');
 
 
 
-exports.AuthProvider = _chunk5FVNY65Mcjs.AuthProvider; exports.AzureProvider = _chunk5FVNY65Mcjs.AzureProvider; exports.DiscoveryDocumentCache = _chunkIXYHFFR6cjs.DiscoveryDocumentCache; exports.FastMCP = _chunkIXYHFFR6cjs.FastMCP; exports.FastMCPError = _chunkIXYHFFR6cjs.FastMCPError; exports.FastMCPSession = _chunkIXYHFFR6cjs.FastMCPSession; exports.GitHubProvider = _chunk5FVNY65Mcjs.GitHubProvider; exports.GoogleProvider = _chunk5FVNY65Mcjs.GoogleProvider; exports.MEDIA_FETCH_TIMEOUT_MS = _chunkIXYHFFR6cjs.MEDIA_FETCH_TIMEOUT_MS; exports.OAuthProvider = _chunk5FVNY65Mcjs.OAuthProvider; exports.ServerState = _chunkIXYHFFR6cjs.ServerState; exports.SessionError = _chunkIXYHFFR6cjs.SessionError; exports.UnexpectedStateError = _chunkIXYHFFR6cjs.UnexpectedStateError; exports.UserError = _chunkIXYHFFR6cjs.UserError; exports.audioContent = _chunkIXYHFFR6cjs.audioContent; exports.getAuthSession = _chunk5FVNY65Mcjs.getAuthSession; exports.imageContent = _chunkIXYHFFR6cjs.imageContent; exports.jsonSchemaAdapter = _chunkIXYHFFR6cjs.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 = _chunkGTUJ3UXAcjs.DiscoveryDocumentCache; exports.FastMCP = _chunkGTUJ3UXAcjs.FastMCP; exports.FastMCPError = _chunkGTUJ3UXAcjs.FastMCPError; exports.FastMCPSession = _chunkGTUJ3UXAcjs.FastMCPSession; exports.GitHubProvider = _chunk5FVNY65Mcjs.GitHubProvider; exports.GoogleProvider = _chunk5FVNY65Mcjs.GoogleProvider; exports.MEDIA_FETCH_TIMEOUT_MS = _chunkGTUJ3UXAcjs.MEDIA_FETCH_TIMEOUT_MS; exports.OAuthProvider = _chunk5FVNY65Mcjs.OAuthProvider; exports.ServerState = _chunkGTUJ3UXAcjs.ServerState; exports.SessionError = _chunkGTUJ3UXAcjs.SessionError; exports.UnexpectedStateError = _chunkGTUJ3UXAcjs.UnexpectedStateError; exports.UserError = _chunkGTUJ3UXAcjs.UserError; exports.audioContent = _chunkGTUJ3UXAcjs.audioContent; exports.getAuthSession = _chunk5FVNY65Mcjs.getAuthSession; exports.imageContent = _chunkGTUJ3UXAcjs.imageContent; exports.jsonSchemaAdapter = _chunkGTUJ3UXAcjs.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.

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.

package/dist/FastMCP.js

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

package/dist/{chunk-IXYHFFR6.cjs → chunk-GTUJ3UXA.cjs}

@@ -490,6 +490,15 @@ var FastMCPSession = class extends FastMCPSessionEventEmitter {
   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;
@@ -593,14 +602,12 @@ var FastMCPSession = class extends FastMCPSessionEventEmitter {
       for (const resource of resources) {
         this.addResource(resource);
       }
+      for (const resourceTemplate of resourcesTemplates) {
+        this.addResourceTemplate(resourceTemplate);
+      }
       this.setupResourceHandlers();
       this.setupResourceSubscriptionHandlers();
-      if (resourcesTemplates.length) {
-        for (const resourceTemplate of resourcesTemplates) {
-          this.addResourceTemplate(resourceTemplate);
-        }
-        this.setupResourceTemplateHandlers();
-      }
+      this.setupResourceTemplateHandlers();
     }
     if (prompts.length) {
       this.setupPromptHandlers();
@@ -611,6 +618,7 @@ var FastMCPSession = class extends FastMCPSessionEventEmitter {
     if (this.#pingInterval) {
       clearInterval(this.#pingInterval);
     }
+    this.#abortSession();
     try {
       await this.#server.close();
     } catch (error) {
@@ -801,6 +809,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`.
@@ -1070,6 +1088,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(_typesjs.SetLevelRequestSchema, (request) => {
@@ -1418,6 +1439,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: {
@@ -1429,6 +1458,7 @@ ${error instanceof Error ? error.stack : JSON.stringify(error)}`
               requestId: typeof _optionalChain([request, 'access', _41 => _41.params, 'optionalAccess', _42 => _42._meta, 'optionalAccess', _43 => _43.requestId]) === "string" ? request.params._meta.requestId : void 0,
               session: this.#auth,
               sessionId: this.sessionId,
+              signal,
               streamContent
             })
           );
@@ -1440,11 +1470,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),
@@ -2775,4 +2805,4 @@ var FastMCP = class extends FastMCPEventEmitter {
 
 
 exports.DiscoveryDocumentCache = DiscoveryDocumentCache; exports.jsonSchemaAdapter = jsonSchemaAdapter; exports.MEDIA_FETCH_TIMEOUT_MS = MEDIA_FETCH_TIMEOUT_MS; exports.imageContent = imageContent; exports.audioContent = audioContent; exports.FastMCPError = FastMCPError; exports.SessionError = SessionError; exports.UnexpectedStateError = UnexpectedStateError; exports.UserError = UserError; exports.ServerState = ServerState; exports.FastMCPSession = FastMCPSession; exports.FastMCP = FastMCP;
-//# sourceMappingURL=chunk-IXYHFFR6.cjs.map
+//# sourceMappingURL=chunk-GTUJ3UXA.cjs.map