MkDocs MCP Example

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

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

# Terminal 1: Documentation server
make docs-serve

# Terminal 2: MCP server
make mcp-server

Visit 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

make setup          # Complete development setup
make install        # Install dependencies only

🧹 Code Quality

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

make test           # Run all tests
make test-cov       # Run tests with coverage
make test-watch     # Run tests in watch mode

📚 Documentation

make docs-serve     # Start documentation server
make docs-build     # Build static documentation
make docs-clean     # Clean build artifacts

🤖 MCP Server

make mcp-server     # Start MCP server
make mcp-test       # Run MCP server tests

🚀 Development Workflow

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

🏗️ Architecture

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

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
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
• Quick Start Tutorial
• MCP Server Documentation
• API Reference

🤝 Contributing

We welcome contributions! Please see our Contributing Guide 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

# Clean Podman cache and try again
podman system prune -a

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

Port conflicts

make docs-serve MKDOCS_PORT=8002

Dependency issues

make clean
make dev-install

See the Troubleshooting Guide for more solutions.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• MkDocs - Static site generator
• Material for MkDocs - Beautiful theme
• Model Context Protocol - AI integration standard
• uv - Fast Python package manager
• Ruff - Python linting and formatting
• Podman - Container runtime

📞 Support

• Documentation: Project Documentation
• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

⭐ Star this repo if you find it helpful!

Built with ❤️ using modern Python development practices.