fastmcp 2.3.3__tar.gz → 2.3.5__tar.gz

fastmcp-2.3.5/.github/labeler.yml

@@ -0,0 +1,29 @@
+documentation:
+  - changed-files:
+      - any-glob-to-any-file: "docs/**"
+
+example:
+  - changed-files:
+      - any-glob-to-any-file:
+          - "examples/**"
+
+tests:
+  - changed-files:
+      - any-glob-to-any-file: "tests/**"
+
+"component: HTTP":
+  - changed-files:
+      - any-glob-to-any-file: "src/fastmcp/server/http.py"
+
+"component: client":
+  - changed-files:
+      - any-glob-to-any-file: "src/fastmcp/client/**"
+
+"contrib":
+  - changed-files:
+      - any-glob-to-any-file: "src/fastmcp/contrib/**"
+
+"component: openapi":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "src/**/*openapi*.py"

fastmcp-2.3.5/.github/workflows/labeler.yml

@@ -0,0 +1,12 @@
+name: "Pull Request Labeler"
+on:
+  - pull_request_target
+
+jobs:
+  labeler:
+    permissions:
+      contents: read
+      pull-requests: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/labeler@v5

{fastmcp-2.3.3 → fastmcp-2.3.5}/.github/workflows/run-static.yml

@@ -14,13 +14,10 @@ on:
       - "uv.lock"
       - "pyproject.toml"
       - ".github/workflows/**"
+
+  # run on all pull requests because these checks are required and will block merges otherwise
   pull_request:
-    paths:
-      - "src/**"
-      - "tests/**"
-      - "uv.lock"
-      - "pyproject.toml"
-      - ".github/workflows/**"
+
   workflow_dispatch:
 
 permissions:

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

@@ -13,13 +13,9 @@ on:
       - "uv.lock"
       - "pyproject.toml"
       - ".github/workflows/**"
+
+  # run on all pull requests because these checks are required and will block merges otherwise
   pull_request:
-    paths:
-      - "src/**"
-      - "tests/**"
-      - "uv.lock"
-      - "pyproject.toml"
-      - ".github/workflows/**"
 
   workflow_dispatch:
 
@@ -45,18 +41,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.5/AGENTS.md

