fastmcp 2.3.4__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.4 → 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.4 → 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:
 

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.4 → fastmcp-2.3.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastmcp
-Version: 2.3.4
+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.1
+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.4 → 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.4 → 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,7 +125,7 @@ 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, timeout: float | 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 | ...]
@@ -123,10 +133,18 @@ The standard client methods return user-friendly representations that may change
     
     # 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
 
@@ -235,6 +253,64 @@ 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.

fastmcp-2.3.5/docs/clients/transports.mdx

@@ -0,0 +1,320 @@
+---
+title: Client Transports
+sidebarTitle: Transports
+description: Understand the different ways FastMCP Clients can connect to servers.
+icon: link
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.0.0" />
+
+The FastMCP `Client` relies on a `ClientTransport` object to handle the specifics of connecting to and communicating with an MCP server. FastMCP provides several built-in transport implementations for common connection methods.
+
+While the `Client` often infers the correct transport automatically (see [Client Overview](/clients/client#transport-inference)), you can also instantiate transports explicitly for more control.
+
+<Tip>
+Clients are lightweight objects, so don't hesitate to create new ones as needed. However, be mindful of the context management - each time you open a client context (`async with client:`), a new connection or process starts. For best performance, keep client contexts open while performing multiple operations rather than repeatedly opening and closing them.
+</Tip>
+
+## Choosing a Transport
+
+Choose the transport that best fits your use case:
+
+- **Connecting to Remote/Persistent Servers:** Use `StreamableHttpTransport` (recommended, default for HTTP URLs) or `SSETransport` (legacy option) for web-based deployments.
+
+- **Local Development/Testing:** Use `FastMCPTransport` for in-memory, same-process testing of your FastMCP servers.
+
+- **Running Local Servers:** Use `UvxStdioTransport` (Python/uv) or `NpxStdioTransport` (Node/npm) if you need to run MCP servers as packaged tools.
+
+## Network Transports
+
+These transports connect to servers running over a network, typically long-running services accessible via URLs.
+
+### Streamable HTTP
+
+<VersionBadge version="2.3.0" />
+
+Streamable HTTP is the recommended transport for web-based deployments, providing efficient bidirectional communication over HTTP.
+
+#### Overview
+
+- **Class:** `fastmcp.client.transports.StreamableHttpTransport`
+- **Inferred From:** URLs starting with `http://` or `https://` (default for HTTP URLs since v2.3.0) that do not contain `/sse/` in the path
+- **Server Compatibility:** Works with FastMCP servers running in `streamable-http` mode
+
+#### Basic Usage
+
+The simplest way to use Streamable HTTP is to let the transport be inferred from a URL:
+
+```python
+from fastmcp import Client
+import asyncio
+
+# The Client automatically uses StreamableHttpTransport for HTTP URLs
+client = Client("https://example.com/mcp")
+
+async def main():
+    async with client:
+        tools = await client.list_tools()
+        print(f"Available tools: {tools}")
+
+asyncio.run(main())
+```
+
+You can also explicitly instantiate the transport:
+
+```python
+from fastmcp.client.transports import StreamableHttpTransport
+
+transport = StreamableHttpTransport(url="https://example.com/mcp")
+client = Client(transport)
+```
+
+#### Authentication with Headers
+
+For servers requiring authentication:
+
+```python
+from fastmcp import Client
+from fastmcp.client.transports import StreamableHttpTransport
+
+# Create transport with authentication headers
+transport = StreamableHttpTransport(
+    url="https://example.com/mcp",
+    headers={"Authorization": "Bearer your-token-here"}
+)
+
+client = Client(transport)
+```
+
+### SSE (Server-Sent Events)
+
+<VersionBadge version="2.0.0" />
+
+Server-Sent Events (SSE) is a transport that allows servers to push data to clients over HTTP connections. While still supported, Streamable HTTP is now the recommended transport for new web-based deployments.
+
+#### Overview
+
+- **Class:** `fastmcp.client.transports.SSETransport`
+- **Inferred From:** HTTP URLs containing `/sse/` in the path
+- **Server Compatibility:** Works with FastMCP servers running in `sse` mode
+
+#### Basic Usage
+
+The simplest way to use SSE is to let the transport be inferred from a URL with `/sse/` in the path:
+
+```python
+from fastmcp import Client
+import asyncio
+
+# The Client automatically uses SSETransport for URLs containing /sse/ in the path
+client = Client("https://example.com/sse")
+
+async def main():
+    async with client:
+        tools = await client.list_tools()
+        print(f"Available tools: {tools}")
+
+asyncio.run(main())
+```
+
+You can also explicitly instantiate the transport for URLs that do not contain `/sse/` in the path or for more control: 
+
+```python
+from fastmcp.client.transports import SSETransport
+
+transport = SSETransport(url="https://example.com/sse")
+client = Client(transport)
+```
+
+#### Authentication with Headers
+
+SSE transport also supports custom headers for authentication:
+
+```python
+from fastmcp import Client
+from fastmcp.client.transports import SSETransport
+
+# Create SSE transport with authentication headers
+transport = SSETransport(
+    url="https://example.com/sse",
+    headers={"Authorization": "Bearer your-token-here"}
+)
+
+client = Client(transport)
+```
+
+#### When to Use SSE vs. Streamable HTTP
+
+- **Use Streamable HTTP when:**
+  - Setting up new deployments (recommended default)
+  - You need bidirectional streaming
+  - You're connecting to FastMCP servers running in `streamable-http` mode
+
+- **Use SSE when:**
+  - Connecting to legacy FastMCP servers running in `sse` mode
+  - Working with infrastructure optimized for Server-Sent Events
+
+## Local Transports
+
+These transports manage an MCP server running as a subprocess, communicating with it via standard input (stdin) and standard output (stdout). This is the standard mechanism used by clients like Claude Desktop.
+
+### Python Stdio
+
+- **Class:** `fastmcp.client.transports.PythonStdioTransport`
+- **Inferred From:** Paths to `.py` files
+- **Use Case:** Running a Python-based MCP server script in a subprocess
+
+This is the most common way to interact with local FastMCP servers during development or when integrating with tools that expect to launch a server script.
+
+```python
+from fastmcp import Client
+from fastmcp.client.transports import PythonStdioTransport
+
+server_script = "my_mcp_server.py" # Path to your server script
+
+# Option 1: Inferred transport
+client = Client(server_script)
+
+# Option 2: Explicit transport with custom configuration
+transport = PythonStdioTransport(
+    script_path=server_script,
+    python_cmd="/usr/bin/python3.11", # Optional: specify Python interpreter
+    # args=["--some-server-arg"],      # Optional: pass arguments to the script
+    # env={"MY_VAR": "value"},         # Optional: set environment variables
+)
+client = Client(transport)
+
+async def main():
+    async with client:
+        tools = await client.list_tools()
+        print(f"Connected via Python Stdio, found tools: {tools}")
+
+asyncio.run(main())
+```
+
+<Warning>
+The server script must include logic to start the MCP server and listen on stdio, typically via `mcp.run()` or `fastmcp.server.run()`. The Client only launches the script; it doesn't inject the server logic.
+</Warning>
+
+### Node.js Stdio
+
+- **Class:** `fastmcp.client.transports.NodeStdioTransport`
+- **Inferred From:** Paths to `.js` files
+- **Use Case:** Running a Node.js-based MCP server script in a subprocess
+
+Similar to the Python transport, but for JavaScript servers.
+
+```python
+from fastmcp import Client
+from fastmcp.client.transports import NodeStdioTransport
+
+node_server_script = "my_mcp_server.js" # Path to your Node.js server script
+
+# Option 1: Inferred transport
+client = Client(node_server_script)
+
+# Option 2: Explicit transport
+transport = NodeStdioTransport(
+    script_path=node_server_script,
+    node_cmd="node" # Optional: specify path to Node executable
+)
+client = Client(transport)
+
+async def main():
+    async with client:
+        tools = await client.list_tools()
+        print(f"Connected via Node.js Stdio, found tools: {tools}")
+
+asyncio.run(main())
+```
+
+### UVX Stdio (Experimental)
+
+- **Class:** `fastmcp.client.transports.UvxStdioTransport`
+- **Inferred From:** Not automatically inferred
+- **Use Case:** Running an MCP server packaged as a Python tool using [`uvx`](https://docs.astral.sh/uv/reference/cli/#uvx)
+
+This is useful for executing MCP servers distributed as command-line tools or packages without installing them into your environment.
+
+```python
+from fastmcp import Client
+from fastmcp.client.transports import UvxStdioTransport
+
+# Run a hypothetical 'cloud-analyzer-mcp' tool via uvx
+transport = UvxStdioTransport(
+    tool_name="cloud-analyzer-mcp",
+    # from_package="cloud-analyzer-cli", # Optional: specify package if tool name differs
+    # with_packages=["boto3", "requests"] # Optional: add dependencies
+)
+client = Client(transport)
+
+async def main():
+    async with client:
+        result = await client.call_tool("analyze_bucket", {"name": "my-data"})
+        print(f"Analysis result: {result}")
+
+asyncio.run(main())
+```
+
+### NPX Stdio (Experimental)
+
+- **Class:** `fastmcp.client.transports.NpxStdioTransport`
+- **Inferred From:** Not automatically inferred
+- **Use Case:** Running an MCP server packaged as an NPM package using `npx`
+
+Similar to `UvxStdioTransport`, but for the Node.js ecosystem.
+
+```python
+from fastmcp import Client
+from fastmcp.client.transports import NpxStdioTransport
+
+# Run an MCP server from an NPM package
+transport = NpxStdioTransport(
+    package="mcp-server-package",
+    # args=["--port", "stdio"] # Optional: pass arguments to the package
+)
+client = Client(transport)
+
+async def main():
+    async with client:
+        result = await client.call_tool("get_npm_data", {})
+        print(f"Result: {result}")
+
+asyncio.run(main())
+```
+
+## In-Memory Transports
+
+### 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
+
+This is extremely useful for testing your FastMCP servers.
+
+```python
+from fastmcp import FastMCP, Client
+import asyncio
+
+# 1. Create your FastMCP server instance
+server = FastMCP(name="InMemoryServer")
+
+@server.tool()
+def ping(): 
+    return "pong"
+
+# 2. Create a client pointing directly to the server instance
+client = Client(server)  # Transport is automatically inferred
+
+async def main():
+    async with client:
+        result = await client.call_tool("ping")
+        print(f"In-memory call result: {result}")
+
+asyncio.run(main())
+```
+
+Communication happens through efficient in-memory queues, making it very fast and ideal for unit testing.