# MkDocs MCP Example
[](https://www.python.org/downloads/)
[](https://squidfunk.github.io/mkdocs-material/)
[](https://modelcontextprotocol.io/)
[](https://docs.astral.sh/uv/)
[](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.