@@ -0,0 +1,67 @@
+# AGENTS
+
+> **Audience**: LLM-driven engineering agents
+
+This file provides guidance for autonomous coding agents working inside the **FastMCP** repository.
+
+---
+
+## Repository map
+
+| Path             | Purpose                                                                                  |
+| ---------------- | ---------------------------------------------------------------------------------------- |
+| `src/fastmcp/`   | Library source code (Python ≥ 3.10)                                                      |
+| `  └─server/`    | Server implementation, `FastMCP`, auth, networking                                       |
+| `  └─client/`    | High‑level client SDK + helpers                                                          |
+| `  └─resources/` | MCP resources and resource templates                                                     |
+| `  └─prompts/`   | Prompt templates                                                                         |
+| `  └─tools/`     | Tool implementations                                                                     |
+| `tests/`         | Pytest test‑suite                                                                        |
+| `docs/`          | Mintlify‑flavoured Markdown, published to [https://gofastmcp.com](https://gofastmcp.com) |
+| `examples/`      | Minimal runnable demos                                                                   |
+
+---
+
+## Mandatory dev workflow
+
+```bash
+uv sync                              # install dependencies
+uv run pre-commit run --all-files    # Ruff + Prettier + Pyright
+uv run pytest                        # run full test suite
+```
+
+*Tests must pass* and *lint/typing must be clean* before committing.
+
+### Core MCP objects
+
+There are four major MCP object types:
+
+- Tools (`src/tools/`)
+- Resources (`src/resources/`)
+- Resource Templates (`src/resources/`)
+- Prompts (`src/prompts`)
+
+While these have slightly different semantics and implementations, in general changes that affect interactions with any one (like adding tags, importing, etc.) will need to be adopted, applied, and tested on all others. Be sure to look at not only the object definition but also the related `Manager` (e.g. `ToolManager`, `ResourceManager`, and `PromptManager`). Also note that while resources and resource templates are different objects, they both are handled by the `ResourceManager`.
+
+---
+
+## Code conventions
+
+* **Language:** Python ≥ 3.10
+* **Style:** Enforced through pre-commit hooks
+* **Type-checking:** Fully typed codebase
+* **Tests:** Each feature should have corresponding tests
+
+---
+
+## Development guidelines
+
+1. **Set up** the environment:
+   ```bash
+   uv sync && uv run pre-commit run --all-files
+   ```
+2. **Run tests**: `uv run pytest` until they pass.
+3. **Iterate**: if a command fails, read the output, fix the code, retry.
+4. Make the smallest set of changes that achieve the desired outcome.
+5. Always read code before modifying it blindly.
+6. Follow established patterns and maintain consistency.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastmcp
-Version: 2.3.3
+Version: 2.3.5
 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.9.0
 Requires-Dist: openapi-pydantic>=0.5.1
 Requires-Dist: python-dotenv>=1.1.0
 Requires-Dist: rich>=13.9.4
@@ -290,7 +290,7 @@ FastMCP introduces powerful ways to structure and deploy your MCP applications.
 
 ### Proxy Servers
 
-Create a FastMCP server that acts as an intermediary for another local or remote MCP server using `FastMCP.from_client()`. This is especially useful for bridging transports (e.g., remote SSE to local Stdio) or adding a layer of logic to a server you don't control.
+Create a FastMCP server that acts as an intermediary for another local or remote MCP server using `FastMCP.as_proxy()`. This is especially useful for bridging transports (e.g., remote SSE to local Stdio) or adding a layer of logic to a server you don't control.
 
 Learn more in the [**Proxying Documentation**](https://gofastmcp.com/patterns/proxy).
 

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

@@ -261,7 +261,7 @@ FastMCP introduces powerful ways to structure and deploy your MCP applications.
 
 ### Proxy Servers
 
-Create a FastMCP server that acts as an intermediary for another local or remote MCP server using `FastMCP.from_client()`. This is especially useful for bridging transports (e.g., remote SSE to local Stdio) or adding a layer of logic to a server you don't control.
+Create a FastMCP server that acts as an intermediary for another local or remote MCP server using `FastMCP.as_proxy()`. This is especially useful for bridging transports (e.g., remote SSE to local Stdio) or adding a layer of logic to a server you don't control.
 
 Learn more in the [**Proxying Documentation**](https://gofastmcp.com/patterns/proxy).
 

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

@@ -18,6 +18,17 @@ The FastMCP Client architecture separates the protocol logic (`Client`) from the
 - **`Client`**: Handles sending MCP requests (like `tools/call`, `resources/read`), receiving responses, and managing callbacks.
 - **`Transport`**: Responsible for establishing and maintaining the connection to the server (e.g., via WebSockets, SSE, Stdio, or in-memory).
 
+```python
+from fastmcp import Client, FastMCP
+from fastmcp.client import (
+    RootsHandler,
+    RootsList,
+    LogHandler,
+    MessageHandler,
+    SamplingHandler,
+    ProgressHandler  # For handling progress notifications
+)
+```
 
 ### Transports
 
@@ -30,9 +41,8 @@ The following inference rules are used to determine the appropriate `ClientTrans
 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**:
-    *   If it starts with `http://` or `https://`: Creates an `SSETransport`.
-    *   If it starts with `ws://` or `wss://`: Creates a `WSTransport`.
+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.
 
 ```python
@@ -41,24 +51,24 @@ from fastmcp import Client, FastMCP
 
 # Example transports (more details in Transports page)
 server_instance = FastMCP(name="TestServer") # In-memory server
-sse_url = "http://localhost:8000/sse"       # SSE server URL
+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_sse = Client(sse_url)
+client_http = Client(http_url)
 client_ws = Client(ws_url)
 client_stdio = Client(server_script)
 
 print(client_in_memory.transport)
-print(client_sse.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')>
-# <SSE(url='http://localhost:8000/sse')>
+# <StreamableHttp(url='https://example.com/mcp')>
 # <WebSocket(url='ws://localhost:9000')>
 # <PythonStdioTransport(command='python', args=['/path/to/your/my_mcp_server.py'])>
 ```
@@ -115,14 +125,26 @@ 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, progress_handler: ProgressHandler | 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)
+    
+    # With progress handler (to track execution progress)
+    result = await client.call_tool(
+        "long_running_task",
+        {"param": "value"},
+        progress_handler=my_progress_handler
+    )
     ```
     *   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.
+    *   The optional `progress_handler` parameter receives progress updates during execution, overriding any client-level progress handler.
 
 #### Resource Operations
 
@@ -191,6 +213,103 @@ 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>
+
+#### 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