fastmcp 2.2.5__tar.gz → 2.2.6__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastmcp
-Version: 2.2.5
+Version: 2.2.6
 Summary: The fast, Pythonic way to build MCP servers.
 Project-URL: Homepage, https://gofastmcp.com
 Project-URL: Repository, https://github.com/jlowin/fastmcp
@@ -24,7 +24,7 @@ Requires-Dist: openapi-pydantic>=0.5.1
 Requires-Dist: python-dotenv>=1.1.0
 Requires-Dist: rich>=13.9.4
 Requires-Dist: typer>=0.15.2
-Requires-Dist: websockets>=15.0.1
+Requires-Dist: websockets>=14.0
 Description-Content-Type: text/markdown
 
 <div align="center">

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

@@ -149,83 +149,90 @@ 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.
 
-### Callbacks
+### Advanced Features
 
-MCP allows servers to make requests *back* to the client for certain capabilities. The `Client` constructor accepts callback functions to handle these server requests:
+MCP allows servers to interact with clients in order to provide additional capabilities. The `Client` constructor accepts additional configuration to handle these server requests.
 
-#### Roots
 
-*   **`roots: RootsList | RootsHandler | None`**: Provides the server with a list of root directories the client grants access to. This can be a static list or a function that dynamically determines roots.
-    ```python
-    from pathlib import Path
-    from fastmcp.client.roots import RootsHandler, RootsList
-    from mcp.shared.context import RequestContext # For type hint
-
-    # Option 1: Static list
-    static_roots: RootsList = [str(Path.home() / "Documents")]
-
-    # Option 2: Dynamic function
-    def dynamic_roots_handler(context: RequestContext) -> RootsList:
-        # Logic to determine accessible roots based on context
-        print(f"Server requested roots (Request ID: {context.request_id})")
-        return [str(Path.home() / "Downloads")]
-
-    client_with_roots = Client(
-        "my_server.py",
-        roots=dynamic_roots_handler # or roots=static_roots
-    )
+#### LLM Sampling
 
-    # Tell the server the roots might have changed (if needed)
-    # async with client_with_roots:
-    #     await client_with_roots.send_roots_list_changed()
-    ```
-    See `fastmcp.client.roots` for helpers.
+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.
 
-#### LLM Sampling
+The following example uses the `marvin` library to generate a completion:
 
-*   **`sampling_handler: SamplingHandler | None`**: Handles `sampling/createMessage` requests from the server. This callback receives messages from the server and should return an LLM completion.
-    ```python
-    from fastmcp.client.sampling import SamplingHandler, MessageResult
-    from mcp.types import SamplingMessage, SamplingParams, TextContent
-    from mcp.shared.context import RequestContext # For type hint
-
-    async def my_llm_handler(
-        messages: list[SamplingMessage],
-        params: SamplingParams,
-        context: RequestContext
-    ) -> str | MessageResult:
-        print(f"Server requested sampling (Request ID: {context.request_id})")
-        # In a real scenario, call your LLM API here
-        last_user_message = next((m for m in reversed(messages) if m.role == 'user'), None)
-        prompt = last_user_message.content.text if last_user_message and isinstance(last_user_message.content, TextContent) else "Default prompt"
-
-        # Simulate LLM response
-        response_text = f"LLM processed: {prompt[:50]}..."
-        # Return simple string (becomes TextContent) or a MessageResult object
-        return response_text
-
-    client_with_sampling = Client(
-        "my_server.py",
-        sampling_handler=my_llm_handler
+```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,
     )
-    ```
-    See `fastmcp.client.sampling` for helpers.
+
+client = Client(
+    ...,
+    sampling_handler=sampling_handler,
+)
+```
 
 #### Logging
 
-*   **`log_handler: LoggingFnT | None`**: Receives log messages sent from the server (`ctx.info`, `ctx.error`, etc.).
-    ```python
-    from mcp.client.session import LoggingFnT, LogLevel
+MCP servers can emit logs to clients. The client can set a logging callback to receive these logs.
 
-    def my_log_handler(level: LogLevel, message: str, logger_name: str | None):
-        print(f"[Server Log - {level.upper()}] {logger_name or 'default'}: {message}")
+```python {4-5, 9}
+from fastmcp import Client
+from fastmcp.client.logging import LogHandler, LogMessage
 
