fastmcp 2.2.6__tar.gz → 2.2.7__tar.gz

{fastmcp-2.2.6 → fastmcp-2.2.7}/.github/workflows/run-tests.yml

@@ -59,4 +59,4 @@ jobs:
           uv pip install pyreadline3
 
       - name: Run tests
-        run: uv run pytest -vv
+        run: uv run --frozen pytest -vv

{fastmcp-2.2.6 → fastmcp-2.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastmcp
-Version: 2.2.6
+Version: 2.2.7
 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.6.0
+Requires-Dist: mcp<2.0.0,>=1.7.1
 Requires-Dist: openapi-pydantic>=0.5.1
 Requires-Dist: python-dotenv>=1.1.0
 Requires-Dist: rich>=13.9.4
@@ -789,7 +789,7 @@ Contributions make the open-source community vibrant! We welcome improvements an
 
 Run the test suite:
 ```bash
-uv run pytest -vv
+uv run --frozen pytest -vv
 ```
 
 #### Formatting & Linting

{fastmcp-2.2.6 → fastmcp-2.2.7}/README.md

@@ -760,7 +760,7 @@ Contributions make the open-source community vibrant! We welcome improvements an
 
 Run the test suite:
 ```bash
-uv run pytest -vv
+uv run --frozen pytest -vv
 ```
 
 #### Formatting & Linting

{fastmcp-2.2.6 → fastmcp-2.2.7}/docs/clients/client.mdx

@@ -149,6 +149,34 @@ The `Client` provides methods corresponding to standard MCP requests:
 *   **`list_prompts()`**: Retrieves available prompt templates.
 *   **`get_prompt(name: str, arguments: dict[str, Any] | None = None)`**: Retrieves a rendered prompt message list.
 
+### Raw MCP Protocol Objects
+
+The FastMCP client attempts to provide a "friendly" interface to the MCP protocol, but sometimes you may need access to the raw MCP protocol objects. Each of the main client methods that returns data has a corresponding `*_mcp` method that returns the raw MCP protocol objects directly.
+
+```python
+# Standard method - returns just the list of tools
+tools = await client.list_tools()
+# tools -> list[mcp.types.Tool]
+
+# Raw MCP method - returns the full protocol object
+result = await client.list_tools_mcp()
+# result -> mcp.types.ListToolsResult
+tools = result.tools
+```
+
+Available raw MCP methods:
+
+*   **`list_tools_mcp()`**: Returns `mcp.types.ListToolsResult`
+*   **`call_tool_mcp(name, arguments)`**: Returns `mcp.types.CallToolResult`
+*   **`list_resources_mcp()`**: Returns `mcp.types.ListResourcesResult`
+*   **`list_resource_templates_mcp()`**: Returns `mcp.types.ListResourceTemplatesResult`
+*   **`read_resource_mcp(uri)`**: Returns `mcp.types.ReadResourceResult`
+*   **`list_prompts_mcp()`**: Returns `mcp.types.ListPromptsResult`
+*   **`get_prompt_mcp(name, arguments)`**: Returns `mcp.types.GetPromptResult`
+*   **`complete_mcp(ref, argument)`**: Returns `mcp.types.CompleteResult`
+
+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
 
 MCP allows servers to interact with clients in order to provide additional capabilities. The `Client` constructor accepts additional configuration to handle these server requests.
@@ -268,5 +296,5 @@ async def safe_call_tool():
 Other errors, like connection failures, will raise standard Python exceptions (e.g., `ConnectionError`, `TimeoutError`). 
 
 <Tip>
-The client transport often has its own error-handling mechanisms, so you can not always trap errors like those raised by `call_tool` outside of the `async with` block. Instead, you can call `call_tool(..., _return_raw_result=True)` to get the raw `mcp.types.CallToolResult` object and handle errors yourself by checking its `isError` attribute.
+The client transport often has its own error-handling mechanisms, so you can not always trap errors like those raised by `call_tool` outside of the `async with` block. Instead, you can use `call_tool_mcp()` to get the raw `mcp.types.CallToolResult` object and handle errors yourself by checking its `isError` attribute.
 </Tip>

{fastmcp-2.2.6 → fastmcp-2.2.7}/docs/patterns/composition.mdx

@@ -30,8 +30,6 @@ The choice of importing or mounting depends on your use case and requirements. I
 | **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 |
-| **Lifespan** | Not managed | Automatically managed |
-| **Synchronicity** | Async (must be awaited) | Sync |
 | **Best For** | Bundling finalized components | Modular runtime composition |
 
 ### Proxy Servers
@@ -184,12 +182,12 @@ if __name__ == "__main__":
 
 ### How Mounting Works
 
-When you call `main_mcp.mount(prefix, server)`:
+Mounting creates a relationship between two servers where one server (the parent) delegates certain operations to another (the mounted server) based on prefixes. When mounting is configured:
 
-1. **Live Link**: A live connection is established between `main_mcp` and the `subserver`.
-2. **Dynamic Updates**: Changes made to the `subserver` (e.g., adding new tools) **will be reflected** immediately when accessing components through `main_mcp`.
-3. **Lifespan Management**: The `subserver`'s `lifespan` context **is automatically managed** and executed within the `main_mcp`'s lifespan.
-4. **Delegation**: Requests for components matching the prefix are delegated to the subserver at runtime.
+1. **Live Link**: The parent server establishes a connection to the mounted server.
+2. **Dynamic Updates**: Changes made to the mounted server (e.g., adding new tools) are immediately reflected when accessed through the parent server.
+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.
 
@@ -207,6 +205,49 @@ main_mcp.mount(
 )
 ```
 
+### Direct vs. Proxy Mounting
+
+FastMCP supports two modes for mounting servers:
+
+1. **Direct Mounting** (default): The parent server directly accesses the mounted server's objects in memory for optimal performance and observability. In this mode:
+   - 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. In this mode:
+   - 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
+   - This preserves all client-facing behaviors but is slightly less efficient
+
+You can control which mode to use with the `as_proxy` parameter:
+
+```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 by explicitly setting `as_proxy=False` or `as_proxy=True`.
+
+#### Interaction with Proxy Servers
+
+When using `FastMCP.from_client()` to create a proxy server, mounting that server will always use proxy mounting since the proxy server is already designed to be accessed via a client interface.
+
+```python
+from fastmcp import FastMCP, Client
+
+# Create a proxy for a remote server
+remote_proxy = FastMCP.from_client(Client("http://example.com/mcp"))
+
+# Mount the proxy - this will preserve full client lifecycle
+main_server.mount("remote", remote_proxy)
+```
+
+This is particularly useful for incorporating remote servers into your local application architecture.
+
 
 ## Example: Modular Application
 

{fastmcp-2.2.6 → fastmcp-2.2.7}/docs/servers/context.mdx

@@ -253,7 +253,9 @@ async def request_info(ctx: Context) -> dict:
 
 ### Advanced Access
 
-For advanced use cases, you can access the underlying MCP session and FastMCP server.
+For advanced use cases, you can access the underlying MCP session, FastMCP server, and HTTP requests.
+
+#### Accessing FastMCP and Sessions
 
 ```python
 @mcp.tool()
@@ -269,11 +271,35 @@ async def advanced_tool(ctx: Context) -> str:
     return f"Server: {server_name}"
 ```
 
-**Advanced Properties:**
+#### Accessing HTTP Requests
+
+<VersionBadge version="2.2.7" />
+
+For web applications, you can access the underlying HTTP request:
+
+```python
+@mcp.tool()
+async def handle_web_request(ctx: Context) -> dict:
+    """Access HTTP request information from the Starlette request."""
+    request = ctx.get_http_request()
+    
+    # Access HTTP headers, query parameters, etc.
+    user_agent = request.headers.get("user-agent", "Unknown")
+    client_ip = request.client.host if request.client else "Unknown"
+    
+    return {
+        "user_agent": user_agent,
+        "client_ip": client_ip,
+        "path": request.url.path,
+    }
+```
+
+#### Advanced Properties Reference
 
 - **`ctx.fastmcp -> FastMCP`**: Access the server instance the context belongs to
 - **`ctx.session`**: Access the raw `mcp.server.session.ServerSession` object
 - **`ctx.request_context`**: Access the raw `mcp.shared.context.RequestContext` object
+- **`ctx.get_http_request() -> Request`**: Access the active Starlette request object (when running with a web server)
 
 <Warning>
 Direct use of `session` or `request_context` requires understanding the low-level MCP Python SDK and may be less stable than using the methods provided directly on the `Context` object.

{fastmcp-2.2.6 → fastmcp-2.2.7}/docs/servers/fastmcp.mdx

@@ -245,6 +245,7 @@ sub = FastMCP(name="Sub")
 def hello(): 
     return "hi"
 
+# Mount directly
 main.mount("sub", sub)
 ```
 
@@ -292,4 +293,42 @@ print(mcp.settings.on_duplicate_tools) # Output: "error"
 - **`on_duplicate_resources`**: How to handle duplicate resource registrations
 - **`on_duplicate_prompts`**: How to handle duplicate prompt registrations
 
-All of these can be configured directly as parameters when creating the `FastMCP` instance.
+All of these can be configured directly as parameters when creating the `FastMCP` instance.
+
+## Authentication
+
+<VersionBadge version="2.2.7" />
+
+FastMCP inherits support for OAuth 2.0 authentication from the MCP protocol, allowing servers to protect their tools and resources behind authentication.
+
+### OAuth 2.0 Support
+
+The `mcp.server.auth` module implements an OAuth 2.0 server interface that servers can use by providing an implementation of the `OAuthServerProvider` protocol.
+
+```python
+from fastmcp import FastMCP
+from mcp.server.auth.settings import (
+    RevocationOptions,
+    ClientRegistrationOptions,
+    AuthSettings,
+)
+
+
+# Create a server with authentication
+mcp = FastMCP(
+    name="SecureApp",
+    auth_provider=MyOAuthServerProvider(),
+    auth=AuthSettings(
+        issuer_url="https://myapp.com",
+        revocation_options=RevocationOptions(
+            enabled=True,
+        ),
+        client_registration_options=ClientRegistrationOptions(
+            enabled=True,
+            valid_scopes=["myscope", "myotherscope"],
+            default_scopes=["myscope"],
+        ),
+        required_scopes=["myscope"],
+    ),
+)
+```

{fastmcp-2.2.6 → fastmcp-2.2.7}/docs/servers/tools.mdx

@@ -5,6 +5,8 @@ description: Expose functions as executable capabilities for your MCP client.
 icon: wrench
 ---
 
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
 Tools are the core building blocks that allow your LLM to interact with external systems, execute code, and access data that isn't in its training data. In FastMCP, tools are Python functions exposed to LLMs through the MCP protocol.
 
 ## What Are Tools?
@@ -263,8 +265,46 @@ FastMCP automatically catches exceptions raised within your tool function:
 
 Using informative exceptions helps the LLM understand failures and react appropriately.
 
-## MCP Context
+### Annotations
+
+<VersionBadge version="2.2.7" />
+
+FastMCP allows you to add specialized metadata to your tools through annotations. These annotations communicate how tools behave to client applications without consuming token context in LLM prompts.
+
+Annotations serve several purposes in client applications:
+- Adding user-friendly titles for display purposes
+- Indicating whether tools modify data or systems
+- Describing the safety profile of tools (destructive vs. non-destructive)
+- Signaling if tools interact with external systems
 
+You can add annotations to a tool using the `annotations` parameter in the `@mcp.tool()` decorator:
+
+```python
+@mcp.tool(
+    annotations={
+        "title": "Calculate Sum",
+        "readOnlyHint": True,
+        "openWorldHint": False
+    }
+)
+def calculate_sum(a: float, b: float) -> float:
+    """Add two numbers together."""
+    return a + b
+```
+
+FastMCP supports these standard annotations:
+
+| Annotation | Type | Default | Purpose |
+| :--------- | :--- | :------ | :------ |
+| `title` | string | - | Display name for user interfaces |
+| `readOnlyHint` | boolean | false | Indicates if the tool only reads without making changes |
+| `destructiveHint` | boolean | true | For non-readonly tools, signals if changes are destructive |
+| `idempotentHint` | boolean | false | Indicates if repeated identical calls have the same effect as a single call |
+| `openWorldHint` | boolean | true | Specifies if the tool interacts with external systems |
+
+Remember that annotations help make better user experiences but should be treated as advisory hints. They help client applications present appropriate UI elements and safety controls, but won't enforce security boundaries on their own. Always focus on making your annotations accurately represent what your tool actually does.
+
+## MCP Context
 
 Tools can access MCP features like logging, reading resources, or reporting progress through the `Context` object. To use it, add a parameter to your tool function with the type hint `Context`.
 

fastmcp-2.2.7/examples/serializer.py

@@ -0,0 +1,32 @@
+import asyncio
+from typing import Any
+
+import yaml
+
+from fastmcp import FastMCP
+
+
+# Define a simple custom serializer
+def custom_dict_serializer(data: Any) -> str:
+    return yaml.dump(data, width=100, sort_keys=False)
+
+
+server = FastMCP(name="CustomSerializerExample", tool_serializer=custom_dict_serializer)
+
+
+@server.tool()
+def get_example_data() -> dict:
+    """Returns some example data."""
+    return {"name": "Test", "value": 123, "status": True}
+
+
+async def example_usage():
+    result = await server._mcp_call_tool("get_example_data", {})
+    print("Tool Result:")
+    print(result)
+    print("This is an example of using a custom serializer with FastMCP.")
+
+
+if __name__ == "__main__":
+    asyncio.run(example_usage())
+    server.run()

fastmcp-2.2.7/examples/smart_home/README.md

@@ -0,0 +1,15 @@
+# smart home mcp server
+
+```bash
+cd examples/smart_home
+mcp install src/smart_home/hub.py:hub_mcp -f .env
+```
+where `.env` contains the following:
+```
+HUE_BRIDGE_IP=<your hue bridge ip>
+HUE_BRIDGE_USERNAME=<your hue bridge username>
+```
+
+```bash
+open -a Claude
+```

{fastmcp-2.2.6 → fastmcp-2.2.7}/justfile

@@ -6,4 +6,4 @@ test: build
 
 # Run pyright on all files
 typecheck:
-    uv run pyright
+    uv run --frozen pyright

{fastmcp-2.2.6 → fastmcp-2.2.7}/pyproject.toml

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