Enhanced Dash MCP Server

增强型Dash MCP服务器

🎯 这是什么？

这是一个 模型上下文协议（MCP） 桥接服务器 冲撞 -适用于macOS的流行离线API文档浏览器-带有Claude Desktop和其他代理开发环境。MCP是一种开放协议，使Claude和Warp等AI助手能够通过结构化API安全地访问计算机上的本地资源和工具。

简单来说： 该服务器允许Claude和其他代理编码工具立即搜索和阅读您本地的Dash文档（200多个API文档、备忘单和指南），以根据您安装的实际文档提供准确的、特定版本的答案-所有这些都是离线的、私人的和快速的。

📚 关于达世币

冲撞 是适用于macOS的API文档浏览器和代码段管理器，可让您即时离线访问200多个API文档集。它是开发人员的首选工具，他们希望快速、可搜索、离线文档，而不依赖于互联网连接或处理缓慢的网络搜索。

🔗 为什么这种整合很重要

• 离线优先：无需互联网连接即可访问您的所有文档
• 版本特定：根据您安装的库的确切版本获取答案
• 注重隐私：你的代码上下文和查询永远不会离开你的机器
• 迅速的在千兆字节的文档中进行亚秒级搜索
• 上下文感知：Claude了解您的项目堆栈，并自动建议相关文档

看 更改日志.md 版本历史。

🚀 特性

核心能力

• 🔍 智能搜索 -具有拼写容差和智能排名的模糊匹配
• 📚 内容提取 -从HTML、Markdown和文本文档中提取干净的文本
• ⚡ 多层缓存 -内存+磁盘缓存，实现闪电般快速的重复搜索
• 🎯 项目意识 -自动检测您的技术栈并优先处理相关文档
• 🛠️ 实施指南 -特定功能的最佳实践和模式
• 📈 迁移支持 -版本升级文档和重大更改
• 🔄 最新API参考 -当前API文档及实际示例

开发人员工作流集成

• 经纱终端 -本地命令面板和工作流集成
• 子速率复用器 -跨终端会话的后台服务器执行
• 尼奥夫 -通过Claude编码时访问文档
• 哦，我的Zsh -增强的别名和生产力快捷方式
• Git集成 -支持存储库的文档建议

支持的技术

JavaScript/TypeScript、React、Next.js、Vue.js、Angular、Node.js、Python、Django、Flask、FastAPI、pandas、NumPy等等。

📋 先决条件

• macOS 安装了达世币应用程序
• Python 3.8+ （推荐使用Python 3.11+）
• Dash文档集 下载（JavaScript、Python、React等）
• 克劳德 支持MCP
• 子速率复用器 （建议后台执行）

⚠️ 重要依赖性要求

此服务器需要 Pydantic v2.0+ 为了MCP兼容性。如果你有Pydantic v1.x的现有项目，你可能需要：

1. 使用虚拟环境（推荐）
2. 检查与其他工具的兼容性（如 pieces-os-client)
3. 考虑为不同的项目使用单独的Python环境

# Check your current Pydantic version
pip show pydantic

# If you have v1.x, you'll need to upgrade
pip install "pydantic>=2.0.0"

📦 依赖项

安装脚本会自动安装所有必需的依赖项，包括：

• mcp>=1.9.0 -模型上下文协议框架
• pydantic>=2.0.0 -数据验证（MCP兼容性所需）
• beautifulsoup4>=4.12.0 -HTML内容提取
• fuzzywuzzy>=0.18.0 -模糊字符串匹配
• python-levenshtein>=0.27.0 -快速字符串相似性
• aiofiles>=24.0.0 -异步文件操作
• aiohttp>=3.11.0 -异步HTTP客户端
• rapidfuzz>=3.0.0 -增强模糊匹配
• typing-extensions>=4.12.0 -扩展类型提示

⚡ 快速开始

🔄 重要提示：清除现有用户的缓存

如果您从以前的版本升级，服务器现在通过搜索整个达世币目录树发现了8倍多的文档集（364个而不是45个）。要查看所有新的文档集，请清除缓存：

# 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

发生了什么变化：

• 之前：仅搜索 ~/Library/Application Support/Dash/DocSets/ （45个文件集）
• 之后：搜索整个 ~/Library/Application Support/Dash/ 目录（364个文档集）
• 利益：现在包括用户贡献、Python DocSets、版本化DocSets等！