-    client_with_logging = Client(
-        "my_server.py",
-        log_handler=my_log_handler
-    )
-    ```
+async def my_log_handler(params: LogMessage):
+    print(f"[Server Log - {params.level.upper()}] {params.logger or 'default'}: {params.data}")
 
+client_with_logging = Client(
+    ...,
+    log_handler=my_log_handler,
+)
+```
+
+#### Roots
+
+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>
 ### Utility Methods
 
 *   **`ping()`**: Sends a ping request to the server to verify connectivity.

{fastmcp-2.2.5 → fastmcp-2.2.6}/docs/docs.json

@@ -62,7 +62,8 @@
                     "patterns/decorating-methods",
                     "patterns/openapi",
                     "patterns/fastapi",
-                    "patterns/contrib"
+                    "patterns/contrib",
+                    "patterns/testing"
                 ]
             },
             {

{fastmcp-2.2.5 → fastmcp-2.2.6}/docs/patterns/fastapi.mdx

@@ -44,6 +44,19 @@ if __name__ == "__main__":
     mcp.run()  # Start the MCP server
 ```
 
+## Configuration Options
+
+### Timeout
+
+You can set a timeout for all API requests:
+
+```python
+# Set a 5 second timeout for all requests
+mcp = FastMCP.from_fastapi(app=app, timeout=5.0)
+```
+
+This timeout is applied to all requests made by tools, resources, and resource templates.
+
 ## Route Mapping
 
 By default, FastMCP will map FastAPI routes to MCP components according to the following rules:
@@ -60,7 +73,7 @@ For more details on route mapping or custom mapping rules, see the [OpenAPI inte
 
 Here's a more detailed example with a data model:
 
-```python
+```python [expandable]
 import asyncio
 from fastapi import FastAPI, HTTPException
 from pydantic import BaseModel
@@ -95,24 +108,32 @@ def create_item(item: Item):
     return items[item_id]
 
 # Test your MCP server with a client
-async def test():
-    # Create MCP server from FastAPI app
-    mcp = await FastMCP.from_fastapi(app=app)
-    
+async def check_mcp(mcp: FastMCP):
     # List the components that were created
-    tools = await mcp.list_tools()
-    resources = await mcp.list_resources()
-    templates = await mcp.list_resource_templates()
+    tools = await mcp.get_tools()
+    resources = await mcp.get_resources()
+    templates = await mcp.get_resource_templates()
     
-    print(f"Generated {len(tools)} tools")
-    print(f"Generated {len(resources)} resources")
-    print(f"Generated {len(templates)} templates")
+    print(
+        f"{len(tools)} Tool(s): {', '.join([t.name for t in tools.values()])}"
+    )
+    print(
+        f"{len(resources)} Resource(s): {', '.join([r.name for r in resources.values()])}"
+    )
+    print(
+        f"{len(templates)} Resource Template(s): {', '.join([t.name for t in templates.values()])}"
+    )
     
-    # In a real scenario, you would run the server:
-    # mcp.run()
+    return mcp
 
 if __name__ == "__main__":
-    asyncio.run(test())
+    # Create MCP server from FastAPI app
+    mcp = FastMCP.from_fastapi(app=app)
+    
+    asyncio.run(check_mcp(mcp))
+    
+    # In a real scenario, you would run the server:
+    mcp.run()
 ```
 
 ## Benefits

{fastmcp-2.2.5 → fastmcp-2.2.6}/docs/patterns/openapi.mdx

@@ -27,6 +27,23 @@ if __name__ == "__main__":
     mcp.run()
 ```
 
+## Configuration Options
+
+### Timeout
+
+You can set a timeout for all API requests:
+
+```python
+# Set a 5 second timeout for all requests
+mcp = FastMCP.from_openapi(
+    openapi_spec=spec, 
+    client=api_client, 
+    timeout=5.0
+)
+```
+
+This timeout is applied to all requests made by tools, resources, and resource templates.
+
 ## Route Mapping
 
 By default, OpenAPI routes are mapped to MCP components based on these rules:
@@ -89,26 +106,67 @@ mcp = await FastMCP.from_openapi(
    - It sends the request through the provided httpx client
    - It translates the HTTP response to the appropriate MCP format
 
-## Complete Example
+### Request Parameter Handling
+
+FastMCP carefully handles different types of parameters in OpenAPI requests:
+
+#### Query Parameters
+
+By default, FastMCP will only include query parameters that have non-empty values. Parameters with `None` values or empty strings (`""`) are automatically filtered out of requests. This ensures that API servers don't receive unnecessary empty parameters that might cause issues.
 
+For example, if you call a tool with these parameters:
 ```python
+await client.call_tool("search_products", {
+    "category": "electronics",  # Will be included
+    "min_price": 100,           # Will be included
+    "max_price": None,          # Will be excluded
+    "brand": "",                # Will be excluded
+})
+```
+
+The resulting HTTP request will only include `category=electronics&min_price=100`.
+
+#### Path Parameters
+
+For path parameters, which are typically required by REST APIs, FastMCP filters out `None` values and checks that all required path parameters are provided. If a required path parameter is missing or `None`, an error will be raised.
+
+```python
+# This will work
+await client.call_tool("get_product", {"product_id": 123})
+
+# This will raise ValueError: "Missing required path parameters: {'product_id'}"
+await client.call_tool("get_product", {"product_id": None})
+```
+
+## Complete Example
+
+```python [expandable]
 import asyncio
+
 import httpx
+
 from fastmcp import FastMCP
 
 # Sample OpenAPI spec for a Pet Store API
 petstore_spec = {
     "openapi": "3.0.0",
+    "info": {
+        "title": "Pet Store API",
+        "version": "1.0.0",
+        "description": "A sample API for managing pets",
+    },
     "paths": {
         "/pets": {
             "get": {
                 "operationId": "listPets",
-                "summary": "List all pets"
+                "summary": "List all pets",
+                "responses": {"200": {"description": "A list of pets"}},
             },
             "post": {
                 "operationId": "createPet",
-                "summary": "Create a new pet"
-            }
+                "summary": "Create a new pet",
+                "responses": {"201": {"description": "Pet created successfully"}},
+            },
         },
         "/pets/{petId}": {
             "get": {
@@ -119,38 +177,50 @@ petstore_spec = {
                         "name": "petId",
                         "in": "path",
                         "required": True,
-                        "schema": {"type": "string"}
+                        "schema": {"type": "string"},
                     }
-                ]
+                ],
+                "responses": {
+                    "200": {"description": "Pet details"},
+                    "404": {"description": "Pet not found"},
+                },
             }
-        }
-    }
+        },
+    },
 }
 
