fastmcp 2.3.0rc1__tar.gz → 2.3.2__tar.gz

{fastmcp-2.3.0rc1 → fastmcp-2.3.2}/.github/workflows/run-tests.yml

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastmcp
-Version: 2.3.0rc1
+Version: 2.3.2
 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
+Requires-Dist: mcp<2.0.0,>=1.8.0
 Requires-Dist: openapi-pydantic>=0.5.1
 Requires-Dist: python-dotenv>=1.1.0
 Requires-Dist: rich>=13.9.4
@@ -44,7 +44,7 @@ Description-Content-Type: text/markdown
 > [!NOTE]
 > #### FastMCP 2.0 & The Official MCP SDK
 >
-> Recognize the `FastMCP` name? You might have used the version integrated into the [official MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk), which was based on **FastMCP 1.0**.
+> Recognize the `FastMCP` name? You might have seen the version that was contributed to the [official MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk), which was based on **FastMCP 1.0**.
 >
 > **Welcome to FastMCP 2.0!** This is the actively developed successor, and it significantly expands on 1.0 by introducing powerful client capabilities, server proxying & composition, OpenAPI/FastAPI integration, and more advanced features.
 >
@@ -76,7 +76,13 @@ fastmcp run server.py
 
 ### 📚 Documentation
 