看 docs/help.md 有关如何运行服务器的简要概述。

1. 克隆和设置

# 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

脚本会提示输入安装目录。按 进入 接受 默认路径或提供自定义位置。默认值为 ~/enhanced-dash-mcp.

2. 配置Claude

将此添加到Claude的MCP设置中：

{
  "mcpServers": {
    "enhanced-dash-mcp": {
      "command": "$DASH_MCP_DIR/venv/bin/python3",
      "args": [
        "$DASH_MCP_DIR/enhanced_dash_server.py"
      ],
      "env": {}
    }
  }
}

3. 启动和测试

# 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"

🎮 用法

基本文档搜索

# Ask Claude:
"Search for Python pandas DataFrame methods"
"Find React hooks best practices"
"Get FastAPI routing documentation with examples"

项目感知智能

# 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?"

迁移和升级帮助

# 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参考及示例

# 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"

🛠️ 高级设置

曲速终端集成

为了增强曲速终端支持：

# 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别名和函数

设置后，您将获得以下方便的命令：

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   # Quick API reference
dash-best-practices  # Implementation guidance
dash-help                   # Show all commands

Powerlevel 10k集成

将MCP服务器状态添加到提示中：

# Add to ~/.p10k.zsh (see p10k-dash-mcp.zsh for details)
# Shows 📚 when running, 📕 when stopped

🔧 配置

缓存设置

# Default cache TTL: 1 hour
# Cache location: ~/.cache/dash-mcp/
# Memory + disk caching for optimal performance

模糊搜索调优

# Default threshold: 60% match
# Adjustable in server configuration
# Typo tolerance with intelligent ranking

内容提取限制

# Default: 5000 characters per document
# Configurable for performance vs. detail trade-off

🤖 自动化和非交互式操作

增强型Dash MCP服务器具有全面的自动化检测和非交互式操作功能，使其适用于CI/CD管道、部署脚本和容器化环境。

🔍 交互模式检测逻辑

服务器使用8阶段检测序列来确定它是以交互模式还是自动模式运行：

第一阶段：CI环境检测

检查持续集成指标：

# 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

第二阶段：自动化环境检测

标识自动化/批处理：

# 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.

阶段3-8：终端和过程环境

• 终端类型：验证 TERM 环境（拒绝 dumb, unknown)
• 壳牌能力：检查交互式shell支持
• TTY流检测：验证STDIN/STDOUT/STDERR是否连接到终端
• 过程环境：检测守护进程、nohup、孤立进程
• SSH连接：验证远程连接中的TTY分配
• 会话管理：识别tmux/secreen会话

📊 自动化行为矩阵

⚙️ 自动化特定功能

超时保护

# 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

信号处理

# 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

非交互式设置

# 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

🔒 安全与安保

环境验证

• 路径消毒：验证并清理所有文件路径
• 输入验证：全面的查询和参数验证
• 资源限制：内存和CPU使用限制
• 速率限制：内置请求速率限制（100个呼叫/分钟）

错误恢复

# Robust error handling
Partial installations: Automatic cleanup
Network failures: Retry mechanisms with backoff
Corrupted cache: Automatic cache rebuilding
Docset issues: Graceful degradation

📈 自动化性能

基准测试

# 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

自动化优化

• 并行操作：同时进行文档集扫描和验证
• 智能缓存：容器重启后，持久缓存仍然存在
• 延迟加载：按需内容提取
• 内存管理：自动清理大型操作

🛠️ 自动化测试

服务器包括全面的自动化测试：

# 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

测试覆盖率

• ✅ CI环境测试：GitHub Actions、GitLab CI、Jenkins
• ✅ 集装箱测试：Docker构建，Kubernetes Pod
• ✅ 超时机制测试：所有操作都尊重超时
• ✅ 信号处理测试：优雅的中断和清理
• ✅ 环境检测试验：所有26+环境变量
• ✅ 非交互式测试：stdin重定向，批处理模式

📋 部署示例

GitHub操作工作流

- name: Setup Enhanced Dash MCP
  run: |
    git clone 
    cd enhanced-dash-mcp
    CI=true ./scripts/setup-dash-mcp.sh
    # No prompts, automatic defaults

