fastmcp 2.1.4 → 2.2.1

package/src/FastMCP.ts

@@ -44,6 +44,7 @@ type FastMCPEvents<T extends FastMCPSessionAuth> = {
 
 type FastMCPSessionEvents = {
   error: (event: { error: Error }) => void;
+  ready: () => void;
   rootsChanged: (event: { roots: Root[] }) => void;
 };
 
@@ -281,12 +282,35 @@ const AudioContentZodSchema = z
   })
   .strict() satisfies z.ZodType<AudioContent>;
 
-type Content = AudioContent | ImageContent | TextContent;
+type ResourceContent = {
+  resource: {
+    blob?: string;
+    mimeType?: string;
+    text?: string;
+    uri: string;
+  };
+  type: "resource";
+};
+
+const ResourceContentZodSchema = z
+  .object({
+    resource: z.object({
+      blob: z.string().optional(),
+      mimeType: z.string().optional(),
+      text: z.string().optional(),
+      uri: z.string(),
+    }),
+    type: z.literal("resource"),
+  })
+  .strict() satisfies z.ZodType<ResourceContent>;
+
+type Content = AudioContent | ImageContent | ResourceContent | TextContent;
 
 const ContentZodSchema = z.discriminatedUnion("type", [
   TextContentZodSchema,
   ImageContentZodSchema,
   AudioContentZodSchema,
+  ResourceContentZodSchema,
 ]) satisfies z.ZodType<Content>;
 
 type ContentResult = {
@@ -534,7 +558,13 @@ type Tool<
     args: StandardSchemaV1.InferOutput<Params>,
     context: Context<T>,
   ) => Promise<
-    AudioContent | ContentResult | ImageContent | string | TextContent | void
+    | AudioContent
+    | ContentResult
+    | ImageContent
+    | ResourceContent
+    | string
+    | TextContent
+    | void
   >;
   name: string;
   parameters?: Params;
@@ -599,6 +629,9 @@ export class FastMCPSession<
   public get clientCapabilities(): ClientCapabilities | null {
     return this.#clientCapabilities ?? null;
   }
+  public get isReady(): boolean {
+    return this.#connectionState === "ready";
+  }
   public get loggingLevel(): LoggingLevel {
     return this.#loggingLevel;
   }
@@ -611,6 +644,7 @@ export class FastMCPSession<
   #auth: T | undefined;
   #capabilities: ServerCapabilities = {};
   #clientCapabilities?: ClientCapabilities;
+  #connectionState: "closed" | "connecting" | "error" | "ready" = "connecting";
   #loggingLevel: LoggingLevel = "info";
   #pingConfig?: ServerOptions<T>["ping"];
   #pingInterval: null | ReturnType<typeof setInterval> = null;