-This readme provides only a high-level overview. For detailed guides, API references, and advanced patterns, please refer to the complete FastMCP documentation at **[gofastmcp.com](https://gofastmcp.com)**.
+FastMCP's complete documentation is available at **[gofastmcp.com](https://gofastmcp.com)**, including detailed guides, API references, and advanced patterns. This readme provides only a high-level overview.
+
+Documentation is also available in [llms.txt format](https://llmstxt.org/), which is a simple markdown standard that LLMs can consume easily. 
+
+There are two ways to access the LLM-friendly documentation:
+- [`llms.txt`](https://gofastmcp.com/llms.txt) is essentially a sitemap, listing all the pages in the documentation.
+- [`llms-full.txt`](https://gofastmcp.com/llms-full.txt) contains the entire documentation. Note this may exceed the context window of your LLM.
 
 ---
 
@@ -302,50 +308,40 @@ Learn more: [**OpenAPI Integration**](https://gofastmcp.com/patterns/openapi) |
 
 ## Running Your Server
 
-You can run your FastMCP server in several ways:
-
-1.  **Development (`fastmcp dev`)**: Recommended for building and testing. Provides an interactive testing environment with the MCP Inspector.
-    ```bash
-    fastmcp dev server.py
-    # Optionally add temporary dependencies
-    fastmcp dev server.py --with pandas numpy
-    ```
-
-2. **FastMCP CLI**: Run your server with the FastMCP CLI. This can autodetect and load your server object and run it with any transport configuration you want. 
-    ```bash
-    fastmcp run path/to/server.py:server_object
-
-    # Run as SSE on port 4200
-    fastmcp run path/to/server.py:server_object --transport sse --port 4200
-    ```
-    FastMCP will auto-detect the server object if it's named `mcp`, `app`, or `server`. In these cases, you can omit the `:server_object` part unless you need to select a specific object.
-
-3.  **Direct Execution**: For maximum compatibility with the MCP ecosystem, you can run your server directly as part of a Python script. You will typically do this within an `if __name__ == "__main__":` block in your script:
-    ```python
-    # Add this to server.py
-    if __name__ == "__main__":
-        # Default: runs stdio transport
-        mcp.run()
-
-        # Example: Run with SSE transport on a specific port
-        mcp.run(transport="sse", host="127.0.0.1", port=9000)
-    ```
-    Run your script:
-    ```bash
-    python server.py
-    # or using uv to manage the environment
-    uv run python server.py
-    ```
-4.  **Claude Desktop Integration (`fastmcp install`)**: The easiest way to make your server persistently available in the Claude Desktop app. It handles creating an isolated environment using `uv`.
-    ```bash
-    fastmcp install server.py --name "My Analysis Tool"
-    # Optionally add dependencies and environment variables
-    fastmcp install server.py --with requests -v API_KEY=123 -f .env
-    ```
-
-
-See the [**Server Documentation**](https://gofastmcp.com/servers/fastmcp#running-the-server) for more details on transports and configuration.
+The main way to run a FastMCP server is by calling the `run()` method on your server instance:
+
+```python
+# server.py
+from fastmcp import FastMCP
+
+mcp = FastMCP("Demo 🚀")
+
+@mcp.tool()
+def hello(name: str) -> str:
+    return f"Hello, {name}!"
+
+if __name__ == "__main__":
+    mcp.run()  # Default: uses STDIO transport
+```
+
+FastMCP supports three transport protocols:
+
+**STDIO (Default)**: Best for local tools and command-line scripts.
+```python
+mcp.run(transport="stdio")  # Default, so transport argument is optional
+```
+
+**Streamable HTTP**: Recommended for web deployments.
+```python
+mcp.run(transport="streamable-http", host="127.0.0.1", port=8000, path="/mcp")
+```
+
+**SSE**: For compatibility with existing SSE clients.
+```python
+mcp.run(transport="sse", host="127.0.0.1", port=8000)
+```
 
+See the [**Running Server Documentation**](https://gofastmcp.com/deployment/running-server) for more details.
 
 ## Contributing
 

{fastmcp-2.3.0rc1 → fastmcp-2.3.2}/README.md

@@ -15,7 +15,7 @@
 > [!NOTE]
 > #### FastMCP 2.0 & The Official MCP SDK
 >
-> Recognize the `FastMCP` name? You might have used the version integrated into the [official MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk), which was based on **FastMCP 1.0**.
+> Recognize the `FastMCP` name? You might have seen the version that was contributed to the [official MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk), which was based on **FastMCP 1.0**.
 >
 > **Welcome to FastMCP 2.0!** This is the actively developed successor, and it significantly expands on 1.0 by introducing powerful client capabilities, server proxying & composition, OpenAPI/FastAPI integration, and more advanced features.
 >
@@ -47,7 +47,13 @@ fastmcp run server.py
 
 ### 📚 Documentation
 
-This readme provides only a high-level overview. For detailed guides, API references, and advanced patterns, please refer to the complete FastMCP documentation at **[gofastmcp.com](https://gofastmcp.com)**.
+FastMCP's complete documentation is available at **[gofastmcp.com](https://gofastmcp.com)**, including detailed guides, API references, and advanced patterns. This readme provides only a high-level overview.
+
+Documentation is also available in [llms.txt format](https://llmstxt.org/), which is a simple markdown standard that LLMs can consume easily. 
+
+There are two ways to access the LLM-friendly documentation:
+- [`llms.txt`](https://gofastmcp.com/llms.txt) is essentially a sitemap, listing all the pages in the documentation.
+- [`llms-full.txt`](https://gofastmcp.com/llms-full.txt) contains the entire documentation. Note this may exceed the context window of your LLM.
 
 ---
 
@@ -273,50 +279,40 @@ Learn more: [**OpenAPI Integration**](https://gofastmcp.com/patterns/openapi) |
 
 ## Running Your Server
 
-You can run your FastMCP server in several ways:
-
-1.  **Development (`fastmcp dev`)**: Recommended for building and testing. Provides an interactive testing environment with the MCP Inspector.
-    ```bash
-    fastmcp dev server.py
-    # Optionally add temporary dependencies
-    fastmcp dev server.py --with pandas numpy
-    ```
-
-2. **FastMCP CLI**: Run your server with the FastMCP CLI. This can autodetect and load your server object and run it with any transport configuration you want. 
-    ```bash
-    fastmcp run path/to/server.py:server_object
-
-    # Run as SSE on port 4200
-    fastmcp run path/to/server.py:server_object --transport sse --port 4200
-    ```
-    FastMCP will auto-detect the server object if it's named `mcp`, `app`, or `server`. In these cases, you can omit the `:server_object` part unless you need to select a specific object.
-
-3.  **Direct Execution**: For maximum compatibility with the MCP ecosystem, you can run your server directly as part of a Python script. You will typically do this within an `if __name__ == "__main__":` block in your script:
-    ```python
-    # Add this to server.py
-    if __name__ == "__main__":
-        # Default: runs stdio transport
-        mcp.run()
-
-        # Example: Run with SSE transport on a specific port
-        mcp.run(transport="sse", host="127.0.0.1", port=9000)
-    ```
-    Run your script:
-    ```bash
-    python server.py
-    # or using uv to manage the environment
-    uv run python server.py
-    ```
-4.  **Claude Desktop Integration (`fastmcp install`)**: The easiest way to make your server persistently available in the Claude Desktop app. It handles creating an isolated environment using `uv`.
-    ```bash
-    fastmcp install server.py --name "My Analysis Tool"
-    # Optionally add dependencies and environment variables
-    fastmcp install server.py --with requests -v API_KEY=123 -f .env
-    ```
-
-
-See the [**Server Documentation**](https://gofastmcp.com/servers/fastmcp#running-the-server) for more details on transports and configuration.
+The main way to run a FastMCP server is by calling the `run()` method on your server instance:
+
+```python
+# server.py
+from fastmcp import FastMCP
+
+mcp = FastMCP("Demo 🚀")
+
+@mcp.tool()
+def hello(name: str) -> str:
+    return f"Hello, {name}!"
+
+if __name__ == "__main__":
+    mcp.run()  # Default: uses STDIO transport
+```
+
+FastMCP supports three transport protocols:
+
+**STDIO (Default)**: Best for local tools and command-line scripts.
+```python
+mcp.run(transport="stdio")  # Default, so transport argument is optional
+```
+
+**Streamable HTTP**: Recommended for web deployments.
+```python
+mcp.run(transport="streamable-http", host="127.0.0.1", port=8000, path="/mcp")
+```
+
+**SSE**: For compatibility with existing SSE clients.
+```python
+mcp.run(transport="sse", host="127.0.0.1", port=8000)
+```
 
+See the [**Running Server Documentation**](https://gofastmcp.com/deployment/running-server) for more details.
 
 ## Contributing
 

{fastmcp-2.3.0rc1 → fastmcp-2.3.2}/docs/clients/transports.mdx

@@ -14,6 +14,69 @@ The FastMCP `Client` relies on a `ClientTransport` object to handle the specific
 While the `Client` often infers the correct transport automatically (see [Client Overview](/clients/client#transport-inference)), you can also instantiate transports explicitly for more control.
 
 
+## Network Transports
+
+These transports connect to servers running over a network, typically long-running services accessible via URLs.
+
+### Streamable HTTP
+
+<VersionBadge version="2.3.0" />
+
+*   **Class:** `fastmcp.client.transports.StreamableHttpTransport`
+*   **Inferred From:** `http://` or `https://` URLs (default for HTTP URLs as of v2.3.0)
+*   **Use Case:** Connecting to persistent MCP servers exposed over HTTP/S using FastMCP's `mcp.run(transport="streamable-http")` mode.
+
+Streamable HTTP is the recommended transport for web-based deployments, providing efficient bidirectional communication over HTTP.
+
+```python
+from fastmcp import Client
+from fastmcp.client.transports import StreamableHttpTransport
+
+http_url = "http://localhost:8000/mcp"
+
+# Option 1: Inferred transport (default for HTTP URLs)
+client_inferred = Client(http_url)
+
+# Option 2: Explicit transport (e.g., to add custom headers)
+headers = {"Authorization": "Bearer mytoken"}
+transport_explicit = StreamableHttpTransport(url=http_url, headers=headers)
+client_explicit = Client(transport_explicit)
+
+async def use_streamable_http_client(client):
+    async with client:
+        tools = await client.list_tools()
+        print(f"Connected via Streamable HTTP, found tools: {tools}")
+
+# asyncio.run(use_streamable_http_client(client_inferred))
+# asyncio.run(use_streamable_http_client(client_explicit))
+```
+
+### SSE (Server-Sent Events)
+
+*   **Class:** `fastmcp.client.transports.SSETransport`
+*   **Inferred From:** Not automatically inferred for most HTTP URLs (as of v2.3.0)
+*   **Use Case:** Connecting to MCP servers using Server-Sent Events, often using FastMCP's `mcp.run(transport="sse")` mode.
+
+While SSE is still supported, Streamable HTTP is the recommended transport for new web-based deployments.
+
+```python
+from fastmcp import Client
+from fastmcp.client.transports import SSETransport
+
+sse_url = "http://localhost:8000/sse"
+
+# Since v2.3.0, HTTP URLs default to StreamableHttpTransport,
+# so you must explicitly use SSETransport for SSE connections
+transport_explicit = SSETransport(url=sse_url)
+client_explicit = Client(transport_explicit)
+
+async def use_sse_client(client):
+    async with client:
+        tools = await client.list_tools()
+        print(f"Connected via SSE, found tools: {tools}")
+
+# asyncio.run(use_sse_client(client_explicit))
+```
 ## Stdio Transports
 
 These transports manage an MCP server running as a subprocess, communicating with it via standard input (stdin) and standard output (stdout). This is the standard mechanism used by clients like Claude Desktop.
@@ -133,70 +196,6 @@ client = Client(transport)
 # async with client:
 #     response = await client.call_tool("get_npm_data", {})
 ```
-## Network Transports
-
-These transports connect to servers running over a network, typically long-running services accessible via URLs.
-
-### SSE (Server-Sent Events)
-
-*   **Class:** `fastmcp.client.transports.SSETransport`
-*   **Inferred From:** `http://` or `https://` URLs
-*   **Use Case:** Connecting to persistent MCP servers exposed over HTTP/S, often using FastMCP's `mcp.run(transport="sse")` mode.
-
-SSE is a simple, unidirectional protocol where the server pushes messages to the client over a standard HTTP connection.
-
-```python
-from fastmcp import Client
-from fastmcp.client.transports import SSETransport
-
-sse_url = "http://localhost:8000/sse"
-
-# Option 1: Inferred transport
-client_inferred = Client(sse_url)
-
-# Option 2: Explicit transport (e.g., to add custom headers)
-headers = {"Authorization": "Bearer mytoken"}
-transport_explicit = SSETransport(url=sse_url, headers=headers)
-client_explicit = Client(transport_explicit)
-
-async def use_sse_client(client):
-    async with client:
-        tools = await client.list_tools()
-        print(f"Connected via SSE, found tools: {tools}")
-
-# asyncio.run(use_sse_client(client_inferred))
-# asyncio.run(use_sse_client(client_explicit))
-```
-
-### WebSocket
-
-*   **Class:** `fastmcp.client.transports.WSTransport`
-*   **Inferred From:** `ws://` or `wss://` URLs
-*   **Use Case:** Connecting to MCP servers using the WebSocket protocol for bidirectional communication.
-
-WebSockets provide a persistent, full-duplex connection between client and server.
-
-```python
-from fastmcp import Client
-from fastmcp.client.transports import WSTransport
-
-ws_url = "ws://localhost:9000"
-
-# Option 1: Inferred transport
-client_inferred = Client(ws_url)
-
-# Option 2: Explicit transport
-transport_explicit = WSTransport(url=ws_url)
-client_explicit = Client(transport_explicit)
-
-async def use_ws_client(client):
-    async with client:
-        tools = await client.list_tools()
-        print(f"Connected via WebSocket, found tools: {tools}")
-
-# asyncio.run(use_ws_client(client_inferred))
-# asyncio.run(use_ws_client(client_explicit))
-```
 
 ## In-Memory Transports
 
@@ -240,6 +239,6 @@ Communication happens through efficient in-memory queues, making it very fast.
 ## Choosing a Transport
 
 *   **Local Development/Testing:** Use `PythonStdioTransport` (inferred from `.py` files) or `FastMCPTransport` (for same-process testing).
-*   **Connecting to Remote/Persistent Servers:** Use `SSETransport` (for `http/s`) or `WSTransport` (for `ws/s`).
+*   **Connecting to Remote/Persistent Servers:** Use `StreamableHttpTransport` (recommended, default for HTTP URLs) or `SSETransport` (legacy option).
 *   **Running Packaged Tools:** Use `UvxStdioTransport` (Python/uv) or `NpxStdioTransport` (Node/npm) if you need to run MCP servers without local installation.
 *   **Integrating with Claude Desktop (or similar):** These tools typically expect to run a Python script, so your server should be runnable via `python your_server.py`, making `PythonStdioTransport` the relevant mechanism on the client side. 

fastmcp-2.3.2/docs/deployment/asgi.mdx

@@ -0,0 +1,211 @@
+---
+title: Integrating FastMCP in ASGI Applications
+sidebarTitle: ASGI Integration
+description: Integrate FastMCP servers into existing Starlette, FastAPI, or other ASGI applications
+icon: plug
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+
+While FastMCP provides standalone server capabilities, you can also integrate your FastMCP server into existing web applications. This approach is useful for:
+
+- Adding MCP functionality to an existing website or API
+- Mounting MCP servers under specific URL paths
+- Combining multiple services in a single application
+- Leveraging existing authentication and middleware
+
+Please note that all FastMCP servers have a `run()` method that can be used to start the server. This guide focuses on integration with broader ASGI frameworks.
+
+## ASGI Server
+
+FastMCP servers can be created as [Starlette](https://www.starlette.io/) ASGI apps for straightforward hosting or integration into existing applications.
+
+The first step is to obtain a Starlette application instance from your FastMCP server using the `http_app()` method:
+
+<Tip>
+The `http_app()` method is new in FastMCP 2.3.2. In older versions, use `sse_app()` for SSE transport or `streamable_http_app()` for Streamable HTTP transport.
+</Tip>
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP("MyServer")
+
+@mcp.tool()
+def hello(name: str) -> str:
+    return f"Hello, {name}!"
+
+# Get a Starlette app instance for Streamable HTTP transport (recommended)
+http_app = mcp.http_app()
+
+# For legacy SSE transport (deprecated)
+sse_app = mcp.http_app(transport="sse")
+```
+
+Both approaches return a Starlette application that can be integrated with other ASGI-compatible web frameworks. 
+
+The MCP server's endpoint is mounted at the root path `/mcp` for Streamable HTTP transport, and `/sse` for SSE transport, though you can change these paths by passing a `path` argument to the `http_app()` method:
+
+```python
+# For Streamable HTTP transport
+http_app = mcp.http_app(path="/custom-mcp-path")
+
+# For SSE transport (deprecated)
+sse_app = mcp.http_app(path="/custom-sse-path", transport="sse")
+```
+
+### Running the Server
+
+To run the FastMCP server, you can use the `uvicorn` ASGI server:
+
+```python
+from fastmcp import FastMCP
+import uvicorn
+
+mcp = FastMCP("MyServer")
+
+http_app = mcp.http_app()
+
+if __name__ == "__main__":
+    uvicorn.run(http_app, host="0.0.0.0", port=8000)
+```
+
+Or, from the command line:
+
+```bash
+uvicorn path.to.your.app:http_app --host 0.0.0.0 --port 8000
+```
+
+### Custom Middleware
+
+<VersionBadge version="2.3.2" />
+
+You can add custom Starlette middleware to your FastMCP ASGI apps by passing a list of middleware instances to the app creation methods:
+
+```python
+from fastmcp import FastMCP
+from starlette.middleware import Middleware
+from starlette.middleware.cors import CORSMiddleware
+
+# Create your FastMCP server
+mcp = FastMCP("MyServer")
+
+# Define custom middleware
+custom_middleware = [
+    Middleware(CORSMiddleware, allow_origins=["*"]),
+]
+
+# Create ASGI app with custom middleware
+http_app = mcp.http_app(middleware=custom_middleware)
+```
+
+
+## Starlette Integration
+
+<VersionBadge version="2.3.1" />
+
+You can mount your FastMCP server in another Starlette application:
+
+```python
+from fastmcp import FastMCP
+from starlette.applications import Starlette
+from starlette.routing import Mount
+
+# Create your FastMCP server as well as any tools, resources, etc.
+mcp = FastMCP("MyServer")
+
+# Create the ASGI app
+mcp_app = mcp.http_app(path='/mcp')
+
+# Create a Starlette app and mount the MCP server
+app = Starlette(
+    routes=[
+        Mount("/mcp-server", app=mcp_app),
+        # Add other routes as needed
+    ],
+    lifespan=mcp_app.router.lifespan_context,
+)
+```
+
+The MCP endpoint will be available at `/mcp-server/mcp` of the resulting Starlette app.
+
+<Warning>
+For Streamable HTTP transport, you **must** pass the lifespan context from the FastMCP app to the resulting Starlette app, as nested lifespans are not recognized. Otherwise, the FastMCP server's session manager will not be properly initialized.
+</Warning>
+
+### Nested Mounts
+
+
+You can create complex routing structures by nesting mounts:
+
+```python
+from fastmcp import FastMCP
+from starlette.applications import Starlette
+from starlette.routing import Mount
+
+# Create your FastMCP server as well as any tools, resources, etc.
+mcp = FastMCP("MyServer")
+
+# Create the ASGI app
+mcp_app = mcp.http_app(path='/mcp')
+
+# Create nested application structure
+inner_app = Starlette(routes=[Mount("/inner", app=mcp_app)])
+app = Starlette(
+    routes=[Mount("/outer", app=inner_app)],
+    lifespan=mcp_app.router.lifespan_context,
+)
+```
+
+In this setup, the MCP server is accessible at the `/outer/inner/mcp` path of the resulting Starlette app.
+
+<Warning>
+For Streamable HTTP transport, you **must** pass the lifespan context from the FastMCP app to the *outer* Starlette app, as nested lifespans are not recognized. Otherwise, the FastMCP server's session manager will not be properly initialized.
+</Warning>
+## FastAPI Integration
+
+<VersionBadge version="2.3.1" />
+
+FastAPI is built on Starlette, so you can mount your FastMCP server in a similar way:
+
+```python
+from fastmcp import FastMCP
+from fastapi import FastAPI
+from starlette.routing import Mount
+
+# Create your FastMCP server as well as any tools, resources, etc.
+mcp = FastMCP("MyServer")
+
+# Create the ASGI app
+mcp_app = mcp.http_app(path='/mcp')
+
+# Create a FastAPI app and mount the MCP server
+app = FastAPI(lifespan=mcp_app.router.lifespan_context)
+app.mount("/mcp-server", mcp_app)
+```
+
+The MCP endpoint will be available at `/mcp-server/mcp` of the resulting FastAPI app.
+
+<Warning>
+For Streamable HTTP transport, you **must** pass the lifespan context from the FastMCP app to the resulting FastAPI app, as nested lifespans are not recognized. Otherwise, the FastMCP server's session manager will not be properly initialized.
+</Warning>
+
+
+## Custom Routes
+
+In addition to adding your FastMCP server to an existing ASGI app, you can also add custom web routes to your FastMCP server, which will be exposed alongside the MCP endpoint. To do so, use the `@custom_route` decorator. Note that this is less flexible than using a full ASGI framework, but can be useful for adding simple endpoints like health checks to your standalone server.
+
+```python
+from fastmcp import FastMCP
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+mcp = FastMCP("MyServer")
+
+@mcp.custom_route("/health", methods=["GET"])
+async def health_check(request: Request) -> JSONResponse:
+    return JSONResponse({"status": "healthy"})
+```
+
+These routes will be included in the FastMCP app when mounted in your web application.