fastmcp 2.10.4__tar.gz → 2.10.5__tar.gz

{fastmcp-2.10.4 → fastmcp-2.10.5}/.github/labeler.yml

@@ -27,3 +27,7 @@ tests:
   - changed-files:
       - any-glob-to-any-file:
           - "src/**/*openapi*.py"
+          - "src/**/openapi/**"
+          - "tests/**/*openapi*.py"
+          - "tests/**/openapi/**"
+          - "docs/**/*openapi*"

{fastmcp-2.10.4 → fastmcp-2.10.5}/.github/workflows/run-tests.yml

@@ -48,3 +48,5 @@ jobs:
 
       - name: Run tests
         run: uv run pytest tests
+        env:
+          FASTMCP_GITHUB_TOKEN: ${{ secrets.FASTMCP_GITHUB_TOKEN }}

{fastmcp-2.10.4 → fastmcp-2.10.5}/.gitignore

@@ -60,3 +60,6 @@ dmypy.json
 *.sqlite
 *.db
 *.ddb
+
+# Claude worktree management
+.claude-wt/worktrees

{fastmcp-2.10.4 → fastmcp-2.10.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastmcp
-Version: 2.10.4
+Version: 2.10.5
 Summary: The fast, Pythonic way to build MCP servers and clients.
 Project-URL: Homepage, https://gofastmcp.com
 Project-URL: Repository, https://github.com/jlowin/fastmcp

fastmcp-2.10.5/README_OPENAPI.md

@@ -0,0 +1,246 @@
+# FastMCP OpenAPI Integration
+
+This document explains how FastMCP's OpenAPI integration works, what features are supported, and how to extend it. The OpenAPI functionality is split across two main files:
+
+- `server/openapi.py` - High-level FastMCP server implementation and MCP component creation
+- `utilities/openapi.py` - Low-level OpenAPI parsing and intermediate representation
+
+## Architecture Overview
+
+```
+OpenAPI Spec → Parse → HTTPRoute IR → Create MCP Components → FastMCP Server
+```
+
+### 1. Parsing Phase (`utilities/openapi.py`)
+
+OpenAPI specifications are parsed into an intermediate representation (IR) that normalizes differences between OpenAPI 3.0 and 3.1:
+
+- **Input**: Raw OpenAPI spec (dict)
+- **Output**: List of `HTTPRoute` objects with normalized parameter information
+- **Key Classes**: 
+  - `HTTPRoute` - Represents a single operation
+  - `ParameterInfo` - Represents a parameter with location, style, explode, etc.
+  - `RequestBodyInfo` - Represents request body information
+  - `ResponseInfo` - Represents response information
+
+### 2. Component Creation Phase (`server/openapi.py`)
+
+HTTPRoute objects are converted into FastMCP components based on route mapping rules:
+
+- **Tools** (`OpenAPITool`) - HTTP operations that can be called
+- **Resources** (`OpenAPIResource`) - HTTP endpoints that return data
+- **Resource Templates** (`OpenAPIResourceTemplate`) - Parameterized resources
+
+## Parameter Handling
+
+FastMCP supports various OpenAPI parameter serialization styles and formats:
+
+### Supported Parameter Locations
+- `query` - Query string parameters
+- `path` - Path parameters  
+- `header` - HTTP headers
+- `cookie` - Cookie parameters (parsed but not used in requests)
+
+### Supported Parameter Styles
+
+#### Query Parameters
+- **`form`** (default) - Standard query parameter format
+  - `explode=true` (default): `?tags=red&tags=blue`
+  - `explode=false`: `?tags=red,blue`
+- **`deepObject`** - Object parameters with bracket notation
+  - `explode=true`: `?filter[name]=John&filter[age]=30`
+  - `explode=false`: Falls back to JSON string (non-standard, logs warning)
+
+#### Path Parameters  
+- **`simple`** (default) - Comma-separated for arrays: `/users/1,2,3`
+
+#### Header Parameters
+- **`simple`** (default) - Standard header format
+
+### Parameter Type Support
+
+#### Arrays
+- String arrays with `explode=true/false`
+- Number arrays with `explode=true/false` 
+- Boolean arrays with `explode=true/false`
+- Complex object arrays (basic support, may not handle all cases)
+
+#### Objects
+- Objects with `deepObject` style and `explode=true`
+- Objects with other styles fall back to JSON serialization
+
+#### Primitives
+- Strings, numbers, booleans
+- Enums
+- Default values
+
+## Request Body Handling
+
+### Supported Content Types
+- `application/json` - JSON request bodies
+
+### Schema Support
+- Object schemas with properties
+- Array schemas
+- Primitive schemas
+- Schema references (`$ref` to local schemas only)
+- Required properties
+- Default values
+
+## Response Handling  
+
+### Content Type Detection
+- `application/json` - Parsed as JSON
+- `text/*` - Returned as text
+- `application/xml` - Returned as text
+- Other types - Returned as binary
+
+### Output Schema Generation
+- Success response schemas (200, 201, 202, 204)
+- Object response wrapping for MCP compliance
+- Schema compression (removes unused `$defs`)
+
+## Route Mapping
+
+Routes are mapped to MCP component types using `RouteMap` configurations:
+
+```python
+RouteMap(
+    methods=["GET", "POST"],           # HTTP methods to match
+    pattern=r"/api/users/.*",          # Regex pattern for path
+    mcp_type=MCPType.RESOURCE_TEMPLATE, # Target component type
+    tags={"user"},                     # OpenAPI tags to match (AND condition)
+    mcp_tags={"fastmcp-user"}         # Tags to add to created components
+)
+```
+
+### Default Behavior
+- All routes become **Tools** by default
+- Use route maps to override specific patterns
+
+### Component Types
+- `MCPType.TOOL` - Callable operations
+- `MCPType.RESOURCE` - Static data endpoints  
+- `MCPType.RESOURCE_TEMPLATE` - Parameterized data endpoints
+- `MCPType.EXCLUDE` - Skip route entirely
+
+## Known Limitations & Edge Cases
+
+### Parameter Edge Cases
+1. **Parameter Name Collisions** - When path/query parameters have same names as request body properties, non-body parameters get `__location` suffixes
+2. **Complex Array Serialization** - Limited support for arrays containing objects
+3. **Cookie Parameters** - Parsed but not used in requests
+4. **Non-standard Combinations** - e.g., `deepObject` with `explode=false`
+
+### Request Body Edge Cases  
+1. **Content Type Priority** - Only first available content type is used
+2. **Nested Objects** - Deep nesting may not serialize correctly
+3. **Binary Content** - No support for file uploads or binary data
+
+### Response Edge Cases
+1. **Multiple Content Types** - Only JSON-compatible types are used for output schemas
+2. **Error Responses** - Not used for MCP output schema generation
+3. **Response Headers** - Not captured or exposed
+
+### Schema Edge Cases
+1. **External References** - `$ref` to external files not supported
+2. **Circular References** - May cause issues in schema processing
+3. **Polymorphism** - `oneOf`/`anyOf`/`allOf` limited support
+
+## Debugging Tips
+
+### Common Issues
+1. **"Unknown tool/resource"** - Check route mapping configuration
+2. **Parameter not found** - Check for name collisions or incorrect style/explode
+3. **Invalid request format** - Check parameter serialization and content types
+4. **Schema validation errors** - Check for external refs or complex schemas
+
+### Debugging Tools
+```python
+# Parse routes to inspect intermediate representation
+routes = parse_openapi_to_http_routes(openapi_spec)
+for route in routes:
+    print(f"{route.method} {route.path}")
+    for param in route.parameters:
+        print(f"  {param.name} ({param.location}): style={param.style}, explode={param.explode}")
+
+# Check component creation
+server = FastMCP.from_openapi(openapi_spec, client)
+tools = await server.get_tools()
+print(f"Created {len(tools)} tools: {list(tools.keys())}")
+```
+
+### Logging
+- Set `FASTMCP_LOG_LEVEL=DEBUG` to see detailed parameter processing
+- Look for warnings about non-standard parameter combinations
+- Check for schema parsing errors in logs
+
+## Extension Points
+
+### Adding New Parameter Styles
+1. Add style handling in `utilities/openapi.py` - `ParameterInfo` class
+2. Implement serialization logic in `server/openapi.py` - `OpenAPITool.run()`
+3. Add tests for parsing and serialization
+
+### Adding New Content Types
+1. Extend request body handling in `OpenAPITool.run()`  
+2. Add response parsing logic for new types
+3. Update content type priority in utilities
+
+### Custom Route Mapping
+Use `route_map_fn` for complex routing logic:
+
+```python
+def custom_mapper(route: HTTPRoute, current_type: MCPType) -> MCPType:
+    if route.path.startswith("/admin"):
+        return MCPType.EXCLUDE
+    return current_type
+
+server = FastMCP.from_openapi(spec, client, route_map_fn=custom_mapper)
+```
+
+## Testing Patterns
+
+### Unit Tests
+- Test parameter parsing with various styles/explode combinations
+- Test route mapping with different patterns and tags
+- Test schema generation and compression
+
+### Integration Tests  
+- Mock HTTP client to verify actual request parameters
+- Test end-to-end component creation and execution
+- Test error handling and edge cases
+
+### Example Test Pattern
+```python
+async def test_parameter_style():
+    # 1. Create OpenAPI spec with specific parameter configuration
+    spec = {"openapi": "3.1.0", ...}
+    
+    # 2. Parse and create components
+    routes = parse_openapi_to_http_routes(spec)
+    tool = OpenAPITool(mock_client, routes[0], ...)
+    
+    # 3. Execute and verify request parameters
+    await tool.run({"param": "value"})
+    actual_params = mock_client.request.call_args.kwargs["params"]
+    assert actual_params == expected_params
+```
+
+## Testing
+
+OpenAPI functionality is tested across multiple files in `tests/server/openapi/`:
+
+- `test_basic_functionality.py` - Core component creation and execution
+- `test_explode_integration.py` - Parameter explode behavior  
+- `test_deepobject_style.py` - DeepObject style parameter encoding
+- `test_parameter_collisions.py` - Parameter name collision handling
+- `test_openapi_path_parameters.py` - Path parameter serialization
+- `test_configuration.py` - Route mapping and MCP names
+- `test_description_propagation.py` - Schema and description handling
+
+When adding new OpenAPI features, create focused test files rather than adding to existing monolithic files.
+
+---
+
+*This document should be updated when new OpenAPI features are added or when edge cases are discovered and addressed.*

fastmcp-2.10.5/docs/clients/transports.mdx

@@ -0,0 +1,310 @@
+---
+title: Client Transports
+sidebarTitle: Transports
+description: Configure how FastMCP Clients connect to and communicate with servers.
+icon: link
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+
+<VersionBadge version="2.0.0" />
+
+The FastMCP `Client` communicates with MCP servers through transport objects that handle the underlying connection mechanics. While the client can automatically select a transport based on what you pass to it, instantiating transports explicitly gives you full control over configuration—environment variables, authentication, session management, and more.
+
+Think of transports as configurable adapters between your client code and MCP servers. Each transport type handles a different communication pattern: subprocesses with pipes, HTTP connections, or direct in-memory calls.
+
+## Choosing the Right Transport
+
+- **Use [STDIO Transport](#stdio-transport)** when you need to run local MCP servers with full control over their environment and lifecycle
+- **Use [Remote Transports](#remote-transports)** when connecting to production services or shared MCP servers running independently  
+- **Use [In-Memory Transport](#in-memory-transport)** for testing FastMCP servers without subprocess or network overhead
+- **Use [MCP JSON Configuration](#mcp-json-configuration-transport)** when you need to connect to multiple servers defined in configuration files
+
+## STDIO Transport
+
+STDIO (Standard Input/Output) transport communicates with MCP servers through subprocess pipes. This is the standard mechanism used by desktop clients like Claude Desktop and is the primary way to run local MCP servers.
+
+### The Client Runs the Server
+
+<Warning>
+**Critical Concept**: When using STDIO transport, your client actually launches and manages the server process. This is fundamentally different from network transports where you connect to an already-running server. Understanding this relationship is key to using STDIO effectively.
+</Warning>
+
+With STDIO transport, your client:
+- Starts the server as a subprocess when you connect
+- Manages the server's lifecycle (start, stop, restart)
+- Controls the server's environment and configuration
+- Communicates through stdin/stdout pipes
+
+This architecture enables powerful local integrations but requires understanding environment isolation and process management.
+
+### Environment Isolation
+
+STDIO servers run in isolated environments by default. This is a security feature enforced by the MCP protocol to prevent accidental exposure of sensitive data.
+
+When your client launches an MCP server:
+- The server does NOT inherit your shell's environment variables
+- API keys, paths, and other configuration must be explicitly passed
+- The working directory and system paths may differ from your shell
+
+To pass environment variables to your server, use the `env` parameter:
+
+```python
+from fastmcp import Client
+
+# If your server needs environment variables (like API keys),
+# you must explicitly pass them:
+client = Client(
+    "my_server.py",
+    env={"API_KEY": "secret", "DEBUG": "true"}
+)
+
+# This won't work - the server runs in isolation:
+# export API_KEY="secret"  # in your shell
+# client = Client("my_server.py")  # server can't see API_KEY
+```
+
+### Basic Usage
+
+To use STDIO transport, you create a transport instance with the command and arguments needed to run your server:
+
+```python
+from fastmcp.client.transports import StdioTransport
+
+transport = StdioTransport(
+    command="python",
+    args=["my_server.py"]
+)
+client = Client(transport)
+```
+
+You can configure additional settings like environment variables, working directory, or command arguments:
+
+```python
+transport = StdioTransport(
+    command="python",
+    args=["my_server.py", "--verbose"],
+    env={"LOG_LEVEL": "DEBUG"},
+    cwd="/path/to/server"
+)
+client = Client(transport)
+```
+
+For convenience, the client can also infer STDIO transport from file paths, but this doesn't allow configuration:
+
+```python
+from fastmcp import Client
+
+client = Client("my_server.py")  # Limited - no configuration options
+```
+
+### Environment Variables
+
+Since STDIO servers don't inherit your environment, you need strategies for passing configuration. Here are two common approaches:
+
+**Selective forwarding** passes only the variables your server actually needs:
+
+```python
+import os
+from fastmcp.client.transports import StdioTransport
+
+required_vars = ["API_KEY", "DATABASE_URL", "REDIS_HOST"]
+env = {
+    var: os.environ[var] 
+    for var in required_vars 
+    if var in os.environ
+}
+
+transport = StdioTransport(
+    command="python",
+    args=["server.py"],
+    env=env
+)
+client = Client(transport)
+```
+
+**Loading from .env files** keeps configuration separate from code:
+
+```python
+from dotenv import dotenv_values
+from fastmcp.client.transports import StdioTransport
+
+env = dotenv_values(".env")
+transport = StdioTransport(
+    command="python",
+    args=["server.py"],
+    env=env
+)
+client = Client(transport)
+```
+
+### Session Persistence
+
+STDIO transports maintain sessions across multiple client contexts by default (`keep_alive=True`). This improves performance by reusing the same subprocess for multiple connections, but can be controlled when you need isolation.
+
+By default, the subprocess persists between connections:
+
+```python
+from fastmcp.client.transports import StdioTransport
+
+transport = StdioTransport(
+    command="python",
+    args=["server.py"]
+)
+client = Client(transport)
+
+async def efficient_multiple_operations():
+    async with client:
+        await client.ping()
+    
+    async with client:  # Reuses the same subprocess
+        await client.call_tool("process_data", {"file": "data.csv"})
+```
+
+For complete isolation between connections, disable session persistence:
+
+```python
+transport = StdioTransport(
+    command="python",
+    args=["server.py"],
+    keep_alive=False
+)
+client = Client(transport)
+```
+
+Use `keep_alive=False` when you need complete isolation (e.g., in test suites) or when server state could cause issues between connections.
+
+### Specialized STDIO Transports
+
+FastMCP provides convenience transports that are thin wrappers around `StdioTransport` with pre-configured commands:
+
+- **`PythonStdioTransport`** - Uses `python` command for `.py` files
+- **`NodeStdioTransport`** - Uses `node` command for `.js` files  
+- **`UvxStdioTransport`** - Uses `uvx` for Python packages (uses `env_vars` parameter)
+- **`NpxStdioTransport`** - Uses `npx` for Node packages (uses `env_vars` parameter)
+
+For most use cases, instantiate `StdioTransport` directly with your desired command. These specialized transports are primarily useful for client inference shortcuts.
+
+## Remote Transports
+
+Remote transports connect to MCP servers running as web services. This is a fundamentally different model from STDIO transports—instead of your client launching and managing a server process, you connect to an already-running service that manages its own environment and lifecycle.
+
+### Streamable HTTP Transport
+
+<VersionBadge version="2.3.0" />
+
+Streamable HTTP is the recommended transport for production deployments, providing efficient bidirectional streaming over HTTP connections.
+
+- **Class:** `StreamableHttpTransport`
+- **Server compatibility:** FastMCP servers running with `mcp run --transport http`
+
+The transport requires a URL and optionally supports custom headers for authentication and configuration:
+
+```python
+from fastmcp.client.transports import StreamableHttpTransport
+
+# Basic connection
+transport = StreamableHttpTransport(url="https://api.example.com/mcp")
+client = Client(transport)
+
+# With custom headers for authentication
+transport = StreamableHttpTransport(
+    url="https://api.example.com/mcp",
+    headers={
+        "Authorization": "Bearer your-token-here",
+        "X-Custom-Header": "value"
+    }
+)
+client = Client(transport)
+```
+
+For convenience, FastMCP also provides authentication helpers:
+
+```python
+from fastmcp.client.auth import BearerAuth
+
+client = Client(
+    "https://api.example.com/mcp",
+    auth=BearerAuth("your-token-here")
+)
+```
+
+### SSE Transport (Legacy)
+
+Server-Sent Events transport is maintained for backward compatibility but is superseded by Streamable HTTP for new deployments.
+
+- **Class:** `SSETransport`  
+- **Server compatibility:** FastMCP servers running with `mcp run --transport sse`
+
+SSE transport supports the same configuration options as Streamable HTTP:
+
+```python
+from fastmcp.client.transports import SSETransport
+
+transport = SSETransport(
+    url="https://api.example.com/sse",
+    headers={"Authorization": "Bearer token"}
+)
+client = Client(transport)
+```
+
+Use Streamable HTTP for new deployments unless you have specific infrastructure requirements for SSE.
+
+## In-Memory Transport
+
+In-memory transport connects directly to a FastMCP server instance within the same Python process. This eliminates both subprocess management and network overhead, making it ideal for testing and development.
+
+- **Class:** `FastMCPTransport`
+
+<Note>
+Unlike STDIO transports, in-memory servers have full access to your Python process's environment. They share the same memory space and environment variables as your client code—no isolation or explicit environment passing required.
+</Note>
+
+```python
+from fastmcp import FastMCP, Client
+import os
+
+mcp = FastMCP("TestServer")
+
+@mcp.tool
+def greet(name: str) -> str:
+    prefix = os.environ.get("GREETING_PREFIX", "Hello")
+    return f"{prefix}, {name}!"
+
+client = Client(mcp)
+
+async with client:
+    result = await client.call_tool("greet", {"name": "World"})
+```
+
+## MCP JSON Configuration Transport
+
+<VersionBadge version="2.4.0" />
+
+This transport supports the emerging MCP JSON configuration standard for defining multiple servers:
+
+- **Class:** `MCPConfigTransport`
+
+```python
+config = {
+    "mcpServers": {
+        "weather": {
+            "url": "https://weather.example.com/mcp",
+            "transport": "http"
+        },
+        "assistant": {
+            "command": "python",
+            "args": ["./assistant.py"],
+            "env": {"LOG_LEVEL": "INFO"}
+        }
+    }
+}
+
+client = Client(config)
+
+async with client:
+    # Tools are namespaced by server
+    weather = await client.call_tool("weather_get_forecast", {"city": "NYC"})
+    answer = await client.call_tool("assistant_ask", {"question": "What?"})
+```
+

{fastmcp-2.10.4 → fastmcp-2.10.5}/docs/docs.json

@@ -62,7 +62,11 @@
               {
                 "group": "Servers",
                 "pages": [
-                  "servers/server",
+                  {
+                    "group": "Essentials",
+                    "icon": "cube",
+                    "pages": ["servers/server", "deployment/running-server"]
+                  },
                   {
                     "group": "Core Components",
                     "icon": "toolbox",
@@ -77,32 +81,30 @@
                     "icon": "stars",
                     "pages": [
                       "servers/context",
+                      "servers/proxy",
+                      "servers/composition",
                       "servers/elicitation",
                       "servers/logging",
                       "servers/progress",
-                      "servers/sampling"
+                      "servers/sampling",
+                      "servers/middleware"
                     ]
                   },
                   {
                     "group": "Authentication",
                     "icon": "shield-check",
                     "pages": ["servers/auth/bearer"]
-                  },
-                  "servers/middleware",
-                  "servers/openapi",
-                  "servers/proxy",
-                  "servers/composition",
-                  {
-                    "group": "Deployment",
-                    "icon": "upload",
-                    "pages": ["deployment/running-server", "deployment/asgi"]
                   }
                 ]
               },
               {
                 "group": "Clients",
                 "pages": [
-                  "clients/client",
+                  {
+                    "group": "Essentials",
+                    "icon": "cube",
+                    "pages": ["clients/client", "clients/transports"]
+                  },
                   {
                     "group": "Core Operations",
                     "icon": "handshake",
@@ -124,7 +126,6 @@
                       "clients/roots"
                     ]
                   },
-                  "clients/transports",
                   {
                     "group": "Authentication",
                     "icon": "user-shield",
@@ -141,9 +142,12 @@
                   "integrations/claude-desktop",
                   "integrations/cursor",
                   "integrations/eunomia-authorization",
+                  "integrations/fastapi",
                   "integrations/gemini",
                   "integrations/mcp-json-configuration",
-                  "integrations/openai"
+                  "integrations/openai",
+                  "integrations/openapi",
+                  "integrations/starlette"
                 ]
               },
               {