# Documentation MCP Server
A Model Context Protocol (MCP) server that enables AI assistants to navigate and query documentation through hierarchical structures, supporting markdown files with YAML frontmatter and OpenAPI 3.x specifications.
## Features
- **Hierarchical Navigation**: Navigate documentation organized in nested directory structures with unlimited depth
- **Markdown Support**: Parse markdown files with YAML frontmatter metadata (title, tags, category, order)
- **OpenAPI Integration**: Load and query OpenAPI 3.x specifications as documentation resources
- **Intelligent Search**: Full-text search with metadata filtering and hierarchical context
- **Web Interface**: Built-in web server provides browser-based access to documentation with the same tools available to LLMs
- **Cross-Platform**: Works with Claude Desktop, VS Code/GitHub Copilot, and other MCP-compatible AI assistants
- **Security**: Built-in path validation, query sanitization, and audit logging
- **Performance**: Caching with TTL and automatic file change detection
## Quick Start
### Installation
**Minimal (No Semantic Search):**
```bash
# Install base package - keyword search only, smallest footprint
pip install your-docs-mcp
```
**With Vector Search (CPU - Recommended):**
```bash
# Install with semantic search using CPU-only PyTorch (~200MB vs ~1.5GB)
pip install "your-docs-mcp[vector]" --extra-index-url https://download.pytorch.org/whl/cpu
```
**With Vector Search (GPU/CUDA):**
```bash
# Install with semantic search using CUDA-enabled PyTorch
# Only use if you have NVIDIA GPU and need faster embeddings
pip install "your-docs-mcp[vector-gpu]"
```
**From Source:**
```bash
git clone https://github.com/esola-thomas/Markdown-MCP
cd Markdown-MCP
# CPU vector search (recommended)
pip install -e ".[vector]" --extra-index-url https://download.pytorch.org/whl/cpu
# Or minimal (no vector search)
pip install -e .
```
> **Note:** The `[vector]` extra installs ChromaDB and Sentence Transformers for semantic search.
> Without it, the server still works but uses keyword-based search only.
### Basic Configuration
1. Set your documentation root directory:
```bash
export DOCS_ROOT=/path/to/your/docs
```
2. Start the server:
```bash
# MCP + Web server (recommended for development)
your-docs-server
# MCP server only (for AI clients like Claude Desktop)
your-docs-mcp
# Web server only (REST API + browser UI)
your-docs-web
```
**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
```json
{
"mcpServers": {
"docs": {
"command": "your-docs-mcp",
"env": {
"DOCS_ROOT": "/absolute/path/to/your/docs"
}
}
}
}
```
**VS Code** (create `.vscode/mcp.json`):
```json
{
"servers": {
"docs": {
"command": "your-docs-mcp",
"env": {
"DOCS_ROOT": "${workspaceFolder}/docs"
}
}
}
}
```
**Other MCP Clients**: Use the `your-docs-mcp` command with `DOCS_ROOT` environment variable.
## 🛠️ Available MCP Tools
Once connected, AI assistants can use these tools:
| Tool | Description |
|------|-------------|
| `search_documentation` | Full-text search with relevance scoring and hierarchical context |
| `navigate_to` | Navigate to specific docs by URI (e.g., `docs://guides/quickstart`) |
| `get_table_of_contents` | Get complete documentation hierarchy |
| `get_document` | Retrieve full document content with metadata |
| `search_by_tags` | Filter documentation by tags (e.g., `[api, authentication]`) |
| `get_all_tags` | List all available tags across documentation |
| `generate_pdf_release` | Generate PDF documentation with custom branding |
## 📄 Supported Documentation Formats
**Markdown with YAML frontmatter**:
```markdown
---
title: Getting Started Guide
tags: [guide, quickstart]
category: guides
order: 1
---
# Getting Started
Your content here...
```
**OpenAPI 3.x Specifications** (`.yaml`, `.json`):
```yaml
openapi: 3.0.3
info:
title: My API
version: 1.0.0
paths:
/users:
get:
summary: List users
```
## 📊 Key Features
- **🗂️ Hierarchical Navigation**: Unlimited nesting depth, automatic breadcrumbs
- **🔍 Intelligent Search**: Full-text + semantic search (with vector extra)
- **📝 Markdown & OpenAPI**: Parse markdown with frontmatter + OpenAPI specs
- **🌐 Web Interface**: Browser-based documentation access (same tools as AI)
- **📑 PDF Generation**: Create professional PDF releases with branding
- **🔒 Security**: Path validation, query sanitization, audit logging
- **⚡ Performance**: Smart caching with automatic invalidation
- **🔌 Cross-Platform**: Works with Claude Desktop, VS Code, any MCP client
## 🌐 Web Interface & REST API
### Access the Web UI
```bash
your-docs-server # Starts MCP + web server
# Or
your-docs-web # Web server only (no MCP)
```
Open **http://localhost:8123** in your browser.
**Features**:
- 🔍 Search with relevance scoring and highlighted excerpts
- 📚 Browse hierarchical table of contents
- 🏷️ Filter by tags
- 📖 View formatted documents
- 📊 Real-time stats
### REST API
**Endpoints**:
```bash
GET /api/health # Server status
POST /api/search # Search docs
POST /api/navigate # Navigate to URI
POST /api/toc # Table of contents
POST /api/search-by-tags # Tag search
POST /api/document # Get document
POST /api/pdf-generate # Generate PDF
```
**Example**:
```bash
curl "http://localhost:8123/api/search?query=authentication"
curl -X POST "http://localhost:8123/api/pdf-generate" \
-H "Content-Type: application/json" \
-d '{"title": "My Docs", "subtitle": "v1.0", "version": "1.0.0"}'
```
## 📑 PDF Generation
Generate professional PDF documentation releases:
```bash
# Via MCP (ask your AI assistant):
"Generate a PDF of all documentation titled 'Product Docs' version 1.0"
# Via REST API:
curl -X POST "http://localhost:8123/api/pdf-generate" \
-H "Content-Type: application/json" \
-d '{
"title": "Product Documentation",
"subtitle": "Complete Technical Guide",
"author": "Your Team",
"version": "1.0.0",
"confidential": false
}'
# Via command line script:
DOCS_ROOT=/path/to/docs ./scripts/generate-docs-pdf.sh \
--title "My Docs" \
--subtitle "Technical Guide" \
--author "Team Name" \
1.0.0
```
**PDF Features**:
- 📚 Automatic table of contents with page numbers
- 🎨 Custom branding (title, subtitle, author, owner)
- 🔒 Confidential markings (watermark, headers/footers)
- 🔗 Preserves document hierarchy and navigation
- 📄 Professional LaTeX rendering via Pandoc
**Requirements** (system packages):
```bash
# Ubuntu/Debian
sudo apt install pandoc texlive-xetex texlive-latex-extra
# macOS
brew install pandoc basictex
```
## ⚙️ Configuration
### Environment Variables
```bash
# Required
DOCS_ROOT=/path/to/docs # Documentation root directory
# Optional
MCP_DOCS_CACHE_TTL=3600 # Cache TTL in seconds
MCP_DOCS_SEARCH_LIMIT=10 # Max search results
MCP_DOCS_OPENAPI_SPECS=/path/to/spec.yaml # OpenAPI spec paths (comma-separated)
# Web Server (for your-docs-server)
MCP_DOCS_ENABLE_WEB_SERVER=true # Enable web interface
MCP_DOCS_WEB_HOST=127.0.0.1 # Web server host
MCP_DOCS_WEB_PORT=8123 # Web server port
# Logging
LOG_LEVEL=INFO # DEBUG, INFO, WARNING, ERROR
```
### Multi-Source Configuration
For complex setups, create `.mcp-docs.yaml`:
```yaml
sources:
- path: ./docs
category: guides
label: User Guides
recursive: true
- path: ./api-specs
category: api
label: API Reference
format_type: openapi
cache:
ttl: 3600
m🔒 Security Features
- ✅ **Path Validation**: Prevents directory traversal attacks
- ✅ **Hidden Files Exclusion**: `.` files excluded by default
- ✅ **Query Sanitization**: Search queries sanitized against injection
- ✅ **Audit Logging**: All file access logged for security review
## 🧪 Development
### Setup
```bash
git clone https://github.com/esola-thomas/your-docs-mcp
cd your-docs-mcp
pip install -e ".[dev,vector,pdf]" --extra-index-url https://download.pytorch.org/whl/cpu
```
### Testing
```bash
pytest # Run all tests
pytest -m unit # Unit tests only
pytest --cov=docs_mcp # With coverage
```
### Code Quality
```bash
ruff check docs_mcp # Linting
mypy docs_mcp # Type checking
pytest --cov=docs_mcp --cov-report=html # Coverage report
```
### Project Structure
```
docs_mcp/
├── models/ # Data models (Document, Category, OpenAPI)
├── handlers/ # MCP protocol handlers (tools, resources)
├── services/ # Core logic (markdown, search, hierarchy)
├── security/ # Security validation and sanitization
└── utils/ # Logging and utilities
```
## Claude Code Plugin
This repo includes a Claude Code plugin with skills for managing documentation files.
### Install the Plugin
```bash
claude --plugin-dir /path/to/your-docs-mcp/docs-plugin
```
### Available Skills
| Skill | Description |
|-------|-------------|
| `docs-plugin/skills/doc-create` | Create new docs with proper frontmatter |
| `docs-plugin/skills/doc-validate` | Validate docs against standards |
| `docs-plugin/skills/doc-template` | Generate doc templates |
| `docs-plugin/skills/doc-search` | Search documentation content |
See [`docs-plugin/README.md`](docs-plugin/README.md) for full details.
## Contributing
Contributions are welcome! Please see the contribution guidelines for more information.
## License
MIT License - see LICENSE file for details
## Links
- [Documentation](https://github.com/esola-thomas/Markdown-MCP/tree/main/docs)
- [Issue Tracker](https://github.com/esola-thomas/Markdown-MCP/issues)
- [MCP Documentation](https://modelcontextprotocol.io)
