技术文档摘要

Enhanced Dash MCP Server

🎯 这是什么？

这是一个**模型上下文协议（MCP）**服务器，它连接了[Dash]（https://kapeli.com/dash）——一个流行的macOS离线API文档浏览器——与Claude Desktop和其他代理开发环境。MCP是一个开放协议，允许像Claude和Warp这样的AI助手通过结构化的API安全地访问您计算机上的本地资源和工具。

**简单来说：**这个服务器让Claude和其他代理编码工具能够即时搜索并阅读您的本地Dash文档（200多个API文档、速查表和指南），提供基于您已安装的实际文档的准确、特定版本的答案——所有这些都是离线、私密且速度极快的。

📚 关于Dash

[Dash]（https://kapeli.com/dash）是一个用于macOS的API文档浏览器和代码片段管理器，它为您提供即时离线访问200多个API文档集。对于希望快速、可搜索、离线文档而不依赖互联网连接或处理缓慢的网络搜索的开发人员来说，它是首选工具。

🔗 为什么这种集成很重要

• 离线优先：无需互联网连接即可访问所有文档
• 特定版本：根据您已安装的确切库版本获取答案
• 隐私聚焦：您的代码上下文和查询永远不会离开您的机器
• 闪电般快速：通过数GB文档进行亚秒级搜索
• 上下文感知：Claude理解您的项目堆栈，并自动建议相关文档

查看[CHANGELOG.md]（CHANGELOG.md）以了解版本历史。

🚀 功能

核心能力

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

开发者工作流集成

• Warp终端 - 本机命令调色板和工作流集成
• tmux - 跨终端会话执行后台服务器
• Neovim - 通过Claude在编码时访问文档
• Oh-My-Zsh - 增强别名和生产力快捷方式
• Git集成 - 仓库感知的文档建议

支持的技术

JavaScript/TypeScript、React、Next.js、Vue.js、Angular、Node.js、Python、Django、Flask、FastAPI、pandas、NumPy等，通过Dash文档集。

📋 先决条件

• 安装了Dash应用的macOS
• Python 3.8+（推荐使用Python 3.11+）
• 下载了Dash文档集（JavaScript、Python、React等）
• 支持MCP的Claude
• tmux（推荐用于后台执行）

⚠️ 重要依赖要求

此服务器需要**Pydantic v2.0+**以兼容MCP。如果您有使用Pydantic v1.x的现有项目，您可能需要：

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

# 检查当前的Pydantic版本
pip show pydantic

# 如果是v1.x，您需要升级
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 - 扩展类型提示

⚡ 快速开始

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

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

# 清除文档集缓存以发现新可用的文档集
rm -rf ~/.cache/dash-mcp/

# 然后重新启动您的服务器
dash-mcp-restart
# 或者
cd ~/enhanced-dash-mcp && ./start-dash-mcp.sh --test

发生了什么变化：

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

参见[docs/help.md]（docs/help.md）以了解如何运行服务器的简要概述。

1. 克隆&设置

# 克隆或下载项目文件
mkdir ~/enhanced-dash-mcp && cd ~/enhanced-dash-mcp

# 将设置脚本设为可执行
chmod +x scripts/setup-dash-mcp.sh

# 运行自动化设置
./scripts/setup-dash-mcp.sh

该脚本会提示您选择安装目录。按Enter接受默认路径或提供自定义位置。默认路径是~/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. 启动&测试

# 添加shell增强
echo "source ~/enhanced-dash-mcp/dash-mcp-aliases.sh" >> ~/.zshrc
source ~/.zshrc

# 启动服务器
dash-mcp-start

# 使用Claude测试
# "搜索React useState钩子文档"

🎮 使用方法

基本文档搜索

# 询问Claude：
"搜索Python pandas DataFrame方法"
"查找React钩子最佳实践"
"获取带示例的FastAPI路由文档"

项目感知智能

# 导航到您的项目目录，然后询问Claude：
"分析我的当前项目并找到相关的文档"
"获取我在React应用程序中的用户身份验证实现指导"
"我当前的Django项目有哪些最佳实践？"

迁移&升级帮助

# 询问Claude：
"获取从React 17升级到18的迁移文档"
"查找Django 4.2升级指南和重大更改"
"显示Next.js 13到14的迁移文档"

带有示例的API参考

# 询问Claude：
"获取最新的pandas DataFrame.merge API参考及示例"
"显示React useEffect钩子文档和模式"
"查找Express.js中间件文档及其用例"

🛠️ 高级设置

Warp终端集成

为了增强Warp终端支持：

# 运行Warp特定设置
chmod +x scripts/setup-warp-dash-mcp.sh
./scripts/setup-warp-dash-mcp.sh

# 使用命令调色板（⌘K）：
dash-mcp-start
dash-analyze-project
dash-api-ref useState react

shell别名&函数

设置完成后，您将拥有这些方便的命令：

dash-mcp-start              # 在tmux中启动服务器
dash-mcp-status             # 检查是否正在运行
dash-mcp-logs               # 查看服务器输出
enhanced-dash-mcp-for-project       # 分析当前项目
dash-api-lookup <api> <tech> # 快速API参考
dash-best-practices <feature> # 实现指导
dash-help                   # 显示所有命令

