Enhanced Dash MCP Server
🎯 What is this?
This is a Model Context Protocol (MCP) server that bridges Dash - the popular offline API documentation browser for macOS - with Claude Desktop and other agentic development environments. MCP is an open protocol that enables AI assistants like Claude and Warp to securely access local resources and tools on your computer through structured APIs.
In simple terms: This server lets Claude and other agentic coding tools instantly search and read your local Dash documentation (200+ API docs, cheat sheets, and guides) to provide accurate, version-specific answers based on the actual documentation you have installed - all offline, private, and blazing fast.
📚 About Dash
Dash is an API Documentation Browser and Code Snippet Manager for macOS that gives you instant offline access to 200+ API documentation sets. It's the go-to tool for developers who want fast, searchable, offline documentation without relying on internet connectivity or dealing with slow web searches.
🔗 Why This Integration Matters
- Offline-First: Access all your documentation without internet connectivity
- Version-Specific: Get answers based on the exact versions of libraries you have installed
- Privacy-Focused: Your code context and queries never leave your machine
- Lightning Fast: Sub-second searches through gigabytes of documentation
- Context-Aware: Claude understands your project stack and suggests relevant docs automatically
See CHANGELOG.md for version history.
🚀 Features
Core Capabilities
- 🔍 Intelligent Search - Fuzzy matching with typo tolerance and smart ranking
- 📚 Content Extraction - Clean text extraction from HTML, Markdown, and text docs
- ⚡ Multi-Tier Caching - Memory + disk caching for lightning-fast repeated searches
- 🎯 Project Awareness - Automatically detects your tech stack and prioritizes relevant docs
- 🛠️ Implementation Guidance - Best practices and patterns for specific features
- 📈 Migration Support - Version upgrade documentation and breaking changes
- 🔄 Latest API Reference - Current API docs with practical examples
Developer Workflow Integration
- Warp Terminal - Native command palette and workflow integration
- tmux - Background server execution across terminal sessions
- Neovim - Documentation access while coding via Claude
- Oh-My-Zsh - Enhanced aliases and productivity shortcuts
- Git Integration - Repository-aware documentation suggestions
Supported Technologies
JavaScript/TypeScript, React, Next.js, Vue.js, Angular, Node.js, Python, Django, Flask, FastAPI, pandas, NumPy, and many more through Dash docsets.
📋 Prerequisites
- macOS with Dash app installed
- Python 3.8+ (Python 3.11+ recommended)
- Dash docsets downloaded (JavaScript, Python, React, etc.)
- Claude with MCP support
- tmux (recommended for background execution)
⚠️ Important Dependency Requirements
This server requires Pydantic v2.0+ for MCP compatibility. If you have existing projects with Pydantic v1.x, you may need to:
- Use a virtual environment (recommended)
- Check for compatibility with other tools (like
pieces-os-client) - Consider using separate Python environments for different projects
# Check your current Pydantic version
pip show pydantic
# If you have v1.x, you'll need to upgrade
pip install "pydantic>=2.0.0"
📦 Dependencies
The setup script automatically installs all required dependencies, including:
mcp>=1.9.0- Model Context Protocol frameworkpydantic>=2.0.0- Data validation (required for MCP compatibility)beautifulsoup4>=4.12.0- HTML content extractionfuzzywuzzy>=0.18.0- Fuzzy string matchingpython-levenshtein>=0.27.0- Fast string similarityaiofiles>=24.0.0- Async file operationsaiohttp>=3.11.0- Async HTTP clientrapidfuzz>=3.0.0- Enhanced fuzzy matchingtyping-extensions>=4.12.0- Extended type hints
⚡ Quick Start
🔄 Important: Cache Clearing for Existing Users
If you're upgrading from a previous version, the server now discovers 8x more docsets (364 instead of 45) by searching the entire Dash directory tree. To see all the new docsets, clear the cache:
# Clear the docset cache to discover newly available docsets
rm -rf ~/.cache/dash-mcp/
# Then restart your server
dash-mcp-restart
# or
cd ~/enhanced-dash-mcp && ./start-dash-mcp.sh --test
What changed:
- Before: Searched only
~/Library/Application Support/Dash/DocSets/(45 docsets) - After: Searches entire
~/Library/Application Support/Dash/directory (364 docsets) - Benefit: Now includes User Contributed, Python DocSets, Versioned DocSets, and more!
See docs/help.md for a brief overview of how to run the server.
1. Clone & Setup
# Clone or download the project files
mkdir ~/enhanced-dash-mcp && cd ~/enhanced-dash-mcp
# Make setup script executable
chmod +x scripts/setup-dash-mcp.sh
# Run automated setup
./scripts/setup-dash-mcp.sh
The script prompts for an installation directory. Press Enter to accept the
default path or provide a custom location. The default is ~/enhanced-dash-mcp.
2. Configure Claude
Add this to Claude's MCP settings:
{
"mcpServers": {
"enhanced-dash-mcp": {
"command": "$DASH_MCP_DIR/venv/bin/python3",
"args": [
"$DASH_MCP_DIR/enhanced_dash_server.py"
],
"env": {}
}
}
}
3. Start & Test
# Add shell enhancements
echo "source ~/enhanced-dash-mcp/dash-mcp-aliases.sh" >> ~/.zshrc
source ~/.zshrc
# Start the server
dash-mcp-start
# Test with Claude
# "Search for React useState hook documentation"
🎮 Usage
Basic Documentation Search
# Ask Claude:
"Search for Python pandas DataFrame methods"
"Find React hooks best practices"
"Get FastAPI routing documentation with examples"
Project-Aware Intelligence
# Navigate to your project directory, then ask Claude:
"Analyze my current project and find relevant documentation"
"Get implementation guidance for user authentication in my React app"
"What are the best practices for my current Django project?"
Migration & Upgrade Help
# Ask Claude:
"Get migration docs for upgrading from React 17 to 18"
"Find Django 4.2 upgrade guide and breaking changes"
"Show me Next.js 13 to 14 migration documentation"
API Reference with Examples
# Ask Claude:
"Get latest pandas DataFrame.merge API reference with examples"
"Show me React useEffect hook documentation and patterns"
"Find Express.js middleware documentation with use cases"
🛠️ Advanced Setup
Warp Terminal Integration
For enhanced Warp Terminal support:
# Run Warp-specific setup
chmod +x scripts/setup-warp-dash-mcp.sh
./scripts/setup-warp-dash-mcp.sh
# Use Command Palette (⌘K):
dash-mcp-start
dash-analyze-project
dash-api-ref useState react
Shell Aliases & Functions
After setup, you'll have these convenient commands:
dash-mcp-start # Start server in tmux
dash-mcp-status # Check if running
dash-mcp-logs # View server output
enhanced-dash-mcp-for-project # Analyze current project
dash-api-lookup <api> <tech> # Quick API reference
dash-best-practices <feature> # Implementation guidance
dash-help # Show all commands
Powerlevel10k Integration
Add MCP server status to your prompt:
# Add to ~/.p10k.zsh (see p10k-dash-mcp.zsh for details)
# Shows 📚 when running, 📕 when stopped
🔧 Configuration
Cache Settings
# Default cache TTL: 1 hour
# Cache location: ~/.cache/dash-mcp/
# Memory + disk caching for optimal performance
Fuzzy Search Tuning
# Default threshold: 60% match
# Adjustable in server configuration
# Typo tolerance with intelligent ranking
Content Extraction Limits
# Default: 5000 characters per document
# Configurable for performance vs. detail trade-off
🤖 Automation & Non-Interactive Operation
The Enhanced Dash MCP server features comprehensive automation detection and non-interactive operation capabilities, making it suitable for CI/CD pipelines, deployment scripts, and containerized environments.
🔍 Interactive Mode Detection Logic
The server uses an 8-phase detection sequence to determine whether it's running in interactive or automated mode:
Phase 1: CI Environment Detection
Checks for continuous integration indicators:
# Primary CI Variables
CI, CONTINUOUS_INTEGRATION, GITHUB_ACTIONS, GITLAB_CI, JENKINS_URL
TRAVIS, CIRCLECI, BUILDKITE, DRONE, BITBUCKET_BUILD_NUMBER
AZURE_HTTP_USER_AGENT, CODEBUILD_BUILD_ID, TEAMCITY_VERSION
# And 15+ more CI environment variables
Phase 2: Automation Environment Detection
Identifies automated/batch processing:
# Automation Indicators
AUTOMATION, AUTOMATED, NON_INTERACTIVE, BATCH_MODE, HEADLESS
CRON, SYSTEMD_EXEC_PID, KUBERNETES_SERVICE_HOST, DOCKER_CONTAINER
AWS_EXECUTION_ENV, LAMBDA_RUNTIME_DIR, GOOGLE_CLOUD_PROJECT
# Cloud platforms: Heroku, Vercel, Netlify, Railway, etc.
Phase 3-8: Terminal & Process Environment
- Terminal Type: Validates
TERMenvironment (rejectsdumb,unknown) - Shell Capabilities: Checks for interactive shell support
- TTY Stream Detection: Verifies STDIN/STDOUT/STDERR are connected to terminals
- Process Environment: Detects daemon processes, nohup, orphaned processes
- SSH Connections: Validates TTY allocation in remote connections
- Session Management: Recognizes tmux/screen sessions
📊 Automation Behavior Matrix
| Environment Type | Detection Method | Behavior | Logging Level |
|---|---|---|---|
| GitHub Actions | GITHUB_ACTIONS=true | Silent, no prompts | INFO |
| GitLab CI | GITLAB_CI=true | Silent, no prompts | INFO |
| Docker Build | CONTAINER=true or non-TTY | Silent, no prompts | INFO |
| Cron Jobs | CRON=true or non-TTY | Silent operation | INFO |
| SSH Scripts | SSH_CONNECTION without SSH_TTY | Non-interactive | INFO |
| Kubernetes | KUBERNETES_SERVICE_HOST | Pod-aware operation | INFO |
| AWS Lambda | LAMBDA_RUNTIME_DIR | Serverless mode | DEBUG |
| Local Terminal | TTY + interactive shell | Full interaction | DEBUG |
⚙️ Automation-Specific Features
Timeout Protection
# All operations have built-in timeouts
Pip installations: 5-10 minute limits
User prompts: 10-second timeout with auto-defaults
Server startup: Quick validation mode for testing
Network operations: Configurable timeouts
Signal Handling
# Graceful shutdown in automation
SIGINT/SIGTERM: Clean resource cleanup
Keyboard interrupts: Logged and handled gracefully
Partial operations: Automatic rollback/cleanup
Exit codes: Standard automation-friendly codes
Non-Interactive Setup
# Setup script automation modes
./scripts/setup-dash-mcp.sh # Auto-detects environment
CI=true ./scripts/setup-dash-mcp.sh # Force CI mode
BATCH_MODE=true ./scripts/setup-dash-mcp.sh # Force batch mode
🔒 Security & Safety
Environment Validation
- Path Sanitization: Validates and sanitizes all file paths
- Input Validation: Comprehensive query and parameter validation
- Resource Limits: Memory and CPU usage constraints
- Rate Limiting: Built-in request rate limiting (100 calls/minute)
Error Recovery
# Robust error handling
Partial installations: Automatic cleanup
Network failures: Retry mechanisms with backoff
Corrupted cache: Automatic cache rebuilding
Docset issues: Graceful degradation
📈 Performance in Automation
Benchmarks
# Automation environment performance
CI installation time: ~70-80 seconds
Server validation: ~2-3 seconds
Docset discovery: ~500ms (first run), ~50ms (cached)
Timeout response: ~5 seconds maximum
Clean environment setup: ~70-75 seconds
Optimization for Automation
- Parallel Operations: Concurrent docset scanning and validation
- Smart Caching: Persistent cache survives container restarts
- Lazy Loading: On-demand content extraction
- Memory Management: Automatic cleanup of large operations
🛠️ Automation Testing
The server includes comprehensive automation testing:
# Quick CI compatibility test
./test-ci-automation.sh
# Comprehensive automation validation
./test-final-validation.sh
# Individual component testing
./scripts/test-pip-install.sh
CI=true ./scripts/setup-dash-mcp.sh
env -i PATH=/usr/bin:/bin HOME=$HOME CI=true ./scripts/setup-dash-mcp.sh
Test Coverage
- ✅ CI Environment Tests: GitHub Actions, GitLab CI, Jenkins
- ✅ Container Tests: Docker builds, Kubernetes pods
- ✅ Timeout Mechanism Tests: All operations respect timeouts
- ✅ Signal Handling Tests: Graceful interruption and cleanup
- ✅ Environment Detection Tests: All 26+ environment variables
- ✅ Non-Interactive Tests: Stdin redirection, batch mode
📋 Deployment Examples
GitHub Actions Workflow
- name: Setup Enhanced Dash MCP
run: |
git clone <repository-url>
cd enhanced-dash-mcp
CI=true ./scripts/setup-dash-mcp.sh
# No prompts, automatic defaults
Docker Container
RUN git clone <repository-url> && \\
cd enhanced-dash-mcp && \\
CONTAINER=true ./scripts/setup-dash-mcp.sh
# Detects container environment automatically
Kubernetes Job
command: ["/bin/bash", "-c"]
args:
- |
cd /app/enhanced-dash-mcp
KUBERNETES_SERVICE_HOST=true ./scripts/setup-dash-mcp.sh
python3 enhanced_dash_server.py --test
🔍 Debugging Automation Issues
Log Analysis
# View detailed environment detection logs
export DASH_MCP_LOG_LEVEL=DEBUG
python3 enhanced_dash_server.py --test
# Check automation detection reasoning
grep "Detection reason" ~/.cache/dash-mcp/server.log
# Verify environment variables
grep "Environment summary" ~/.cache/dash-mcp/server.log
Common Automation Scenarios
# Force interactive mode (testing)
export FORCE_INTERACTIVE=true
# Override environment detection
export DASH_MCP_MODE=interactive # or 'automation'
# Detailed process information
export DASH_MCP_DEBUG_PROCESS=true
🏗️ Architecture
Core Components
- DashMCPServer - Main server orchestrating all components
- CacheManager - Multi-tier caching (memory + disk)
- ContentExtractor - Clean text extraction from various formats
- FuzzySearchEngine - Intelligent search with ranking algorithms
- ProjectAwareDocumentationServer - Context-aware documentation selection
Data Flow
- Query received from Claude via MCP
- Project context analyzed (language, framework, dependencies)
- Relevant docsets identified and prioritized
- Fuzzy search performed with intelligent ranking
- Content extracted and cached for future requests
- Results returned with project-specific scoring
Caching Strategy
- Memory Cache - Instant access for recently searched items
- Disk Cache - Persistent storage surviving server restarts
- Smart Expiration - 1-hour TTL with automatic cleanup
- Cache Keys - Generated from search parameters for optimal hit rates
📊 Performance
Benchmarks
- First search: ~500ms (includes docset scanning)
- Cached searches: ~50ms (memory cache hits)
- Content extraction: +200-300ms (when requested)
- Fuzzy matching: Minimal overhead with significant quality improvement
Optimization Tips
- Keep server running in tmux for best performance
- Initial searches per docset are slower (cache building)
- Content extraction adds latency but provides much richer context
- Memory cache provides fastest repeated access
🔍 Available Tools
Core Search Tools
| Tool | Description | Use Case |
|---|---|---|
search_dash_docs | Basic documentation search with fuzzy matching | General API/concept lookup |
list_docsets | Show all available documentation sets | Discover available documentation |
get_doc_content | Get full content for specific documentation | Deep dive into specific topics |
Project-Aware Tools
| Tool | Description | Use Case |
|---|---|---|
analyze_project_context | Detect project tech stack and dependencies | Understand current project |
get_project_relevant_docs | Context-aware documentation search | Find docs relevant to your project |
get_implementation_guidance | Best practices for specific features | Implementation planning |
Specialized Tools
| Tool | Description | Use Case |
|---|---|---|
get_migration_docs | Version upgrade documentation | Planning upgrades and migrations |
get_latest_api_reference | Current API docs with examples | Quick reference while coding |
🚨 Troubleshooting
Common Issues
❌ "No docsets found"
# Ensure Dash is installed with docsets
ls ~/Library/Application\ Support/Dash/DocSets/
# Should show *.docset directories
# Optionally set DASH_DOCSETS_PATH if your docsets live elsewhere
# (symlinks to the default location are supported)
# When creating a symlink, point it at `~/Library/Application Support/Dash`.
# A symlink directly to the `DocSets` folder will produce a search path
# ending in `DocSets/DocSets` and no docsets will be discovered.
# The server now resolves such symlinks automatically and also corrects
# `DASH_DOCSETS_PATH` values that point at the parent `Dash` directory.
❌ "Permission errors"
# Check Python environment
which python3
source ~/enhanced-dash-mcp/venv/bin/activate
❌ "Import errors"
# Reinstall dependencies
cd ~/enhanced-dash-mcp
source venv/bin/activate
pip install -r requirements.txt
❌ "Server won't start"
# Check if port is in use
tmux kill-session -t dash-mcp
dash-mcp-start
❌ "Slow searches"
# First searches build cache - subsequent searches are much faster
# Check cache directory
ls ~/.cache/dash-mcp/
Debug Mode
# View detailed server logs
dash-mcp-logs
# Attach to server session for real-time debugging
dash-mcp-attach
🤝 Contributing
Development Setup
# Clone repository
git clone <repository-url>
cd enhanced-dash-mcp
# Create development environment
python3 -m venv dev-env
source dev-env/bin/activate
pip install -r requirements.txt
# Install development dependencies
pip install pytest black flake8 mypy
Running Tests
# Unit tests
pytest tests/
# Linting and type checks
black .
flake8 . # uses settings from .flake8
mypy . # uses settings from mypy.ini
Adding New Features
- Docset Support - Add new file format extractors in
ContentExtractor - Search Algorithms - Enhance ranking in
FuzzySearchEngine - Project Detection - Extend framework detection in
ProjectAwareDocumentationServer - Caching Strategies - Optimize cache management in
CacheManager
📄 License
MIT License - see LICENSE file for details.
🙏 Acknowledgments
- Dash by Kapeli for providing excellent local documentation
- Anthropic for Claude and the MCP framework
- Warp Terminal for innovative terminal experience
- Fort Collins Tech Community for inspiration and feedback
📞 Support
- Issues: Open a GitHub issue for bugs or feature requests
- Discussions: Use GitHub Discussions for questions and ideas
- Documentation: Check the
/docsdirectory for detailed guides
🗺️ Roadmap
v1.1 - Enhanced Intelligence
- ML-powered documentation relevance scoring
- Automatic dependency documentation downloads
- Cross-reference linking between related docs
v1.2 - Extended Platform Support
- VS Code extension for direct editor integration
v1.3 - Advanced Features
- Documentation usage analytics and recommendations
- Team collaboration features for shared documentation
- Integration with popular documentation hosting platforms
Built with ❤️ in Fort Collins, CO for developers who value efficient, intelligent documentation access.
Transform your development workflow with context-aware documentation that understands your project and coding patterns.