fastmcp 4.11.0 → 4.12.1

package/README.md

@@ -33,6 +33,7 @@ A TypeScript framework for building [MCP](https://glama.ai/mcp) servers capable
 - [Configurable ping behavior](#configurable-ping-behavior)
 - [Health-check endpoint](#health-check-endpoint)
 - [Roots](#roots-management)
+- [In-memory transport](#unit-testing-with-an-in-memory-transport) for unit testing without binding a port
 - CLI for [testing](#test-with-mcp-cli) and [debugging](#inspect-with-mcp-inspector)
 
 ## When to use FastMCP over the official SDK?
@@ -2525,6 +2526,51 @@ session.on("error", (event) => {
 
 ## Running Your Server
 
+### Unit testing with an in-memory transport
+
+`server.connect(transport)` attaches the server to a transport you construct yourself, instead of letting `start()` create one. Paired with the SDK's `InMemoryTransport`, this lets you drive a server in-process — no port to bind, no subprocess to spawn — which is usually what you want for testing a `stdio` server:
+
+```ts
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+
+async function createTestClient(server: FastMCP) {
+  const [clientTransport, serverTransport] =
+    InMemoryTransport.createLinkedPair();
+
+  const client = new Client({ name: "test-client", version: "0.0.0" });
+
+  const [session] = await Promise.all([
+    server.connect(serverTransport),
+    client.connect(clientTransport),
+  ]);
+
+  return { client, session };
+}
+
+test("adds two numbers", async () => {
+  const { client } = await createTestClient(server);
+
+  expect(
+    await client.callTool({ arguments: { a: 2, b: 3 }, name: "add" }),
+  ).toEqual({
+    content: [{ text: "5", type: "text" }],
+  });
+
+  await client.close();
+});
+```
+
+The session is built from the tools, resources and prompts registered on the instance, exactly as `start()` builds it, so your tests exercise the same wiring the real server uses — including `canAccess` filtering and the `connect`/`disconnect` events.
+
+Pass session auth as the second argument, equivalent to what your `authenticate` function would return:
+
+```ts
+await server.connect(serverTransport, { id: 7, role: "admin" });
+```
+
+`connect` returns the [`FastMCPSession`](#fastmcpsession), so you can assert on `session.clientCapabilities`, `session.roots`, and the rest. The transport's lifecycle belongs to you: `stop()` does not close transports passed to `connect`, so close the client (and the session, if you need `disconnect` to fire) when the test finishes.
+
 ### Test with `mcp-cli`
 
 The fastest way to test and debug your server is with `fastmcp dev`:

package/dist/FastMCP.cjs

@@ -8,7 +8,9 @@
 
 
 
-var _chunkISO2WPB5cjs = require('./chunk-ISO2WPB5.cjs');
+
+
+var _chunkPOXZCEYEcjs = require('./chunk-POXZCEYE.cjs');
 
 
 
@@ -43,5 +45,7 @@ var _chunkDZYT6QAHcjs = require('./chunk-DZYT6QAH.cjs');
 
 
 
-exports.AuthProvider = _chunkDZYT6QAHcjs.AuthProvider; exports.AzureProvider = _chunkDZYT6QAHcjs.AzureProvider; exports.DiscoveryDocumentCache = _chunkISO2WPB5cjs.DiscoveryDocumentCache; exports.FastMCP = _chunkISO2WPB5cjs.FastMCP; exports.FastMCPSession = _chunkISO2WPB5cjs.FastMCPSession; exports.GitHubProvider = _chunkDZYT6QAHcjs.GitHubProvider; exports.GoogleProvider = _chunkDZYT6QAHcjs.GoogleProvider; exports.OAuthProvider = _chunkDZYT6QAHcjs.OAuthProvider; exports.ServerState = _chunkISO2WPB5cjs.ServerState; exports.UnexpectedStateError = _chunkISO2WPB5cjs.UnexpectedStateError; exports.UserError = _chunkISO2WPB5cjs.UserError; exports.audioContent = _chunkISO2WPB5cjs.audioContent; exports.getAuthSession = _chunkDZYT6QAHcjs.getAuthSession; exports.imageContent = _chunkISO2WPB5cjs.imageContent; exports.jsonSchemaAdapter = _chunkISO2WPB5cjs.jsonSchemaAdapter; exports.requireAll = _chunkDZYT6QAHcjs.requireAll; exports.requireAny = _chunkDZYT6QAHcjs.requireAny; exports.requireAuth = _chunkDZYT6QAHcjs.requireAuth; exports.requireRole = _chunkDZYT6QAHcjs.requireRole; exports.requireScopes = _chunkDZYT6QAHcjs.requireScopes;
+
+
+exports.AuthProvider = _chunkDZYT6QAHcjs.AuthProvider; exports.AzureProvider = _chunkDZYT6QAHcjs.AzureProvider; exports.DiscoveryDocumentCache = _chunkPOXZCEYEcjs.DiscoveryDocumentCache; exports.FastMCP = _chunkPOXZCEYEcjs.FastMCP; exports.FastMCPError = _chunkPOXZCEYEcjs.FastMCPError; exports.FastMCPSession = _chunkPOXZCEYEcjs.FastMCPSession; exports.GitHubProvider = _chunkDZYT6QAHcjs.GitHubProvider; exports.GoogleProvider = _chunkDZYT6QAHcjs.GoogleProvider; exports.OAuthProvider = _chunkDZYT6QAHcjs.OAuthProvider; exports.ServerState = _chunkPOXZCEYEcjs.ServerState; exports.SessionError = _chunkPOXZCEYEcjs.SessionError; exports.UnexpectedStateError = _chunkPOXZCEYEcjs.UnexpectedStateError; exports.UserError = _chunkPOXZCEYEcjs.UserError; exports.audioContent = _chunkPOXZCEYEcjs.audioContent; exports.getAuthSession = _chunkDZYT6QAHcjs.getAuthSession; exports.imageContent = _chunkPOXZCEYEcjs.imageContent; exports.jsonSchemaAdapter = _chunkPOXZCEYEcjs.jsonSchemaAdapter; exports.requireAll = _chunkDZYT6QAHcjs.requireAll; exports.requireAny = _chunkDZYT6QAHcjs.requireAny; exports.requireAuth = _chunkDZYT6QAHcjs.requireAuth; exports.requireRole = _chunkDZYT6QAHcjs.requireRole; exports.requireScopes = _chunkDZYT6QAHcjs.requireScopes;
 //# sourceMappingURL=FastMCP.cjs.map

package/dist/FastMCP.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["/home/runner/work/fastmcp/fastmcp/dist/FastMCP.cjs"],"names":[],"mappings":"AAAA;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,wDAA6B;AAC7B;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,wDAA6B;AAC7B;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,inCAAC","file":"/home/runner/work/fastmcp/fastmcp/dist/FastMCP.cjs"}
+{"version":3,"sources":["/home/runner/work/fastmcp/fastmcp/dist/FastMCP.cjs"],"names":[],"mappings":"AAAA;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,wDAA6B;AAC7B;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,wDAA6B;AAC7B;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,+tCAAC","file":"/home/runner/work/fastmcp/fastmcp/dist/FastMCP.cjs"}

package/dist/FastMCP.d.cts

@@ -242,6 +242,19 @@ type ToolParameters = StandardSchemaV1;
 declare abstract class FastMCPError extends Error {
     constructor(message?: string);
 }
+/**
+ * An error raised when a session encounters a problem (e.g. connection
+ * failures, protocol violations).  Consumers can use this class to
+ * distinguish fastmcp session errors from unrelated runtime errors:
+ *
+ * ```ts
+ * server.on("error", ({ error }) => {
+ *   if (error instanceof SessionError) { ... }
+ * });
+ * ```
+ */
+declare class SessionError extends FastMCPError {
+}
 declare class UnexpectedStateError extends FastMCPError {
     extras?: Extras;
     constructor(message: string, extras?: Extras);
@@ -914,6 +927,34 @@ declare class FastMCP<T extends FastMCPSessionAuth = FastMCPSessionAuth> extends
      * Adds tools to the server.
      */
     addTools<Params extends ToolParameters>(tools: Tool<T, Params>[]): void;
+    /**
+     * Connects the server to a transport you constructed yourself, instead of
+     * letting {@link FastMCP.start} create one.
+     *
+     * The session is built from the tools, resources and prompts registered on
+     * this instance — exactly as `start()` does — so tests exercise the same
+     * wiring the real server uses. The main use case is driving a server
+     * in-process over `InMemoryTransport` without binding a port:
+     *
+     * ```ts
+     * const [clientTransport, serverTransport] =
+     *   InMemoryTransport.createLinkedPair();
+     *
+     * await Promise.all([
+     *   server.connect(serverTransport),
+     *   client.connect(clientTransport),
+     * ]);
+     * ```
+     *
+     * The transport's lifecycle belongs to the caller: `stop()` does not close
+     * transports passed here. Close the returned session (or the transport) when
+     * you are done with it.
+     *
+     * @param transport - An already-constructed MCP server transport.
+     * @param auth - Session auth, equivalent to what `authenticate` would return.
+     * @returns The session bound to the transport.
+     */
+    connect(transport: Transport, auth?: T): Promise<FastMCPSession<T>>;
     /**
      * Embeds a resource by URI, making it easy to include resources in tool responses.
      *
@@ -1011,4 +1052,4 @@ declare class FastMCP<T extends FastMCPSessionAuth = FastMCPSessionAuth> extends
     stop(): Promise<void>;
 }
 
-export { type AudioContent, AuthProvider, type Content, type ContentResult, type Context, DiscoveryDocumentCache, FastMCP, type FastMCPEvents, type FastMCPRequest, type FastMCPResponse, FastMCPSession, type FastMCPSessionAuth, type FastMCPSessionEvents, type HTTPMethod, type ImageContent, type InputPrompt, type InputPromptArgument, type JsonSchemaObject, type JsonSchemaStandardSchema, type LoadContext, type Logger, type LoggingLevel, OAuthSession, type Progress, type Prompt, type PromptArgument, type Resource, type ResourceContent, type ResourceResult, type ResourceTemplate, type ResourceTemplateArgument, type RouteHandler, type RouteOptions, type SSEServer, type SerializableValue, type ServerOptions, ServerState, type TextContent, type Tool, type ToolParameters, UnexpectedStateError, UserError, audioContent, imageContent, jsonSchemaAdapter };
+export { type AudioContent, AuthProvider, type Content, type ContentResult, type Context, DiscoveryDocumentCache, FastMCP, FastMCPError, type FastMCPEvents, type FastMCPRequest, type FastMCPResponse, FastMCPSession, type FastMCPSessionAuth, type FastMCPSessionEvents, type HTTPMethod, type ImageContent, type InputPrompt, type InputPromptArgument, type JsonSchemaObject, type JsonSchemaStandardSchema, type LoadContext, type Logger, type LoggingLevel, OAuthSession, type Progress, type Prompt, type PromptArgument, type Resource, type ResourceContent, type ResourceResult, type ResourceTemplate, type ResourceTemplateArgument, type RouteHandler, type RouteOptions, type SSEServer, type SerializableValue, type ServerOptions, ServerState, SessionError, type TextContent, type Tool, type ToolParameters, UnexpectedStateError, UserError, audioContent, imageContent, jsonSchemaAdapter };

package/dist/FastMCP.d.ts

@@ -242,6 +242,19 @@ type ToolParameters = StandardSchemaV1;
 declare abstract class FastMCPError extends Error {
     constructor(message?: string);
 }
+/**
+ * An error raised when a session encounters a problem (e.g. connection
+ * failures, protocol violations).  Consumers can use this class to
+ * distinguish fastmcp session errors from unrelated runtime errors:
+ *
+ * ```ts
+ * server.on("error", ({ error }) => {
+ *   if (error instanceof SessionError) { ... }
+ * });
+ * ```
+ */
+declare class SessionError extends FastMCPError {
+}
 declare class UnexpectedStateError extends FastMCPError {
     extras?: Extras;
     constructor(message: string, extras?: Extras);
@@ -914,6 +927,34 @@ declare class FastMCP<T extends FastMCPSessionAuth = FastMCPSessionAuth> extends
      * Adds tools to the server.
      */
     addTools<Params extends ToolParameters>(tools: Tool<T, Params>[]): void;
+    /**
+     * Connects the server to a transport you constructed yourself, instead of
+     * letting {@link FastMCP.start} create one.
+     *
+     * The session is built from the tools, resources and prompts registered on
+     * this instance — exactly as `start()` does — so tests exercise the same
+     * wiring the real server uses. The main use case is driving a server
+     * in-process over `InMemoryTransport` without binding a port:
+     *
+     * ```ts
+     * const [clientTransport, serverTransport] =
+     *   InMemoryTransport.createLinkedPair();
+     *
+     * await Promise.all([
+     *   server.connect(serverTransport),
+     *   client.connect(clientTransport),
+     * ]);
+     * ```
+     *
+     * The transport's lifecycle belongs to the caller: `stop()` does not close
+     * transports passed here. Close the returned session (or the transport) when
+     * you are done with it.
+     *
+     * @param transport - An already-constructed MCP server transport.
+     * @param auth - Session auth, equivalent to what `authenticate` would return.
+     * @returns The session bound to the transport.
+     */
+    connect(transport: Transport, auth?: T): Promise<FastMCPSession<T>>;
     /**
      * Embeds a resource by URI, making it easy to include resources in tool responses.
      *
@@ -1011,4 +1052,4 @@ declare class FastMCP<T extends FastMCPSessionAuth = FastMCPSessionAuth> extends
     stop(): Promise<void>;
 }
 
-export { type AudioContent, AuthProvider, type Content, type ContentResult, type Context, DiscoveryDocumentCache, FastMCP, type FastMCPEvents, type FastMCPRequest, type FastMCPResponse, FastMCPSession, type FastMCPSessionAuth, type FastMCPSessionEvents, type HTTPMethod, type ImageContent, type InputPrompt, type InputPromptArgument, type JsonSchemaObject, type JsonSchemaStandardSchema, type LoadContext, type Logger, type LoggingLevel, OAuthSession, type Progress, type Prompt, type PromptArgument, type Resource, type ResourceContent, type ResourceResult, type ResourceTemplate, type ResourceTemplateArgument, type RouteHandler, type RouteOptions, type SSEServer, type SerializableValue, type ServerOptions, ServerState, type TextContent, type Tool, type ToolParameters, UnexpectedStateError, UserError, audioContent, imageContent, jsonSchemaAdapter };
+export { type AudioContent, AuthProvider, type Content, type ContentResult, type Context, DiscoveryDocumentCache, FastMCP, FastMCPError, type FastMCPEvents, type FastMCPRequest, type FastMCPResponse, FastMCPSession, type FastMCPSessionAuth, type FastMCPSessionEvents, type HTTPMethod, type ImageContent, type InputPrompt, type InputPromptArgument, type JsonSchemaObject, type JsonSchemaStandardSchema, type LoadContext, type Logger, type LoggingLevel, OAuthSession, type Progress, type Prompt, type PromptArgument, type Resource, type ResourceContent, type ResourceResult, type ResourceTemplate, type ResourceTemplateArgument, type RouteHandler, type RouteOptions, type SSEServer, type SerializableValue, type ServerOptions, ServerState, SessionError, type TextContent, type Tool, type ToolParameters, UnexpectedStateError, UserError, audioContent, imageContent, jsonSchemaAdapter };

package/dist/FastMCP.js

@@ -1,14 +1,16 @@
 import {
   DiscoveryDocumentCache,
   FastMCP,
+  FastMCPError,
   FastMCPSession,
   ServerState,
+  SessionError,
   UnexpectedStateError,
   UserError,
   audioContent,
   imageContent,
   jsonSchemaAdapter
-} from "./chunk-JOZJUFKE.js";
+} from "./chunk-5BQXF2VT.js";
 import {
   AuthProvider,
   AzureProvider,
@@ -27,11 +29,13 @@ export {
   AzureProvider,
   DiscoveryDocumentCache,
   FastMCP,
+  FastMCPError,
   FastMCPSession,
   GitHubProvider,
   GoogleProvider,
   OAuthProvider,
   ServerState,
+  SessionError,
   UnexpectedStateError,
   UserError,
   audioContent,

package/dist/{chunk-JOZJUFKE.js → chunk-5BQXF2VT.js}

@@ -294,6 +294,8 @@ var FastMCPError = class extends Error {
     this.name = new.target.name;
   }
 };
+var SessionError = class extends FastMCPError {
+};
 var UnexpectedStateError = class extends FastMCPError {
   extras;
   constructor(message, extras) {
@@ -1559,6 +1561,53 @@ var FastMCP = class extends FastMCPEventEmitter {
       this.#toolsListChanged(this.#tools);
     }
   }
+  /**
+   * Connects the server to a transport you constructed yourself, instead of
+   * letting {@link FastMCP.start} create one.
+   *
+   * The session is built from the tools, resources and prompts registered on
+   * this instance — exactly as `start()` does — so tests exercise the same
+   * wiring the real server uses. The main use case is driving a server
+   * in-process over `InMemoryTransport` without binding a port:
+   *
+   * ```ts
+   * const [clientTransport, serverTransport] =
+   *   InMemoryTransport.createLinkedPair();
+   *
+   * await Promise.all([
+   *   server.connect(serverTransport),
+   *   client.connect(clientTransport),
+   * ]);
+   * ```
+   *
+   * The transport's lifecycle belongs to the caller: `stop()` does not close
+   * transports passed here. Close the returned session (or the transport) when
+   * you are done with it.
+   *
+   * @param transport - An already-constructed MCP server transport.
+   * @param auth - Session auth, equivalent to what `authenticate` would return.
+   * @returns The session bound to the transport.
+   */
+  async connect(transport, auth) {
+    const session = this.#createSession(auth);
+    await session.connect(transport);
+    this.#sessions.push(session);
+    session.once("error", () => {
+      this.#removeSession(session);
+    });
+    const originalOnClose = transport.onclose;
+    transport.onclose = () => {
+      this.#removeSession(session);
+      if (originalOnClose) {
+        originalOnClose();
+      }
+    };
+    this.emit("connect", {
+      session
+    });
+    this.#serverState = "running" /* Running */;
+    return session;
+  }
   /**
    * Embeds a resource by URI, making it easy to include resources in tool responses.
    *
@@ -2439,10 +2488,12 @@ export {
   jsonSchemaAdapter,
   imageContent,
   audioContent,
+  FastMCPError,
+  SessionError,
   UnexpectedStateError,
   UserError,
   ServerState,
   FastMCPSession,
   FastMCP
 };
-//# sourceMappingURL=chunk-JOZJUFKE.js.map
+//# sourceMappingURL=chunk-5BQXF2VT.js.map