fastmcp 2.2.4__tar.gz → 2.2.6__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastmcp
-Version: 2.2.4
+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.4 → 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.4 → 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.4 → 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.4 → 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.4 → fastmcp-2.2.6}/docs/servers/context.mdx

@@ -1,16 +1,16 @@
 ---
 title: MCP Context
 sidebarTitle: Context
-description: Access MCP capabilities like logging, progress, and resources within your tools.
+description: Access MCP capabilities like logging, progress, and resources within your MCP objects.
 icon: rectangle-code
 ---
 import { VersionBadge } from '/snippets/version-badge.mdx'
 
-When defining FastMCP [tools](/servers/tools), your functions might need to interact with the underlying MCP session or access server capabilities. FastMCP provides the `Context` object for this purpose.
+When defining FastMCP [tools](/servers/tools), [resources](/servers/resources), resource templates, or [prompts](/servers/prompts), your functions might need to interact with the underlying MCP session or access server capabilities. FastMCP provides the `Context` object for this purpose.
 
 ## What Is Context?
 
-The `Context` object provides a clean interface to access MCP features within your tool functions, including:
+The `Context` object provides a clean interface to access MCP features within your functions, including:
 
 - **Logging**: Send debug, info, warning, and error messages back to the client
 - **Progress Reporting**: Update the client on the progress of long-running operations
@@ -19,9 +19,9 @@ The `Context` object provides a clean interface to access MCP features within yo
 - **Request Information**: Access metadata about the current request
 - **Server Access**: When needed, access the underlying FastMCP server instance
 
-## Accessing Context
+## Accessing the Context
 
-To use the context object within your tool function, simply add a parameter to your function signature and type-hint it as `Context`. FastMCP will automatically inject the context instance when your tool is called.
+To use the context object within any of your functions, simply add a parameter to your function signature and type-hint it as `Context`. FastMCP will automatically inject the context instance when your function is called.
 
 ```python
 from fastmcp import FastMCP, Context
@@ -65,15 +65,15 @@ async def process_file(file_uri: str, ctx: Context) -> str:
 
 - The parameter name (e.g., `ctx`, `context`) doesn't matter, only the type hint `Context` is important.
 - The context parameter can be placed anywhere in your function's signature.
-- The context is optional - tools that don't need it can omit the parameter.
-- Context is only available within tool functions during a request; attempting to use context methods outside a request will raise errors.
-- Context methods are async, so your tool function usually needs to be async as well.
+- The context is optional - functions that don't need it can omit the parameter.
+- Context is only available during a request; attempting to use context methods outside a request will raise errors.
+- Context methods are async, so your function usually needs to be async as well.
 
 ## Context Capabilities
 
 ### Logging
 
-Send log messages back to the MCP client. This is useful for debugging and providing visibility into tool execution during a request.
+Send log messages back to the MCP client. This is useful for debugging and providing visibility into function execution during a request.
 
 ```python
 @mcp.tool()
@@ -97,14 +97,14 @@ async def analyze_data(data: list[float], ctx: Context) -> dict:
 **Available Logging Methods:**
 
 - **`ctx.debug(message: str)`**: Low-level details useful for debugging
-- **`ctx.info(message: str)`**: General information about tool execution
+- **`ctx.info(message: str)`**: General information about execution
 - **`ctx.warning(message: str)`**: Potential issues that didn't prevent execution
 - **`ctx.error(message: str)`**: Errors that occurred during execution
 - **`ctx.log(level: Literal["debug", "info", "warning", "error"], message: str, logger_name: str | None = None)`**: Generic log method supporting custom logger names
 
 ### Progress Reporting
 
-For long-running tools, notify the client about the progress of the operation. This allows clients to display progress indicators and provide a better user experience.
+For long-running operations, notify the client about the progress. This allows clients to display progress indicators and provide a better user experience.
 
 ```python
 @mcp.tool()
@@ -137,7 +137,7 @@ Progress reporting requires the client to have sent a `progressToken` in the ini
 
 ### Resource Access
 
-Read data from resources registered with your FastMCP server. This allows tools to access files, configuration, or dynamically generated content.
+Read data from resources registered with your FastMCP server. This allows functions to access files, configuration, or dynamically generated content.
 
 ```python
 @mcp.tool()
@@ -177,7 +177,7 @@ The returned content is typically accessed via `content_list[0].content` and can
 
 <VersionBadge version="2.0.0" />
 
