fastmcp 3.19.2 → 3.20.0

package/.roo/mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp"],
+      "env": {
+        "DEFAULT_MINIMUM_TOKENS": ""
+      }
+    }
+  }
+}

package/README.md

@@ -11,6 +11,7 @@ A TypeScript framework for building [MCP](https://glama.ai/mcp) servers capable
 - Simple Tool, Resource, Prompt definition
 - [Authentication](#authentication)
 - [Passing headers through context](#passing-headers-through-context)
+- [Session ID and Request ID tracking](#session-id-and-request-id-tracking)
 - [Sessions](#sessions)
 - [Image content](#returning-an-image)
 - [Audio content](#returning-an-audio)
@@ -1529,6 +1530,88 @@ Tool result: {
 }
 ```
 
+#### Session ID and Request ID Tracking
+
+FastMCP automatically exposes session and request IDs to tool handlers through the context parameter. This enables per-session state management and request tracking.
+
+**Session ID** (`context.sessionId`):
+
+- Available only for HTTP-based transports (HTTP Stream, SSE)
+- Extracted from the `Mcp-Session-Id` header
+- Remains constant across multiple requests from the same client
+- Useful for maintaining per-session state, counters, or user-specific data
+
+**Request ID** (`context.requestId`):
+
+- Available for all transports when provided by the client
+- Unique for each individual request
+- Useful for request tracing and debugging
+
+```ts
+import { FastMCP } from "fastmcp";
+import { z } from "zod";
+
+const server = new FastMCP({
+  name: "Session Counter Server",
+  version: "1.0.0",
+});
+
+// Per-session counter storage
+const sessionCounters = new Map<string, number>();
+
+server.addTool({
+  name: "increment_counter",
+  description: "Increment a per-session counter",
+  parameters: z.object({}),
+  execute: async (args, context) => {
+    if (!context.sessionId) {
+      return "Session ID not available (requires HTTP transport)";
+    }
+
+    const counter = sessionCounters.get(context.sessionId) || 0;
+    const newCounter = counter + 1;
+    sessionCounters.set(context.sessionId, newCounter);
+
+    return `Counter for session ${context.sessionId}: ${newCounter}`;
+  },
+});
+
+server.addTool({
+  name: "show_ids",
+  description: "Display session and request IDs",
+  parameters: z.object({}),
+  execute: async (args, context) => {
+    return `Session ID: ${context.sessionId || "N/A"}
+Request ID: ${context.requestId || "N/A"}`;
+  },
+});
+
+server.start({
+  transportType: "httpStream",
+  httpStream: {
+    port: 8080,
+  },
+});
+```
+
+**Use Cases:**
+
+- **Per-session state management**: Maintain counters, caches, or temporary data unique to each client session
+- **User authentication and authorization**: Track authenticated users across requests
+- **Session-specific resource management**: Allocate and manage resources per session
+- **Multi-tenant implementations**: Isolate data and operations by session
+- **Request tracing**: Track individual requests for debugging and monitoring
+
+**Example:**
+
+See [`src/examples/session-id-counter.ts`](src/examples/session-id-counter.ts) for a complete example demonstrating session-based counter management.
+
+**Notes:**
+
+- Session IDs are automatically generated by the MCP transport layer
+- In stateless mode, session IDs are not persisted across requests
+- For stdio transport, `sessionId` will be `undefined` as there's no HTTP session concept
+
 ### Providing Instructions
 
 You can provide instructions to the server using the `instructions` option:

package/dist/FastMCP.d.ts

@@ -62,7 +62,19 @@ type Context<T extends FastMCPSessionAuth> = {
         warn: (message: string, data?: SerializableValue) => void;
     };
     reportProgress: (progress: Progress) => Promise<void>;
+    /**
+     * Request ID from the current MCP request.
+     * Available for all transports when the client provides it.
+     */
+    requestId?: string;
     session: T | undefined;
+    /**
+     * Session ID from the Mcp-Session-Id header.
+     * Only available for HTTP-based transports (SSE, HTTP Stream).
+     * Can be used to track per-session state, implement session-specific
+     * counters, or maintain user-specific data across multiple requests.
+     */
+    sessionId?: string;
     streamContent: (content: Content | Content[]) => Promise<void>;
 };
 type Extra = unknown;
@@ -549,7 +561,9 @@ declare class FastMCPSession<T extends FastMCPSessionAuth = FastMCPSessionAuth>
     get loggingLevel(): LoggingLevel;
     get roots(): Root[];
     get server(): Server;
-    constructor({ auth, instructions, logger, name, ping, prompts, resources, resourcesTemplates, roots, tools, transportType, utils, version, }: {
+    get sessionId(): string | undefined;
+    set sessionId(value: string | undefined);
+    constructor({ auth, instructions, logger, name, ping, prompts, resources, resourcesTemplates, roots, sessionId, tools, transportType, utils, version, }: {
         auth?: T;
         instructions?: string;
         logger: Logger;
@@ -559,6 +573,7 @@ declare class FastMCPSession<T extends FastMCPSessionAuth = FastMCPSessionAuth>
         resources: Resource<T>[];
         resourcesTemplates: InputResourceTemplate<T>[];
         roots?: ServerOptions<T>["roots"];
+        sessionId?: string;
         tools: Tool<T>[];
         transportType?: "httpStream" | "stdio";
         utils?: ServerOptions<T>["utils"];

package/dist/FastMCP.js

@@ -233,6 +233,12 @@ var FastMCPSession = class extends FastMCPSessionEventEmitter {
   get server() {
     return this.#server;
   }
+  get sessionId() {
+    return this.#sessionId;
+  }
+  set sessionId(value) {
+    this.#sessionId = value;
+  }
   #auth;
   #capabilities = {};
   #clientCapabilities;
@@ -248,6 +254,11 @@ var FastMCPSession = class extends FastMCPSessionEventEmitter {
   #roots = [];
   #rootsConfig;
   #server;
+  /**
+   * Session ID from the Mcp-Session-Id header (HTTP transports only).
+   * Used to track per-session state across multiple requests.
+   */
+  #sessionId;
   #utils;
   constructor({
     auth,
@@ -259,6 +270,7 @@ var FastMCPSession = class extends FastMCPSessionEventEmitter {
     resources,
     resourcesTemplates,
     roots,
+    sessionId,
     tools,
     transportType,
     utils,
@@ -269,6 +281,7 @@ var FastMCPSession = class extends FastMCPSessionEventEmitter {
     this.#logger = logger;
     this.#pingConfig = ping;
     this.#rootsConfig = roots;
+    this.#sessionId = sessionId;
     this.#needsEventLoopFlush = transportType === "httpStream";
     if (tools.length) {
       this.#capabilities.tools = {};
@@ -329,6 +342,12 @@ var FastMCPSession = class extends FastMCPSessionEventEmitter {
     this.#connectionState = "connecting";
     try {
       await this.#server.connect(transport);
+      if ("sessionId" in transport) {
+        const transportWithSessionId = transport;
+        if (typeof transportWithSessionId.sessionId === "string") {
+          this.#sessionId = transportWithSessionId.sessionId;
+        }
+      }
       let attempt = 0;
       const maxAttempts = 10;
       const retryDelay = 100;
@@ -900,7 +919,9 @@ ${error instanceof Error ? error.stack : JSON.stringify(error)}`
           },
           log,
           reportProgress,
+          requestId: typeof request.params?._meta?.requestId === "string" ? request.params._meta.requestId : void 0,
           session: this.#auth,
+          sessionId: this.#sessionId,
           streamContent
         });
         const maybeStringResult = await (tool.timeoutMs ? Promise.race([
@@ -1125,7 +1146,7 @@ var FastMCP = class extends FastMCPEventEmitter {
           `[FastMCP info] Starting server in stateless mode on HTTP Stream at http://${httpConfig.host}:${httpConfig.port}${httpConfig.endpoint}`
         );
         this.#httpStreamServer = await startHTTPServer({
-          authenticate: this.#authenticate,
+          ...this.#authenticate ? { authenticate: this.#authenticate } : {},
           createServer: async (request) => {
             let auth;
             if (this.#authenticate) {
@@ -1134,7 +1155,8 @@ var FastMCP = class extends FastMCPEventEmitter {
                 throw new Error("Authentication required");
               }
             }
-            return this.#createSession(auth);
+            const sessionId = Array.isArray(request.headers["mcp-session-id"]) ? request.headers["mcp-session-id"][0] : request.headers["mcp-session-id"];
+            return this.#createSession(auth, sessionId);
           },
           enableJsonResponse: httpConfig.enableJsonResponse,
           eventStore: httpConfig.eventStore,
@@ -1156,13 +1178,14 @@ var FastMCP = class extends FastMCPEventEmitter {
         });
       } else {
         this.#httpStreamServer = await startHTTPServer({
-          authenticate: this.#authenticate,
+          ...this.#authenticate ? { authenticate: this.#authenticate } : {},
           createServer: async (request) => {
             let auth;
             if (this.#authenticate) {
               auth = await this.#authenticate(request);
             }
-            return this.#createSession(auth);
+            const sessionId = Array.isArray(request.headers["mcp-session-id"]) ? request.headers["mcp-session-id"][0] : request.headers["mcp-session-id"];
+            return this.#createSession(auth, sessionId);
           },
           enableJsonResponse: httpConfig.enableJsonResponse,
           eventStore: httpConfig.eventStore,
@@ -1213,7 +1236,11 @@ var FastMCP = class extends FastMCPEventEmitter {
    * Creates a new FastMCPSession instance with the current configuration.
    * Used both for regular sessions and stateless requests.
    */
-  #createSession(auth) {
+  #createSession(auth, sessionId) {
+    if (auth && typeof auth === "object" && "authenticated" in auth && !auth.authenticated) {
+      const errorMessage = "error" in auth && typeof auth.error === "string" ? auth.error : "Authentication failed";
+      throw new Error(errorMessage);
+    }
     const allowedTools = auth ? this.#tools.filter(
       (tool) => tool.canAccess ? tool.canAccess(auth) : true
     ) : this.#tools;
@@ -1227,6 +1254,7 @@ var FastMCP = class extends FastMCPEventEmitter {
       resources: this.#resources,
       resourcesTemplates: this.#resourcesTemplates,
       roots: this.#options.roots,
+      sessionId,
       tools: allowedTools,
       transportType: "httpStream",
       utils: this.#options.utils,