# MkDocs MCP Example

[![Python](https://img.shields.io/badge/Python-3.11%2B-blue)](https://www.python.org/downloads/)
[![MkDocs](https://img.shields.io/badge/MkDocs-Material-526CFE)](https://squidfunk.github.io/mkdocs-material/)
[![MCP](https://img.shields.io/badge/MCP-Server-orange)](https://modelcontextprotocol.io/)
[![uv](https://img.shields.io/badge/uv-Package%20Manager-4051B5)](https://docs.astral.sh/uv/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A comprehensive example project demonstrating the integration of **MkDocs Material** documentation with a **Model Context Protocol (MCP) server**, showcasing modern Python development practices with **uv**, **devcontainers**, and **VSCode**.

## 🌟 Features

### 📚 **Beautiful Documentation**
- **MkDocs Material** theme with modern design
- **Responsive layout** for all devices
- **Advanced search** with full-text indexing
- **Dark/light mode** with system preference detection
- **Mermaid diagrams** and **syntax highlighting**
- **Auto-generated API documentation** with mkdocstrings

### 🤖 **AI-Powered Documentation Access**
- **MCP Server** providing AI access to documentation
- **Resource serving** for direct content access
- **Advanced search tools** for content discovery
- **Code block extraction** and analysis
- **Page outline generation** and navigation

### 🛠️ **Modern Development Stack**
- **Python 3.11+** with type hints and modern practices
- **uv** for lightning-fast dependency management
- **DevContainers** for consistent development environments
- **VSCode** integration with comprehensive tooling
- **Rootless Podman** support for secure containerization

### 🧪 **Quality Assurance**
- **Comprehensive testing** with pytest and coverage
- **Code formatting** with Ruff
- **Type checking** with MyPy
- **Pre-commit hooks** for automated quality checks
- **CI/CD ready** configuration

## 🚀 Quick Start

### Prerequisites

- **Podman** (rootless preferred)
- **VSCode** with Dev Containers extension
- **Git**

### 1. Clone & Open

```bash
git clone https://github.com/robmatesick/mkdocs-mcp-example.git
cd mkdocs-mcp-example
code .
```

### 2. Start DevContainer

- Press `Ctrl+Shift+P` (Windows/Linux) or `Cmd+Shift+P` (macOS)
- Select **"Dev Containers: Reopen in Container"**
- Wait for container setup (~5-10 minutes on first run)

### 3. Start Development

```bash
# Terminal 1: Documentation server
make docs-serve

# Terminal 2: MCP server
make mcp-server
```

Visit [http://localhost:8000](http://localhost:8000) to see your documentation!

## 📁 Project Structure

```
mkdocs-mcp-example/
├── 📁 docs/                    # Documentation source
│   ├── index.md               # Homepage
│   ├── getting-started/       # Setup guides
│   ├── mcp-server/           # MCP documentation  
│   ├── api/                  # Auto-generated API docs
│   └── examples/             # Usage examples
│
├── 📁 mkdocs-site/            # MkDocs configuration
│   ├── mkdocs.yml            # Main configuration
│   ├── pyproject.toml        # Dependencies
│   └── docs/                 # Theme customizations
│
├── 📁 mcp-server/             # MCP server implementation
│   ├── src/mkdocs_mcp/       # Source code
│   │   ├── server.py         # Main server
│   │   ├── resources.py      # Resource management
│   │   └── tools.py          # Search tools
│   ├── tests/                # Unit tests
│   └── pyproject.toml        # Dependencies
│
├── 📁 .devcontainer/          # DevContainer config
├── 📁 .vscode/                # VSCode settings
├── 📁 tests/                  # Integration tests
├── pyproject.toml             # Workspace configuration
├── Makefile                   # Development commands
└── README.md                  # This file
```

## 🔧 Development Commands

The project includes a comprehensive `Makefile` with common development tasks:

### 📦 Setup & Installation
```bash
make setup          # Complete development setup
make install        # Install dependencies only
```

### 🧹 Code Quality
```bash
make format         # Format code with Ruff
make lint           # Lint code and fix issues
make typecheck      # Run MyPy type checking
make quality        # Run all quality checks
```

### 🧪 Testing
```bash
make test           # Run all tests
make test-cov       # Run tests with coverage
make test-watch     # Run tests in watch mode
```

### 📚 Documentation
```bash
make docs-serve     # Start documentation server
make docs-build     # Build static documentation
make docs-clean     # Clean build artifacts
```

### 🤖 MCP Server
```bash
make mcp-server     # Start MCP server
make mcp-test       # Run MCP server tests
```

### 🚀 Development Workflow
```bash
make dev            # Start both docs and MCP server
make clean          # Clean all build artifacts
make ci-check       # Run all CI checks
```

## 🏗️ Architecture

```mermaid
graph TB
    A[📚 MkDocs Site] --> B[📄 Documentation Files]
    B --> C[🤖 MCP Server]
    C --> D[🧠 AI Assistant]
    D --> E[👥 Users]
    
    F[👨‍💻 Developer] --> G[🐳 DevContainer]
    G --> H[📦 uv Environment]
    H --> A
    H --> C
    
    I[🔄 CI/CD] --> J[🧪 Tests]
    I --> K[🏗️ Build]
    I --> L[🚀 Deploy]
```

## 🤖 MCP Server Usage

The MCP server provides AI assistants with direct access to your documentation:

### Available Resources
- **Documentation pages** as readable resources
- **Automatic metadata extraction** from frontmatter
- **Hierarchical navigation** support

### Available Tools
- **`search_docs`** - Full-text search across documentation
- **`find_by_title`** - Find pages by title or heading
- **`list_pages`** - List all available documentation pages
- **`get_page_outline`** - Extract page structure and headings
- **`search_code_blocks`** - Find and filter code examples

### Example Usage

```python
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

# Connect to MCP server
server_params = StdioServerParameters(
    command="python", 
    args=["-m", "mkdocs_mcp.server"]
)

async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        # List available documentation
        resources = await session.list_resources()
        print(f"Found {len(resources.resources)} pages")
        
        # Search documentation
        result = await session.call_tool("search_docs", {
            "query": "installation",
            "max_results": 5
        })
        print(result.content[0].text)
```

## 🏃‍♂️ Getting Started Guide

### For Documentation Writers
1. **Edit content** in the `docs/` directory
2. **Add new pages** and update navigation in `mkdocs.yml`
3. **Preview changes** at [http://localhost:8000](http://localhost:8000)
4. **Use Markdown features** like admonitions, code blocks, and diagrams

### For Python Developers
1. **Modify MCP server** in `mcp-server/src/mkdocs_mcp/`
2. **Add new tools** or resources for AI access
3. **Run tests** with `make test`
4. **Follow type hints** and modern Python practices

### For DevOps Engineers
1. **Customize DevContainer** in `.devcontainer/`
2. **Configure CI/CD** pipelines using the Makefile targets
3. **Deploy documentation** using MkDocs build outputs
4. **Monitor MCP server** performance and usage

## 🔒 Security & Best Practices

- **Rootless containers** for enhanced security
- **No secrets in code** - use environment variables
- **Input validation** in MCP server endpoints
- **Type safety** with comprehensive type hints
- **Dependency scanning** with automated security checks

## 📖 Documentation

Complete documentation is available at:
- **[Getting Started Guide](docs/getting-started/installation.md)**
- **[Quick Start Tutorial](docs/getting-started/quick-start.md)**
- **[MCP Server Documentation](docs/mcp-server/overview.md)**
- **[API Reference](docs/api/)**

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](docs/contributing.md) for details.

### Development Setup
1. Fork the repository
2. Clone your fork
3. Open in DevContainer
4. Run `make setup`
5. Make your changes
6. Run `make ci-check`
7. Submit a pull request

## 📋 Requirements

### System Requirements
- **OS**: Linux, macOS, or Windows with WSL2
- **RAM**: 4GB minimum, 8GB recommended
- **Storage**: 2GB free space

### Software Requirements
- **Python**: 3.11 or higher
- **Podman**: Latest stable version
- **VSCode**: With Dev Containers extension
- **Git**: For version control

## 🆘 Troubleshooting

### Common Issues

**Container build fails**
```bash
# Clean Podman cache and try again
podman system prune -a

# Or rebuild DevContainer from VSCode
# Ctrl+Shift+P -> "Dev Containers: Rebuild Container"
```

**Port conflicts**
```bash
make docs-serve MKDOCS_PORT=8002
```

**Dependency issues**
```bash
make clean
make dev-install
```

See the [Troubleshooting Guide](docs/getting-started/installation.md#troubleshooting) for more solutions.

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- **[MkDocs](https://www.mkdocs.org/)** - Static site generator
- **[Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)** - Beautiful theme
- **[Model Context Protocol](https://modelcontextprotocol.io/)** - AI integration standard  
- **[uv](https://docs.astral.sh/uv/)** - Fast Python package manager
- **[Ruff](https://docs.astral.sh/ruff/)** - Python linting and formatting
- **[Podman](https://podman.io/)** - Container runtime

## 📞 Support

- **Documentation**: [Project Documentation](https://robmatesick.github.io/mkdocs-mcp-example/)
- **Issues**: [GitHub Issues](https://github.com/robmatesick/mkdocs-mcp-example/issues)
- **Discussions**: [GitHub Discussions](https://github.com/robmatesick/mkdocs-mcp-example/discussions)

---

⭐ **Star this repo** if you find it helpful!

Built with ❤️ using modern Python development practices.