使用说明

增强型Dash MCP服务器

🎯 这是什么？

这是一个 模型上下文协议（MCP） 增强官方功能的服务器冲撞 MCP服务器。官方的Dash MCP拥有精确的Dash支持操作：安装的文档集、精确的文档搜索、全文搜索和页面加载。增强的Dash MCP拥有围绕这些操作的更高级别的智能：项目上下文、文档集推荐、本地缓存发现、路由、排名和工作流指导。

简单来说： 该服务器告诉Claude和其他代理编码工具Dash文档集和 search_documentation 用于存储库和前面任务的查询。官方的Dash MCP仍然会获取搜索结果和文档页面。

📚 关于达世币

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

🔗 为什么这种整合很重要

官方短跑交接：返回docset标识符并准备运行 search_documentation 当您提供 list_installed_docsets 快照
本地缓存感知：索引有效的本地达世币缓存文档集，并解释官方达世币MCP看不到哪些文档集
注重隐私：项目检查和本地缓存发现保留在您的计算机上
持久元数据索引：将文档集元数据存储在 ~/.cache/dash-mcp/docset-index-v2.json 因此，冷发现不会被不必要地重复
上下文感知：检测回购的堆栈，并自动建议相关的达世币文档集

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

🚀 特征

核心能力

项目背景分析 -检测语言、框架、依赖关系、清单和公共源文件
Docset推荐 -为仓库或提供的上下文推荐精确的达世币文档集
搜索计划 -生产官方Dash MCP search_documentation 查询计划
结果排名 -在不加载页面内容的情况下重新排列官方达世币搜索结果
覆盖范围概述 -将官方达世币可见文档集与有效的本地缓存文档集进行比较
缺少文档集解释 -解释所请求的docset是官方的、仅限本地的还是不存在的

开发人员工作流集成

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

支持的技术

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

📋 先决条件

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

⚠️ 重要依赖性要求

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

使用虚拟环境（推荐）
检查与其他工具的兼容性（如 pieces-os-client)
考虑为不同的项目使用单独的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兼容性所需）
typing-extensions>=4.12.0 -扩展类型提示

⚡ 快速开始

🔄 重要提示：v2边界更改

如果您从以前的版本升级，增强型Dash MCP不再公开直接搜索/页面加载工具。使用官方Dash MCP：

list_installed_docsets
search_documentation
enable_docset_fts
load_documentation_page

使用增强的达世币MCP进行支持回购的推荐、搜索计划、排名、覆盖率摘要和缺失的文档集解释。

要重建v2元数据索引，请执行以下操作：

# 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

发生了什么变化： 增强的Dash MCP现在仅将本地缓存文档集报告为元数据和回退诊断。它不会获取文档页面。

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

官方Dash快照

通过官方Dash MCP list_installed_docsets 对增强型达世币的回应当您希望在切换信封中包含精确的官方文档集标识符时，可以使用工具。

🤖 自动化和非交互式操作

增强型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会话

📊 自动化行为矩阵

环境类型	检测方法	行为	日志级别
GitHub操作	`GITHUB_ACTIONS=true`	静音，无提示	信息
GitLab 的	`GITLAB_CI=true`	静音，无提示	信息
Docker构建	`CONTAINER=true` 或非TTY	静音，无提示	信息
定时任务	`CRON=true` 或非TTY	静音操作	信息
SSH脚本	`SSH_CONNECTION` 没有 `SSH_TTY`	非交互式	信息
Kubernetes	`KUBERNETES_SERVICE_HOST`	Pod感知操作	信息
AWS Lambda	`LAMBDA_RUNTIME_DIR`	无服务器模式	调试
本地终端	TTY+交互式shell	完全交互	调试

⚙️ 自动化特定功能

超时保护

# 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

自动化优化

并行操作：同时进行文档集扫描和验证
智能缓存：容器重启后，持久缓存仍然存在
官方交接：增强工具计划工作，然后官方Dash MCP加载页面
内存管理：自动清理大型操作

🛠️ 自动化测试

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

# 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 <repository-url>
    cd enhanced-dash-mcp
    CI=true ./scripts/setup-dash-mcp.sh
    # No prompts, automatic defaults

Docker容器

RUN git clone <repository-url> && \\
    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
    ./venv/bin/python3 enhanced_dash_server.py --test

🔍 调试自动化问题

日志分析

# 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