Docker容器

RUN git clone  && \\
    cd enhanced-dash-mcp && \\
    CONTAINER=true ./scripts/setup-dash-mcp.sh
# Detects container environment automatically

Kubernetes作业

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

🔍 调试自动化问题

日志分析

# 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

常见自动化场景

# 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

🏗️ 建筑

核心组件

• DashMCP服务器 -主服务器协调所有组件
• 缓存管理器 -多层缓存（内存+磁盘）
• 内容提取器 -从各种格式中提取干净的文本
• 模糊搜索引擎 -使用排名算法的智能搜索
• ProjectAwardDocumentation服务器 -上下文感知文档选择

数据流

1. 已收到查询 从克劳德经由MCP
2. 项目上下文 分析（语言、框架、依赖关系）
3. 相关文档集 确定并优先考虑
4. 模糊搜索 智能排名
5. 提取的内容 并缓存以备将来请求
6. 返回结果 具有项目特定评分

缓存策略

• 内存缓存 -即时访问最近搜索的项目
• 磁盘缓存 -持久存储幸存服务器重启
• 智能到期 -1小时TTL，自动清理
• 缓存密钥 -根据搜索参数生成，以获得最佳命中率

📊 演出

基准测试

• 首次搜索：~500ms（包括docset扫描）
• 缓存搜索：~50ms（内存缓存命中率）
• 内容提取：+200-300ms（根据要求）
• 模糊匹配：开销最小，质量显著提高

优化提示

• 让服务器在tmux中运行以获得最佳性能
• 每个文档集的初始搜索速度较慢（缓存构建）
• 内容提取增加了延迟，但提供了更丰富的上下文
• 内存缓存提供最快的重复访问

🔍 可用工具

核心搜索工具

项目感知工具

专用工具

🚨 故障排除

常见问题

❌ “未找到文档集”

# 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.

❌ “权限错误”

# Check Python environment
which python3
source ~/enhanced-dash-mcp/venv/bin/activate

❌ “导入错误”

# Reinstall dependencies
cd ~/enhanced-dash-mcp
source venv/bin/activate
pip install -r requirements.txt

❌ “服务器无法启动”

# Check if port is in use
tmux kill-session -t dash-mcp
dash-mcp-start

❌ “搜索速度慢”

# First searches build cache - subsequent searches are much faster
# Check cache directory
ls ~/.cache/dash-mcp/

调试模式

# View detailed server logs
dash-mcp-logs

# Attach to server session for real-time debugging
dash-mcp-attach

🤝 贡献

开发设置

# Clone repository
git clone 
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

运行测试

# Unit tests
pytest tests/

# Linting and type checks
black .
flake8 .  # uses settings from .flake8
mypy .    # uses settings from mypy.ini

添加新功能

1. 文档集支持 -在中添加新的文件格式提取器 ContentExtractor
2. 搜索算法 -提升排名 FuzzySearchEngine
3. 项目检测 -扩展框架检测 ProjectAwareDocumentationServer
4. 缓存策略 -优化缓存管理 CacheManager

📄 许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

🙏 致谢

• 冲撞 由Kapeli提供优秀的当地文件
• Anthropic Claude和MCP框架
• 经纱终端 创新终端体验
• 柯林斯堡技术社区 寻求灵感和反馈

📞 支持

• 问题：针对bug或功能请求打开GitHub问题
• 讨论：使用GitHub讨论来回答问题和想法
• 文档：检查 /docs 详细指南目录

🗺️ Roadmap

v1.1-增强智能

• \[\]基于机器学习的文档相关性评分
• \[\]自动下载依赖关系文档
• \[\]相关文档之间的交叉引用链接

v1.2-扩展平台支持

• \[\]用于直接编辑器集成的VS代码扩展

v1.3-高级功能

• \[\]文档使用分析和建议
• \[\]共享文档的团队协作功能
• \[\]与流行的文档托管平台集成

______________________________________________________________________

内置于❤️ 位于科罗拉多州柯林斯堡，面向重视高效、智能文档访问的开发人员。

_使用了解项目和编码模式的上下文感知文档来转换您的开发工作流程。_

📚 进一步阅读

• 变更日志和CI
• 服务器使用情况
• AI代理指南