From 133254ee252d8279cbc6db0b9d271fe629fb86c8 Mon Sep 17 00:00:00 2001 From: Jeremiah Lowin <153965+jlowin@users.noreply.github.com> Date: Sun, 22 Jun 2025 13:34:36 -0400 Subject: [PATCH] Update docs --- docs/clients/client.mdx | 117 ++++++++++++++++++++--- docs/clients/logging.mdx | 2 +- docs/clients/progress.mdx | 2 +- docs/clients/prompts.mdx | 2 +- docs/clients/resources.mdx | 2 +- docs/clients/roots.mdx | 2 +- docs/clients/sampling.mdx | 2 +- docs/clients/tools.mdx | 2 +- docs/docs.json | 2 +- docs/servers/{fastmcp.mdx => server.mdx} | 4 +- 10 files changed, 113 insertions(+), 24 deletions(-) rename docs/servers/{fastmcp.mdx => server.mdx} (98%) diff --git a/docs/clients/client.mdx b/docs/clients/client.mdx index d246c88fe..c56ce634e 100644 --- a/docs/clients/client.mdx +++ b/docs/clients/client.mdx @@ -1,7 +1,7 @@ --- -title: Client Overview +title: The FastMCP Client sidebarTitle: Overview -description: Learn how to use the FastMCP Client to programmatically interact with MCP servers. +description: Programmatic client for interacting with MCP servers through a well-typed, Pythonic interface. icon: user-robot --- @@ -9,20 +9,24 @@ import { VersionBadge } from '/snippets/version-badge.mdx' -The `fastmcp.Client` is a **programmatic client** for interacting with any Model Context Protocol (MCP) server. It provides a high-level, well-typed, Pythonic interface for deterministic MCP access, making it ideal for: +The central piece of MCP client applications is the `fastmcp.Client` class. This class provides a **programmatic interface** for interacting with any Model Context Protocol (MCP) server, handling protocol details and connection management automatically. + +The FastMCP Client is designed for deterministic, controlled interactions rather than autonomous behavior, making it ideal for: - **Testing MCP servers** during development -- **Building deterministic applications** that need reliable MCP interactions +- **Building deterministic applications** that need reliable MCP interactions - **Creating the foundation for agentic or LLM-based clients** with structured, type-safe operations +All client operations require using the `async with` context manager for proper connection lifecycle management. + This is not an agentic client - it requires explicit function calls and provides direct control over all MCP operations. Use it as a building block for higher-level systems. -## Quick Start +## Creating a Client -Note that all client operations require using the `async with` context manager for proper connection lifecycle management. The client uses transport inference to automatically determine the connection method. +Creating a client is straightforward. You provide a server source and the client automatically infers the appropriate transport mechanism. ```python import asyncio @@ -157,16 +161,57 @@ async def example(): print(f"Connected: {client.is_connected()}") ``` -## Core Operations +## Operations -The client provides methods for all standard MCP operations: +FastMCP clients can interact with several types of server components: -| Operation | Method | Description | -|-----------|--------|-------------| -| **Tools** | `list_tools()`, `call_tool()` | Execute server-side functions | -| **Resources** | `list_resources()`, `read_resource()` | Access server data sources | -| **Prompts** | `list_prompts()`, `get_prompt()` | Retrieve message templates | -| **Utility** | `ping()` | Test server connectivity | +### Tools + +Tools are server-side functions that the client can execute with arguments. + +```python +async with client: + # List available tools + tools = await client.list_tools() + + # Execute a tool + result = await client.call_tool("multiply", {"a": 5, "b": 3}) + print(result[0].text) # "15" +``` + +See [Tools](/clients/tools) for detailed documentation. + +### Resources + +Resources are data sources that the client can read, either static or templated. + +```python +async with client: + # List available resources + resources = await client.list_resources() + + # Read a resource + content = await client.read_resource("file:///config/settings.json") + print(content[0].text) +``` + +See [Resources](/clients/resources) for detailed documentation. + +### Prompts + +Prompts are reusable message templates that can accept arguments. + +```python +async with client: + # List available prompts + prompts = await client.list_prompts() + + # Get a rendered prompt + messages = await client.get_prompt("analyze_data", {"data": [1, 2, 3]}) + print(messages.messages) +``` + +See [Prompts](/clients/prompts) for detailed documentation. ### Server Connectivity @@ -178,6 +223,50 @@ async with client: print("Server is reachable") ``` +## Client Configuration + +Clients can be configured with additional handlers and settings for specialized use cases. + +### Callback Handlers + +The client supports several callback handlers for advanced server interactions: + +```python +from fastmcp import Client +from fastmcp.client.logging import LogMessage + +async def log_handler(message: LogMessage): + print(f"Server log: {message.data}") + +async def progress_handler(progress: float, total: float | None, message: str | None): + print(f"Progress: {progress}/{total} - {message}") + +async def sampling_handler(messages, params, context): + # Integrate with your LLM service here + return "Generated response" + +client = Client( + "my_mcp_server.py", + log_handler=log_handler, + progress_handler=progress_handler, + sampling_handler=sampling_handler, + timeout=30.0 +) +``` + +The `Client` constructor accepts several configuration options: + +- `transport`: Transport instance or source for automatic inference +- `log_handler`: Handle server log messages +- `progress_handler`: Monitor long-running operations +- `sampling_handler`: Respond to server LLM requests +- `roots`: Provide local context to servers +- `timeout`: Default timeout for requests (in seconds) + +### Transport Configuration + +For detailed transport configuration (headers, authentication, environment variables), see the [Transports](/clients/transports) documentation. + ## Next Steps Explore the detailed documentation for each operation type: diff --git a/docs/clients/logging.mdx b/docs/clients/logging.mdx index a9ea86a48..9c28a5d25 100644 --- a/docs/clients/logging.mdx +++ b/docs/clients/logging.mdx @@ -1,7 +1,7 @@ --- title: Server Logging sidebarTitle: Logging -description: Learn how to receive and handle log messages from MCP servers. +description: Receive and handle log messages from MCP servers. icon: receipt --- diff --git a/docs/clients/progress.mdx b/docs/clients/progress.mdx index f8dd9db1c..bd500fa26 100644 --- a/docs/clients/progress.mdx +++ b/docs/clients/progress.mdx @@ -1,7 +1,7 @@ --- title: Progress Monitoring sidebarTitle: Progress -description: Learn how to handle progress notifications from long-running server operations. +description: Handle progress notifications from long-running server operations. icon: bars-progress --- diff --git a/docs/clients/prompts.mdx b/docs/clients/prompts.mdx index 7ccfbd501..0ba4d2765 100644 --- a/docs/clients/prompts.mdx +++ b/docs/clients/prompts.mdx @@ -1,7 +1,7 @@ --- title: Prompts sidebarTitle: Prompts -description: Learn how to list and use server-side prompts with automatic argument serialization. +description: Use server-side prompt templates with automatic argument serialization. icon: message-lines --- diff --git a/docs/clients/resources.mdx b/docs/clients/resources.mdx index 705770879..ecad582e0 100644 --- a/docs/clients/resources.mdx +++ b/docs/clients/resources.mdx @@ -1,7 +1,7 @@ --- title: Resource Operations sidebarTitle: Resources -description: Learn how to list and read static and templated resources from MCP servers. +description: Access static and templated resources from MCP servers. icon: folder-open --- diff --git a/docs/clients/roots.mdx b/docs/clients/roots.mdx index 48c4aa258..2a8d8c1f9 100644 --- a/docs/clients/roots.mdx +++ b/docs/clients/roots.mdx @@ -1,7 +1,7 @@ --- title: Client Roots sidebarTitle: Roots -description: Learn how to provide local context to MCP servers. +description: Provide local context and resource boundaries to MCP servers. icon: folder-tree --- diff --git a/docs/clients/sampling.mdx b/docs/clients/sampling.mdx index 0003999f4..25d035478 100644 --- a/docs/clients/sampling.mdx +++ b/docs/clients/sampling.mdx @@ -1,7 +1,7 @@ --- title: LLM Sampling sidebarTitle: Sampling -description: Learn how to handle server-initiated LLM sampling requests. +description: Handle server-initiated LLM sampling requests. icon: robot --- diff --git a/docs/clients/tools.mdx b/docs/clients/tools.mdx index 95ec06165..3821725cb 100644 --- a/docs/clients/tools.mdx +++ b/docs/clients/tools.mdx @@ -1,7 +1,7 @@ --- title: Tool Operations sidebarTitle: Tools -description: Learn how to discover and execute tools on MCP servers. +description: Discover and execute server-side tools with the FastMCP client. icon: wrench --- diff --git a/docs/docs.json b/docs/docs.json index d35476ca6..399c1f146 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -63,7 +63,7 @@ { "group": "Servers", "pages": [ - "servers/fastmcp", + "servers/server", { "group": "Core Components", "icon": "toolbox", diff --git a/docs/servers/fastmcp.mdx b/docs/servers/server.mdx similarity index 98% rename from docs/servers/fastmcp.mdx rename to docs/servers/server.mdx index 12aa08fd8..1cb5f089b 100644 --- a/docs/servers/fastmcp.mdx +++ b/docs/servers/server.mdx @@ -1,7 +1,7 @@ --- title: The FastMCP Server -sidebarTitle: FastMCP Servers -description: Learn about the core FastMCP server class and how to run it. +sidebarTitle: Overview +description: The core FastMCP server class for building MCP applications with tools, resources, and prompts. icon: server ---