jberends/servemd repository overview

⁠servemd

Serve docs to humans and AI.

Beautiful markdown documentation with native llms.txt support. Zero configuration, production-ready.

⁠Why servemd?

Unlike basic markdown servers, servemd is built for the AI era:

Markdown → Beautiful HTML    → Humans
         → llms.txt          → AI/LLMs
         → llms-full.txt     → Complete AI context
         → /mcp endpoint     → AI assistants (250x less context)

For humans: Nuxt UI-inspired design, three-column layout, zero configuration. For AI: Native llms.txt support, structured context, ready for the Model Context Protocol era.

⁠✨ Features

• 🎨 Beautiful Design — Nuxt UI-inspired three-column layout (sidebar, content, TOC)
• 🤖 AI-Native — Built-in llms.txt and llms-full.txt for Claude, ChatGPT, Cursor, etc.
• 🔌 MCP Support — Model Context Protocol endpoint for interactive AI queries (250x less context)
• ✨ Zero Configuration — Drop .md files and go
• ⚡ Fast — Smart disk caching, <5ms cached responses
• 🐳 Docker Ready — Production-optimized container
• 🧪 Well Tested — 208 tests, 100% passing
• 📱 Responsive — Mobile, tablet, and desktop support

⁠🚀 Quick Start

⁠Install

pip install servemd

⁠Run

# Serve docs from current directory
servemd

# Or specify a directory
servemd ./my-docs

Visit http://localhost:8080⁠ — your documentation is live.

Live demo: https://servemd.me.cloudns.cl⁠

⁠Alternative: Docker

# Quick start - mount your docs
docker run -p 8080:8080 -v $(pwd)/docs:/app/__docs__ jberends/servemd:latest

# Or build custom image with docs baked in
FROM jberends/servemd:latest
COPY ./my-docs/ /app/__docs__/

See DOCKER_README.md⁠ for complete Docker usage guide.

⁠Alternative: uvx (no install)

uvx servemd ./my-docs

📚 Complete Setup Guide →⁠

⁠For Contributors

git clone https://github.com/servemd/servemd
cd servemd
uv sync
uv run python -m docs_server

⁠🤖 AI-Native: llms.txt & MCP Support

servemd automatically serves your docs in AI-friendly formats:

⁠llms.txt - Static Index

Example: Give an AI assistant your docs:

"Read my documentation at https://docs.example.com/llms.txt"

The AI gets a structured index with absolute URLs to every page. For complete context, use /llms-full.txt which includes all page content inline.

⁠MCP - Interactive Queries (Recommended for AI)

Model Context Protocol provides on-demand documentation access with 250x less context:

POST /mcp
{
  "method": "tools/call",
  "params": {
    "name": "search_docs",
    "arguments": {
      "query": "authentication",
      "limit": 5
    }
  }
}

Benefits:

• 🎯 Precise — AI queries only what it needs
• ⚡ Fast — No sending entire documentation every time
• 💰 Cost-effective — 250x less tokens than llms-full.txt
• 🔍 Smart — Full-text search with Whoosh

Available MCP Tools:

• search_docs — Semantic search across documentation
• get_doc_page — Retrieve specific pages with section filtering
• list_doc_pages — List all available pages by category

See MCP Integration Guide⁠ for details.

⁠✨ Key Features

⁠For Humans

• 🎨 Nuxt UI-inspired three-column layout (sidebar, content, TOC)
• 🎨 Syntax highlighting with Pygments
• 🎨 Responsive design (mobile, tablet, desktop)
• 🎨 Dark mode ready
• ✅ Tables, task lists, footnotes, Mermaid diagrams

⁠For AI

• 🤖 llms.txt — Structured documentation index (5KB)
• 🤖 llms-full.txt — Complete context export (500KB+)
• 🔌 MCP endpoint — Interactive queries via Model Context Protocol
  • 250x less context than llms-full.txt
  • Full-text search with Whoosh
  • On-demand page retrieval
  • Section filtering
• 🤖 Automatic link transformation to absolute URLs
• 🤖 Curated or auto-generated indexes

⁠For Developers

• ⚡ Fast — disk caching, <5ms cached responses
• 🔥 Hot reload in debug mode
• 🔧 Zero configuration required
• 🐍 Python 3.11-3.14, FastAPI, Pydantic
• 🧪 208 tests, 100% passing

⁠📁 File Structure

Your documentation needs just 3 required files:

docs/
├── index.md       # Homepage (required)
├── sidebar.md     # Navigation (required)
├── topbar.md      # Top bar (required)
├── llms.txt       # AI index (optional)
└── your-content.md # Your pages

⁠⚙️ Configuration

Configure via environment variables:

DOCS_ROOT=./docs                 # Documentation directory
CACHE_ROOT=./__cache__           # Cache directory
PORT=8080                        # Server port
DEBUG=true                       # Enable debug mode
BASE_URL=https://docs.site.com   # Base URL for llms.txt
MCP_ENABLED=true                 # Enable MCP endpoint (default: true)
MCP_RATE_LIMIT_REQUESTS=120      # MCP rate limit (requests per window)
MCP_RATE_LIMIT_WINDOW=60         # MCP rate limit window (seconds)

See Configuration Guide⁠ for details.

⁠🎯 Use Cases

servemd is perfect for:

• SaaS Documentation — Customer-facing support docs with AI assistant integration
• Open Source Projects — Self-hosted, beautiful docs
• Internal Teams — Company knowledge bases and wikis
• API Documentation — REST/GraphQL API docs
• Technical Writing — Blogs and tutorials

⁠📘 Deployment

⁠🛠️ Examples

Check examples/⁠ for ready-to-use templates:

• Dockerfile.user-template — Custom Docker image
• docker-compose.user.yml — Docker Compose setup
• k8s-simple.yaml — Kubernetes deployment

⁠🏗️ Architecture

Clean, modular FastAPI application:

src/docs_server/
├── config.py           # Settings & environment
├── helpers.py          # Utilities & navigation
├── caching.py          # Smart caching
├── markdown_service.py # Markdown rendering
├── llms_service.py     # LLMs.txt generation
├── templates.py        # HTML templates
├── main.py             # FastAPI routes
└── mcp/                # Model Context Protocol
    ├── server.py       # MCP JSON-RPC handler
    ├── tools.py        # MCP tools (search, get, list)
    ├── search.py       # Full-text search with Whoosh
    └── indexer.py      # Documentation indexing

⁠🧪 Testing

uv run pytest tests/ -v

# 208 tests, 100% passing ✅

⁠🔧 Development

git clone https://github.com/servemd/servemd
cd servemd
uv sync --group dev
uv run pytest tests/ -v
DEBUG=true uv run python -m docs_server

⁠📊 Performance

⁠📖 Documentation

• Quick Setup⁠ — Get running in 5 minutes
• Markdown Features⁠ — Tables, code blocks, diagrams
• LLMs.txt Guide⁠ — AI assistant integration
• MCP Integration⁠ — Interactive queries for LLMs
• Navigation⁠ — Sidebar and topbar configuration
• Configuration⁠ — Environment variables
• API Reference⁠ — HTTP endpoints

⁠🙋 Support

• 📖 Documentation: docs.servemd.dev⁠ or run locally
• 🚀 Live demo: servemd.me.cloudns.cl⁠
• 🐛 Issues: GitHub Issues⁠
• 💬 Discussions: GitHub Discussions⁠

⁠📜 License

MIT License — use freely for any project.

⁠🎉 Get Started Now

pip install servemd
servemd ./my-docs

Visit http://localhost:8080⁠ — beautiful docs for humans, structured context for AI.