# MkDocs MCP Example
Welcome to the MkDocs MCP Example project! This demonstration showcases the integration of **MkDocs Material** documentation with a **Model Context Protocol (MCP) server**, creating a powerful combination for documentation and AI-driven content access.
## 🚀 Project Overview
This project demonstrates:
- **Beautiful Documentation**: Built with MkDocs Material theme
- **AI Integration**: MCP server providing AI access to documentation
- **Modern Development**: Python best practices with uv and devcontainers
- **Professional Workflow**: Complete CI/CD and development environment setup
## ✨ Key Features
### Documentation Features
- 📚 **Modern Theme**: Beautiful, responsive Material Design
- 🔍 **Advanced Search**: Full-text search with highlighting
- 📱 **Mobile Friendly**: Responsive design for all devices
- 🌙 **Dark Mode**: Automatic theme switching
- 📊 **Diagrams**: Mermaid diagram support
- 🔗 **Navigation**: Intuitive navigation with breadcrumbs
### MCP Server Features
- 🤖 **AI Access**: Direct AI access to documentation content
- 📖 **Content Resources**: Serve documentation as MCP resources
- 🔧 **Search Tools**: AI-powered search and query capabilities
- ⚡ **Fast Performance**: Optimized for quick response times
- 🔒 **Secure**: Following MCP security best practices
### Development Features
- 🐍 **Python Best Practices**: Modern Python development with type hints
- 📦 **uv Package Management**: Fast, reliable dependency management
- 🐳 **DevContainers**: Consistent development environment
- 🧪 **Comprehensive Testing**: Unit tests for all components
- 📊 **Code Quality**: Ruff, MyPy, and pre-commit hooks
## 🏗️ 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]
```
## 📋 Quick Start
### Prerequisites
- **Podman** (rootless preferred)
- **VSCode** with DevContainer extension
- **Git**
### Setup
1. **Clone the repository**:
```bash
git clone https://github.com/robmatesick/mkdocs-mcp-example.git
cd mkdocs-mcp-example
```
2. **Open in DevContainer**:
- Open VSCode
- Run "Dev Containers: Reopen in Container"
- Wait for container build and setup
3. **Start development servers**:
```bash
# Terminal 1: Start MkDocs
docs-serve
# Terminal 2: Start MCP Server
mcp-server
```
4. **Access the documentation**:
- Open [http://localhost:8000](http://localhost:8000)
- Documentation will auto-reload on changes
## 📚 What's Inside
### Documentation Structure
```
docs/
├── index.md # This page
├── getting-started/ # Installation and setup guides
├── mcp-server/ # MCP server documentation
├── api/ # Auto-generated API docs
└── examples/ # Usage examples
```
### Code Structure
```
mkdocs-mcp-example/
├── mkdocs-site/ # MkDocs configuration
├── mcp-server/ # MCP server implementation
├── docs/ # Documentation source
├── .devcontainer/ # DevContainer configuration
└── .vscode/ # VSCode settings
```
## 🔧 Development
### Available Commands
- `docs-serve` - Start MkDocs development server
- `mcp-server` - Start MCP server
- `test` - Run all tests
- `lint` - Run code linting
- `format` - Format code
- `typecheck` - Run type checking
### Testing
```bash
# Run all tests
test
# Run with coverage
test-cov
# Run specific test
pytest mcp-server/tests/test_server.py
```
## 🤝 Contributing
We welcome contributions! Please see our [Contributing Guide](contributing.md) for details.
## 📄 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
---
*Built with ❤️ using modern Python development practices*
