Complete Technical Documentation - Transform Your Documents & Emails into an AI-Powered Knowledge Base
Ragdex (formerly Personal Document Library MCP Server) is a sophisticated Model Context Protocol server that enables Claude Desktop to access and analyze a personal collection of documents and emails through RAG (Retrieval-Augmented Generation). The system features a complete MCP protocol implementation with tools, prompts, and resources, supporting multiple document formats and intelligent email filtering.
PDFs, Word, EPUB, MOBI, EMLX, OLM
→Background Processing & OCR
→768-dim Vector Storage
→17 Tools + 5 Prompts + 4 Resources
→AI Assistant Interface
Properly structured as personal_doc_library package with pyproject.toml configuration
ragdex, ragdex-mcp, ragdex-index, ragdex-webpip install ragdexpip install -e .pip install -e ".[document-processing,services]"Full Model Context Protocol implementation with lazy initialization for < 1s startup
src/personal_doc_library/servers/mcp_complete_server.pyCore retrieval-augmented generation system with vector embeddings
sentence-transformers/all-mpnet-base-v2High-performance vector database for document embeddings
CHROMA_TELEMETRY=falseComprehensive file format support with intelligent processing
Automatic monitoring and indexing services
ragdex command)$PERSONAL_LIBRARY_DOC_PATH - Document library location$PERSONAL_LIBRARY_DB_PATH - Vector database (55MB for 68 books)$PERSONAL_LIBRARY_LOGS_PATH - Application and service logs# Using uv (recommended, faster)
uv venv ~/ragdex_env
uv pip install ragdex
# Or standard pip
python -m venv ~/ragdex_env
source ~/ragdex_env/bin/activate
pip install ragdex
# With optional extras
pip install ragdex[document-processing,services]# Clone repository
git clone https://github.com/hpoliset/ragdex
cd ragdex
# Install in editable mode
pip install -e .
# Or with extras
pip install -e ".[document-processing,services]"
# Use CLI commands
ragdex --help
ragdex-mcp # Start MCP server
ragdex-index # Start indexer
ragdex-web # Start web dashboardLocation: ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"ragdex": {
"command": "/Users/YOUR_USERNAME/ragdex_env/bin/ragdex-mcp",
"env": {
"PYTHONUNBUFFERED": "1",
"CHROMA_TELEMETRY": "false",
"PERSONAL_LIBRARY_DOC_PATH": "/path/to/documents",
"PERSONAL_LIBRARY_DB_PATH": "/path/to/database",
"PERSONAL_LIBRARY_LOGS_PATH": "/path/to/logs"
}
}
}
}# Core paths
export PERSONAL_LIBRARY_DOC_PATH="/path/to/documents"
export PERSONAL_LIBRARY_DB_PATH="/path/to/database"
export PERSONAL_LIBRARY_LOGS_PATH="/path/to/logs"
# Email settings (v0.2.0+)
export PERSONAL_LIBRARY_INDEX_EMAILS=true
export PERSONAL_LIBRARY_EMAIL_SOURCES=apple_mail,outlook_local
export PERSONAL_LIBRARY_EMAIL_MAX_AGE_DAYS=365
export PERSONAL_LIBRARY_EMAIL_EXCLUDED_FOLDERS=Spam,Junk,Trash,Deleted Items,Drafts
# Performance tuning
export INDEXING_MEMORY_LIMIT_GB=8
export CHROMA_TELEMETRY=false
export TOKENIZERS_PARALLELISM=falseScan for supported formats
→Check for changes
→1200 chars, 150 overlap
→practice, energy_work, philosophy, general
→768-dim vectors
→ChromaDB + Index
_instance class variable for reuseSmart Filtering: Automatically excludes marketing, promotional, and spam emails
Issue: LaunchAgent services restricted by sandboxing
Solution: Use shell script wrapper (scripts/index_monitor_service.sh)
Details: See docs/LAUNCHAGENT_PERMISSIONS_SOLUTION.md
venv_mcp/bin/python for consistencyragdex warmup before heavy usage to pre-load modelsragdex manage-failed to handle problematic documentsINDEXING_MEMORY_LIMIT_GB for large libraries