fastmcp 2.3.4__tar.gz → 2.4.0__tar.gz

fastmcp-2.4.0/.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.4.0/.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.4.0}/.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.4.0}/.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:
 
@@ -48,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.4.0/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.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastmcp
-Version: 2.3.4
+Version: 2.4.0
 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
@@ -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
@@ -290,7 +313,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.4.0}/README.md

@@ -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
@@ -261,7 +284,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.4.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>