# Install (requires Python 3.10+)
pip install ragdoc-mcp
# or with uv
uvx ragdoc-mcp

# Profile a corpus
ragdoc profile_corpus --path ./my-docs --sample-size 200

# Create a plan
ragdoc plan_rag --path ./my-docs --privacy local_only --hardware cpu

# Build index (after reviewing plan)
ragdoc build_index --plan-id <plan_id>

# Search
ragdoc search --collection my-docs --query "How does the retry logic work?" --k 8

# Diagnose a failure
ragdoc diagnose_failure --collection my-docs --question "What is the timeout?" --expected-source "config/retry.py"

{
  "mcpServers": {
    "ragdoc": {
      "command": "uvx",
      "args": ["ragdoc-mcp"],
      "env": {
        "RAGDOC_BASE_DIR": "~/.ragdoc"
      }
    }
  }
}

hermes mcp add ragdoc --command uvx --args ragdoc-mcp --env RAGDOC_BASE_DIR=~/.ragdoc

src/ragdoc/
├── server.py          # FastMCP server with 7 tools + resources + prompts
├── parsers/           # Fast (pypdf), Docling (layout/tables/formulas/OCR), LlamaParse (cloud)
├── chunkers/          # Heading-aware, token window, table-per-chunk, formula-preserving, AST code
├── embedders/         # fastembed (bge, nomic, e5, jina-code) + sentence-transformers
├── stores/            # LanceDB (default), Qdrant, pgvector adapters
├── retrieval/         # Hybrid RRF + cross-encoder rerank
├── diagnose/          # 7-stage tracer with evidence and fix proposals
├── planner/           # profile_corpus + plan_rag with decision log
├── eval/              # domain_eval + verify_fix
├── security/          # Path allowlist, untrusted text wrapper, instruction detection
├── config/            # Models YAML, settings, scale tiers
└── schemas/           # Pydantic models for all tool I/O

# Clone and setup
git clone https://github.com/your-org/ragdoc-mcp
cd ragdoc-mcp

# Install dev dependencies
uv sync --dev

# Run tests
pytest

# Lint
ruff check .
mypy src

# Type check
mypy src/ragdoc

ragdoc-mcp/
├── src/ragdoc/           # Main package
├── tests/
│   ├── unit/             # Unit tests
│   ├── integration/      # Integration tests
│   └── fixtures/         # Test documents and failure fixtures
├── skills/rag-doctor/    # Claude Code skill
├── docs/                 # Documentation
├── .github/workflows/    # CI/CD
├── pyproject.toml        # Package config
├── server.json           # MCP registry metadata
├── Dockerfile            # Multi-stage Docker image
├── LICENSE               # MIT
└── README.md             # This file

@software{ragdoc-mcp,
  title = {RAG Doctor MCP: Cross-Stage Diagnosis for Retrieval Pipelines},
  year = {2026},
  url = {https://github.com/your-org/ragdoc-mcp}
}