-async def main():
+
+async def check_mcp(mcp: FastMCP):
+    # List what components were created
+    tools = await mcp.get_tools()
+    resources = await mcp.get_resources()
+    templates = await mcp.get_resource_templates()
+
+    print(
+        f"{len(tools)} Tool(s): {', '.join([t.name for t in tools.values()])}"
+    )  # Should include createPet
+    print(
+        f"{len(resources)} Resource(s): {', '.join([r.name for r in resources.values()])}"
+    )  # Should include listPets
+    print(
+        f"{len(templates)} Resource Template(s): {', '.join([t.name for t in templates.values()])}"
+    )  # Should include getPet
+
+    return mcp
+
+
+if __name__ == "__main__":
     # Client for the Pet Store API
     client = httpx.AsyncClient(base_url="https://petstore.example.com/api")
-    
+
     # Create the MCP server
-    mcp = await FastMCP.from_openapi(
-        openapi_spec=petstore_spec,
-        client=client,
-        name="PetStore"
+    mcp = FastMCP.from_openapi(
+        openapi_spec=petstore_spec, client=client, name="PetStore"
     )
-    
-    # List what components were created
-    tools = await mcp.list_tools()
-    resources = await mcp.list_resources()
-    templates = await mcp.list_resource_templates()
-    
-    print(f"Tools: {len(tools)}")          # Should include createPet
-    print(f"Resources: {len(resources)}")  # Should include listPets
-    print(f"Templates: {len(templates)}")  # Should include getPet
-    
+
+    asyncio.run(check_mcp(mcp))
+
     # Start the MCP server
     mcp.run()
-
-if __name__ == "__main__":
-    asyncio.run(main())
 ```
 

fastmcp-2.2.6/docs/patterns/testing.mdx

@@ -0,0 +1,38 @@
+---
+title: Testing MCP Servers
+sidebarTitle: Testing
+description: Learn how to test your FastMCP servers effectively 
+icon: vial
+---
+
+
+Testing your MCP servers thoroughly is essential for ensuring they work correctly when deployed. FastMCP makes this easy through a variety of testing patterns.
+
+## In-Memory Testing
+
+The most efficient way to test an MCP server is to pass your FastMCP server instance directly to a Client. This enables in-memory testing without having to start a separate server process, which is particularly useful because managing an MCP server programmatically can be challenging.
+
+Here is an example of using a `Client` to test a server with pytest:
+
+```python
+import pytest
+from fastmcp import FastMCP, Client
+
+@pytest.fixture
+def mcp_server():
+    server = FastMCP("TestServer")
+    
+    @server.tool()
+    def greet(name: str) -> str:
+        return f"Hello, {name}!"
+        
+    return server
+
+async def test_tool_functionality(mcp_server):
+    # Pass the server directly to the Client constructor
+    async with Client(mcp_server) as client:
+        result = await client.call_tool("greet", {"name": "World"})
+        assert "Hello, World!" in str(result[0])
+```
+
+This pattern creates a direct connection between the client and server, allowing you to test your server's functionality efficiently.

{fastmcp-2.2.5 → fastmcp-2.2.6}/examples/smart_home/src/smart_home/lights/server.py

@@ -11,15 +11,28 @@ from smart_home.lights.hue_utils import _get_bridge, handle_phue_error
 class HueAttributes(TypedDict, total=False):
     """TypedDict for optional light attributes."""
 
-    on: NotRequired[bool]
-    bri: NotRequired[Annotated[int, Field(ge=0, le=254)]]
-    hue: NotRequired[Annotated[int, Field(ge=0, le=65535)]]
-    sat: NotRequired[Annotated[int, Field(ge=0, le=254)]]
-    xy: NotRequired[list[float]]
-    ct: NotRequired[Annotated[int, Field(ge=153, le=500)]]
+    on: NotRequired[Annotated[bool, Field(description="on/off state")]]
+    bri: NotRequired[Annotated[int, Field(ge=0, le=254, description="brightness")]]
+    hue: NotRequired[
+        Annotated[
+            int,
+            Field(
+                ge=0,
+                le=254,
+                description="saturation",
+            ),
+        ]
+    ]
+    xy: NotRequired[Annotated[list[float], Field(description="xy color coordinates")]]
+    ct: NotRequired[
+        Annotated[
+            int,
+            Field(ge=153, le=500, description="color temperature"),
+        ]
+    ]
     alert: NotRequired[Literal["none", "select", "lselect"]]
     effect: NotRequired[Literal["none", "colorloop"]]
-    transitiontime: NotRequired[int]  # deciseconds
+    transitiontime: NotRequired[Annotated[int, Field(description="deciseconds")]]
 
 
 lights_mcp = FastMCP(
@@ -161,7 +174,7 @@ def activate_scene(group_name: str, scene_name: str) -> dict[str, Any]:
         scenes_data = bridge.get_scene()
         scene_found = False
         scene_in_correct_group = False
-        for sid, sinfo in scenes_data.items():
+        for sinfo in scenes_data.values():
             if sinfo.get("name") == scene_name:
                 scene_found = True
                 # Check if this scene is associated with the target group ID
@@ -217,7 +230,7 @@ def set_light_attributes(light_name: str, attributes: HueAttributes) -> dict[str
         }
 
     try:
-        result = bridge.set_light(light_name, attributes)
+        result = bridge.set_light(light_name, dict(attributes))
         return {
             "light": light_name,
             "set_attributes": attributes,
@@ -243,7 +256,7 @@ def set_group_attributes(group_name: str, attributes: HueAttributes) -> dict[str
         }
 
     try:
-        result = bridge.set_group(group_name, attributes)
+        result = bridge.set_group(group_name, dict(attributes))
         return {
             "group": group_name,
             "set_attributes": attributes,
@@ -269,7 +282,7 @@ def list_lights_by_group() -> dict[str, list[str]] | list[str]:
         lights_data = bridge.get_light_objects("id")  # dict {light_id: {details}}
 
         lights_by_group: dict[str, list[str]] = {}
-        for group_id, group_details in groups_data.items():
+        for group_details in groups_data.values():
             group_name = group_details.get("name")
             light_ids = group_details.get("lights", [])
             if group_name and light_ids:
@@ -282,11 +295,10 @@ def list_lights_by_group() -> dict[str, list[str]] | list[str]:
                         if light_name:
                             light_names.append(light_name)
                 if light_names:
-                    light_names.sort()  # Keep light list sorted
+                    light_names.sort()
                     lights_by_group[group_name] = light_names
 
         return lights_by_group
 
     except (PhueException, Exception) as e:
-        # Return error as list
         return [f"Error listing lights by group: {e}"]

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

@@ -11,7 +11,7 @@ dependencies = [
     "openapi-pydantic>=0.5.1",
     "rich>=13.9.4",
     "typer>=0.15.2",
-    "websockets>=15.0.1",
+    "websockets>=14.0",
 ]
 requires-python = ">=3.10"
 readme = "README.md"

{fastmcp-2.2.5 → fastmcp-2.2.6}/src/fastmcp/__init__.py

@@ -14,6 +14,7 @@ __all__ = [
     "FastMCP",
     "Context",
     "client",
+    "Client",
     "settings",
     "Image",
 ]

{fastmcp-2.2.5 → fastmcp-2.2.6}/src/fastmcp/client/client.py

@@ -5,12 +5,9 @@ from typing import Any, Literal, cast, overload
 
 import mcp.types
 from mcp import ClientSession
-from mcp.client.session import (
-    LoggingFnT,
-    MessageHandlerFnT,
-)
 from pydantic import AnyUrl
 
+from fastmcp.client.logging import LogHandler, MessageHandler
 from fastmcp.client.roots import (
     RootsHandler,
     RootsList,
@@ -22,7 +19,14 @@ from fastmcp.server import FastMCP
 
 from .transports import ClientTransport, SessionKwargs, infer_transport
 
-__all__ = ["Client", "RootsHandler", "RootsList"]
+__all__ = [
+    "Client",
+    "RootsHandler",
+    "RootsList",
+    "LogHandler",
+    "MessageHandler",
+    "SamplingHandler",
+]
 
 
 class Client:
@@ -35,12 +39,12 @@ class Client:
 
     def __init__(
         self,
-        transport: ClientTransport | FastMCP | AnyUrl | Path | str,
+        transport: ClientTransport | FastMCP | AnyUrl | Path | dict[str, Any] | str,
         # Common args
         roots: RootsList | RootsHandler | None = None,
         sampling_handler: SamplingHandler | None = None,
-        log_handler: LoggingFnT | None = None,
-        message_handler: MessageHandlerFnT | None = None,
+        log_handler: LogHandler | None = None,
+        message_handler: MessageHandler | None = None,
         read_timeout_seconds: datetime.timedelta | None = None,
     ):
         self.transport = infer_transport(transport)

fastmcp-2.2.6/src/fastmcp/client/logging.py

@@ -0,0 +1,13 @@
+from typing import TypeAlias
+
+from mcp.client.session import (
+    LoggingFnT,
+    MessageHandlerFnT,
+)
+from mcp.types import LoggingMessageNotificationParams
+
+LogMessage: TypeAlias = LoggingMessageNotificationParams
+LogHandler: TypeAlias = LoggingFnT
+MessageHandler: TypeAlias = MessageHandlerFnT
+
+__all__ = ["LogMessage", "LogHandler", "MessageHandler"]

{fastmcp-2.2.5 → fastmcp-2.2.6}/src/fastmcp/client/sampling.py

@@ -9,6 +9,8 @@ from mcp.shared.context import LifespanContextT, RequestContext
 from mcp.types import CreateMessageRequestParams as SamplingParams
 from mcp.types import SamplingMessage
 
+__all__ = ["SamplingMessage", "SamplingParams", "MessageResult", "SamplingHandler"]
+
 
 class MessageResult(CreateMessageResult):
     role: mcp.types.Role = "assistant"