fastmcp 2.1.4 → 2.2.1

package/README.md

@@ -13,6 +13,7 @@ A TypeScript framework for building [MCP](https://glama.ai/mcp) servers capable
 - [Sessions](#sessions)
 - [Image content](#returning-an-image)
 - [Audio content](#returning-an-audio)
+- [Embedded](#embedded-resources)
 - [Logging](#logging)
 - [Error handling](#errors)
 - [HTTP Streaming](#http-streaming) (with SSE compatibility)
@@ -915,6 +916,114 @@ server.addResourceTemplate({
 });
 ```
 
+### Embedded Resources
+
+FastMCP provides a convenient `embedded()` method that simplifies including resources in tool responses. This feature reduces code duplication and makes it easier to reference resources from within tools.
+
+#### Basic Usage
+
+```js
+server.addTool({
+  name: "get_user_data",
+  description: "Retrieve user information",
+  parameters: z.object({
+    userId: z.string(),
+  }),
+  execute: async (args) => {
+    return {
+      content: [
+        {
+          type: "resource",
+          resource: await server.embedded(`user://profile/${args.userId}`),
+        },
+      ],
+    };
+  },
+});
+```
+
+#### Working with Resource Templates
+
+The `embedded()` method works seamlessly with resource templates:
+
+```js
+// Define a resource template
+server.addResourceTemplate({
+  uriTemplate: "docs://project/{section}",
+  name: "Project Documentation",
+  mimeType: "text/markdown",
+  arguments: [
+    {
+      name: "section",
+      required: true,
+    },
+  ],
+  async load(args) {
+    const docs = {
+      "getting-started": "# Getting Started\n\nWelcome to our project!",
+      "api-reference": "# API Reference\n\nAuthentication is required.",
+    };
+    return {
+      text: docs[args.section] || "Documentation not found",
+    };
+  },
+});
+
+// Use embedded resources in a tool
+server.addTool({
+  name: "get_documentation",
+  description: "Retrieve project documentation",
+  parameters: z.object({
+    section: z.enum(["getting-started", "api-reference"]),
+  }),
+  execute: async (args) => {
+    return {
+      content: [
+        {
+          type: "resource",
+          resource: await server.embedded(`docs://project/${args.section}`),
+        },
+      ],
+    };
+  },
+});
+```
+
+#### Working with Direct Resources
+
+It also works with directly defined resources:
+
+```js
+// Define a direct resource
+server.addResource({
+  uri: "system://status",
+  name: "System Status",
+  mimeType: "text/plain",
+  async load() {
+    return {
+      text: "System operational",
+    };
+  },
+});
+
+// Use in a tool
+server.addTool({
+  name: "get_system_status",
+  description: "Get current system status",
+  parameters: z.object({}),
+  execute: async () => {
+    return {
+      content: [
+        {
+          type: "resource",
+          resource: await server.embedded("system://status"),
+        },
+      ],
+    };
+  },
+});
+```
+
 ### Prompts
 
 [Prompts](https://modelcontextprotocol.io/docs/concepts/prompts) enable servers to define reusable prompt templates and workflows that clients can easily surface to users and LLMs. They provide a powerful way to standardize and share common LLM interactions.
@@ -1197,6 +1306,7 @@ Follow the guide https://modelcontextprotocol.io/quickstart/user and add the fol
 - [aiamblichus/mcp-chat-adapter](https://github.com/aiamblichus/mcp-chat-adapter) – provides a clean interface for LLMs to use chat completion
 - [eyaltoledano/claude-task-master](https://github.com/eyaltoledano/claude-task-master) – advanced AI project/task manager powered by FastMCP
 - [cswkim/discogs-mcp-server](https://github.com/cswkim/discogs-mcp-server) - connects to the Discogs API for interacting with your music collection
+- [Panzer-Jack/feuse-mcp](https://github.com/Panzer-Jack/feuse-mcp) - Frontend Useful MCP Tools - Essential utilities for web developers to automate API integration and code generation
 
 ## Acknowledgements
 

package/dist/FastMCP.d.ts

@@ -22,6 +22,7 @@ type FastMCPSessionEvents = {
     error: (event: {
         error: Error;
     }) => void;
+    ready: () => void;
     rootsChanged: (event: {
         roots: Root[];
     }) => void;
@@ -94,7 +95,16 @@ type AudioContent = {
     mimeType: string;
     type: "audio";
 };
-type Content = AudioContent | ImageContent | TextContent;
+type ResourceContent = {
+    resource: {
+        blob?: string;
+        mimeType?: string;
+        text?: string;
+        uri: string;
+    };
+    type: "resource";
+};
+type Content = AudioContent | ImageContent | ResourceContent | TextContent;
 type ContentResult = {
     content: Content[];
     isError?: boolean;
@@ -264,7 +274,7 @@ type Tool<T extends FastMCPSessionAuth, Params extends ToolParameters = ToolPara
         streamingHint?: boolean;
     } & ToolAnnotations;
     description?: string;
-    execute: (args: StandardSchemaV1.InferOutput<Params>, context: Context<T>) => Promise<AudioContent | ContentResult | ImageContent | string | TextContent | void>;
+    execute: (args: StandardSchemaV1.InferOutput<Params>, context: Context<T>) => Promise<AudioContent | ContentResult | ImageContent | ResourceContent | string | TextContent | void>;
     name: string;
     parameters?: Params;
     timeoutMs?: number;
@@ -316,6 +326,7 @@ declare class FastMCPSessionEventEmitter extends FastMCPSessionEventEmitterBase
 declare class FastMCPSession<T extends FastMCPSessionAuth = FastMCPSessionAuth> extends FastMCPSessionEventEmitter {
     #private;
     get clientCapabilities(): ClientCapabilities | null;
+    get isReady(): boolean;
     get loggingLevel(): LoggingLevel;
     get roots(): Root[];
     get server(): Server;
@@ -334,6 +345,7 @@ declare class FastMCPSession<T extends FastMCPSessionAuth = FastMCPSessionAuth>
     close(): Promise<void>;
     connect(transport: Transport): Promise<void>;
     requestSampling(message: z.infer<typeof CreateMessageRequestSchema>["params"]): Promise<SamplingResponse>;
+    waitForReady(): Promise<void>;
     private addPrompt;
     private addResource;
     private addResourceTemplate;
@@ -373,6 +385,13 @@ declare class FastMCP<T extends Record<string, unknown> | undefined = undefined>
      * Adds a tool to the server.
      */
     addTool<Params extends ToolParameters>(tool: Tool<T, Params>): void;
+    /**
+     * 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
+     */
+    embedded(uri: string): Promise<ResourceContent["resource"]>;
     /**
      * Starts the server.
      */

package/dist/FastMCP.js

@@ -171,10 +171,20 @@ var AudioContentZodSchema = z.object({
   mimeType: z.string(),
   type: z.literal("audio")
 }).strict();
+var 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();
 var ContentZodSchema = z.discriminatedUnion("type", [
   TextContentZodSchema,
   ImageContentZodSchema,
-  AudioContentZodSchema
+  AudioContentZodSchema,
+  ResourceContentZodSchema
 ]);
 var ContentResultZodSchema = z.object({
   content: ContentZodSchema.array(),
@@ -201,6 +211,9 @@ var FastMCPSession = class extends FastMCPSessionEventEmitter {
   get clientCapabilities() {
     return this.#clientCapabilities ?? null;
   }
+  get isReady() {
+    return this.#connectionState === "ready";
+  }
   get loggingLevel() {
     return this.#loggingLevel;
   }
@@ -213,6 +226,7 @@ var FastMCPSession = class extends FastMCPSessionEventEmitter {
   #auth;
   #capabilities = {};
   #clientCapabilities;
+  #connectionState = "connecting";
   #loggingLevel = "info";
   #pingConfig;
   #pingInterval = null;
@@ -279,6 +293,7 @@ var FastMCPSession = class extends FastMCPSessionEventEmitter {
     }
   }
   async close() {
+    this.#connectionState = "closed";
     if (this.#pingInterval) {
       clearInterval(this.#pingInterval);
     }
@@ -292,64 +307,105 @@ var FastMCPSession = class extends FastMCPSessionEventEmitter {
     if (this.#server.transport) {
       throw new UnexpectedStateError("Server is already connected");
     }
-    await this.#server.connect(transport);
-    let attempt = 0;
-    while (attempt++ < 10) {
-      const capabilities = await this.#server.getClientCapabilities();
-      if (capabilities) {
-        this.#clientCapabilities = capabilities;
-        break;
+    this.#connectionState = "connecting";
+    try {
+      await this.#server.connect(transport);
+      let attempt = 0;
+      while (attempt++ < 10) {
+        const capabilities = this.#server.getClientCapabilities();
+        if (capabilities) {
+          this.#clientCapabilities = capabilities;
+          break;
+        }
+        await delay(100);
       }
-      await delay(100);
-    }
-    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.
+      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.
 
 ${e instanceof Error ? e.stack : JSON.stringify(e)}`
-          );
+            );
+          }
         }
       }
-    }
-    if (this.#clientCapabilities) {
-      const pingConfig = this.#getPingConfig(transport);
-      if (pingConfig.enabled) {
-        this.#pingInterval = setInterval(async () => {
-          try {
-            await this.#server.ping();
-          } catch {
-            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 (this.#clientCapabilities) {
+        const pingConfig = this.#getPingConfig(transport);
+        if (pingConfig.enabled) {
+          this.#pingInterval = setInterval(async () => {
+            try {
+              await this.#server.ping();
+            } catch {
+              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);
+        }
       }
+      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;
     }
   }
   async requestSampling(message) {
     return this.#server.createMessage(message);
   }
+  waitForReady() {
+    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"
+          )
+        );
+      }, 5e3);
+      this.once("ready", () => {
+        clearTimeout(timeout);
+        resolve();
+      });
+      this.once("error", (event) => {
+        clearTimeout(timeout);
+        reject(event.error);
+      });
+    });
+  }
   #getPingConfig(transport) {
     const pingConfig = this.#pingConfig || {};
     let defaultEnabled = false;