常见自动化场景

# 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服务器 -内部本地缓存元数据索引器
DashAugmentationServer -项目意识推荐和移交计划员
官方文档索引 -可选的官方达世币快照匹配器
项目文档上下文 -语言、框架、依赖关系和清单的回购上下文模型

数据流

收到任务或仓库路径 从克劳德经由MCP
项目背景 从清单和源文件分析
相关文件集 识别并匹配可选的官方快照
官方达世币搜索计划 在可用时使用标识符生成
仅本地缓存缺口 仅在官方Dash看不到文档集时解释
交回信封 供呼叫者运行官方Dash MCP操作

缓存策略

持久元数据索引 -存储本地文档集元数据，而不是页面内容
时间失效 -当Dash root时重建， Info.plist，或 docSet.dsidx 变化
强制刷新 -接受推荐和覆盖工具 force_refresh=true

📊 演出

基准测试

第一元数据索引：取决于达世币缓存大小和文档集计数
缓存元数据读取：从快速加载JSON docset-index-v2.json
官方搜索/页面加载：由官方Dash MCP处理，而不是此服务器

优化提示

让服务器在tmux中运行以获得最佳性能
当您需要确切的标识符时，请传递官方Dash docset快照
使用 force_refresh=false 常规建议
使用 force_refresh=true 仅在安装或移动docset之后

🔍 可用工具

工具	描述	用例
`analyze_project_docs_context`	检测仓库堆栈、清单和依赖关系	了解当前项目
`recommend_dash_docsets`	推荐官方/本地达世币文档集	为任务选择文档
`plan_dash_searches`	建立官方 `search_documentation` 呼叫	准备Dash MCP切换
`rank_dash_results`	对官方达世币搜索结果进行排名	优先考虑已获取的候选人
`summarize_docset_coverage`	比较官方可见和本地缓存文档集	解释应用程序/缓存差距
`suggest_offline_docs_for_repo`	建议特定于仓库的离线文档	Bootstrap项目文档工作流
`explain_missing_docsets`	解释官方/本地/缺失文档集状态	诊断缺失文档

🚨 故障排除

常见问题

❌ “未找到文档集”

# 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
python --version
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 <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]"

运行测试

# Unit tests
pytest tests/

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

添加新功能

文档集匹配 -在中添加别名 aliases_for_name
排名 -增强 rank_results 具有更多结果字段
项目检测 -在中扩展清单解析 DashAugmentationServer
索引 -在中扩展本地元数据 DashMCPServer

📄 许可证

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

🙏 致谢

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

📞 支持

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

🗺️ 路线图

v1.1-增强智能

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

v1.2-扩展平台支持

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

v1.3-高级功能

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

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

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

使用说明

增强型Dash MCP服务器

🎯 这是什么？

📚 关于达世币

🔗 为什么这种整合很重要

🚀 特征

核心能力

开发人员工作流集成

支持的技术

📋 先决条件

⚠️ 重要依赖性要求

📦 依赖项

⚡ 快速开始

🔄 重要提示：v2边界更改

1. 克隆和设置

2. 配置Claude

3. 启动和测试

🎮 用法

基本文档搜索

项目感知智能

迁移和升级帮助

API参考及示例

🛠️ 高级设置

曲速终端集成

Shell别名和函数

Powerlevel 10k集成

🔧 配置

元数据索引设置

官方Dash快照

🤖 自动化和非交互式操作

🔍 交互模式检测逻辑

第一阶段：CI环境检测

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

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

📊 自动化行为矩阵

⚙️ 自动化特定功能

超时保护

信号处理

非交互式设置

🔒 安全与安保

环境验证

错误恢复

📈 自动化性能

基准测试

自动化优化

🛠️ 自动化测试

测试覆盖率

📋 部署示例

GitHub操作工作流

Docker容器

Kubernetes作业

🔍 调试自动化问题

日志分析

常见自动化场景

🏗️ 建筑

核心组件

数据流

缓存策略

📊 演出

基准测试

优化提示

🔍 可用工具

🚨 故障排除

常见问题

调试模式

🤝 贡献

开发环境

运行测试

添加新功能

📄 许可证

🙏 致谢

📞 支持

🗺️ 路线图

v1.1-增强智能

v1.2-扩展平台支持

v1.3-高级功能

📚 进一步阅读

相关 MCP

Emacs交互服务器

小型企业MCP服务器