fastmcp 1.6.1 → 1.8.0

package/README.md

@@ -1,6 +1,6 @@
 # FastMCP
 
-A TypeScript framework for building [MCP](https://modelcontextprotocol.io/) servers.
+A TypeScript framework for building [MCP](https://modelcontextprotocol.io/) servers capable of handling client sessions.
 
 > [!NOTE]
 > For a Python implementation, see [FastMCP](https://github.com/jlowin/fastmcp).
@@ -8,13 +8,15 @@ A TypeScript framework for building [MCP](https://modelcontextprotocol.io/) serv
 ## Features
 
 - Simple Tool, Resource, Prompt definition
-- Full TypeScript support
-- Built-in support for [image content](#returning-an-image)
-- Built-in [logging](#logging)
-- Built-in [error handling](#errors)
-- Built-in CLI for [testing](#test-with-mcp-cli) and [debugging](#inspect-with-mcp-inspector)
-- Built-in support for [SSE](#sse)
-- Built-in [progress notifications](#progress)
+- [Sessions](#sessions)
+- [Image content](#returning-an-image)
+- [Logging](#logging)
+- [Error handling](#errors)
+- [SSE](#sse)
+- [Progress notifications](#progress)
+- [Typed events](#typed-events)
+- Roots
+- CLI for [testing](#test-with-mcp-cli) and [debugging](#inspect-with-mcp-inspector)
 
 ## Installation
 
@@ -50,6 +52,8 @@ server.start({
 });
 ```
 
+_That's it!_ You have a working MCP server.
+
 You can test the server in terminal with:
 
 ```bash
@@ -371,7 +375,7 @@ async load() {
 
 [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.
 
-```js
+```ts
 server.addPrompt({
   name: "git-commit",
   description: "Generate a Git commit message",
@@ -388,6 +392,68 @@ server.addPrompt({
 });
 ```
 
+### Sessions
+
+The `session` object is an instance of `FastMCPSession` and it describes active client sessions.
+
+```ts
+server.sessions;
+```
+
+We allocate a new server instance for each client connection to enable 1:1 communication between a client and the server.
+
+### Typed events
+
+You can listen to events emitted by the server using the `on` method:
+
+```ts
+server.on("connect", (event) => {
+  console.log("Client connected:", event.session);
+});
+
+server.on("disconnect", (event) => {
+  console.log("Client disconnected:", event.session);
+});
+```
+
+## `FastMCPSession`
+
+`FastMCPSession` represents a client session and provides methods to interact with the client.
+
+Refer to [Sessions](#sessions) for examples of how to obtain a `FastMCPSession` instance.
+
+### `clientCapabilities`
+
+The `clientCapabilities` property contains the client capabilities.
+
+```ts
+session.clientCapabilities;
+```
+
+### `loggingLevel`
+
+The `loggingLevel` property describes the logging level as set by the client.
+
+```ts
+session.loggingLevel;
+```
+
+### `roots`
+
+The `roots` property contains the roots as set by the client.
+
+```ts
+session.roots;
+```
+
+### `server`
+
+The `server` property contains an instance of MCP server that is associated with the session.
+
+```ts
+session.server;
+```
+
 ## Running Your Server
 
 ### Test with `mcp-cli`
@@ -414,7 +480,7 @@ npx fastmcp inspect server.ts
 > [!NOTE]
 > If you've developed a server using FastMCP, please [submit a PR](https://github.com/punkpeye/fastmcp) to showcase it here!
 
-* https://github.com/apinetwork/piapi-mcp-server
+- https://github.com/apinetwork/piapi-mcp-server
 
 ## Acknowledgements
 

package/dist/FastMCP.d.ts

@@ -1,5 +1,21 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { ClientCapabilities, Root } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
+import { StrictEventEmitter } from 'strict-event-emitter-types';
+import { EventEmitter } from 'events';
+import { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
 
+type SSEServer = {
+    close: () => Promise<void>;
+};
+type FastMCPEvents = {
+    connect: (event: {
+        session: FastMCPSession;
+    }) => void;
+    disconnect: (event: {
+        session: FastMCPSession;
+    }) => void;
+};
 /**
  * Generates an image content object from a URL, file path, or buffer.
  */
@@ -100,19 +116,37 @@ type ServerOptions = {
     version: `${number}.${number}.${number}`;
 };
 type LoggingLevel = "debug" | "info" | "notice" | "warning" | "error" | "critical" | "alert" | "emergency";
-declare class FastMCP {
+declare class FastMCPSession {
     #private;
-    options: ServerOptions;
-    constructor(options: ServerOptions);
-    private setupHandlers;
+    constructor({ name, version, tools, resources, prompts, }: {
+        name: string;
+        version: string;
+        tools: Tool[];
+        resources: Resource[];
+        prompts: Prompt[];
+    });
+    get clientCapabilities(): ClientCapabilities | null;
+    get server(): Server;
+    connect(transport: Transport): Promise<void>;
+    get roots(): Root[];
+    close(): Promise<void>;
     private setupErrorHandling;
-    /**
-     * Returns the current logging level.
-     */
     get loggingLevel(): LoggingLevel;
+    private setupLoggingHandlers;
     private setupToolHandlers;
     private setupResourceHandlers;
     private setupPromptHandlers;
+}
+declare const FastMCPEventEmitterBase: {
+    new (): StrictEventEmitter<EventEmitter, FastMCPEvents>;
+};
+declare class FastMCPEventEmitter extends FastMCPEventEmitterBase {
+}
+declare class FastMCP extends FastMCPEventEmitter {
+    #private;
+    options: ServerOptions;
+    constructor(options: ServerOptions);
+    get sessions(): FastMCPSession[];
     /**
      * Adds a tool to the server.
      */
@@ -143,4 +177,4 @@ declare class FastMCP {
     stop(): Promise<void>;
 }
 
-export { FastMCP, UserError, imageContent };
+export { FastMCP, FastMCPSession, type SSEServer, UserError, imageContent };

package/dist/FastMCP.js

@@ -14,8 +14,10 @@ import {
 } from "@modelcontextprotocol/sdk/types.js";
 import { zodToJsonSchema } from "zod-to-json-schema";
 import { z } from "zod";
+import { setTimeout as delay } from "timers/promises";
 import { readFile } from "fs/promises";
 import { fileTypeFromBuffer } from "file-type";
+import { EventEmitter } from "events";
 import { startSSEServer } from "mcp-proxy";
 var imageContent = async (input) => {
   let rawData;
@@ -84,55 +86,97 @@ var ContentResultZodSchema = z.object({
   content: ContentZodSchema.array(),
   isError: z.boolean().optional()
 }).strict();
-var FastMCP = class {
-  constructor(options) {
-    this.options = options;
-    this.#options = options;
-    this.#tools = [];
-    this.#resources = [];
-    this.#prompts = [];
-  }
-  #tools;
-  #resources;
-  #prompts;
-  #server = null;
-  #options;
+var FastMCPSession = class {
+  #capabilities = {};
   #loggingLevel = "info";
-  setupHandlers(server) {
-    this.setupErrorHandling(server);
-    if (this.#tools.length) {
-      this.setupToolHandlers(server);
+  #server;
+  #clientCapabilities;
+  #roots = [];
+  constructor({
+    name,
+    version,
+    tools,
+    resources,
+    prompts
+  }) {
+    if (tools.length) {
+      this.#capabilities.tools = {};
     }
-    if (this.#resources.length) {
-      this.setupResourceHandlers(server);
+    if (resources.length) {
+      this.#capabilities.resources = {};
     }
-    if (this.#prompts.length) {
-      this.setupPromptHandlers(server);
+    if (prompts.length) {
+      this.#capabilities.prompts = {};
     }
-    server.setRequestHandler(SetLevelRequestSchema, (request) => {
-      this.#loggingLevel = request.params.level;
-      return {};
-    });
+    this.#capabilities.logging = {};
+    this.#server = new Server(
+      { name, version },
+      { capabilities: this.#capabilities }
+    );
+    this.setupErrorHandling();
+    this.setupLoggingHandlers();
+    if (tools.length) {
+      this.setupToolHandlers(tools);
+    }
+    if (resources.length) {
+      this.setupResourceHandlers(resources);
+    }
+    if (prompts.length) {
+      this.setupPromptHandlers(prompts);
+    }
+  }
+  get clientCapabilities() {
+    return this.#clientCapabilities ?? null;
+  }
+  get server() {
+    return this.#server;
+  }
+  async connect(transport) {
+    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;
+      }
+      await delay(100);
+    }
+    if (this.#clientCapabilities?.roots) {
+      const roots = await this.#server.listRoots();
+      this.#roots = roots.roots;
+    }
+    if (!this.#clientCapabilities) {
+      throw new UnexpectedStateError("Server did not connect");
+    }
+  }
+  get roots() {
+    return this.#roots;
+  }
+  async close() {
+    await this.#server.close();
   }
-  setupErrorHandling(server) {
-    server.onerror = (error) => {
+  setupErrorHandling() {
+    this.#server.onerror = (error) => {
       console.error("[MCP Error]", error);
     };
-    process.on("SIGINT", async () => {
-      await server.close();
-      process.exit(0);
-    });
   }
-  /**
-   * Returns the current logging level.
-   */
   get loggingLevel() {
     return this.#loggingLevel;
   }
-  setupToolHandlers(server) {
-    server.setRequestHandler(ListToolsRequestSchema, async () => {
+  setupLoggingHandlers() {
+    this.#server.setRequestHandler(SetLevelRequestSchema, (request) => {
+      this.#loggingLevel = request.params.level;
+      return {};
+    });
+  }
+  setupToolHandlers(tools) {
+    this.#server.setRequestHandler(ListToolsRequestSchema, async () => {
       return {
-        tools: this.#tools.map((tool) => {
+        tools: tools.map((tool) => {
           return {
             name: tool.name,
             description: tool.description,
@@ -141,10 +185,8 @@ var FastMCP = class {
         })
       };
     });
-    server.setRequestHandler(CallToolRequestSchema, async (request) => {
-      const tool = this.#tools.find(
-        (tool2) => tool2.name === request.params.name
-      );
+    this.#server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      const tool = tools.find((tool2) => tool2.name === request.params.name);
       if (!tool) {
         throw new McpError(
           ErrorCode.MethodNotFound,
@@ -166,7 +208,7 @@ var FastMCP = class {
       let result;
       try {
         const reportProgress = async (progress) => {
-          await server.notification({
+          await this.#server.notification({
             method: "notifications/progress",
             params: {
               ...progress,
@@ -176,7 +218,7 @@ var FastMCP = class {
         };
         const log = {
           debug: (message, context) => {
-            server.sendLoggingMessage({
+            this.#server.sendLoggingMessage({
               level: "debug",
               data: {
                 message,
@@ -185,7 +227,7 @@ var FastMCP = class {
             });
           },
           error: (message, context) => {
-            server.sendLoggingMessage({
+            this.#server.sendLoggingMessage({
               level: "error",
               data: {
                 message,
@@ -194,7 +236,7 @@ var FastMCP = class {
             });
           },
           info: (message, context) => {
-            server.sendLoggingMessage({
+            this.#server.sendLoggingMessage({
               level: "info",
               data: {
                 message,
@@ -203,7 +245,7 @@ var FastMCP = class {
             });
           },
           warn: (message, context) => {
-            server.sendLoggingMessage({
+            this.#server.sendLoggingMessage({
               level: "warning",
               data: {
                 message,
@@ -242,10 +284,10 @@ var FastMCP = class {
       return result;
     });
   }
-  setupResourceHandlers(server) {
-    server.setRequestHandler(ListResourcesRequestSchema, async () => {
+  setupResourceHandlers(resources) {
+    this.#server.setRequestHandler(ListResourcesRequestSchema, async () => {
       return {
-        resources: this.#resources.map((resource) => {
+        resources: resources.map((resource) => {
           return {
             uri: resource.uri,
             name: resource.name,
@@ -254,43 +296,46 @@ var FastMCP = class {
         })
       };
     });
-    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
-      const resource = this.#resources.find(
-        (resource2) => resource2.uri === request.params.uri
-      );
-      if (!resource) {
-        throw new McpError(
-          ErrorCode.MethodNotFound,
-          `Unknown resource: ${request.params.uri}`
-        );
-      }
-      let result;
-      try {
-        result = await resource.load();
-      } catch (error) {
-        throw new McpError(
-          ErrorCode.InternalError,
-          `Error reading resource: ${error}`,
-          {
-            uri: resource.uri
-          }
+    this.#server.setRequestHandler(
+      ReadResourceRequestSchema,
+      async (request) => {
+        const resource = resources.find(
+          (resource2) => resource2.uri === request.params.uri
         );
+        if (!resource) {
+          throw new McpError(
+            ErrorCode.MethodNotFound,
+            `Unknown resource: ${request.params.uri}`
+          );
+        }
+        let result;
+        try {
+          result = await resource.load();
+        } catch (error) {
+          throw new McpError(
+            ErrorCode.InternalError,
+            `Error reading resource: ${error}`,
+            {
+              uri: resource.uri
+            }
+          );
+        }
+        return {
+          contents: [
+            {
+              uri: resource.uri,
+              mimeType: resource.mimeType,
+              ...result
+            }
+          ]
+        };
       }
-      return {
-        contents: [
-          {
-            uri: resource.uri,
-            mimeType: resource.mimeType,
-            ...result
-          }
-        ]
-      };
-    });
+    );
   }
-  setupPromptHandlers(server) {
-    server.setRequestHandler(ListPromptsRequestSchema, async () => {
+  setupPromptHandlers(prompts) {
+    this.#server.setRequestHandler(ListPromptsRequestSchema, async () => {
       return {
-        prompts: this.#prompts.map((prompt) => {
+        prompts: prompts.map((prompt) => {
           return {
             name: prompt.name,
             description: prompt.description,
@@ -299,8 +344,8 @@ var FastMCP = class {
         })
       };
     });
-    server.setRequestHandler(GetPromptRequestSchema, async (request) => {
-      const prompt = this.#prompts.find(
+    this.#server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+      const prompt = prompts.find(
         (prompt2) => prompt2.name === request.params.name
       );
       if (!prompt) {
@@ -340,6 +385,25 @@ var FastMCP = class {
       };
     });
   }
+};
+var FastMCPEventEmitterBase = EventEmitter;
+var FastMCPEventEmitter = class extends FastMCPEventEmitterBase {
+};
+var FastMCP = class extends FastMCPEventEmitter {
+  constructor(options) {
+    super();
+    this.options = options;
+    this.#options = options;
+  }
+  #options;
+  #prompts = [];
+  #resources = [];
+  #sessions = [];
+  #sseServer = null;
+  #tools = [];
+  get sessions() {
+    return this.#sessions;
+  }
   /**
    * Adds a tool to the server.
    */
@@ -358,39 +422,55 @@ var FastMCP = class {
   addPrompt(prompt) {
     this.#prompts.push(prompt);
   }
-  #sseServer = null;
   /**
    * Starts the server.
    */
   async start(options = {
     transportType: "stdio"
   }) {
-    const capabilities = {};
-    if (this.#tools.length) {
-      capabilities.tools = {};
-    }
-    if (this.#resources.length) {
-      capabilities.resources = {};
-    }
-    if (this.#prompts.length) {
-      capabilities.prompts = {};
-    }
-    capabilities.logging = {};
-    this.#server = new Server(
-      { name: this.#options.name, version: this.#options.version },
-      { capabilities }
-    );
-    this.setupHandlers(this.#server);
     if (options.transportType === "stdio") {
       const transport = new StdioServerTransport();
-      await this.#server.connect(transport);
+      const session = new FastMCPSession({
+        name: this.#options.name,
+        version: this.#options.version,
+        tools: this.#tools,
+        resources: this.#resources,
+        prompts: this.#prompts
+      });
+      await session.connect(transport);
+      this.#sessions.push(session);
+      this.emit("connect", {
+        session
+      });
       console.error(`server is running on stdio`);
     } else if (options.transportType === "sse") {
       this.#sseServer = await startSSEServer({
         endpoint: options.sse.endpoint,
         port: options.sse.port,
-        server: this.#server
+        createServer: async () => {
+          return new FastMCPSession({
+            name: this.#options.name,
+            version: this.#options.version,
+            tools: this.#tools,
+            resources: this.#resources,
+            prompts: this.#prompts
+          });
+        },
+        onClose: (session) => {
+          this.emit("disconnect", {
+            session
+          });
+        },
+        onConnect: async (session) => {
+          this.#sessions.push(session);
+          this.emit("connect", {
+            session
+          });
+        }
       });
+      console.error(
+        `server is running on SSE at http://localhost:${options.sse.port}${options.sse.endpoint}`
+      );
     } else {
       throw new Error("Invalid transport type");
     }
@@ -406,6 +486,7 @@ var FastMCP = class {
 };
 export {
   FastMCP,
+  FastMCPSession,
   UserError,
   imageContent
 };