π The fast, Pythonic way to build MCP servers and clients.
add client docs
Jeremiah Lowin3707be070075
diff --git a/docs/clients/overview.mdx b/docs/clients/overview.mdxnew file mode 100644index 000000000..7f4212f08--- /dev/null+++ b/docs/clients/overview.mdx@@ -0,0 +1,252 @@+---+title: Client Overview+sidebarTitle: Overview+description: Learn how to use the FastMCP Client to interact with MCP servers.+icon: user-robot+---++The `fastmcp.Client` provides a high-level, asynchronous interface for interacting with any Model Context Protocol (MCP) server, whether it's built with FastMCP or another implementation. It simplifies communication by handling protocol details and connection management.++## FastMCP Client++The FastMCP Client architecture separates the protocol logic (`Client`) from the connection mechanism (`Transport`).++- **`Client`**: Handles sending MCP requests (like `tools/call`, `resources/read`), receiving responses, and managing callbacks.+- **`Transport`**: Responsible for establishing and maintaining the connection to the server (e.g., via WebSockets, SSE, Stdio, or in-memory).+++### Transports++Clients must be initialized with a `transport`. You can either provide an already instantiated transport object, or provide a transport source and let FastMCP attempt to infer the correct transport to use.++The following inference rules are used to determine the appropriate `ClientTransport` based on the input type:++1. **`ClientTransport` Instance**: If you provide an already instantiated transport object, it's used directly.+2. **`FastMCP` Instance**: Creates a `FastMCPTransport` for efficient in-memory communication (ideal for testing).+3. **`Path` or `str` pointing to an existing file**:+ * If it ends with `.py`: Creates a `PythonStdioTransport` to run the script using `python`.+ * If it ends with `.js`: Creates a `NodeStdioTransport` to run the script using `node`.+4. **`AnyUrl` or `str` pointing to a URL**:+ * If it starts with `http://` or `https://`: Creates an `SSETransport`.+ * If it starts with `ws://` or `wss://`: Creates a `WSTransport`.+5. **Other**: Raises a `ValueError` if the type cannot be inferred.++```python+import asyncio+from fastmcp import Client, FastMCP++# Example transports (more details in Transports page)+server_instance = FastMCP(name="TestServer") # In-memory server+sse_url = "http://localhost:8000/sse" # SSE server URL+ws_url = "ws://localhost:9000" # WebSocket server URL+server_script = "my_mcp_server.py" # Path to a Python server file++# Client automatically infers the transport type+client_in_memory = Client(server_instance)+client_sse = Client(sse_url)+client_ws = Client(ws_url)+client_stdio = Client(server_script)++print(client_in_memory.transport)+print(client_sse.transport)+print(client_ws.transport)+print(client_stdio.transport)++# Expected Output (types may vary slightly based on environment):+# <FastMCP(server='TestServer')>+# <SSE(url='http://localhost:8000/sse')>+# <WebSocket(url='ws://localhost:9000')>+# <PythonStdioTransport(command='python', args=['/path/to/your/my_mcp_server.py'])>+```+<Tip>+For more control over connection details (like headers for SSE, environment variables for Stdio), you can instantiate the specific `ClientTransport` class yourself and pass it to the `Client`. See the [Transports](/clients/transports) page for details.+</Tip>++## Client Usage++### Connection Lifecycle++The client operates asynchronously and must be used within an `async with` block. This context manager handles establishing the connection, initializing the MCP session, and cleaning up resources upon exit.++```python+import asyncio+from fastmcp import Client++client = Client("my_mcp_server.py") # Assumes my_mcp_server.py exists++async def main():+ # Connection is established here+ async with client:+ print(f"Client connected: {client.is_connected()}")++ # Make MCP calls within the context+ tools = await client.list_tools()+ print(f"Available tools: {tools}")++ if any(tool.name == "greet" for tool in tools):+ result = await client.call_tool("greet", {"name": "World"})+ print(f"Greet result: {result}")++ # Connection is closed automatically here+ print(f"Client connected: {client.is_connected()}")++if __name__ == "__main__":+ asyncio.run(main())+```++You can make multiple calls to the server within the same `async with` block using the established session.++### Client Methods++The `Client` provides methods corresponding to standard MCP requests:++#### Tool Operations++* **`list_tools()`**: Retrieves a list of tools available on the server.+ ```python+ tools = await client.list_tools()+ # tools -> list[mcp.types.Tool]+ ```+* **`call_tool(name: str, arguments: dict[str, Any] | None = None)`**: Executes a tool on the server.+ ```python+ result = await client.call_tool("add", {"a": 5, "b": 3})+ # result -> list[mcp.types.TextContent | mcp.types.ImageContent | ...]+ print(result[0].text) # Assuming TextContent, e.g., '8'+ ```+ * Arguments are passed as a dictionary. FastMCP servers automatically handle JSON string parsing for complex types if needed.+ * Returns a list of content objects (usually `TextContent` or `ImageContent`).++#### Resource Operations++* **`list_resources()`**: Retrieves a list of static resources.+ ```python+ resources = await client.list_resources()+ # resources -> list[mcp.types.Resource]+ ```+* **`list_resource_templates()`**: Retrieves a list of resource templates.+ ```python+ templates = await client.list_resource_templates()+ # templates -> list[mcp.types.ResourceTemplate]+ ```+* **`read_resource(uri: str | AnyUrl)`**: Reads the content of a resource or a resolved template.+ ```python+ # Read a static resource+ readme_content = await client.read_resource("file:///path/to/README.md")+ # readme_content -> list[mcp.types.TextResourceContents | mcp.types.BlobResourceContents]+ print(readme_content[0].text) # Assuming text++ # Read a resource generated from a template+ weather_content = await client.read_resource("data://weather/london")+ print(weather_content[0].text) # Assuming text JSON+ ```++#### Prompt Operations++* **`list_prompts()`**: Retrieves available prompt templates.+* **`get_prompt(name: str, arguments: dict[str, Any] | None = None)`**: Retrieves a rendered prompt message list.++### Callbacks++MCP allows servers to make requests *back* to the client for certain capabilities. The `Client` constructor accepts callback functions 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+ )++ # 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.++#### LLM Sampling++* **`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+ )+ ```+ See `fastmcp.client.sampling` for helpers.++#### 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++ def my_log_handler(level: LogLevel, message: str, logger_name: str | None):+ print(f"[Server Log - {level.upper()}] {logger_name or 'default'}: {message}")++ client_with_logging = Client(+ "my_server.py",+ log_handler=my_log_handler+ )+ ```+++### Error Handling++When a `call_tool` request results in an error on the server (e.g., the tool function raised an exception), the `client.call_tool()` method will raise a `fastmcp.client.ClientError`.++```python+async def safe_call_tool():+ async with client:+ try:+ # Assume 'divide' tool exists and might raise ZeroDivisionError+ result = await client.call_tool("divide", {"a": 10, "b": 0})+ print(f"Result: {result}")+ except ClientError as e:+ print(f"Tool call failed: {e}")+ except ConnectionError as e:+ print(f"Connection failed: {e}")+ except Exception as e:+ print(f"An unexpected error occurred: {e}")++# Example Output if division by zero occurs:+# Tool call failed: Division by zero is not allowed.+```++Other errors, like connection failures, will raise standard Python exceptions (e.g., `ConnectionError`, `TimeoutError`).++<Tip>+The client transport often has its own error-handling mechanisms, so you can not always trap errors like those raised by `call_tool` outside of the `async with` block. Instead, you can call `call_tools(..., return_raw_result=True)` to get the raw result object and handle errors yourself by checking its `isError` attribute.+</Tip>diff --git a/docs/clients/transports.mdx b/docs/clients/transports.mdxnew file mode 100644index 000000000..b86ca3d65--- /dev/null+++ b/docs/clients/transports.mdx@@ -0,0 +1,241 @@+---+title: Client Transports+sidebarTitle: Transports+description: Understand the different ways FastMCP Clients can connect to servers.+icon: link+---++The FastMCP `Client` relies on a `ClientTransport` object to handle the specifics of connecting to and communicating with an MCP server. FastMCP provides several built-in transport implementations for common connection methods.++While the `Client` often infers the correct transport automatically (see [Client Overview](/clients/overview#transport-inference)), you can also instantiate transports explicitly for more control.+++## 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.++### Python Stdio++* **Class:** `fastmcp.client.transports.PythonStdioTransport`+* **Inferred From:** Paths to `.py` files.+* **Use Case:** Running a Python-based MCP server script (like one using FastMCP or the base `mcp` library) in a subprocess.++This is the most common way to interact with local FastMCP servers during development or when integrating with tools that expect to launch a server script.++```python+from fastmcp import Client+from fastmcp.client.transports import PythonStdioTransport++server_script = "my_mcp_server.py" # Assumes this file exists and runs mcp.run()++# Option 1: Inferred transport+client_inferred = Client(server_script)++# Option 2: Explicit transport (e.g., to use a specific python executable or add args)+transport_explicit = PythonStdioTransport(+ script_path=server_script,+ python_cmd="/usr/bin/python3.11", # Specify python version+ # args=["--some-server-arg"], # Pass args to the script+ # env={"MY_VAR": "value"}, # Set environment variables+ # cwd="/path/to/run/in" # Set working directory+)+client_explicit = Client(transport_explicit)++async def use_stdio_client(client):+ async with client:+ tools = await client.list_tools()+ print(f"Connected via Python Stdio, found tools: {tools}")++# asyncio.run(use_stdio_client(client_inferred))+# asyncio.run(use_stdio_client(client_explicit))+```++<Warning>+The server script (`my_mcp_server.py` in the example) *must* include logic to start the MCP server and listen on stdio, typically via `mcp.run()` or `fastmcp.server.run()`. The `Client` only launches the script; it doesn't inject the server logic.+</Warning>++### Node.js Stdio++* **Class:** `fastmcp.client.transports.NodeStdioTransport`+* **Inferred From:** Paths to `.js` files.+* **Use Case:** Running a Node.js-based MCP server script in a subprocess.++Similar to the Python transport, but for JavaScript servers.++```python+from fastmcp import Client+from fastmcp.client.transports import NodeStdioTransport++node_server_script = "my_mcp_server.js" # Assumes this JS file starts an MCP server on stdio++# Option 1: Inferred transport+client_inferred = Client(node_server_script)++# Option 2: Explicit transport+transport_explicit = NodeStdioTransport(+ script_path=node_server_script,+ node_cmd="node" # Or specify path to Node executable+)+client_explicit = Client(transport_explicit)++# Usage is the same as other clients+# async with client_explicit:+# tools = await client_explicit.list_tools()+```++### UVX Stdio (Experimental)++* **Class:** `fastmcp.client.transports.UvxStdioTransport`+* **Inferred From:** Not automatically inferred. Must be instantiated explicitly.+* **Use Case:** Running an MCP server packaged as a Python tool using [`uvx`](https://docs.astral.sh/uv/reference/cli/#uvx) (part of the `uv` toolchain). This allows running tools without explicitly installing them into the current environment.++This is useful for executing MCP servers distributed as command-line tools or packages.++```python+from fastmcp.client.transports import UvxStdioTransport++# Example: Run a hypothetical 'cloud-analyzer-mcp' tool via uvx+# Assume this tool, when run, starts an MCP server on stdio+transport = UvxStdioTransport(+ tool_name="cloud-analyzer-mcp",+ # from_package="cloud-analyzer-cli", # Optionally specify package if tool name differs+ # with_packages=["boto3", "requests"], # Add dependencies if needed+ # tool_args=["--config", "prod.yaml"] # Pass args to the tool itself+)+client = Client(transport)++# async with client:+# analysis = await client.call_tool("analyze_bucket", {"name": "my-data"})+```++### NPX Stdio (Experimental)++* **Class:** `fastmcp.client.transports.NpxStdioTransport`+* **Inferred From:** Not automatically inferred. Must be instantiated explicitly.+* **Use Case:** Running an MCP server packaged as an NPM package using `npx`.++Similar to `UvxStdioTransport`, but for the Node.js ecosystem.++```python+from fastmcp.client.transports import NpxStdioTransport++# Example: Run a hypothetical 'npm-mcp-server-package' via npx+transport = NpxStdioTransport(+ package="npm-mcp-server-package",+ # args=["--port", "stdio"] # Args passed to the package script+)+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++### FastMCP Transport++* **Class:** `fastmcp.client.transports.FastMCPTransport`+* **Inferred From:** An instance of `fastmcp.server.FastMCP`.+* **Use Case:** Connecting directly to a `FastMCP` server instance running in the *same Python process*.++This is extremely useful for:+* **Testing:** Writing unit or integration tests for your FastMCP server without needing subprocesses or network connections.+* **Embedding:** Using an MCP server as a component within a larger application.++```python+from fastmcp import FastMCP, Client+from fastmcp.client.transports import FastMCPTransport++# 1. Create your FastMCP server instance+server = FastMCP(name="InMemoryServer")+def ping(): return "pong"++# 2. Create a client pointing directly to the server instance+# Option A: Inferred+client_inferred = Client(server)++# Option B: Explicit+transport_explicit = FastMCPTransport(mcp=server)+client_explicit = Client(transport_explicit)++# 3. Use the client (no subprocess or network involved)+async def test_in_memory():+ async with client_inferred: # Or client_explicit+ result = await client_inferred.call_tool("ping")+ print(f"In-memory call result: {result[0].text}") # Output: pong++# asyncio.run(test_in_memory())+```+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`).+* **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.\ No newline at end of filediff --git a/docs/docs.json b/docs/docs.jsonindex abaa30f3d..7cf7726a4 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -15,7 +15,9 @@"description": "The fast, Pythonic way to build MCP servers.","footer": {"socials": {- "github": "https://github.com/jlowin/fastmcp"+ "bluesky": "https://bsky.app/profile/jlowin.dev",+ "github": "https://github.com/jlowin/fastmcp",+ "x": "https://x.com/jlowin"}},"name": "FastMCP",@@ -47,7 +49,10 @@},{"group": "Clients",- "pages": []+ "pages": [+ "clients/overview",+ "clients/transports"+ ]},{"group": "Deployment",diff --git a/docs/style.css b/docs/style.cssindex d0cb5e5c3..08c49042a 100644--- a/docs/style.css+++ b/docs/style.css@@ -1,13 +1,13 @@-/* Target inline code elements with higher specificity */-p code,-table code,-li code,-h1 code,-h2 code,-h3 code,-h4 code,-h5 code,-h6 code {+/* Target only inline code elements, not code blocks */+p code:not(pre code),+table code:not(pre code),+li code:not(pre code),+h1 code:not(pre code),+h2 code:not(pre code),+h3 code:not(pre code),+h4 code:not(pre code),+h5 code:not(pre code),+h6 code:not(pre code) {color: #f72585 !important;background-color: #ea54551a !important;}