# Installation
This guide will help you set up the MkDocs MCP Example project on your local machine.
## Prerequisites
Before you begin, ensure you have the following installed:
### Required Software
- **Podman** (rootless preferred) - Container runtime
- **VSCode** - IDE with DevContainer support
- **Git** - Version control
- **GitHub CLI** (optional) - For repository management
### System Requirements
- **OS**: Linux, macOS, or Windows with WSL2
- **RAM**: 4GB minimum, 8GB recommended
- **Storage**: 2GB free space for containers and dependencies
## Installation Methods
### Method 1: DevContainer Setup (Recommended)
The easiest way to get started is using the provided DevContainer configuration:
1. **Clone the repository**:
```bash
git clone https://github.com/robmatesick/mkdocs-mcp-example.git
cd mkdocs-mcp-example
```
2. **Open in VSCode**:
```bash
code .
```
3. **Start DevContainer**:
- Press `Ctrl+Shift+P` (or `Cmd+Shift+P` on macOS)
- Select "Dev Containers: Reopen in Container"
- Wait for the container to build (first time takes ~5-10 minutes)
4. **Verify installation**:
```bash
# Check Python version
python --version
# Check uv installation
uv --version
# Verify dependencies
uv sync --dev
```
### Method 2: Manual Setup
If you prefer to set up the environment manually:
1. **Clone and navigate**:
```bash
git clone https://github.com/robmatesick/mkdocs-mcp-example.git
cd mkdocs-mcp-example
```
2. **Install uv**:
```bash
# On macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# On Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```
3. **Create virtual environment**:
```bash
uv venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
```
4. **Install dependencies**:
```bash
uv sync --dev
```
5. **Install pre-commit hooks**:
```bash
pre-commit install
```
## Podman Configuration
### Rootless Podman Setup
For the best security and compatibility:
1. **Install Podman**:
```bash
# Ubuntu/Debian
sudo apt update && sudo apt install podman
# RHEL/CentOS/Fedora
sudo dnf install podman
# macOS
brew install podman
```
2. **Configure rootless mode**:
```bash
# Initialize rootless configuration
podman system reset --force
podman info
```
3. **Test container functionality**:
```bash
podman run --rm hello-world
```
### DevContainer with Podman
VSCode DevContainer extension works seamlessly with Podman:
1. **Install VSCode extensions**:
- Dev Containers (`ms-vscode-remote.remote-containers`)
- Python (`ms-python.python`)
2. **Configure VSCode for Podman** (if needed):
```json
// In settings.json
{
"dev.containers.dockerPath": "podman"
}
```
## Verification
After installation, verify everything works:
### 1. Test MkDocs
```bash
cd mkdocs-site
mkdocs serve
```
Visit [http://localhost:8000](http://localhost:8000) to see the documentation.
### 2. Test MCP Server
```bash
cd mcp-server
python -m mkdocs_mcp.server
```
The server should start without errors.
### 3. Run Tests
```bash
pytest
```
All tests should pass.
### 4. Check Code Quality
```bash
# Format code
ruff format .
# Check linting
ruff check .
# Type checking
mypy .
```
## Troubleshooting
### Common Issues
#### Container Build Fails
**Problem**: DevContainer fails to build
**Solution**:
```bash
# Clear Podman cache
podman system prune -a
# Rebuild without cache
podman build --no-cache -t mkdocs-mcp-dev .devcontainer/
```
#### Permission Issues
**Problem**: File permission errors in container
**Solution**: Ensure rootless Podman is properly configured:
```bash
# Check user namespaces
podman unshare cat /proc/self/uid_map
# Reset if needed
podman system reset --force
```
#### Port Already in Use
**Problem**: Port 8000 is already occupied
**Solution**:
```bash
# Find process using port
lsof -i :8000
# Kill process or use different port
mkdocs serve -a localhost:8001
```
#### Missing Dependencies
**Problem**: Import errors or missing packages
**Solution**:
```bash
# Reinstall dependencies
uv sync --reinstall
# Clear cache if needed
uv cache clean
```
### Getting Help
If you encounter issues:
1. Check the [troubleshooting section](#troubleshooting)
2. Search existing [GitHub Issues](https://github.com/robmatesick/mkdocs-mcp-example/issues)
3. Create a new issue with:
- OS and version
- Python version
- Error messages
- Steps to reproduce
## Next Steps
Once installation is complete:
1. Read the [Quick Start Guide](quick-start.md)
2. Explore the [Configuration Options](configuration.md)
3. Try the [Examples](../examples/basic-usage.md)
## Environment Variables
The following environment variables can customize your setup:
| Variable | Default | Description |
|----------|---------|-------------|
| `MKDOCS_PORT` | `8000` | Port for MkDocs development server |
| `MCP_SERVER_PORT` | `8001` | Port for MCP server |
| `PYTHONPATH` | Auto-set | Python module search path |
| `UV_CACHE_DIR` | `~/.cache/uv` | uv cache directory |
Set these in your shell profile or `.env` file as needed.