@@ -710,6 +744,8 @@ export class FastMCPSession<
   }
 
   public async close() {
+    this.#connectionState = "closed";
+
     if (this.#pingInterval) {
       clearInterval(this.#pingInterval);
     }
@@ -726,72 +762,90 @@ export class FastMCPSession<
       throw new UnexpectedStateError("Server is already connected");
     }
 
-    await this.#server.connect(transport);
+    this.#connectionState = "connecting";
 
-    let attempt = 0;
+    try {
+      await this.#server.connect(transport);
 
-    while (attempt++ < 10) {
-      const capabilities = await this.#server.getClientCapabilities();
+      let attempt = 0;
 
-      if (capabilities) {
-        this.#clientCapabilities = capabilities;
+      while (attempt++ < 10) {
+        const capabilities = this.#server.getClientCapabilities();
 
-        break;
-      }
+        if (capabilities) {
+          this.#clientCapabilities = capabilities;
 
-      await delay(100);
-    }
+          break;
+        }
 
-    if (!this.#clientCapabilities) {
-      console.warn("[FastMCP warning] could not infer client capabilities");
-    }
+        await delay(100);
+      }
 
-    if (
-      this.#clientCapabilities?.roots?.listChanged &&
-      typeof this.#server.listRoots === "function"
-    ) {
-      try {
-        const roots = await this.#server.listRoots();
-        this.#roots = roots.roots;
-      } catch (e) {
-        if (e instanceof McpError && e.code === ErrorCode.MethodNotFound) {
-          console.debug(
-            "[FastMCP debug] listRoots method not supported by client",
-          );
-        } else {
-          console.error(
-            `[FastMCP error] received error listing roots.\n\n${e instanceof Error ? e.stack : JSON.stringify(e)}`,
-          );
+      if (!this.#clientCapabilities) {
+        console.warn("[FastMCP warning] could not infer client capabilities");
+      }
+
+      if (
+        this.#clientCapabilities?.roots?.listChanged &&
+        typeof this.#server.listRoots === "function"
+      ) {
+        try {
+          const roots = await this.#server.listRoots();
+          this.#roots = roots.roots;
+        } catch (e) {
+          if (e instanceof McpError && e.code === ErrorCode.MethodNotFound) {
+            console.debug(
+              "[FastMCP debug] listRoots method not supported by client",
+            );
+          } else {
+            console.error(
+              `[FastMCP error] received error listing roots.\n\n${e instanceof Error ? e.stack : JSON.stringify(e)}`,
+            );
+          }
         }
       }
-    }
 
-    if (this.#clientCapabilities) {
-      const pingConfig = this.#getPingConfig(transport);
+      if (this.#clientCapabilities) {
+        const pingConfig = this.#getPingConfig(transport);
 
-      if (pingConfig.enabled) {
-        this.#pingInterval = setInterval(async () => {
-          try {
-            await this.#server.ping();
-          } catch {
-            // The reason we are not emitting an error here is because some clients
-            // seem to not respond to the ping request, and we don't want to crash the server,
-            // e.g., https://github.com/punkpeye/fastmcp/issues/38.
-            const logLevel = pingConfig.logLevel;
-            if (logLevel === "debug") {
-              console.debug("[FastMCP debug] server ping failed");
-            } else if (logLevel === "warning") {
-              console.warn(
-                "[FastMCP warning] server is not responding to ping",
-              );
-            } else if (logLevel === "error") {
-              console.error("[FastMCP error] server is not responding to ping");
-            } else {
-              console.info("[FastMCP info] server ping failed");
+        if (pingConfig.enabled) {
+          this.#pingInterval = setInterval(async () => {
+            try {
+              await this.#server.ping();
+            } catch {
+              // The reason we are not emitting an error here is because some clients
+              // seem to not respond to the ping request, and we don't want to crash the server,
+              // e.g., https://github.com/punkpeye/fastmcp/issues/38.
+              const logLevel = pingConfig.logLevel;
+
+              if (logLevel === "debug") {
+                console.debug("[FastMCP debug] server ping failed");
+              } else if (logLevel === "warning") {
+                console.warn(
+                  "[FastMCP warning] server is not responding to ping",
+                );
+              } else if (logLevel === "error") {
+                console.error(
+                  "[FastMCP error] server is not responding to ping",
+                );
+              } else {
+                console.info("[FastMCP info] server ping failed");
+              }
             }
-          }
-        }, pingConfig.intervalMs);
+          }, pingConfig.intervalMs);
+        }
       }
+
+      // Mark connection as ready and emit event
+      this.#connectionState = "ready";
+      this.emit("ready");
+    } catch (error) {
+      this.#connectionState = "error";
+      const errorEvent = {
+        error: error instanceof Error ? error : new Error(String(error)),
+      };
+      this.emit("error", errorEvent);
+      throw error;
     }
   }
 
@@ -801,6 +855,41 @@ export class FastMCPSession<
     return this.#server.createMessage(message);
   }
 
+  public waitForReady(): Promise<void> {
+    if (this.isReady) {
+      return Promise.resolve();
+    }
+
+    if (
+      this.#connectionState === "error" ||
+      this.#connectionState === "closed"
+    ) {
+      return Promise.reject(
+        new Error(`Connection is in ${this.#connectionState} state`),
+      );
+    }
+
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        reject(
+          new Error(
+            "Connection timeout: Session failed to become ready within 5 seconds",
+          ),
+        );
+      }, 5000);
+
+      this.once("ready", () => {
+        clearTimeout(timeout);
+        resolve();
+      });
+
+      this.once("error", (event) => {
+        clearTimeout(timeout);
+        reject(event.error);
+      });
+    });
+  }
+
   #getPingConfig(transport: Transport): {
     enabled: boolean;
     intervalMs: number;
@@ -1362,6 +1451,7 @@ export class FastMCPSession<
           | ContentResult
           | ImageContent
           | null
+          | ResourceContent
           | string
           | TextContent
           | undefined;
@@ -1470,6 +1560,88 @@ export class FastMCP<
     this.#tools.push(tool as unknown as Tool<T>);
   }
 