-Request the client's LLM to generate text based on provided messages. This is useful when your tool needs to leverage the LLM's capabilities to process data or generate responses.
+Request the client's LLM to generate text based on provided messages. This is useful when your function needs to leverage the LLM's capabilities to process data or generate responses.
 
 ```python
 @mcp.tool()
@@ -279,6 +279,60 @@ async def advanced_tool(ctx: Context) -> str:
 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.
 </Warning>
 
-## Using Context in Other Components
+## Using Context in Different Components
 
-Currently, Context is primarily designed for use within tool functions. Support for Context in other components like resources and prompts is planned for future releases. 
+All FastMCP components (tools, resources, templates, and prompts) can use the Context object following the same pattern - simply add a parameter with the `Context` type annotation.
+
+### Context in Resources and Templates
+
+Resources and resource templates can access context to customize their behavior:
+
+```python
+@mcp.resource("resource://user-data")
+async def get_user_data(ctx: Context) -> dict:
+    """Fetch personalized user data based on the request context."""
+    user_id = ctx.client_id or "anonymous"
+    await ctx.info(f"Fetching data for user {user_id}")
+    
+    # Example of using context for dynamic resource generation
+    return {
+        "user_id": user_id,
+        "last_access": datetime.now().isoformat(),
+        "request_id": ctx.request_id
+    }
+
+@mcp.resource("resource://users/{user_id}/profile")
+async def get_user_profile(user_id: str, ctx: Context) -> dict:
+    """Fetch user profile from database with context-aware logging."""
+    await ctx.info(f"Fetching profile for user {user_id}")
+    
+    # Example of using context in a template resource
+    # In a real implementation, you might query a database
+    return {
+        "id": user_id,
+        "name": f"User {user_id}",
+        "request_id": ctx.request_id
+    }
+```
+
+### Context in Prompts
+
+Prompts can use context to generate more dynamic templates:
+
+```python
+@mcp.prompt()
+async def data_analysis_request(dataset: str, ctx: Context) -> str:
+    """Generate a request to analyze data with contextual information."""
+    await ctx.info(f"Generating data analysis prompt for {dataset}")
+    
+    # Could use context to read configuration or personalize the prompt
+    return f"""Please analyze the following dataset: {dataset}
+    
+Request initiated at: {datetime.now().isoformat()}
+Request ID: {ctx.request_id}
+"""
+```
+
+<VersionBadge version="2.3.0" />
+
+All FastMCP objects now support context injection using the same consistent pattern, making it easy to add session-aware capabilities to all aspects of your MCP server. 

{fastmcp-2.2.4 → fastmcp-2.2.6}/docs/servers/prompts.mdx

@@ -20,7 +20,7 @@ Prompts provide parameterized message templates for LLMs. When a client requests
 
 This allows you to define consistent, reusable templates that LLMs can use across different clients and contexts.
 
-## Defining Prompts
+## Prompts
 
 ### The `@prompt` Decorator
 
@@ -171,33 +171,24 @@ async def data_based_prompt(data_id: str) -> str:
 
 Use `async def` when your prompt function performs I/O operations like network requests, database queries, file I/O, or external service calls.
 
-### The MCP Session
+### Accessing MCP Context
 
-Prompts can access the MCP features via the `Context` object, just like tools.
+<VersionBadge version="2.2.5" />
 
-```python
-from fastmcp import Context
+Prompts can access additional MCP information and features through the `Context` object. To access it, add a parameter to your prompt function with a type annotation of `Context`:
+
+```python {6}
+from fastmcp import FastMCP, Context
+
+mcp = FastMCP(name="PromptServer")
 
 @mcp.prompt()
 async def generate_report_request(report_type: str, ctx: Context) -> str:
-    """Generates a request for a report based on available data."""
-    # Log the request
-    await ctx.info(f"Generating prompt for report type: {report_type}")
-    
-    # Could potentially use ctx.read_resource to fetch data
-    # Or ctx.sample to get additional input from the LLM
-    
-    return f"Please create a {report_type} report based on the available data."
+    """Generates a request for a report."""
+    return f"Please create a {report_type} report. Request ID: {ctx.request_id}"
 ```
 
-Using the `ctx` parameter (based on its `Context` type hint), you can access:
-
--   **Logging:** `ctx.debug()`, `ctx.info()`, etc.
--   **Resource Access:** `ctx.read_resource(uri)`
--   **LLM Sampling:** `ctx.sample(...)`
--   **Request Info:** `ctx.request_id`, `ctx.client_id`
-
-Refer to the [Context documentation](/servers/context) for more details on these capabilities.
+For full documentation on the Context object and all its capabilities, see the [Context documentation](/servers/context).
 
 ## Server Behavior