your-docs-mcp 1.1.0

Model Context Protocol server for hierarchical documentation navigation with markdown and OpenAPI support

Documentation MCP Server

Turn your documentation into an intelligent, AI-accessible knowledge base

Give AI assistants like Claude, ChatGPT, and Copilot structured access to your documentation through the Model Context Protocol (MCP). Navigate hierarchical docs, search semantically, generate PDFs, and browse via web interface—all from a single server.

⚡ Quick Start (60 seconds)

# Install from PyPI
pip install your-docs-mcp

# Point to your docs folder
export DOCS_ROOT=/path/to/your/docs

# Start MCP server + web interface
your-docs-server

That's it! Your docs are now:

• ✅ Accessible to AI assistants via MCP
• ✅ Browseable at http://localhost:8123
• ✅ Searchable with full-text and metadata filters
• ✅ Ready for PDF generation

🎯 What Can You Do?

For AI Assistants

Once connected, ask your AI:

• "Show me the getting started guide"
• "List all API endpoints for user management"
• "Search for authentication documentation"
• "Generate a PDF of all documentation"

For Humans

• Browse documentation in your browser at http://localhost:8123
• Search with semantic understanding (with [vector] extra)
• Generate PDF releases with custom branding
• Access documentation via REST API

📦 Installation

From PyPI (Recommended)

Basic install (keyword search only):

pip install your-docs-mcp

With semantic search (CPU-optimized, recommended):

pip install "your-docs-mcp[vector]" --extra-index-url https://download.pytorch.org/whl/cpu

With PDF generation:

pip install "your-docs-mcp[pdf]"

# Requires system dependencies
# Ubuntu/Debian: sudo apt install pandoc texlive-xetex texlive-latex-extra
# macOS: brew install pandoc basictex

All features:

pip install "your-docs-mcp[vector,pdf]" --extra-index-url https://download.pytorch.org/whl/cpu

From Source

git clone https://github.com/esola-thomas/your-docs-mcp
cd your-docs-mcp
pip install -e ".[vector,pdf]" --extra-index-url https://download.pytorch.org/whl/cpu

🔧 Setup for AI Assistants

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "docs": {
      "command": "your-docs-mcp",
      "env": {
        "DOCS_ROOT": "/absolute/path/to/your/docs"
      }
    }
  }
}

VS Code (create .vscode/mcp.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:

---
title: Getting Started Guide
tags: [guide, quickstart]
category: guides
order: 1
---

# Getting Started

Your content here...

OpenAPI 3.x Specifications (.yaml, .json):

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

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:

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:

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:

# 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):

# Ubuntu/Debian
sudo apt install pandoc texlive-xetex texlive-latex-extra

# macOS
brew install pandoc basictex

⚙️ Configuration

Environment Variables

# 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:

sources:
  - path: ./docs
    category: guides
    label: User Guides
    recursive: true

  - path: ./api-specs
    category: api
    label: API Reference
    format_type: openapi

cache:
  ttl: 3600
  max_memory_mb: 500

security:
  allow_hidden_files: false
  audit_logging: true

Running Modes

# 1. MCP Server + Web Interface (recommended)
your-docs-server

# 2. MCP Server only (for AI clients)
your-docs-mcp

# 3. Web Server only (no MCP)
your-docs-web

🔒 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

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

pytest                              # Run all tests
pytest -m unit                      # Unit tests only
pytest --cov=docs_mcp              # With coverage

Code Quality

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

📚 Example: Try It Now

This repo includes sample docs in the docs/ folder:

# Clone and test
git clone https://github.com/esola-thomas/your-docs-mcp
cd your-docs-mcp
export DOCS_ROOT=$(pwd)/docs
your-docs-server

The sample docs demonstrate:

• ✅ Hierarchical structure with nested categories
• ✅ Markdown with YAML frontmatter
• ✅ OpenAPI specification integration
• ✅ Best practices for organization

💡 Tips & Best Practices

Document Organization:

docs/
├── README.md           # Overview (processed first)
├── guides/
│   ├── README.md       # Category overview
│   ├── quickstart.md
│   └── advanced.md
└── api/
    ├── README.md
    └── reference.md

Frontmatter:

---
title: Clear, Descriptive Title
tags: [category, topic, level]
category: guides  # Maps to directory structure
order: 1          # Controls display order
---

For Best Results:

• Use descriptive titles in frontmatter
• Tag documents consistently
• Organize by topic in subdirectories
• Include README.md in each category
• Keep documents focused and modular

🤝 Contributing

Contributions welcome! See Contributing Guide for details.

📄 License

MIT License - see LICENSE for details.

🔗 Links

• Homepage: https://github.com/esola-thomas/your-docs-mcp
• Documentation: docs/
• Issues: https://github.com/esola-thomas/your-docs-mcp/issues
• MCP Spec: https://modelcontextprotocol.io
• PyPI: https://pypi.org/project/your-docs-mcp/

---

Questions? Open an issue or check the documentation.