fastmcp 2.2.10__tar.gz → 2.3.0rc1__tar.gz

{fastmcp-2.2.10 → fastmcp-2.3.0rc1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastmcp
-Version: 2.2.10
+Version: 2.3.0rc1
 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.7.1
+Requires-Dist: mcp
 Requires-Dist: openapi-pydantic>=0.5.1
 Requires-Dist: python-dotenv>=1.1.0
 Requires-Dist: rich>=13.9.4

fastmcp-2.3.0rc1/docs/deployment/authentication.mdx

@@ -0,0 +1,15 @@
+---
+title: Authentication
+sidebarTitle: Authentication
+description: Secure your FastMCP server with authentication.
+icon: lock
+---
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="2.2.7" />
+
+This document will cover how to implement authentication for your FastMCP servers.
+
+FastMCP leverages the OAuth 2.0 support provided by the underlying Model Context Protocol (MCP) SDK.
+
+For now, refer to the [MCP Server Authentication documentation](/servers/fastmcp#authentication) for initial details and the [official MCP SDK documentation](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization) for more.

fastmcp-2.3.0rc1/docs/deployment/running-server.mdx

@@ -0,0 +1,192 @@
+---
+title: Running Your FastMCP Server
+sidebarTitle: Running the Server
+description: Learn how to run and deploy your FastMCP server using various transport protocols like STDIO, Streamable HTTP, and SSE.
+icon: circle-play
+---
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+
+FastMCP servers can be run in different ways depending on your application's needs, from local command-line tools to persistent web services. This guide covers the primary methods for running your server, focusing on the available transport protocols: STDIO, Streamable HTTP, and SSE.
+
+## The `run()` Method
+
+The main way to run a FastMCP server from a Python script is by calling the `run()` method on a `FastMCP` instance. 
+
+<Tip>
+For maximum compatibility, it's best practice to place the `run()` call within an `if __name__ == "__main__":` block. This ensures the server starts only when the script is executed directly, not when imported as a module.
+</Tip>
+
+```python {9-10} my_server.py
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="MyServer")
+
+@mcp.tool()
+def hello(name: str) -> str:
+    return f"Hello, {name}!"
+
+if __name__ == "__main__":
+    mcp.run()
+```
+You can now run this MCP server by executing `python my_server.py`. 
+
+MCP servers can be run with a variety of different transport options, depending on your application's requirements. The `run()` method can take a `transport` argument and other transport-specific keyword arguments to configure how the server operates.
+
+## Transport Options
+
+Below is a comparison of available transport options to help you choose the right one for your needs:
+
+| Transport | Use Cases | Recommendation |
+| --------- | --------- | -------------- |
+| **STDIO** | Local tools, command-line scripts, and integrations with clients like Claude Desktop | Best for local tools and when clients manage server processes |
+| **Streamable HTTP** | Web-based deployments, microservices, exposing MCP over a network | Recommended choice for new web-based deployments |
+| **SSE** | Existing web-based deployments that rely on SSE | Suitable for compatibility with SSE clients; prefer Streamable HTTP for new projects |
+
+### STDIO
+
+The STDIO transport is the default and most widely compatible option for local MCP server execution. It is ideal for local tools, command-line integrations, and clients like Claude Desktop. However, it has the disadvantage of having to run the MCP code locally, which can introduce security concerns with third-party servers.
+
+STDIO is the default transport, so you don't need to specify it when calling `run()`. However, you can specify it explicitly to make your intent clear:
+
+```python {6}
+from fastmcp import FastMCP
+
+mcp = FastMCP()
+
+if __name__ == "__main__":
+    mcp.run(transport="stdio")
+```
+
+When using Stdio transport, you will typically *not* run the server yourself as a separate process. Rather, your *clients* will spin up a new server process for each session. As such, no additional configuration is required.
+
+### Streamable HTTP
+
+<VersionBadge version="2.3.0" />
+
+Streamable HTTP is a modern, efficient transport for exposing your MCP server via HTTP. It is generally recommended over SSE for new web-based deployments.
+
+To run a server using Streamable HTTP, you can use the `run()` method with the `transport` argument set to `"streamable-http"`. This will start a Uvicorn server on the default host (`127.0.0.1`), port (`8000`), and path (`/mcp`).
+<CodeGroup>
+```python {6} server.py
+from fastmcp import FastMCP
+
+mcp = FastMCP()
+
+if __name__ == "__main__":
+    mcp.run(transport="streamable-http")
+```
+```python {5} client.py
+import asyncio
+from fastmcp import Client
+
+async def example():
+    async with Client("http://127.0.0.1:8000/mcp") as client:
+        await client.ping()
+
+if __name__ == "__main__":
+    asyncio.run(example())
+```
+</CodeGroup>
+
+To customize the host, port, path, or log level, provide appropriate keyword arguments to the `run()` method.
+
+<CodeGroup>
+```python {8-11} server.py
+from fastmcp import FastMCP
+
+mcp = FastMCP()
+
+if __name__ == "__main__":
+    mcp.run(
+        transport="streamable-http",
+        host="127.0.0.1",
+        port=4200,
+        path="/my-custom-path",
+        log_level="debug",
+    )
+```
+```python {5} client.py
+import asyncio
+from fastmcp import Client
+
+async def example():
+    async with Client("http://127.0.0.1:4200/my-custom-path") as client:
+        await client.ping()
+
+if __name__ == "__main__":
+    asyncio.run(example())
+```
+</CodeGroup>
+
+
+### SSE
+
+Server-Sent Events (SSE) is an HTTP-based protocol for server-to-client streaming. While FastMCP supports SSE, Streamable HTTP is preferred for new projects.
+
+To run a server using SSE, you can use the `run()` method with the `transport` argument set to `"sse"`. This will start a Uvicorn server on the default host (`127.0.0.1`), port (`8000`), and with default SSE path (`/sse`) and message path (`/messages/`).
+
+<CodeGroup>
+```python {6} server.py
+from fastmcp import FastMCP
+
+mcp = FastMCP()
+
+if __name__ == "__main__":
+    mcp.run(transport="sse")
+```
+```python {3,7} client.py
+import asyncio
+from fastmcp import Client
+from fastmcp.client.transports import SSETransport
+
+async def example():
+    async with Client(
+        transport=SSETransport("http://127.0.0.1:8000/sse")
+    ) as client:
+        await client.ping()
+
+if __name__ == "__main__":
+    asyncio.run(example())
+```
+</CodeGroup>
+
+<Tip>
+Notice that the client in the above example uses an explicit `SSETransport` to connect to the server. FastMCP will attempt to infer the appropriate transport from the provided configuration, but HTTP URLs are assumed to be Streamable HTTP (as of FastMCP 2.3.0).
+</Tip>
+
+To customize the host, port, or log level, provide appropriate keyword arguments to the `run()` method. You can also adjust the SSE path (which clients should connect to) and the message POST endpoint (which clients use to send subsequent messages).
+
+<CodeGroup>
+```python {8-12} server.py
+from fastmcp import FastMCP
+
+mcp = FastMCP()
+
+if __name__ == "__main__":
+    mcp.run(
+        transport="sse",
+        host="127.0.0.1",
+        port=4200,
+        log_level="debug",
+        path="/my-custom-sse-path",
+        message_path="/my-custom-message-path/",
+    )
+```
+```python {7} client.py
+import asyncio
+from fastmcp import Client
+from fastmcp.client.transports import SSETransport
+
+async def example():
+    async with Client(
+        transport=SSETransport("http://127.0.0.1:4200/my-custom-sse-path")
+    ) as client:
+        await client.ping()
+
+if __name__ == "__main__":
+    asyncio.run(example())
+```
+</CodeGroup>
+
+Your client only needs to know the host, port, and "main" path; the message path will be transmitted to it as part of the connection handshake.

{fastmcp-2.2.10 → fastmcp-2.3.0rc1}/docs/docs.json

@@ -49,7 +49,16 @@
                     "servers/tools",
                     "servers/resources",
                     "servers/prompts",
-                    "servers/context"
+                    "servers/context",
+                    "patterns/proxy",
+                    "patterns/composition"
+                ]
+            },
+            {
+                "group": "Deployment",
+                "pages": [
+                    "deployment/running-server",
+                    "deployment/authentication"
                 ]
             },
             {
@@ -62,9 +71,8 @@
             {
                 "group": "Patterns",
                 "pages": [
-                    "patterns/proxy",
-                    "patterns/composition",
                     "patterns/decorating-methods",
+                    "patterns/http-requests",
                     "patterns/openapi",
                     "patterns/fastapi",
                     "patterns/contrib",

{fastmcp-2.2.10 → fastmcp-2.3.0rc1}/docs/getting-started/quickstart.mdx

@@ -1,6 +1,6 @@
 ---
 title: Quickstart
-icon: rocket
+icon: rocket-launch
 ---
 
 Welcome! This guide will help you quickly set up FastMCP and run your first MCP server.

fastmcp-2.3.0rc1/docs/patterns/http-requests.mdx

@@ -0,0 +1,79 @@
+---
+title: HTTP Requests
+sidebarTitle: HTTP Requests
+description: Accessing and using HTTP requests in FastMCP servers
+icon: network-wired
+---
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="2.2.11" />
+
+## Overview
+
+When running FastMCP as a web server, your MCP tools, resources, and prompts might need to access the underlying HTTP request information, such as headers, client IP, or query parameters.
+
+FastMCP provides a clean way to access HTTP request information through a dependency function.
+
+## Accessing HTTP Requests
+
+The recommended way to access the current HTTP request is through the `get_http_request()` dependency function:
+
+```python {2, 3, 11}
+from fastmcp import FastMCP
+from fastmcp.server.dependencies import get_http_request
+from starlette.requests import Request
+
+mcp = FastMCP(name="HTTPRequestDemo")
+
+@mcp.tool()
+async def user_agent_info() -> dict:
+    """Return information about the user agent."""
+    # Get the HTTP request
+    request: Request = get_http_request()
+    
+    # Access request data
+    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,
+    }
+```
+
+This approach works anywhere within a request's execution flow, not just within your MCP function. It's useful when:
+
+1. You need access to HTTP information in helper functions
+2. You're calling nested functions that need HTTP request data
+3. You're working with middleware or other request processing code
+
+## Important Notes
+
+- HTTP requests are only available when FastMCP is running as part of a web application
+- Accessing the HTTP request outside of a web request context will raise a `RuntimeError`
+- The `get_http_request()` function returns a standard [Starlette Request](https://www.starlette.io/requests/) object
+
+## Common Use Cases
+
+### Accessing Request Headers
+
+```python
+from fastmcp.server.dependencies import get_http_request
+
+@mcp.tool()
+async def get_auth_info() -> dict:
+    """Get authentication information from request headers."""
+    request = get_http_request()
+    
+    # Get authorization header
+    auth_header = request.headers.get("authorization", "")
+    
+    # Check for Bearer token
+    is_bearer = auth_header.startswith("Bearer ")
+    
+    return {
+        "has_auth": bool(auth_header),
+        "auth_type": "Bearer" if is_bearer else "Other" if auth_header else "None"
+    }
+```

{fastmcp-2.2.10 → fastmcp-2.3.0rc1}/docs/patterns/proxy.mdx

@@ -1,6 +1,6 @@
 ---
-title: Proxying Servers
-sidebarTitle: Proxying
+title: Proxy Servers
+sidebarTitle: Proxy Servers
 description: Use FastMCP to act as an intermediary or change transport for other MCP servers.
 icon: arrows-retweet
 ---

{fastmcp-2.2.10 → fastmcp-2.3.0rc1}/docs/servers/context.mdx

@@ -21,8 +21,21 @@ The `Context` object provides a clean interface to access MCP features within yo
 
 ## Accessing the Context
 
+### Via Dependency Injection
+
 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.
 
+**Key Points:**
+
+- 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; it will not be exposed to MCP clients as a valid parameter.
+- The context is optional - functions that don't need it can omit the parameter entirely.
+- Context methods are async, so your function usually needs to be async as well.
+- The type hint can be a union (`Context | None`) or use `Annotated[]` and it will still work properly.
+- Context is only available during a request; attempting to use context methods outside a request will raise errors. If you need to debug or call your context methods outside of a request, you can type your variable as `Context | None=None` to avoid missing argument errors.
+
+#### Tools
+
 ```python
 from fastmcp import FastMCP, Context
 
@@ -31,43 +44,72 @@ mcp = FastMCP(name="ContextDemo")
 @mcp.tool()
 async def process_file(file_uri: str, ctx: Context) -> str:
     """Processes a file, using context for logging and resource access."""
-    request_id = ctx.request_id
-    await ctx.info(f"[{request_id}] Starting processing for {file_uri}")
+    # Context is available as the ctx parameter
+    return "Processed file"
+```
 
-    try:
-        # Use context to read a resource
-        contents_list = await ctx.read_resource(file_uri)
-        if not contents_list:
-            await ctx.warning(f"Resource {file_uri} is empty.")
-            return "Resource empty"
+#### Resources and Templates
 
-        data = contents_list[0].content # Assuming TextResourceContents
-        await ctx.debug(f"Read {len(data)} bytes from {file_uri}")
+<VersionBadge version="2.2.5" />
 
-        # Report progress
-        await ctx.report_progress(progress=50, total=100)
-        
-        # Simulate work
-        processed_data = data.upper() # Example processing
+```python
+@mcp.resource("resource://user-data")
+async def get_user_data(ctx: Context) -> dict:
+    """Fetch personalized user data based on the request context."""
+    # Context is available as the ctx parameter
+    return {"user_id": "example"}
 
-        await ctx.report_progress(progress=100, total=100)
-        await ctx.info(f"Processing complete for {file_uri}")
+@mcp.resource("resource://users/{user_id}/profile")
+async def get_user_profile(user_id: str, ctx: Context) -> dict:
+    """Fetch user profile with context-aware logging."""
+    # Context is available as the ctx parameter
+    return {"id": user_id}
+```
 
-        return f"Processed data length: {len(processed_data)}"
+#### Prompts
 
-    except Exception as e:
-        # Use context to log errors
-        await ctx.error(f"Error processing {file_uri}: {str(e)}")
-        raise # Re-raise to send error back to client
+<VersionBadge version="2.2.5" />
+
+```python
+@mcp.prompt()
+async def data_analysis_request(dataset: str, ctx: Context) -> str:
+    """Generate a request to analyze data with contextual information."""
+    # Context is available as the ctx parameter
+    return f"Please analyze the following dataset: {dataset}"
 ```
 
-**Key Points:**
 
-- 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 - 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.
+### Via Dependency Function
+
+<VersionBadge version="2.2.11" />
+
+While the simplest way to access context is through function parameter injection as shown above, there are cases where you need to access the context in code that may not be easy to modify to accept a context parameter, or that is nested deeper within your function calls.
+
+FastMCP provides dependency functions that allow you to retrieve the active context from anywhere within a server request's execution flow:
+
+```python {2,9}
+from fastmcp import FastMCP, Context
+from fastmcp.server.dependencies import get_context
+
+mcp = FastMCP(name="DependencyDemo")
+
+# Utility function that needs context but doesn't receive it as a parameter
+async def process_data(data: list[float]) -> dict:
+    # Get the active context - only works when called within a request
+    ctx = get_context()    
+    await ctx.info(f"Processing {len(data)} data points")
+    
+@mcp.tool()
+async def analyze_dataset(dataset_name: str) -> dict:
+    # Call utility function that uses context internally
+    data = load_data(dataset_name)
+    await process_data(data)
+```
+
+**Important Notes:**
+
+- The `get_context` function should only be used within the context of a server request. Calling it outside of a request will raise a `RuntimeError`.
+- The `get_context` function is server-only and should not be used in client code.
 
 ## Context Capabilities
 
@@ -253,9 +295,8 @@ async def request_info(ctx: Context) -> dict:
 
 ### Advanced Access
 
-For advanced use cases, you can access the underlying MCP session, FastMCP server, and HTTP requests.
 
-#### Accessing FastMCP and Sessions
+#### FastMCP Server and Sessions
 
 ```python
 @mcp.tool()
@@ -271,10 +312,16 @@ async def advanced_tool(ctx: Context) -> str:
     return f"Server: {server_name}"
 ```
 
-#### Accessing HTTP Requests
+#### HTTP Requests
 
 <VersionBadge version="2.2.7" />
 
+<Warning>
+The `ctx.get_http_request()` method is deprecated and will be removed in a future version.
+Please use the `get_http_request()` dependency function instead.
+See the [HTTP Requests pattern](/patterns/http-requests) for more details.
+</Warning>
+
 For web applications, you can access the underlying HTTP request:
 
 ```python
@@ -299,66 +346,7 @@ async def handle_web_request(ctx: Context) -> dict:
 - **`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.
 </Warning>
-
-## Using Context in Different Components
-
-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.