Doc site work (#5)

* site config (URL, site name, API ref tweaks)

* Shard README into *.md in docs/

* minor quickstart tweak

Author: mmacy

docs/asgi-integration.md

@@ -1,3 +1,82 @@
-# MCP Server
+# MCP Python SDK
 
-This is the MCP Server implementation in Python.
+A Python implementation of the Model Context Protocol (MCP) that enables applications to provide context for LLMs in a standardized way.
+
+## Overview
+
+The Model Context Protocol allows you to build servers that expose data and functionality to LLM applications securely. This Python SDK implements the full MCP specification with both high-level FastMCP and low-level server implementations.
+
+### Key features
+
+- **FastMCP server framework** - High-level, decorator-based server creation
+- **Multiple transports** - stdio, SSE, and Streamable HTTP support
+- **Type-safe development** - Full type hints and Pydantic integration
+- **Authentication support** - OAuth 2.1 resource server capabilities
+- **Rich tooling** - Built-in development and deployment utilities
+
+## Quick start
+
+Create a simple MCP server in minutes:
+
+```python
+from mcp.server.fastmcp import FastMCP
+
+# Create server
+mcp = FastMCP("Demo")
+
+@mcp.tool()
+def add(a: int, b: int) -> int:
+    """Add two numbers"""
+    return a + b
+
+@mcp.resource("greeting://{name}")
+def get_greeting(name: str) -> str:
+    """Get a personalized greeting"""
+    return f"Hello, {name}!"
+```
+
+Install in Claude Desktop:
+
+```bash
+uv run mcp install server.py
+```
+
+## Documentation sections
+
+### Getting started
+- **[Quickstart](quickstart.md)** - Build your first MCP server
+- **[Installation](installation.md)** - Setup and dependencies
+
+### Core concepts
+- **[Servers](servers.md)** - Server creation and lifecycle management
+- **[Resources](resources.md)** - Exposing data to LLMs
+- **[Tools](tools.md)** - Creating LLM-callable functions
+- **[Prompts](prompts.md)** - Reusable interaction templates
+- **[Context](context.md)** - Request context and capabilities
+
+### Advanced features
+- **[Images](images.md)** - Working with image data
+- **[Authentication](authentication.md)** - OAuth 2.1 implementation
+- **[Sampling](sampling.md)** - LLM text generation
+- **[Elicitation](elicitation.md)** - User input collection
+- **[Progress & logging](progress-logging.md)** - Status updates and notifications
+
+### Transport & deployment
+- **[Running servers](running-servers.md)** - Development and production deployment
+- **[Streamable HTTP](streamable-http.md)** - Modern HTTP transport
+- **[ASGI integration](asgi-integration.md)** - Mounting to existing web servers
+
+### Client development
+- **[Writing clients](writing-clients.md)** - MCP client implementation
+- **[OAuth for clients](oauth-clients.md)** - Client-side authentication
+- **[Display utilities](display-utilities.md)** - UI helper functions
+- **[Parsing results](parsing-results.md)** - Handling tool responses
+
+### Advanced usage
+- **[Low-level server](low-level-server.md)** - Direct protocol implementation
+- **[Structured output](structured-output.md)** - Advanced type patterns
+- **[Completions](completions.md)** - Argument completion system
+
+## API reference
+
+Complete API documentation is auto-generated from the source code and available in the [API Reference](reference/) section.

docs/authentication.md

@@ -0,0 +1,194 @@
+# Installation
+
+Learn how to install and set up the MCP Python SDK for different use cases.
+
+## Prerequisites
+
+- **Python 3.10 or later**
+- **uv package manager** (recommended) or pip
+
+### Installing uv
+
+If you don't have uv installed:
+
+```bash
+# macOS and Linux
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Windows
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+
+# Or with pip
+pip install uv
+```
+
+## Installation methods
+
+### For new projects (recommended)
+
+Create a new uv-managed project:
+
+```bash
+uv init my-mcp-server
+cd my-mcp-server
+uv add "mcp[cli]"
+```
+
+This creates a complete project structure with:
+- `pyproject.toml` - Project configuration
+- `src/` directory for your code
+- Virtual environment management
+
+### Add to existing project
+
+If you have an existing project:
+
+```bash
+uv add "mcp[cli]"
+```
+
+### Using pip
+
+For projects that use pip:
+
+```bash
+pip install "mcp[cli]"
+```
+
+## Package variants
+
+The MCP SDK offers different installation options:
+
+### Core package
+```bash
+uv add mcp
+```
+
+Includes:
+- Core MCP protocol implementation
+- FastMCP server framework
+- Client libraries
+- All transport types (stdio, SSE, Streamable HTTP)
+
+### CLI tools
+```bash
+uv add "mcp[cli]"
+```
+
+Adds CLI utilities for:
+- `mcp dev` - Development server with web inspector
+- `mcp install` - Claude Desktop integration
+- `mcp run` - Direct server execution
+
+### Rich output
+```bash
+uv add "mcp[rich]"
+```
+
+Adds enhanced terminal output with colors and formatting.
+
+### WebSocket support
+```bash
+uv add "mcp[ws]"
+```
+
+Adds WebSocket transport capabilities.
+
+### All features
+```bash
+uv add "mcp[cli,rich,ws]"
+```
+
+## Development setup
+
+For contributing to the MCP SDK or advanced development:
+
+```bash
+git clone https://github.com/modelcontextprotocol/python-sdk
+cd python-sdk
+uv sync --group docs --group dev
+```
+
+This installs:
+- All dependencies
+- Development tools (ruff, pyright, pytest)
+- Documentation tools (mkdocs, mkdocs-material)
+
+## Verify installation
+
+Test your installation:
+
+```bash
+# Check MCP CLI is available
+uv run mcp --help
+
+# Create and test a simple server
+echo 'from mcp.server.fastmcp import FastMCP
+mcp = FastMCP("Test")
+@mcp.tool()
+def hello() -> str:
+    return "Hello from MCP!"
+if __name__ == "__main__":
+    mcp.run()' > test_server.py
+
+# Test the server
+uv run mcp dev test_server.py
+```
+
+If successful, you'll see the MCP Inspector web interface open.
+
+## IDE integration
+
+### VS Code
+
+For the best development experience, install:
+
+- **Python extension** - Python language support
+- **Pylance** - Advanced Python features
+- **Ruff** - Code formatting and linting
+
+### Type checking
+
+The MCP SDK includes comprehensive type hints. Enable strict type checking:
+
+```bash
+# Check types
+uv run pyright
+
+# In VS Code, add to settings.json:
+{
+    "python.analysis.typeCheckingMode": "strict"
+}
+```
+
+## Troubleshooting
+
+### Common issues
+
+**"mcp command not found"**
+- Ensure uv is in your PATH
+- Try `uv run mcp` instead of just `mcp`
+
+**Import errors**
+- Verify installation: `uv run python -c "import mcp; print(mcp.__version__)"`
+- Check you're in the right directory/virtual environment
+
+**Permission errors on Windows**
+- Run terminal as administrator for global installations
+- Use `--user` flag with pip if needed
+
+**Python version conflicts**
+- Check version: `python --version`
+- Use specific Python: `uv python install 3.11` then `uv python use 3.11`
+
+### Getting help
+
+- **GitHub Issues**: [Report bugs and feature requests](https://github.com/modelcontextprotocol/python-sdk/issues)
+- **Discussions**: [Community support](https://github.com/modelcontextprotocol/python-sdk/discussions)
+- **Documentation**: [Official MCP docs](https://modelcontextprotocol.io)
+
+## Next steps
+
+- **[Build your first server](quickstart.md)** - Follow the quickstart guide
+- **[Learn core concepts](servers.md)** - Understand MCP fundamentals
+- **[Explore examples](https://github.com/modelcontextprotocol/python-sdk/tree/main/examples)** - See real-world implementations