@@ -889,6 +945,66 @@ var FastMCP = class extends FastMCPEventEmitter {
   addTool(tool) {
     this.#tools.push(tool);
   }
+  /**
+   * 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
+   */
+  async embedded(uri) {
+    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 = {
+        mimeType: directResource.mimeType,
+        uri
+      };
+      if ("text" in firstResult) {
+        resourceData.text = firstResult.text;
+      }
+      if ("blob" in firstResult) {
+        resourceData.blob = firstResult.blob;
+      }
+      return resourceData;
+    }
+    for (const template of this.#resourcesTemplates) {
+      const templateBase = template.uriTemplate.split("{")[0];
+      if (uri.startsWith(templateBase)) {
+        const params = {};
+        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
+        );
+        const resourceData = {
+          mimeType: template.mimeType,
+          uri
+        };
+        if ("text" in result) {
+          resourceData.text = result.text;
+        }
+        if ("blob" in result) {
+          resourceData.blob = result.blob;
+        }
+        return resourceData;
+      }
+    }
+    throw new UnexpectedStateError(`Resource not found: ${uri}`, { uri });
+  }
   /**
    * Starts the server.
    */
@@ -948,13 +1064,30 @@ var FastMCP = class extends FastMCPEventEmitter {
           const enabled = healthConfig.enabled === void 0 ? true : healthConfig.enabled;
           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"
                 }).end(healthConfig.message ?? "ok");
                 return;
               }
+              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);
             }