Merge pull request #25 from modelcontextprotocol/davidsp/more-docs

docs: Initial frame for the guide documentation

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.

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.

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
+```

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"
+    )
+```

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: