fastmcp 2.3.5__tar.gz → 2.5.0__tar.gz

{fastmcp-2.3.5 → fastmcp-2.5.0}/.github/workflows/run-tests.yml

@@ -44,7 +44,7 @@ jobs:
           python-version: ${{ matrix.python-version }}
 
       - name: Install FastMCP
-        run: uv sync --dev --locked
+        run: uv sync --locked
 
       - name: Run tests
-        run: uv run pytest
+        run: uv run pytest tests

{fastmcp-2.3.5 → fastmcp-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastmcp
-Version: 2.3.5
+Version: 2.5.0
 Summary: The fast, Pythonic way to build MCP servers.
 Project-URL: Homepage, https://gofastmcp.com
 Project-URL: Repository, https://github.com/jlowin/fastmcp
@@ -44,11 +44,11 @@ Description-Content-Type: text/markdown
 > [!NOTE]
 > #### FastMCP 2.0 & The Official MCP SDK
 >
-> Recognize the `FastMCP` name? You might have seen the version that was contributed to the [official MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk), which was based on **FastMCP 1.0**.
+> FastMCP is the standard framework for building MCP servers and clients. FastMCP 1.0 was incorporated into the [official MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk).
 >
-> **Welcome to FastMCP 2.0!** This is the actively developed successor, and it significantly expands on 1.0 by introducing powerful client capabilities, server proxying & composition, OpenAPI/FastAPI integration, and more advanced features.
+> **This is FastMCP 2.0,** the actively maintained version that significantly expands on 1.0's basic server-building capabilities by introducing full client support, server composition, OpenAPI/FastAPI integration, remote server proxying, built-in testing tools, and more.
 >
-> FastMCP 2.0 is the recommended path for building modern, powerful MCP applications. Ready to upgrade or get started? Follow the [installation instructions](https://gofastmcp.com/getting-started/installation), which include specific steps for upgrading from the official MCP SDK.
+> FastMCP 2.0 is the complete toolkit for modern AI applications. Ready to upgrade or get started? Follow the [installation instructions](https://gofastmcp.com/getting-started/installation), which include specific steps for upgrading from the official MCP SDK.
 
 ---
 
@@ -282,6 +282,29 @@ async def main():
         # ... use the client
 ```
 
+FastMCP also supports connecting to multiple servers through a single unified client using the standard MCP configuration format:
+
+```python
+from fastmcp import Client
+
+# Standard MCP configuration with multiple servers
+config = {
+    "mcpServers": {
+        "weather": {"url": "https://weather-api.example.com/mcp"},
+        "assistant": {"command": "python", "args": ["./assistant_server.py"]}
+    }
+}
+
+# Create a client that connects to all servers
+client = Client(config)
+
+async def main():
+    async with client:
+        # Access tools and resources with server prefixes
+        forecast = await client.call_tool("weather_get_forecast", {"city": "London"})
+        answer = await client.call_tool("assistant_answer_question", {"query": "What is MCP?"})
+```
+
 Learn more in the [**Client Documentation**](https://gofastmcp.com/clients/client) and [**Transports Documentation**](https://gofastmcp.com/clients/transports).
 
 ## Advanced Features

{fastmcp-2.3.5 → fastmcp-2.5.0}/README.md

@@ -15,11 +15,11 @@
 > [!NOTE]
 > #### FastMCP 2.0 & The Official MCP SDK
 >
-> Recognize the `FastMCP` name? You might have seen the version that was contributed to the [official MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk), which was based on **FastMCP 1.0**.
+> FastMCP is the standard framework for building MCP servers and clients. FastMCP 1.0 was incorporated into the [official MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk).
 >
-> **Welcome to FastMCP 2.0!** This is the actively developed successor, and it significantly expands on 1.0 by introducing powerful client capabilities, server proxying & composition, OpenAPI/FastAPI integration, and more advanced features.
+> **This is FastMCP 2.0,** the actively maintained version that significantly expands on 1.0's basic server-building capabilities by introducing full client support, server composition, OpenAPI/FastAPI integration, remote server proxying, built-in testing tools, and more.
 >
-> FastMCP 2.0 is the recommended path for building modern, powerful MCP applications. Ready to upgrade or get started? Follow the [installation instructions](https://gofastmcp.com/getting-started/installation), which include specific steps for upgrading from the official MCP SDK.
+> FastMCP 2.0 is the complete toolkit for modern AI applications. Ready to upgrade or get started? Follow the [installation instructions](https://gofastmcp.com/getting-started/installation), which include specific steps for upgrading from the official MCP SDK.
 
 ---
 
@@ -253,6 +253,29 @@ async def main():
         # ... use the client
 ```
 
+FastMCP also supports connecting to multiple servers through a single unified client using the standard MCP configuration format:
+
+```python
+from fastmcp import Client
+
+# Standard MCP configuration with multiple servers
+config = {
+    "mcpServers": {
+        "weather": {"url": "https://weather-api.example.com/mcp"},
+        "assistant": {"command": "python", "args": ["./assistant_server.py"]}
+    }
+}
+
+# Create a client that connects to all servers
+client = Client(config)
+
+async def main():
+    async with client:
+        # Access tools and resources with server prefixes
+        forecast = await client.call_tool("weather_get_forecast", {"city": "London"})
+        answer = await client.call_tool("assistant_answer_question", {"query": "What is MCP?"})
+```
+
 Learn more in the [**Client Documentation**](https://gofastmcp.com/clients/client) and [**Transports Documentation**](https://gofastmcp.com/clients/transports).
 
 ## Advanced Features

fastmcp-2.5.0/docs/clients/advanced-features.mdx

@@ -0,0 +1,152 @@
+---
+title: Advanced Features
+sidebarTitle: Advanced Features
+description: Learn about the advanced features of the FastMCP Client.
+icon: stars
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+In addition to basic server interaction, FastMCP clients can also handle more advanced features and server interaction patterns. The `Client` constructor accepts additional configuration to handle these server requests.
+
+<Tip>
+To enable many of these features, you must provide an appropriate handler or callback function. For example. In most cases, if you do not provide a handler, FastMCP's default handler will emit a `DEBUG` level log.
+</Tip>
+
+## Logging and Notifications
+
+<VersionBadge version="2.0.0" />
+MCP servers can emit logs to clients. To process these logs, you can provide a `log_handler` to the client.
+
+The `log_handler` must be an async function that accepts a single argument, which is an instance of `fastmcp.client.logging.LogMessage`. This has attributes like `level`, `logger`, and `data`.
+
+```python {2, 12}
+from fastmcp import Client
+from fastmcp.client.logging import LogMessage
+
+async def log_handler(message: LogMessage):
+    level = message.level.upper()
+    logger = message.logger or 'default'
+    data = message.data
+    print(f"[Server Log - {level}] {logger}: {data}")
+
+client_with_logging = Client(
+    ...,
+    log_handler=log_handler,
+)
+```
+## Progress Monitoring
+
+<VersionBadge version="2.3.5" />
+
+MCP servers can report progress during long-running operations. The client can set a progress handler to receive and process these updates.
+
+```python {2, 13}
+from fastmcp import Client
+from fastmcp.client.progress import ProgressHandler
+
+async def my_progress_handler(
+    progress: float, 
+    total: float | None, 
+    message: str | None
+) -> None:
+    print(f"Progress: {progress} / {total} ({message})")
+
+client = Client(
+    ...,
+    progress_handler=my_progress_handler
+)
+```
+
+By default, FastMCP uses a handler that logs progress updates at the debug level. This default handler properly handles cases where `total` or `message` might be None.
+
+You can override the progress handler for specific tool calls:
+
+```python
+# Client uses the default debug logger for progress
+client = Client(...)
+
+async with client:
+    # Use default progress handler (debug logging)
+    result1 = await client.call_tool("long_task", {"param": "value"})
+    
+    # Override with custom progress handler just for this call
+    result2 = await client.call_tool(
+        "another_task", 
+        {"param": "value"}, 
+        progress_handler=my_progress_handler
+    )
+```
+
+A typical progress update includes:
+- Current progress value (e.g., 2 of 5 steps completed)
+- Total expected value (may be None)
+- Status message (may be None)
+
+## LLM Sampling
+
+<VersionBadge version="2.0.0" />
+
+MCP Servers can request LLM completions from clients. The client can provide a `sampling_handler` to handle these requests. The sampling handler receives a list of messages and other parameters from the server, and should return a string completion.
+
+The following example uses the `marvin` library to generate a completion:
+
+```python {8-17, 21}
+import marvin
+from fastmcp import Client
+from fastmcp.client.sampling import (
+    SamplingMessage,
+    SamplingParams,
+    RequestContext,
+)
+
+async def sampling_handler(
+    messages: list[SamplingMessage],
+    params: SamplingParams,
+    context: RequestContext
+) -> str:
+    return await marvin.say_async(
+        message=[m.content.text for m in messages],
+        instructions=params.systemPrompt,
+    )
+
+client = Client(
+    ...,
+    sampling_handler=sampling_handler,
+)
+```
+
+
+## Roots
+
+<VersionBadge version="2.0.0" />
+
+Roots are a way for clients to inform servers about the resources they have access to or certain boundaries on their access. The server can use this information to adjust behavior or provide more accurate responses.
+
+Servers can request roots from clients, and clients can notify servers when their roots change.
+
+To set the roots when creating a client, users can either provide a list of roots (which can be a list of strings) or an async function that returns a list of roots.
+
+<CodeGroup>
+```python Static Roots {5}
+from fastmcp import Client
+
+client = Client(
+    ..., 
+    roots=["/path/to/root1", "/path/to/root2"],
+)
+```
+```python Dynamic Roots Callback {4-6, 10}
+from fastmcp import Client
+from fastmcp.client.roots import RequestContext
+
+async def roots_callback(context: RequestContext) -> list[str]:
+    print(f"Server requested roots (Request ID: {context.request_id})")
+    return ["/path/to/root1", "/path/to/root2"]
+
+client = Client(
+    ..., 
+    roots=roots_callback,
+)
+```
+</CodeGroup>

{fastmcp-2.3.5 → fastmcp-2.5.0}/docs/clients/client.mdx

@@ -37,13 +37,14 @@ Clients must be initialized with a `transport`. You can either provide an alread
 The following inference rules are used to determine the appropriate `ClientTransport` based on the input type:
 
 1.  **`ClientTransport` Instance**: If you provide an already instantiated transport object, it's used directly.
-2.  **`FastMCP` Instance**: Creates a `FastMCPTransport` for efficient in-memory communication (ideal for testing).
+2.  **`FastMCP` Instance**: Creates a `FastMCPTransport` for efficient in-memory communication (ideal for testing). This also works with a **FastMCP 1.0 server** created via `mcp.server.fastmcp.FastMCP`.
 3.  **`Path` or `str` pointing to an existing file**:
     *   If it ends with `.py`: Creates a `PythonStdioTransport` to run the script using `python`.
     *   If it ends with `.js`: Creates a `NodeStdioTransport` to run the script using `node`.
 4.  **`AnyUrl` or `str` pointing to a URL that begins with `http://` or `https://`**:
     *   Creates a `StreamableHttpTransport`
-5.  **Other**: Raises a `ValueError` if the type cannot be inferred.
+5.  **`MCPConfig` or dictionary matching MCPConfig schema**: Creates a client that connects to one or more MCP servers specified in the config.
+6.  **Other**: Raises a `ValueError` if the type cannot be inferred.
 
 ```python
 import asyncio
@@ -52,30 +53,100 @@ from fastmcp import Client, FastMCP
 # Example transports (more details in Transports page)
 server_instance = FastMCP(name="TestServer") # In-memory server
 http_url = "https://example.com/mcp"        # HTTP server URL
-ws_url = "ws://localhost:9000"             # WebSocket server URL
 server_script = "my_mcp_server.py"         # Path to a Python server file
 
 # Client automatically infers the transport type
 client_in_memory = Client(server_instance)
 client_http = Client(http_url)
-client_ws = Client(ws_url)
+
 client_stdio = Client(server_script)
 
 print(client_in_memory.transport)
 print(client_http.transport)
-print(client_ws.transport)
 print(client_stdio.transport)
 
 # Expected Output (types may vary slightly based on environment):
 # <FastMCP(server='TestServer')>
 # <StreamableHttp(url='https://example.com/mcp')>
-# <WebSocket(url='ws://localhost:9000')>
 # <PythonStdioTransport(command='python', args=['/path/to/your/my_mcp_server.py'])>
 ```
+
+You can also initialize a client from an MCP configuration dictionary or `MCPConfig` file:
+
+```python
+from fastmcp import Client
+
+config = {
+    "mcpServers": {
+        "local": {"command": "python", "args": ["local_server.py"]},
+        "remote": {"url": "https://example.com/mcp"},
+    }
+}
+
+client_config = Client(config)
+```
 <Tip>
 For more control over connection details (like headers for SSE, environment variables for Stdio), you can instantiate the specific `ClientTransport` class yourself and pass it to the `Client`. See the [Transports](/clients/transports) page for details.
 </Tip>
 
+### Multi-Server Clients
+
+<VersionBadge version="2.4.0" />
+
+FastMCP supports creating clients that connect to multiple MCP servers through a single client interface using a standard MCP configuration format (`MCPConfig`). This configuration approach makes it easy to connect to multiple specialized servers or create composable systems with a simple, declarative syntax.
+
+<Note>
+The MCP configuration format follows an emerging standard and may evolve as the specification matures. FastMCP will strive to maintain compatibility with future versions, but be aware that field names or structure might change.
+</Note>
+
+When you create a client with an `MCPConfig` containing multiple servers:
+
+1. FastMCP creates a composite client that internally mounts all servers using their config names as prefixes
+2. Tools and resources from each server are accessible with appropriate prefixes in the format `servername_toolname` and `protocol://servername/resource/path`
+3. You interact with this as a single unified client, with requests automatically routed to the appropriate server
+
+```python
+from fastmcp import Client
+
+# Create a standard MCP configuration with multiple servers
+config = {
+    "mcpServers": {
+        # A remote HTTP server
+        "weather": {
+            "url": "https://weather-api.example.com/mcp",
+            "transport": "streamable-http"
+        },
+        # A local server running via stdio
+        "assistant": {
+            "command": "python",
+            "args": ["./my_assistant_server.py"],
+            "env": {"DEBUG": "true"}
+        }
+    }
+}
+
+# Create a client that connects to both servers
+client = Client(config)
+
+async def main():
+    async with client:
+        # Access tools from different servers with prefixes
+        weather_data = await client.call_tool("weather_get_forecast", {"city": "London"})
+        response = await client.call_tool("assistant_answer_question", {"question": "What's the capital of France?"})
+        
+        # Access resources with prefixed URIs
+        weather_icons = await client.read_resource("weather://weather/icons/sunny")
+        templates = await client.read_resource("resource://assistant/templates/list")
+        
+        print(f"Weather: {weather_data}")
+        print(f"Assistant: {response}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+If your configuration has only a single server, FastMCP will create a direct client to that server without any prefixing.
+
 ## Client Usage
 
 ### Connection Lifecycle
@@ -209,11 +280,19 @@ Available raw MCP methods:
 
 These methods are especially useful for debugging or when you need to access metadata or fields that aren't exposed by the simplified methods.
 
-### Advanced Features
+### Additional Features
+
+#### Pinging the server
 
-MCP allows servers to interact with clients in order to provide additional capabilities. The `Client` constructor accepts additional configuration to handle these server requests.
+The client can be used to ping the server to verify connectivity.
+
+```python
+async with client:
+    await client.ping()
+    print("Server is reachable")
+```
 
-#### Timeout Control
+#### Timeouts
 
 <VersionBadge version="2.3.4" />
 
@@ -253,154 +332,7 @@ Timeout behavior varies between transport types:
 For consistent behavior across all transports, we recommend explicitly setting timeouts at the individual tool call level when needed, rather than relying on client-level timeouts.
 </Warning>
 
-#### Progress Tracking
-
-<VersionBadge version="2.3.5" />
-
-MCP servers can report progress during long-running operations. The client can set a progress handler to receive and process these updates.
-
-```python
-from fastmcp import Client
-from fastmcp.client.progress import ProgressHandler
-
-# A simple progress handler that prints progress updates
-async def my_progress_handler(
-    progress: float, 
-    total: float | None, 
-    message: str | None
-) -> None:
-    """Handle progress updates from the server."""
-    if total is not None:
-        percent = (progress / total) * 100
-        print(f"Progress: {percent:.1f}% ({progress}/{total})")
-    else:
-        print(f"Progress: {progress}")
-    
-    if message:
-        print(f"Message: {message}")
-
-# Set the progress handler at client level
-client = Client(
-    my_mcp_server,
-    progress_handler=my_progress_handler
-)
-```
-
-By default, FastMCP uses a handler that logs progress updates at the debug level. This default handler properly handles cases where `total` or `message` might be None.
-
-You can override the progress handler for specific tool calls:
-
-```python
-# Client uses the default debug logger for progress
-client = Client(my_mcp_server)
-
-async with client:
-    # Use default progress handler (debug logging)
-    result1 = await client.call_tool("long_task", {"param": "value"})
-    
-    # Override with custom progress handler just for this call
-    result2 = await client.call_tool(
-        "another_task", 
-        {"param": "value"}, 
-        progress_handler=my_progress_handler
-    )
-```
-
-A typical progress update includes:
-- Current progress value (e.g., 2 of 5 steps completed)
-- Total expected value (may be None)
-- Status message (may be None)
-
-#### LLM Sampling
-
-MCP Servers can request LLM completions from clients. The client can provide a `sampling_handler` to handle these requests. The sampling handler receives a list of messages and other parameters from the server, and should return a string completion.
-
-The following example uses the `marvin` library to generate a completion:
-
-```python {8-17, 21}
-import marvin
-from fastmcp import Client
-from fastmcp.client.sampling import (
-    SamplingMessage,
-    SamplingParams,
-    RequestContext,
-)
-
-async def sampling_handler(
-    messages: list[SamplingMessage],
-    params: SamplingParams,
-    context: RequestContext
-) -> str:
-    return await marvin.say_async(
-        message=[m.content.text for m in messages],
-        instructions=params.systemPrompt,
-    )
-
-client = Client(
-    ...,
-    sampling_handler=sampling_handler,
-)
-```
-
-#### Logging
-
-MCP servers can emit logs to clients. The client can set a logging callback to receive these logs.
-
-```python {4-5, 9}
-from fastmcp import Client
-from fastmcp.client.logging import LogHandler, LogMessage
-
-async def my_log_handler(params: LogMessage):
-    print(f"[Server Log - {params.level.upper()}] {params.logger or 'default'}: {params.data}")
-
-client_with_logging = Client(
-    ...,
-    log_handler=my_log_handler,
-)
-```
-
-#### Roots
-
-Roots are a way for clients to inform servers about the resources they have access to or certain boundaries on their access. The server can use this information to adjust behavior or provide more accurate responses.
-
-Servers can request roots from clients, and clients can notify servers when their roots change.
-
-To set the roots when creating a client, users can either provide a list of roots (which can be a list of strings) or an async function that returns a list of roots.
-
-<CodeGroup>
-```python Static Roots {5}
-from fastmcp import Client
-
-client = Client(
-    ..., 
-    roots=["/path/to/root1", "/path/to/root2"],
-)
-```
-```python Dynamic Roots Callback {4-6, 10}
-from fastmcp import Client
-from fastmcp.client.roots import RequestContext
-
-async def roots_callback(context: RequestContext) -> list[str]:
-    print(f"Server requested roots (Request ID: {context.request_id})")
-    return ["/path/to/root1", "/path/to/root2"]
-
-client = Client(
-    ..., 
-    roots=roots_callback,
-)
-```
-</CodeGroup>
-### Utility Methods
-
-*   **`ping()`**: Sends a ping request to the server to verify connectivity.
-    ```python
-    async def check_connection():
-        async with client:
-            await client.ping()
-            print("Server is reachable")
-    ```
-
-### Error Handling
+#### Error Handling
 
 When a `call_tool` request results in an error on the server (e.g., the tool function raised an exception), the `client.call_tool()` method will raise a `fastmcp.client.ClientError`.
 

{fastmcp-2.3.5 → fastmcp-2.5.0}/docs/clients/transports.mdx

@@ -290,8 +290,8 @@ asyncio.run(main())
 ### FastMCP Transport
 
 - **Class:** `fastmcp.client.transports.FastMCPTransport`
-- **Inferred From:** An instance of `fastmcp.server.FastMCP`
-- **Use Case:** Connecting directly to a `FastMCP` server instance in the same Python process
+- **Inferred From:** An instance of `fastmcp.server.FastMCP` or a **FastMCP 1.0 server** (`mcp.server.fastmcp.FastMCP`)
+- **Use Case:** Connecting directly to a FastMCP server instance in the same Python process
 
 This is extremely useful for testing your FastMCP servers.
 
@@ -317,4 +317,64 @@ async def main():
 asyncio.run(main())
 ```
 
-Communication happens through efficient in-memory queues, making it very fast and ideal for unit testing. 
+Communication happens through efficient in-memory queues, making it very fast and ideal for unit testing. 
+
+## Configuration-Based Transports
+
+### MCPConfig Transport
+
+<VersionBadge version="2.4.0" />
+
+- **Class:** `fastmcp.client.transports.MCPConfigTransport`
+- **Inferred From:** An instance of `MCPConfig` or a dictionary matching the MCPConfig schema
+- **Use Case:** Connecting to one or more MCP servers defined in a configuration object
+
+MCPConfig follows an emerging standard for MCP server configuration but is subject to change as the specification evolves. The standard supports both local servers (running via stdio) and remote servers (accessed via HTTP).
+
+```python
+from fastmcp import Client
+
+# Configuration for multiple MCP servers (both local and remote)
+config = {
+    "mcpServers": {
+        # Remote HTTP server
+        "weather": {
+            "url": "https://weather-api.example.com/mcp",
+            "transport": "streamable-http"
+        },
+        # Local stdio server
+        "assistant": {
+            "command": "python",
+            "args": ["./assistant_server.py"],
+            "env": {"DEBUG": "true"}
+        },
+        # Another remote server
+        "calendar": {
+            "url": "https://calendar-api.example.com/mcp",
+            "transport": "streamable-http"
+        }
+    }
+}
+
+# Create a transport from the config (happens automatically with Client)
+client = Client(config)
+
+async def main():
+    async with client:
+        # Tools are accessible with server name prefixes
+        weather = await client.call_tool("weather_get_forecast", {"city": "London"})
+        answer = await client.call_tool("assistant_answer_question", {"query": "What is MCP?"})
+        events = await client.call_tool("calendar_list_events", {"date": "2023-06-01"})
+        
+        # Resources use prefixed URI paths
+        icons = await client.read_resource("weather://weather/icons/sunny")
+        docs = await client.read_resource("resource://assistant/docs/mcp")
+
+asyncio.run(main())
+```
+
+If your configuration has only a single server, the client will connect directly to that server without any prefixing. This makes it convenient to switch between single and multi-server configurations without changing your client code.
+
+<Note>
+The MCPConfig format is an emerging standard for MCP server configuration and may change as the MCP ecosystem evolves. While FastMCP aims to maintain compatibility with future versions, be aware that field names or structure might change.
+</Note> 

{fastmcp-2.3.5 → fastmcp-2.5.0}/docs/docs.json

@@ -50,6 +50,7 @@
                     "servers/resources",
                     "servers/prompts",
                     "servers/context",
+                    "servers/openapi",
                     "servers/proxy",
                     "servers/composition"
                 ]
@@ -67,7 +68,8 @@
                 "group": "Clients",
                 "pages": [
                     "clients/client",
-                    "clients/transports"
+                    "clients/transports",
+                    "clients/advanced-features"
                 ]
             },
             {
@@ -75,8 +77,6 @@
                 "pages": [
                     "patterns/decorating-methods",
                     "patterns/http-requests",
-                    "patterns/openapi",
-                    "patterns/fastapi",
                     "patterns/contrib",
                     "patterns/testing"
                 ]