Powerlevel10k集成

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

# 添加到~/.p10k.zsh（详见p10k-dash-mcp.zsh）
# 当运行时显示📚，停止时显示📚

🔧 配置

缓存设置

# 默认缓存TTL：1小时
# 缓存位置：~/.cache/dash-mcp/
# 内存+磁盘缓存以获得最佳性能

模糊搜索调整

# 默认阈值：60%匹配
# 可在服务器配置中调整
# 具有拼写错误容忍度和智能排名

内容提取限制

# 默认：每个文档5000个字符
# 可根据性能与细节之间的权衡进行配置

🤖 自动化&非交互式操作

Enhanced Dash MCP服务器具备全面的自动化检测和非交互式操作能力，使其适用于CI/CD流水线、部署脚本和容器化环境。

🔍 交互模式检测逻辑

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

第1阶段：持续集成环境检测

检查持续集成指标：

# 主要CI变量
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
# 和15多个CI环境变量

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

识别自动化/批处理处理：

# 自动化指标
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
# 云平台：Heroku, Vercel, Netlify, Railway等

第3-8阶段：终端&进程环境

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

📊 自动化行为矩阵

环境类型	检测方法	行为	日志级别
GitHub Actions	GITHUB_ACTIONS=true	静默，无提示	INFO
GitLab CI	GITLAB_CI=true	静默，无提示	INFO
Docker构建	CONTAINER=true 或非TTY	静默，无提示	INFO
Cron作业	CRON=true 或非TTY	静默操作	INFO
SSH脚本	SSH_CONNECTION 无SSH_TTY	非交互式	INFO
Kubernetes	KUBERNETES_SERVICE_HOST	Pod感知操作	INFO
AWS Lambda	LAMBDA_RUNTIME_DIR	无服务器模式	DEBUG
本地终端	TTY + 交互式shell	完全交互	DEBUG

⚙️ 自动化特定功能

超时保护

# 所有操作都内置了超时
Pip安装：5-10分钟限制
用户提示：10秒超时，自动默认
服务器启动：快速验证模式用于测试
网络操作：可配置超时

信号处理

# 自动化中的优雅关闭
SIGINT/SIGTERM：清理资源
键盘中断：记录并优雅处理
部分操作：自动回滚/清理
退出码：标准自动化友好代码

非交互式设置

# 设置脚本自动化模式
./scripts/setup-dash-mcp.sh    # 自动检测环境
CI=true ./scripts/setup-dash-mcp.sh    # 强制CI模式
BATCH_MODE=true ./scripts/setup-dash-mcp.sh    # 强制批处理模式

🔒 安全&保障

环境验证

• 路径净化：验证并净化所有文件路径
• 输入验证：全面查询和参数验证
• 资源限制：内存和CPU使用约束
• 速率限制：内置请求速率限制（每分钟100次）

错误恢复

# 坚固的错误处理
部分安装：自动清理
网络故障：具有退避机制的重试
损坏的缓存：自动重建缓存
文档集问题：优雅降级

📈 自动化中的性能

基准

# 自动化环境性能
CI安装时间：约70-80秒
服务器验证：约2-3秒
文档集发现：约500毫秒（首次运行），约50毫秒（缓存）
超时响应：最大5秒
干净环境设置：约70-75秒

自动化优化

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

🛠️ 自动化测试

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

# 快速CI兼容性测试
./test-ci-automation.sh

# 全面自动化验证
./test-final-validation.sh

# 单独组件测试
./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 Actions工作流程

- 名称：设置Enhanced Dash MCP
  运行：|
    git clone <repository-url>
    cd enhanced-dash-mcp
    CI=true ./scripts/setup-dash-mcp.sh
    # 无提示，自动默认

Docker容器

RUN git clone <repository-url> && \\
    cd enhanced-dash-mcp && \\
    CONTAINER=true ./scripts/setup-dash-mcp.sh
# 自动检测容器环境

Kubernetes任务

命令：[/bin/bash, "-c"]
参数：
  - |
    cd /app/enhanced-dash-mcp
    KUBERNETES_SERVICE_HOST=true ./scripts/setup-dash-mcp.sh
    python3 enhanced_dash_server.py --test

🔍 调试自动化问题

日志分析

# 查看详细的环境检测日志
export DASH_MCP_LOG_LEVEL=DEBUG
python3 enhanced_dash_server.py --test

# 检查自动化检测原因
grep "Detection reason" ~/.cache/dash-mcp/server.log

# 验证环境变量
grep "Environment summary" ~/.cache/dash-mcp/server.log

常见自动化场景

# 强制交互模式（测试）
export FORCE_INTERACTIVE=true

# 覆盖环境检测
export DASH_MCP_MODE=interactive  # 或'automation'

# 详细过程信息
export DASH_MCP_DEBUG_PROCESS=true

🏗️ 架构

核心组件

• DashMCPServer - 主服务器协调所有组件
• CacheManager - 多级缓存（内存+磁盘）
• ContentExtractor - 从各种格式中干净地提取文本
• **F