# Configuration
This guide covers all configuration options for the MkDocs MCP Example project.
## MkDocs Configuration
The main MkDocs configuration is in `mkdocs-site/mkdocs.yml`:
### Basic Settings
```yaml
site_name: MkDocs MCP Example
site_description: Example project combining MkDocs Material documentation with MCP server
site_author: Rob Matesick
site_url: https://robmatesick.github.io/mkdocs-mcp-example/
repo_name: robmatesick/mkdocs-mcp-example
repo_url: https://github.com/robmatesick/mkdocs-mcp-example
```
### Theme Configuration
The Material theme is extensively configured:
```yaml
theme:
name: material
palette:
# Automatic mode detection
- media: "(prefers-color-scheme)"
toggle:
icon: material/brightness-auto
name: Switch to light mode
# Light mode
- media: "(prefers-color-scheme: light)"
scheme: default
primary: blue
accent: blue
# Dark mode
- media: "(prefers-color-scheme: dark)"
scheme: slate
primary: blue
accent: blue
```
### Features
Enabled Material theme features:
- **Navigation**: Instant loading, sections, tabs, tracking
- **Search**: Advanced search with highlighting
- **Content**: Code copying, tooltips, tabs
- **Header**: Auto-hide on scroll
### Plugins
Key plugins configured:
- **Search**: Enhanced search functionality
- **Minify**: Compress HTML output
- **Git revision date**: Show last modified dates
- **Mkdocstrings**: Auto-generate API documentation
## MCP Server Configuration
The MCP server can be configured through environment variables or code:
### Environment Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `MKDOCS_MCP_DOCS_PATH` | `../docs` | Path to documentation directory |
| `MKDOCS_MCP_LOG_LEVEL` | `INFO` | Logging level |
| `MKDOCS_MCP_CACHE_SIZE` | `100` | Resource cache size |
### Server Configuration
```python
from mkdocs_mcp.server import MkDocsMCPServer
from pathlib import Path
# Basic configuration
server = MkDocsMCPServer(docs_path=Path("./docs"))
# With custom settings
server = MkDocsMCPServer(
docs_path=Path("./docs"),
# Additional configuration options can be added here
)
```
### Resource Management
Configure how documentation resources are handled:
```python
from mkdocs_mcp.resources import DocumentationResourceManager
# Custom resource manager
resource_manager = DocumentationResourceManager(
docs_path=Path("./docs"),
# Configure caching, indexing, etc.
)
```
## Development Environment Configuration
### VSCode Settings
Key VSCode settings in `.vscode/settings.json`:
```json
{
"python.defaultInterpreterPath": "./venv/bin/python",
"python.linting.ruffEnabled": true,
"python.analysis.typeCheckingMode": "strict",
"python.testing.pytestEnabled": true,
"editor.formatOnSave": true
}
```
### DevContainer Configuration
DevContainer settings in `.devcontainer/devcontainer.json`:
```json
{
"name": "MkDocs MCP Development",
"build": {
"dockerfile": "Dockerfile",
"context": ".."
},
"runArgs": [
"--userns=keep-id",
"--security-opt", "label=disable"
],
"forwardPorts": [8000, 8001]
}
```
### Pre-commit Configuration
Pre-commit hooks in `.pre-commit-config.yaml`:
```yaml
repos:
- repo: https://github.com/astral-sh/ruff-pre-commit
rev: v0.1.9
hooks:
- id: ruff
args: [--fix, --exit-non-zero-on-fix]
- id: ruff-format
- repo: https://github.com/pre-commit/mirrors-mypy
rev: v1.8.0
hooks:
- id: mypy
additional_dependencies: [types-requests, types-PyYAML]
```
## Project Configuration
### Workspace Configuration
Root `pyproject.toml` configures the uv workspace:
```toml
[tool.uv.workspace]
members = ["mcp-server", "mkdocs-site"]
[tool.ruff]
target-version = "py311"
line-length = 88
select = ["E", "W", "F", "I", "B", "C4", "UP"]
[tool.mypy]
python_version = "3.11"
check_untyped_defs = true
disallow_untyped_defs = true
strict_equality = true
```
### Dependency Management
Each workspace member has its own `pyproject.toml`:
#### MkDocs Site Dependencies
```toml
# mkdocs-site/pyproject.toml
dependencies = [
"mkdocs>=1.5.3",
"mkdocs-material>=9.4.0",
"mkdocs-mermaid2-plugin>=1.1.0",
"mkdocstrings[python]>=0.24.0",
]
```
#### MCP Server Dependencies
```toml
# mcp-server/pyproject.toml
dependencies = [
"mcp>=1.0.0",
"pydantic>=2.5.0",
"anyio>=4.0.0",
"aiofiles>=23.0.0",
]
```
## Customization Options
### Theme Customization
Add custom CSS in `mkdocs-site/docs/stylesheets/extra.css`:
```css
:root {
--md-primary-fg-color: #1976d2;
--md-accent-fg-color: #2196f3;
}
.custom-class {
background-color: var(--md-primary-fg-color--light);
}
```
### Navigation Structure
Configure navigation in `mkdocs.yml`:
```yaml
nav:
- Home: index.md
- Getting Started:
- Installation: getting-started/installation.md
- Quick Start: getting-started/quick-start.md
- Configuration: getting-started/configuration.md
- MCP Server:
- Overview: mcp-server/overview.md
- API Reference: api/
```
### Search Configuration
Customize search behavior:
```yaml
plugins:
- search:
separator: '[\s\-,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
lang: en
```
### Code Highlighting
Configure syntax highlighting:
```yaml
markdown_extensions:
- pymdownx.highlight:
anchor_linenums: true
line_spans: __span
pygments_lang_class: true
- pymdownx.inlinehilite
```
## Production Configuration
### Docker/Podman Configuration
For production deployment:
```dockerfile
# Production Dockerfile
FROM python:3.12-slim
# Install uv
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
# Copy and install dependencies
COPY pyproject.toml uv.lock ./
RUN uv sync --no-dev
# Copy source code
COPY . .
# Set production environment
ENV PYTHONPATH="/app"
ENV MKDOCS_MCP_LOG_LEVEL="WARNING"
# Run MCP server
CMD ["python", "-m", "mkdocs_mcp.server"]
```
### CI/CD Configuration
Example GitHub Actions workflow:
```yaml
name: CI/CD
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v4
with:
python-version: '3.11'
- run: make ci-check
deploy:
if: github.ref == 'refs/heads/main'
needs: test
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: make docs-build
- uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./mkdocs-site/site
```
## Environment-Specific Settings
### Development
```bash
export MKDOCS_MCP_LOG_LEVEL=DEBUG
export MKDOCS_MCP_CACHE_SIZE=10
```
### Testing
```bash
export MKDOCS_MCP_LOG_LEVEL=WARNING
export MKDOCS_MCP_DOCS_PATH="/tmp/test-docs"
```
### Production
```bash
export MKDOCS_MCP_LOG_LEVEL=ERROR
export MKDOCS_MCP_CACHE_SIZE=1000
```
## Troubleshooting Configuration
### Common Issues
**MkDocs build fails**
- Check `mkdocs.yml` syntax
- Verify all referenced files exist
- Check plugin compatibility
**MCP server startup fails**
- Verify docs directory exists
- Check Python path configuration
- Review log output for errors
**DevContainer issues**
- Verify Podman installation
- Check file permissions
- Review DevContainer logs
### Debugging Configuration
Enable debug logging:
```python
import logging
logging.basicConfig(level=logging.DEBUG)
```
Check configuration values:
```python
from mkdocs_mcp.server import MkDocsMCPServer
server = MkDocsMCPServer()
print(f"Docs path: {server.docs_path}")
```
## Next Steps
- Review [API Reference](../api/) for detailed configuration options
- Explore [Examples](../examples/basic-usage.md) for common configurations
- Check [Contributing Guide](../contributing.md) for development configuration
