From b86bd50a938628fb0ce0f8b1cd7f0abf056acc0a Mon Sep 17 00:00:00 2001 From: David Soria Parra Date: Tue, 15 Oct 2024 20:10:01 +0100 Subject: [PATCH] docs: Add a simple outline for a guide This is the beginning of a guide documentation for using the SDK. --- docs/guide/_index.md | 29 ++++ docs/guide/overview.md | 39 ++++++ docs/guide/python/_index.md | 48 +++++++ docs/guide/python/servers/_index.md | 203 ++++++++++++++++++++++++++++ site/hugo.yaml | 6 +- 5 files changed, 323 insertions(+), 2 deletions(-) create mode 100644 docs/guide/overview.md create mode 100644 docs/guide/python/_index.md create mode 100644 docs/guide/python/servers/_index.md diff --git a/docs/guide/_index.md b/docs/guide/_index.md index f95eda9..27a3771 100644 --- a/docs/guide/_index.md +++ b/docs/guide/_index.md @@ -3,3 +3,32 @@ title: Guide cascade: type: docs --- +The Model Context Protocol (MCP) is a protocol designed to enable LLM assistant surfaces to receive contextual information from specialized servers. Whether you're building an IDE coding assistant, a chat interface, or any other LLM-powered application, MCP provides a standardized way to obtain and utilize relevant context. + +## What is MCP? + +MCP separates the concerns of providing context from the LLM interaction loop itself. This separation allows developers to: + +- Create pluggable context providers that work across multiple LLM surfaces +- Implement custom context gathering workflows without modifying the LLM application +- Combine multiple context sources to enhance LLM interactions + +## Key Components + +The protocol consists of two main parts: + +1. **MCP Servers**: Processes or services that provide context through various means (file systems, databases, APIs, etc.) +2. **MCP Clients**: Applications that connect to MCP servers to obtain context for LLM interactions + +## How to Use This Guide + +This guide is structured to help you understand and implement MCP in your applications: + +1. Start with the installation and basic setup instructions +2. Learn about core concepts and components +3. Follow practical examples for both client and server implementations +4. Explore advanced features and best practices + +Whether you're building a new MCP server, integrating MCP into an existing application, or just exploring the protocol, this guide will help you navigate the implementation process. + +Let's begin by setting up your development environment and getting familiar with the basic concepts. diff --git a/docs/guide/overview.md b/docs/guide/overview.md new file mode 100644 index 0000000..3edcde1 --- /dev/null +++ b/docs/guide/overview.md @@ -0,0 +1,39 @@ +--- +title: Overview +type: docs +weight: 2 +cascade: + type: docs +--- + +# SDK Documentation + +MCP provides SDKs in multiple languages to help you integrate with the protocol. Currently available SDKs: + +## Python SDK +The Python SDK offers server and client implementations along with type definitions: + +- [Python SDK on PyPI](https://pypi.org/project/mcp-python/) +- [Python SDK Documentation](/sdk/python) +- [Python SDK Source]({{< param "github_base" >}}/python-sdk) + +## TypeScript SDK +The TypeScript SDK provides client and server implementations: + +- [TypeScript SDK on NPM](https://www.npmjs.com/package/@modelcontextprotocol/sdk) +- [TypeScript SDK Documentation](/sdk/typescript) +- [TypeScript SDK Source]({{< param "github_base" >}}/typescript-sdk) + +## Getting Started + +Choose your preferred SDK from above and follow the installation instructions in its documentation. The SDKs follow similar patterns for usage but may have language-specific idioms. + +Each SDK provides: + +- Client implementation for connecting to MCP servers +- Server implementation for creating MCP servers +- Type definitions for the protocol +- Utility functions for common operations +- Examples and sample code + +See the individual SDK documentation for detailed installation and usage instructions. diff --git a/docs/guide/python/_index.md b/docs/guide/python/_index.md new file mode 100644 index 0000000..88ff5c0 --- /dev/null +++ b/docs/guide/python/_index.md @@ -0,0 +1,48 @@ +--- +title: Python +type: docs +weight: 2 +cascade: + type: docs +--- + +The MCP Python SDK provides a comprehensive implementation of the Model Context Protocol, split into several key components: + +## Core Components + +- **Client Module**: Implements the MCP client interface for connecting to servers +- **Server Module**: Provides a decorator-based API for implementing MCP servers +- **Types Module**: Contains all protocol type definitions and models +- **Shared Components**: Common utilities and base classes used by both client and server + +## Transport Options + +The SDK supports multiple transport mechanisms for client-server communication: + +- **stdio**: Communication over standard input/output streams, ideal for local process-to-process communication +- **SSE (Server-Sent Events)**: HTTP-based transport with server push capabilities, suitable for web deployments + +Each transport option has its own benefits: + +- stdio is simple and secure for local usage +- SSE works well with existing HTTP infrastructure +- WebSocket provides low-latency bidirectional communication + +## Key Design Principles + +- **Async-first**: Built on anyio for async/await patterns and compatibility with both asyncio and trio +- **Type Safety**: Full typing support via Pydantic models +- **Protocol Conformance**: Strict adherence to the MCP specification +- **Extensibility**: Easy to extend with custom functionality + +## Installation + +Install the MCP Python SDK using pip: + +```bash +pip install mcp-python +``` +or add it to your [pyproject.toml](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/) using [uv]( {{< param "uv_docs" >}} ). +```bash +uv add mcp-python +``` diff --git a/docs/guide/python/servers/_index.md b/docs/guide/python/servers/_index.md new file mode 100644 index 0000000..4261956 --- /dev/null +++ b/docs/guide/python/servers/_index.md @@ -0,0 +1,203 @@ +--- +title: Server +type: docs +weight: 1 +cascade: + type: docs +--- + +This guide walks you through setting up and implementing a basic MCP server using Python. + +## Installation + +Install the MCP Python SDK using pip: + +```bash +pip install mcp-python +``` +or add it to your [pyproject.toml](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/) using [uv]( {{< param "uv_docs" >}} ). +```bash +uv add mcp-python +``` + +## Server API Overview + +The Python SDK provides a decorator-based API for implementing MCP servers. The main `Server` class offers decorators for handling different types of requests: + +### Resource Handling +- `@server.list_resources()`: Lists available resources +- `@server.read_resource()`: Reads content of a specific resource +- `@server.subscribe_resource()`: Handles resource subscription requests +- `@server.unsubscribe_resource()`: Handles unsubscribe requests + +### Tool Support +- `@server.list_tools()`: Lists available tools +- `@server.call_tool()`: Handles tool execution requests + +### Prompt Management +- `@server.list_prompts()`: Lists available prompts +- `@server.get_prompt()`: Retrieves specific prompt templates + +### Progress & Logging +- `@server.progress_notification()`: Handles progress updates +- `@server.set_logging_level()`: Controls server logging + +The decorators automatically handle request/response formatting and protocol compliance, allowing you to focus on implementing the core functionality. + +## Basic Server Implementation + +Here's a minimal example of implementing an MCP server: + +```python +from mcp_python.server import Server +import anyio + +# Create a new server instance +server = Server("example-server") + +# Implement resource handling +@server.list_resources() +async def list_resources(): + # Return list of available resources + return [ + { + "uri": "example://resource1", + "name": "Example Resource 1", + "description": "An example resource" + } + ] + +@server.read_resource() +async def read_resource(uri): + # Return content for the requested resource + if uri == "example://resource1": + return "Example resource content" + raise ValueError(f"Unknown resource: {uri}") + +# Main server loop +async def main(): + # Use stdio transport for this example + async with stdio_server() as (read_stream, write_stream): + await server.run( + read_stream, + write_stream, + server.create_initialization_options() + ) + +if __name__ == "__main__": + anyio.run(main) +``` + +## Advanced Server Features + +### Adding Tool Support + +```python +@server.list_tools() +async def list_tools(): + return [ + { + "name": "example-tool", + "description": "An example tool", + "parameters": { + "type": "object", + "properties": { + "param1": {"type": "string"} + } + } + } + ] + +@server.call_tool() +async def call_tool(name, **kwargs): + if name == "example-tool": + return f"Tool executed with params: {kwargs}" + raise ValueError(f"Unknown tool: {name}") +``` + +### Adding Prompt Support + +```python +@server.list_prompts() +async def list_prompts(): + return [ + { + "name": "example-prompt", + "description": "An example prompt", + "parameters": { + "type": "object", + "properties": { + "param1": {"type": "string"} + } + } + } + ] + +@server.get_prompt() +async def get_prompt(name, arguments): + if name == "example-prompt": + return PromptResponse( + messages=[ + Message( + role="user", + content=f"Example prompt with args: {arguments}" + ) + ], + desc="Example prompt response" + ) + raise ValueError(f"Unknown prompt: {name}") +``` + +## Running the Server + +Start the server from the command line: + +```bash +python your_server.py +``` + +For SSE or WebSocket transport, you'll need to use an ASGI server like Hypercorn: + +```bash +hypercorn your_server:app --bind 0.0.0.0:8000 +``` + +## Best Practices + +1. Always implement proper error handling for all server methods +2. Use typing hints for better code clarity and IDE support +3. Document your server's capabilities and resources +4. Implement logging for debugging purposes +5. Follow the MCP specification for consistent behavior + +## Common Patterns + +### Resource Updates + +```python +async def notify_resource_update(uri, session): + await session.send_resource_updated(uri) +``` + +### Progress Notifications + +```python +async def long_running_operation(session): + for i in range(100): + await session.send_progress_notification( + "operation-1", + progress=i, + total=100 + ) +``` + +### Logging + +```python +async def log_operation(session): + await session.send_log_message( + level="info", + data="Operation completed", + logger="example-server" + ) +``` diff --git a/site/hugo.yaml b/site/hugo.yaml index 996f73a..13be2db 100644 --- a/site/hugo.yaml +++ b/site/hugo.yaml @@ -13,10 +13,12 @@ module: imports: - path: github.com/imfing/hextra - - contentDir: ../docs +params: + github_base: "https://github.com/modelcontextprotocol" + uv_docs: "https://docs.astral.sh/uv/" + markup: goldmark: renderer: