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

Edit content in the docs/ directory
Add new pages and update navigation in mkdocs.yml
Preview changes at http://localhost:8000
Use Markdown features like admonitions, code blocks, and diagrams

For Python Developers

Modify MCP server in mcp-server/src/mkdocs_mcp/
Add new tools or resources for AI access
Run tests with make test
Follow type hints and modern Python practices

For DevOps Engineers

Customize DevContainer in .devcontainer/
Configure CI/CD pipelines using the Makefile targets
Deploy documentation using MkDocs build outputs
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:

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

Fork the repository
Clone your fork
Open in DevContainer
Run make setup
Make your changes
Run make ci-check
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.

MkDocs MCP Server