Enhanced Dash MCP Server

🎯 What is this?

This is a Model Context Protocol (MCP) server that augments the official Dash MCP server. The official Dash MCP owns exact Dash-backed operations: installed docsets, precise documentation search, full-text search, and page loading. Enhanced Dash MCP owns the higher-level intelligence around those operations: project context, docset recommendation, local cache discovery, routing, ranking, and workflow guidance.

In simple terms: this server tells Claude and other agentic coding tools which Dash docsets and search_documentation queries to use for the repo and task in front of them. The official Dash MCP still fetches the search results and documentation pages.

📚 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

• Official Dash Handoff: returns docset identifiers and ready-to-run search_documentation calls when you provide a list_installed_docsets snapshot
• Local Cache Awareness: indexes valid local Dash cache docsets and explains which ones the official Dash MCP cannot see
• Privacy-Focused: project inspection and local cache discovery stay on your machine
• Persistent Metadata Index: stores docset metadata in ~/.cache/dash-mcp/docset-index-v2.json so cold discovery is not repeated unnecessarily
• Context-Aware: detects a repo's stack and suggests relevant Dash docsets automatically

See CHANGELOG.md for version history.

🚀 Features

Core Capabilities

• Project Context Analysis - detects languages, frameworks, dependencies, manifests, and common source files
• Docset Recommendation - recommends exact Dash docsets for a repo or supplied context
• Search Planning - produces official Dash MCP search_documentation query plans
• Result Ranking - re-ranks official Dash search results without loading page content
• Coverage Summaries - compares official Dash-visible docsets with valid local cache docsets
• Missing Docset Explanations - explains whether a requested docset is official, local-only, or absent

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.11+
• 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:

1. Use a virtual environment (recommended)
2. Check for compatibility with other tools (like pieces-os-client)
3. 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 framework
• pydantic>=2.0.0 - Data validation (required for MCP compatibility)
• typing-extensions>=4.12.0 - Extended type hints

⚡ Quick Start

🔄 Important: v2 Boundary Change

If you're upgrading from a previous version, Enhanced Dash MCP no longer exposes direct search/page loading tools. Use the official Dash MCP for:

• list_installed_docsets
• search_documentation
• enable_docset_fts
• load_documentation_page

Use Enhanced Dash MCP for repo-aware recommendations, search planning, ranking, coverage summaries, and missing-docset explanations.

To rebuild the v2 metadata index:

# Clear the metadata index
rm -f ~/.cache/dash-mcp/docset-index-v2.json

# Then restart your server
dash-mcp-restart
# or
cd ~/enhanced-dash-mcp && ./start-dash-mcp.sh --test

What changed: Enhanced Dash MCP now reports local cache docsets only as metadata and fallback diagnostics. It does not fetch documentation pages.

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> # Plan official Dash MCP searches
dash-best-practices <feature> # Recommend docsets and search routes
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

Metadata Index Settings

# Default index: ~/.cache/dash-mcp/docset-index-v2.json
# Test override: DASH_MCP_INDEX_PATH=/tmp/docset-index.json
# Rebuild: pass force_refresh=true to recommendation/coverage tools

Official Dash Snapshot

Pass the official Dash MCP list_installed_docsets response to Enhanced Dash tools when you want exact official docset identifiers in the handoff envelope.

🤖 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 TERM environment (rejects dumb, 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
• Official Handoff: enhanced tools plan work, then official Dash MCP loads pages
• 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
    ./venv/bin/python3 enhanced_dash_server.py --test

🔍 Debugging Automation Issues

Log Analysis

# View detailed environment detection logs
export DASH_MCP_LOG_LEVEL=DEBUG
./venv/bin/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 - Internal local-cache metadata indexer
• DashAugmentationServer - Project-aware recommendation and handoff planner
• OfficialDocsetIndex - Optional official Dash snapshot matcher
• ProjectDocsContext - Repo context model for languages, frameworks, dependencies, and manifests

Data Flow

1. Task or repo path received from Claude via MCP
2. Project context analyzed from manifests and source files
3. Relevant docsets identified and matched against the optional official snapshot
4. Official Dash search plans generated with identifiers when available
5. Local-only cache gaps explained only when official Dash cannot see the docset
6. Handoff envelope returned for the caller to run official Dash MCP operations

Caching Strategy

• Persistent Metadata Index - Stores local docset metadata, not page content
• Mtime Invalidation - Rebuilds when the Dash root, Info.plist, or docSet.dsidx changes
• Force Refresh - Recommendation and coverage tools accept force_refresh=true

📊 Performance

Benchmarks

• First metadata index: depends on Dash cache size and docset count
• Cached metadata reads: fast JSON load from docset-index-v2.json
• Official search/page loading: handled by the official Dash MCP, not this server

Optimization Tips

• Keep server running in tmux for best performance
• Pass an official Dash docset snapshot when you need exact identifiers
• Use force_refresh=false for routine recommendations
• Use force_refresh=true only after installing or moving docsets

🔍 Available Tools

Tool	Description	Use Case
analyze_project_docs_context	Detect repo stack, manifests, and dependencies	Understand current project
recommend_dash_docsets	Recommend official/local Dash docsets	Choose docs for a task
plan_dash_searches	Build official search_documentation calls	Prepare Dash MCP handoff
rank_dash_results	Rank official Dash search results	Prioritize fetched candidates
summarize_docset_coverage	Compare official-visible and local-cache docsets	Explain app/cache gap
suggest_offline_docs_for_repo	Suggest repo-specific offline docs	Bootstrap project docs workflow
explain_missing_docsets	Explain official/local/missing docset status	Diagnose missing docs

🚨 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
python --version
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
python -m venv dev-env
source dev-env/bin/activate
pip install -r requirements.txt

# Install development dependencies
pip install -e ".[dev]"

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

1. Docset Matching - Add aliases in aliases_for_name
2. Ranking - Enhance rank_results with more result fields
3. Project Detection - Extend manifest parsing in DashAugmentationServer
4. Indexing - Extend local metadata in DashMCPServer

📄 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 /docs directory 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.

📚 Further Reading

• Changelog and CI
• Server Usage
• AI Agent Guide