+  /**
+   * Embeds a resource by URI, making it easy to include resources in tool responses.
+   *
+   * @param uri - The URI of the resource to embed
+   * @returns Promise<ResourceContent> - The embedded resource content
+   */
+  public async embedded(uri: string): Promise<ResourceContent["resource"]> {
+    // First, try to find a direct resource match
+    const directResource = this.#resources.find(
+      (resource) => resource.uri === uri,
+    );
+
+    if (directResource) {
+      const result = await directResource.load();
+      const results = Array.isArray(result) ? result : [result];
+      const firstResult = results[0];
+
+      const resourceData: ResourceContent["resource"] = {
+        mimeType: directResource.mimeType,
+        uri,
+      };
+
+      if ("text" in firstResult) {
+        resourceData.text = firstResult.text;
+      }
+
+      if ("blob" in firstResult) {
+        resourceData.blob = firstResult.blob;
+      }
+
+      return resourceData;
+    }
+
+    // Try to match against resource templates
+    for (const template of this.#resourcesTemplates) {
+      // Check if the URI starts with the template base
+      const templateBase = template.uriTemplate.split("{")[0];
+
+      if (uri.startsWith(templateBase)) {
+        const params: Record<string, string> = {};
+        const templateParts = template.uriTemplate.split("/");
+        const uriParts = uri.split("/");
+
+        for (let i = 0; i < templateParts.length; i++) {
+          const templatePart = templateParts[i];
+
+          if (templatePart?.startsWith("{") && templatePart.endsWith("}")) {
+            const paramName = templatePart.slice(1, -1);
+            const paramValue = uriParts[i];
+
+            if (paramValue) {
+              params[paramName] = paramValue;
+            }
+          }
+        }
+
+        const result = await template.load(
+          params as ResourceTemplateArgumentsToObject<
+            typeof template.arguments
+          >,
+        );
+
+        const resourceData: ResourceContent["resource"] = {
+          mimeType: template.mimeType,
+          uri,
+        };
+
+        if ("text" in result) {
+          resourceData.text = result.text;
+        }
+
+        if ("blob" in result) {
+          resourceData.blob = result.blob;
+        }
+
+        return resourceData; // The resource we're looking for
+      }
+    }
+
+    throw new UnexpectedStateError(`Resource not found: ${uri}`, { uri });
+  }
+
   /**
    * Starts the server.
    */
@@ -1546,12 +1718,10 @@ export class FastMCP<
 
           if (enabled) {
             const path = healthConfig.path ?? "/health";
+            const url = new URL(req.url || "", "http://localhost");
 
             try {
-              if (
-                req.method === "GET" &&
-                new URL(req.url || "", "http://localhost").pathname === path
-              ) {
+              if (req.method === "GET" && url.pathname === path) {
                 res
                   .writeHead(healthConfig.status ?? 200, {
                     "Content-Type": "text/plain",
@@ -1560,6 +1730,34 @@ export class FastMCP<
 
                 return;
               }
+
+              // Enhanced readiness check endpoint
+              if (req.method === "GET" && url.pathname === "/ready") {
+                const readySessions = this.#sessions.filter(
+                  (s) => s.isReady,
+                ).length;
+                const totalSessions = this.#sessions.length;
+                const allReady =
+                  readySessions === totalSessions && totalSessions > 0;
+
+                const response = {
+                  ready: readySessions,
+                  status: allReady
+                    ? "ready"
+                    : totalSessions === 0
+                      ? "no_sessions"
+                      : "initializing",
+                  total: totalSessions,
+                };
+
+                res
+                  .writeHead(allReady ? 200 : 503, {
+                    "Content-Type": "application/json",
+                  })
+                  .end(JSON.stringify(response));
+
+                return;
+              }
             } catch (error) {
               console.error("[FastMCP error] health endpoint error", error);
             }

package/src/examples/addition.ts

@@ -170,6 +170,62 @@ server.addPrompt({
   name: "git-commit",
 });
 
+server.addResourceTemplate({
+  arguments: [
+    {
+      description: "Documentation section to retrieve",
+      name: "section",
+      required: true,
+    },
+  ],
+  description: "Get project documentation",
+  load: async (args) => {
+    const docs = {
+      "api-reference":
+        "# API Reference\n\n## Authentication\nAll API requests require a valid API key in the Authorization header.\n\n## Endpoints\n- GET /users - List all users\n- POST /users - Create new user",
+      deployment:
+        "# Deployment Guide\n\nTo deploy this application:\n\n1. Build the project: `npm run build`\n2. Set environment variables\n3. Deploy to your hosting platform",
+      "getting-started":
+        "# Getting Started\n\nWelcome to our project! Follow these steps to set up your development environment:\n\n1. Clone the repository\n2. Install dependencies with `npm install`\n3. Run `npm start` to begin",
+    };
+
+    return {
+      text:
+        docs[args.section as keyof typeof docs] ||
+        "Documentation section not found",
+    };
+  },
+  mimeType: "text/markdown",
+  name: "Project Documentation",
+  uriTemplate: "docs://project/{section}",
+});
+
+server.addTool({
+  annotations: {
+    openWorldHint: false,
+    readOnlyHint: true,
+    title: "Get Documentation (Embedded)",
+  },
+  description:
+    "Retrieve project documentation using embedded resources - demonstrates the new embedded() feature",
+  execute: async (args) => {
+    return {
+      content: [
+        {
+          resource: await server.embedded(`docs://project/${args.section}`),
+          type: "resource",
+        },
+      ],
+    };
+  },
+  name: "get-documentation",
+  parameters: z.object({
+    section: z
+      .enum(["getting-started", "api-reference", "deployment"])
+      .describe("Documentation section to retrieve"),
+  }),
+});
+
 // Select transport type based on command line arguments
 const transportType = process.argv.includes("--http-stream")
   ? "httpStream"