fastmcp 2.3.2__tar.gz → 2.3.4__tar.gz

{fastmcp-2.3.2 → fastmcp-2.3.4}/.github/workflows/run-tests.yml

@@ -45,18 +45,10 @@ jobs:
         with:
           enable-cache: true
           cache-dependency-glob: "uv.lock"
-
-      - name: Set up Python ${{ matrix.python-version }}
-        run: uv python install ${{ matrix.python-version }}
+          python-version: ${{ matrix.python-version }}
 
       - name: Install FastMCP
-        run: uv sync --dev
-
-      - name: Fix pyreadline on Windows
-        if: matrix.os == 'windows-latest'
-        run: |
-          uv pip uninstall -y pyreadline
-          uv pip install pyreadline3
+        run: uv sync --dev --locked
 
       - name: Run tests
-        run: uv run --frozen pytest
+        run: uv run pytest

{fastmcp-2.3.2 → fastmcp-2.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastmcp
-Version: 2.3.2
+Version: 2.3.4
 Summary: The fast, Pythonic way to build MCP servers.
 Project-URL: Homepage, https://gofastmcp.com
 Project-URL: Repository, https://github.com/jlowin/fastmcp
@@ -19,7 +19,7 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: exceptiongroup>=1.2.2
 Requires-Dist: httpx>=0.28.1
-Requires-Dist: mcp<2.0.0,>=1.8.0
+Requires-Dist: mcp<2.0.0,>=1.8.1
 Requires-Dist: openapi-pydantic>=0.5.1
 Requires-Dist: python-dotenv>=1.1.0
 Requires-Dist: rich>=13.9.4

{fastmcp-2.3.2 → fastmcp-2.3.4}/docs/clients/client.mdx

@@ -115,14 +115,18 @@ The standard client methods return user-friendly representations that may change
     tools = await client.list_tools()
     # tools -> list[mcp.types.Tool]
     ```
-*   **`call_tool(name: str, arguments: dict[str, Any] | None = None)`**: Executes a tool on the server.
+*   **`call_tool(name: str, arguments: dict[str, Any] | None = None, timeout: float | None = None)`**: Executes a tool on the server.
     ```python
     result = await client.call_tool("add", {"a": 5, "b": 3})
     # result -> list[mcp.types.TextContent | mcp.types.ImageContent | ...]
     print(result[0].text) # Assuming TextContent, e.g., '8'
+    
+    # With timeout (aborts if execution takes longer than 2 seconds)
+    result = await client.call_tool("long_running_task", {"param": "value"}, timeout=2.0)
     ```
     *   Arguments are passed as a dictionary. FastMCP servers automatically handle JSON string parsing for complex types if needed.
     *   Returns a list of content objects (usually `TextContent` or `ImageContent`).
+    *   The optional `timeout` parameter limits the maximum execution time (in seconds) for this specific call, overriding any client-level timeout.
 
 #### Resource Operations
 
@@ -191,6 +195,45 @@ These methods are especially useful for debugging or when you need to access met
 
 MCP allows servers to interact with clients in order to provide additional capabilities. The `Client` constructor accepts additional configuration to handle these server requests.
 
+#### Timeout Control
+
+<VersionBadge version="2.3.4" />
+
+You can control request timeouts at both the client level and individual request level:
+
+```python
+from fastmcp import Client
+from fastmcp.exceptions import McpError
+
+# Client with a global 5-second timeout for all requests
+client = Client(
+    my_mcp_server,
+    timeout=5.0  # Default timeout in seconds
+)
+
+async with client:
+    # This uses the global 5-second timeout
+    result1 = await client.call_tool("quick_task", {"param": "value"})
+    
+    # This specifies a 10-second timeout for this specific call
+    result2 = await client.call_tool("slow_task", {"param": "value"}, timeout=10.0)
+    
+    try:
+        # This will likely timeout
+        result3 = await client.call_tool("medium_task", {"param": "value"}, timeout=0.01)
+    except McpError as e:
+        # Handle timeout error
+        print(f"The task timed out: {e}")
+```
+
+<Warning>
+Timeout behavior varies between transport types:
+
+- With **SSE** transport, the per-request (tool call) timeout **always** takes precedence, regardless of which is lower.
+- With **HTTP** transport, the **lower** of the two timeouts (client or tool call) takes precedence.
+
+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>
 
 #### LLM Sampling
 

fastmcp-2.3.4/docs/servers/composition.mdx

@@ -0,0 +1,212 @@
+---
+title: Server Composition
+sidebarTitle: Composition
+description: Combine multiple FastMCP servers into a single, larger application using mounting and importing.
+icon: puzzle-piece
+---
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="2.2.0" />
+
+As your MCP applications grow, you might want to organize your tools, resources, and prompts into logical modules or reuse existing server components. FastMCP supports composition through two methods:
+
+- **`import_server`**: For a one-time copy of components with prefixing (static composition).
+- **`mount`**: For creating a live link where the main server delegates requests to the subserver (dynamic composition).
+
+## Why Compose Servers?
+
+-   **Modularity**: Break down large applications into smaller, focused servers (e.g., a `WeatherServer`, a `DatabaseServer`, a `CalendarServer`).
+-   **Reusability**: Create common utility servers (e.g., a `TextProcessingServer`) and mount them wherever needed.
+-   **Teamwork**: Different teams can work on separate FastMCP servers that are later combined.
+-   **Organization**: Keep related functionality grouped together logically.
+
+### Importing vs Mounting
+
+The choice of importing or mounting depends on your use case and requirements.
+
+| Feature | Importing | Mounting |
+|---------|----------------|---------|
+| **Method** | `FastMCP.import_server()` | `FastMCP.mount()` |
+| **Composition Type** | One-time copy (static) | Live link (dynamic) |
+| **Updates** | Changes to subserver NOT reflected | Changes to subserver immediately reflected |
+| **Best For** | Bundling finalized components | Modular runtime composition |
+
+### Proxy Servers
+
+FastMCP supports [MCP proxying](/patterns/proxy), which allows you to mirror a local or remote server in a local FastMCP instance. Proxies are fully compatible with both importing and mounting.
+
+## Importing (Static Composition)
+
+The `import_server()` method copies all components (tools, resources, templates, prompts) from one `FastMCP` instance (the *subserver*) into another (the *main server*). A `prefix` is added to avoid naming conflicts.
+
+```python
+from fastmcp import FastMCP
+import asyncio
+
+# Define subservers
+weather_mcp = FastMCP(name="WeatherService")
+
+@weather_mcp.tool()
+def get_forecast(city: str) -> dict:
+    """Get weather forecast."""
+    return {"city": city, "forecast": "Sunny"}
+
+@weather_mcp.resource("data://cities/supported")
+def list_supported_cities() -> list[str]:
+    """List cities with weather support."""
+    return ["London", "Paris", "Tokyo"]
+
+# Define main server
+main_mcp = FastMCP(name="MainApp")
+
+# Import subserver
+async def setup():
+    await main_mcp.import_server("weather", weather_mcp)
+
+# Result: main_mcp now contains prefixed components:
+# - Tool: "weather_get_forecast"
+# - Resource: "weather+data://cities/supported" 
+
+if __name__ == "__main__":
+    asyncio.run(setup())
+    main_mcp.run()
+```
+
+### How Importing Works
+
+When you call `await main_mcp.import_server(prefix, subserver)`:
+
+1.  **Tools**: All tools from `subserver` are added to `main_mcp` with names prefixed using `{prefix}_`.
+    -   `subserver.tool(name="my_tool")` becomes `main_mcp.tool(name="{prefix}_my_tool")`.
+2.  **Resources**: All resources are added with URIs prefixed using `{prefix}+`.
+    -   `subserver.resource(uri="data://info")` becomes `main_mcp.resource(uri="{prefix}+data://info")`.
+3.  **Resource Templates**: Templates are prefixed similarly to resources.
+    -   `subserver.resource(uri="data://{id}")` becomes `main_mcp.resource(uri="{prefix}+data://{id}")`.
+4.  **Prompts**: All prompts are added with names prefixed like tools.
+    -   `subserver.prompt(name="my_prompt")` becomes `main_mcp.prompt(name="{prefix}_my_prompt")`.
+
+Note that `import_server` performs a **one-time copy** of components. Changes made to the `subserver` *after* importing **will not** be reflected in `main_mcp`. The `subserver`'s `lifespan` context is also **not** executed by the main server.
+
+## Mounting (Live Linking)
+
+The `mount()` method creates a **live link** between the `main_mcp` server and the `subserver`. Instead of copying components, requests for components matching the `prefix` are **delegated** to the `subserver` at runtime.
+
+```python
+import asyncio
+from fastmcp import FastMCP, Client
+
+# Define subserver
+dynamic_mcp = FastMCP(name="DynamicService")
+
+@dynamic_mcp.tool()
+def initial_tool():
+    """Initial tool demonstration."""
+    return "Initial Tool Exists"
+
+# Mount subserver (synchronous operation)
+main_mcp = FastMCP(name="MainAppLive")
+main_mcp.mount("dynamic", dynamic_mcp)
+
+# Add a tool AFTER mounting - it will be accessible through main_mcp
+@dynamic_mcp.tool()
+def added_later():
+    """Tool added after mounting."""
+    return "Tool Added Dynamically!"
+
+# Testing access to mounted tools
+async def test_dynamic_mount():
+    tools = await main_mcp.get_tools()
+    print("Available tools:", list(tools.keys()))
+    # Shows: ['dynamic_initial_tool', 'dynamic_added_later']
+    
+    async with Client(main_mcp) as client:
+        result = await client.call_tool("dynamic_added_later")
+        print("Result:", result[0].text)
+        # Shows: "Tool Added Dynamically!"
+
+if __name__ == "__main__":
+    asyncio.run(test_dynamic_mount())
+```
+
+### How Mounting Works
+
+When mounting is configured:
+
+1. **Live Link**: The parent server establishes a connection to the mounted server.
+2. **Dynamic Updates**: Changes to the mounted server are immediately reflected when accessed through the parent.
+3. **Prefixed Access**: The parent server uses prefixes to route requests to the mounted server.
+4. **Delegation**: Requests for components matching the prefix are delegated to the mounted server at runtime.
+
+The same prefixing rules apply as with `import_server` for naming tools, resources, templates, and prompts.
+
+### Direct vs. Proxy Mounting
+
+<VersionBadge version="2.2.7" />
+
+FastMCP supports two mounting modes:
+
+1. **Direct Mounting** (default): The parent server directly accesses the mounted server's objects in memory.
+   - No client lifecycle events occur on the mounted server
+   - The mounted server's lifespan context is not executed
+   - Communication is handled through direct method calls
+   
+2. **Proxy Mounting**: The parent server treats the mounted server as a separate entity and communicates with it through a client interface.
+   - Full client lifecycle events occur on the mounted server
+   - The mounted server's lifespan is executed when a client connects
+   - Communication happens via an in-memory Client transport
+
+```python
+# Direct mounting (default when no custom lifespan)
+main_mcp.mount("api", api_server)
+
+# Proxy mounting (preserves full client lifecycle)
+main_mcp.mount("api", api_server, as_proxy=True)
+```
+
+FastMCP automatically uses proxy mounting when the mounted server has a custom lifespan, but you can override this behavior with the `as_proxy` parameter.
+
+#### Interaction with Proxy Servers
+
+When using `FastMCP.from_client()` to create a proxy server, mounting that server will always use proxy mounting:
+
+```python
+# Create a proxy for a remote server
+remote_proxy = FastMCP.from_client(Client("http://example.com/mcp"))
+
+# Mount the proxy (always uses proxy mounting)
+main_server.mount("remote", remote_proxy)
+```
+
+## Customizing Separators
+
+Both `import_server()` and `mount()` allow you to customize the separators used for prefixing components. The defaults are `_` for tools and prompts, and `+` for resources.
+
+<CodeGroup>
+
+```python import_server
+await main_mcp.import_server(
+    prefix="api",
+    app=some_subserver,
+    tool_separator="_",       # Tool name becomes: "api_sub_tool_name"
+    resource_separator="+",   # Resource URI becomes: "api+data://sub_resource"
+    prompt_separator="_"      # Prompt name becomes: "api_sub_prompt_name"
+)
+```
+
+```python mount
+main_mcp.mount(
+    prefix="api",
+    app=some_subserver,
+    tool_separator="_",       # Tool name becomes: "api_sub_tool_name"
+    resource_separator="+",   # Resource URI becomes: "api+data://sub_resource"
+    prompt_separator="_"      # Prompt name becomes: "api_sub_prompt_name"
+)
+```
+</CodeGroup>
+<Warning>
+Be cautious when choosing separators. Some MCP clients (like Claude Desktop) might have restrictions on characters allowed in tool names (e.g., `/` might not be supported). The defaults (`_` for names, `+` for URIs) are generally safe.
+</Warning>
+
+<Tip>
+To "cleanly" import or mount a server, set the prefix and all separators to `""` (empty string). This is generally unecessary but could save a couple tokens at the risk of a name collision!
+</Tip>

{fastmcp-2.3.2 → fastmcp-2.3.4}/docs/servers/resources.mdx

@@ -147,6 +147,7 @@ async def read_important_log() -> str:
         return "Log file not found."
 ```
 
+
 ### Resource Classes
 
 While `@mcp.resource` is ideal for dynamic content, you can directly register pre-defined resources (like static files or simple text) using `mcp.add_resource()` and concrete `Resource` subclasses.
@@ -403,17 +404,45 @@ In this stacked decorator pattern:
 - Each parameter defaults to `None` when not included in the URI
 - The function logic handles whichever parameter is provided
 
-**How Templates Work:**
+Templates provide a powerful way to expose parameterized data access points following REST-like principles.
+
+## Error Handling
 
-1.  **Definition:** When FastMCP sees `{...}` placeholders in the `@resource` URI and matching function parameters, it registers a `ResourceTemplate`.
-2.  **Discovery:** Clients list templates via `resources/listResourceTemplates`.
-3.  **Request & Matching:** A client requests a specific URI, e.g., `weather://london/current`. FastMCP matches this to the `weather://{city}/current` template.
-4.  **Parameter Extraction:** It extracts the parameter value: `city="london"`.
-5.  **Type Conversion & Function Call:** It converts extracted values to the types hinted in the function and calls `get_weather(city="london")`.
-6.  **Default Values:** For any function parameters with default values not included in the URI template, FastMCP uses the default values.
-7.  **Response:** The function's return value is formatted (e.g., dict to JSON) and sent back as the resource content.
+<VersionBadge version="2.3.4" />
 
-Templates provide a powerful way to expose parameterized data access points following REST-like principles.
+If your resource function encounters an error, you can raise a standard Python exception (`ValueError`, `TypeError`, `FileNotFoundError`, custom exceptions, etc.) or a FastMCP `ResourceError`.
+
+For security reasons, most exceptions are wrapped in a generic `ResourceError` before being sent to the client, with internal error details masked. However, if you raise a `ResourceError` directly, its contents **are** included in the response. This allows you to provide informative error messages to the client on an opt-in basis.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.exceptions import ResourceError
+
+mcp = FastMCP(name="DataServer")
+
+@mcp.resource("resource://safe-error")
+def fail_with_details() -> str:
+    """This resource provides detailed error information."""
+    # ResourceError contents are sent back to clients
+    raise ResourceError("Unable to retrieve data: file not found")
+
+@mcp.resource("resource://masked-error")
+def fail_with_masked_details() -> str:
+    """This resource masks internal error details."""
+    # Other exceptions are converted to ResourceError with generic message
+    raise ValueError("Sensitive internal file path: /etc/secrets.conf")
+
+@mcp.resource("data://{id}")
+def get_data_by_id(id: str) -> dict:
+    """Template resources also support the same error handling pattern."""
+    if id == "secure":
+        raise ValueError("Cannot access secure data")
+    elif id == "missing":
+        raise ResourceError("Data ID 'missing' not found in database")
+    return {"id": id, "value": "data"}
+```
+
+This error handling pattern applies to both regular resources and resource templates.
 
 ## Server Behavior
 

{fastmcp-2.3.2 → fastmcp-2.3.4}/docs/servers/tools.mdx

@@ -248,27 +248,30 @@ def do_nothing() -> None:
 
 ### Error Handling
 
-If your tool encounters an error, simply raise a standard Python exception (`ValueError`, `TypeError`, `FileNotFoundError`, custom exceptions, etc.).
+<VersionBadge version="2.3.4" />
+
+If your tool encounters an error, you can raise a standard Python exception (`ValueError`, `TypeError`, `FileNotFoundError`, custom exceptions, etc.) or a FastMCP `ToolError`.
+
+In all cases, the exception is logged and converted into an MCP error response to be sent back to the client LLM. For security reasons, the error message is **not** included in the response by default. However, if you raise a `ToolError`, the contents of the exception **are** included in the response. This allows you to provide informative error messages to the client LLM on an opt-in basis, which can help the LLM understand failures and react appropriately.
+
+```python {2, 10, 14}
+from fastmcp import FastMCP
+from fastmcp.exceptions import ToolError
 
-```python
 @mcp.tool()
 def divide(a: float, b: float) -> float:
     """Divide a by b."""
-    if b == 0:
-        # Raise a standard exception
-        raise ValueError("Division by zero is not allowed.")
+
+    # Python exceptions raise errors but the contents are not sent to clients
     if not isinstance(a, (int, float)) or not isinstance(b, (int, float)):
         raise TypeError("Both arguments must be numbers.")
+
+    if b == 0:
+        # ToolError contents are sent back to clients
+        raise ToolError("Division by zero is not allowed.")
     return a / b
 ```
 
-FastMCP automatically catches exceptions raised within your tool function:
-1.  It converts the exception into an MCP error response, typically including the exception type and message.
-2.  This error response is sent back to the client/LLM.
-3.  The LLM can then inform the user or potentially try the tool again with different arguments.
-
-Using informative exceptions helps the LLM understand failures and react appropriately.
-
 ### Annotations
 
 <VersionBadge version="2.2.7" />
@@ -709,6 +712,25 @@ The duplicate behavior options are:
 -   `"replace"`: Silently replaces the existing tool with the new one.
 -   `"ignore"`: Keeps the original tool and ignores the new registration attempt.
 
+### Removing Tools
+
+<VersionBadge version="2.3.4" />
+
+You can dynamically remove tools from a server using the `remove_tool` method:
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="DynamicToolServer")
+
+@mcp.tool()
+def calculate_sum(a: int, b: int) -> int:
+    """Add two numbers together."""
+    return a + b
+
+mcp.remove_tool("calculate_sum")
+```
+
 ### Legacy JSON Parsing
 
 <VersionBadge version="2.2.10" />

{fastmcp-2.3.2 → fastmcp-2.3.4}/examples/complex_inputs.py

@@ -8,7 +8,7 @@ from typing import Annotated
 
 from pydantic import BaseModel, Field
 
-from fastmcp.server import FastMCP
+from fastmcp import FastMCP
 
 mcp = FastMCP("Shrimp Tank")
 

{fastmcp-2.3.2 → fastmcp-2.3.4}/examples/desktop.py

@@ -6,7 +6,7 @@ A simple example that exposes the desktop directory as a resource.
 
 from pathlib import Path
 
-from fastmcp.server import FastMCP
+from fastmcp import FastMCP
 
 # Create server
 mcp = FastMCP("Demo")

{fastmcp-2.3.2 → fastmcp-2.3.4}/pyproject.toml

@@ -7,7 +7,7 @@ dependencies = [
     "python-dotenv>=1.1.0",
     "exceptiongroup>=1.2.2",
     "httpx>=0.28.1",
-    "mcp>=1.8.0,<2.0.0",
+    "mcp>=1.8.1,<2.0.0",
     "openapi-pydantic>=0.5.1",
     "rich>=13.9.4",
     "typer>=0.15.2",

{fastmcp-2.3.2 → fastmcp-2.3.4}/src/fastmcp/client/__init__.py

@@ -9,6 +9,7 @@ from .transports import (
     UvxStdioTransport,
     NpxStdioTransport,
     FastMCPTransport,
+    StreamableHttpTransport,
 )
 
 __all__ = [
@@ -22,4 +23,5 @@ __all__ = [
     "UvxStdioTransport",
     "NpxStdioTransport",
     "FastMCPTransport",
+    "StreamableHttpTransport",
 ]