Docset MCP

DocsetMCP

直接从人工智能助手访问您当地的达世币文档 🚀

DocsetMCP是一个模型上下文协议（MCP）服务器，它将您的本地达世币文档集与Claude等人工智能助手无缝集成，使您无需离开对话即可即时访问离线文档。

📋 目录

• 为什么选择DocsetMCP？
• 快速开始
• 特性
• 先决条件
• 安装
• 配置
• 使用示例
• 可用工具
• 故障排除
• 发展
• 贡献
• 许可证

为什么选择DocsetMCP？

• 📚 即时文档：没有切换，没有网络搜索。在AI对话中直接进入文档
• 🔒 本地和私人：在您的计算机上使用docset文件
• ⚡ 迅速的：优化缓存和直接数据库查询
• 🎯 精确的结果：通过智能过滤获得所需内容

快速开始

{
  "mcpServers": {
    "docsetmcp": {
      "command": "uvx",
      "args": ["docsetmcp"]
    }
  }
}

添加到MCP配置并重新启动MCP客户端。然后试着问“给我找AppIntent文档”之类的问题

✨ 特性

文档搜索

• 多文档集支持：搜索165多个支持的文档集，包括Apple、NodeJS、Python等
• 语言过滤：针对文档集中的特定编程语言
• 基于名称的搜索：仅返回搜索词与项目名称匹配的条目，以获得精确的结果
• 智能排名：按匹配类型（精确>前缀>子字符串）和动态类型排序的结果
• 集装箱指南：框架和类条目显示了探索成员的深入注释

备忘单访问

• 快速参考：即时访问Git、Vim、Docker和40多个其他备忘单
• 模糊匹配：即使名字不全，也能找到备忘单
• 类别浏览：在每个备忘单中按类别浏览命令
• 搜索范围：查询任何备忘单中的特定命令

性能与集成

• 高效缓存：用于重复查询的内存缓存
• 直接数据库访问：没有中间服务器或API
• 通用：适用于Claude Desktop、Cursor、VS Code和任何兼容MCP的客户端
• 框架发现：列出任何文档集中的所有可用框架/类型
• 集装箱指南：带有成员的框架和类的自动深入注释

📦 支持的文档集

DocsetMCP支持165多个文档集，包括：

Popular Languages

• Python（2和3）
• JavaScript/TypeScript
• Java
• C/C++
• 去
• 锈
• 红宝石
• Swift/Objective-C
• PHP程序
• 猛击
• 还有更多。..

Web Frameworks

• React/Angular/Vue
• Node.js/Express
• Django/Flask
• Ruby on Rails
• 独自创立
• jQuery
• 还有更多。..

Developer Tools

• Git（备忘单）
• Docker（备忘单）
• Vim（备忘单）
• MySQL/PostgreSQL
• MongoDB/Redis
• nginx/Apache
• 还有更多。..

使用 list_available_docsets 查看系统上安装的所有docset。

先决条件

• macOS（Dash仅适用于Mac）
• 冲撞 已下载所需的文档集
• Python 3.10或更高版本
• UV包管理器(如何安装)
• 支持MCP的AI助手（Claude Desktop、Claude Code CLI、Cursor IDE等）

配置

自定义文档集位置

默认情况下，DocsetMCP在达世币的标准目录中查找文档集：

• 文档集: ~/Library/Application Support/Dash/DocSets
• 备忘单: ~/Library/Application Support/Dash/Cheat Sheets

您可以使用以下方式自定义这些位置：

环境变量

# Set custom docset directory
export DOCSET_PATH="/path/to/your/docsets"

# Set custom cheatsheet directory  
export CHEATSHEET_PATH="/path/to/your/cheatsheets"

# Run with custom paths
docsetmcp

命令行参数

# Test with custom docset path
docsetmcp --docset-path "/path/to/your/docsets" --list-docsets

# Test with custom cheatsheet path
docsetmcp --cheatsheet-path "/path/to/your/cheatsheets" --test-connection

# Use both custom paths
docsetmcp --docset-path "/custom/docsets" --cheatsheet-path "/custom/cheatsheets"

# Use additional search paths (searches multiple locations)
docsetmcp --additional-docset-paths "/extra/docsets" "/more/docsets"
docsetmcp --additional-cheatsheet-paths "/extra/cheatsheets" "/more/cheatsheets"

优先级顺序：

1. CLI参数（最高优先级）
2. 环境变量
3. 默认达世币位置（最低优先级）

其他搜索路径：

这 --additional-docset-paths 和 --additional-cheatsheet-paths 选项允许DocsetMCP在主路径之外的多个位置进行搜索。这在以下情况下很有用：

• 您在多个目录中都有文档集
• 您想包含第三方或自定义文档集
• 您正在跨不同工具共享文档集

DocsetMCP将自动发现并配置这些附加路径中的文档集。

MCP客户端设置

请在下面选择您的MCP客户端以获取具体的设置说明：

🤖 Claude Desktop

增添 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "docsetmcp": {
      "command": "uvx",
      "args": ["docsetmcp"]
    }
  }
}

对于自定义文档集位置：

{
  "mcpServers": {
    "docsetmcp": {
      "command": "uvx",
      "args": ["docsetmcp"],
      "env": {
        "DOCSET_PATH": "/path/to/your/docsets",
        "CHEATSHEET_PATH": "/path/to/your/cheatsheets"
      }
    }
  }
}

⌨️ Claude Code CLI

# For current project
claude mcp add docsetmcp "uvx docsetmcp"

# For all projects
claude mcp add --scope user docsetmcp "uvx docsetmcp"

📝 Cursor, VS Code, Windsurf and other MCP-compatible clients

添加到MCP配置（光标： .mcp/mcp.json 在项目根目录中：

{
  "mcpServers": {
    "docsetmcp": {
      "command": "uvx",
      "args": ["docsetmcp"]
    }
  }
}

备注：重新启动客户端并检查MCP设置的连接状态。

安装

无需安装（推荐）

如果您的MCP客户端支持 uvx，无需安装！该软件包将在需要时自动下载并运行。请参阅 快速开始 或 配置 部分。

手动安装

如果您更喜欢在本地安装或您的MCP客户端不支持 uvx:

pip install docsetmcp

然后使用 docsetmcp 而不是 uvx docsetmcp 在您的配置中。

开发安装

1. 克隆并安装:

   git clone https://github.com/codybrom/docsetmcp.git
   cd docsetmcp
   pip install -e .

1. 运行测试 （可选）：

   # Install test dependencies
   pip install pytest pytest-cov pytest-xdist

   # Run basic tests
   pytest tests/test_docsets.py::TestDocsets::test_yaml_structure -v

   # Run quick tests (structure + existence checks)
   pytest tests/ -k "yaml_structure or test_docset_exists" -v

   # Run full test suite (all docsets)
   pytest tests/ -v

   # Run with coverage
   pytest tests/ --cov=docsetmcp --cov-report=html -v

   # Validate all local cheatsheets work (integration test)
   python scripts/validate_cheatsheets.py

使用示例

配置后，您可以要求您的AI助手自然搜索文档：

🍎 iOS/macOS开发

"Search for URLSession documentation"
"Show me how to use AppIntent in SwiftUI"
"Find CarPlay framework documentation"  # Returns framework + related entries with drilldown notes
"Search for CPListTemplate class"       # Returns specific CarPlay class
"Find NSPredicate examples"

🌐 网站开发

"Look up Express.js middleware documentation"
"Search React hooks in the React docset"
"Find CSS flexbox properties"

🛠️ DevOps与终端

"Search git rebase commands in the Git cheatsheet"
"Show Docker compose syntax from the cheatsheet"
"Find bash array manipulation commands"

📊 数据科学

"Search pandas DataFrame methods"
"Look up NumPy array broadcasting"
"Find matplotlib pyplot functions"

高级用法

# Search specific docset with language filter
"Use search_docs for 'URLSession' in the apple_api_reference docset with Swift language"

# Explore framework members using drilldown guidance
"Search for 'SwiftData' then follow the drilldown note to see all members"

# List all available tools
"What frameworks are available in the nodejs docset?"

# Browse cheatsheet categories
"Show all categories in the vim cheatsheet"

发现工作流程

DocsetMCP是为 基于名称的搜索，而不是关键字搜索。遵循以下工作流程：

1. 从发现工具开始

# Find what languages are available
"List all available programming languages"

# Find docsets for your language
"Show me all Python docsets"

# See what types are available in a docset
"List all types in the apple_api_reference docset for Swift"

# Browse entries by type with letter filters
"Show me all Classes starting with 'UI' in apple_api_reference for Swift"

2. 然后按确切名称搜索

# Once you know exact names, search for them
"Search for UIViewController in apple_api_reference with Swift"
"Find readFile documentation in nodejs docset"
"Show me the CarPlay framework documentation"

3. 使用深入笔记

当您找到容器类型（框架、类）时，请遵循深入指导：

# Container entry will show: "contains 42 additional members - use search_docs('ContainerName', max_results=50)"
"Search for SwiftData in apple_api_reference with max_results=50"

运作原理

1. 多格式支持：处理Apple缓存格式和tarix压缩
2. 直接数据库访问：查询达世币的SQLite数据库以实现快速查找
3. 基于名称的匹配：仅返回搜索词与项目名称匹配的条目（无误报）
4. 智能排名：优先考虑精确匹配，然后是前缀匹配，再是子字符串匹配
5. 动态类型排序：使用docset配置文件进行智能结果优先级排序
6. 集装箱检测：自动检测具有成员的框架/类，并提供探索指导
7. 智能提取：解压缩Apple的DocC JSON或从tarix档案中提取HTML
8. Markdown格式：将文档转换为可读的Markdown

可用工具

DocsetMCP提供了11个强大的工具来访问您的文档：

🔍 search_docs

从任何文档集中搜索和提取文档。

📋 search_cheatsheet

搜索Dash备忘单以获取快速命令参考。

📚 list_available_docsets

列出所有已安装的达世币文档集及其支持的语言。

📝 list_available_cheatsheets

列出所有可搜索的达世币备忘单。

🏗️ list_frameworks

列出特定文档集中的框架/类型。

🌍 list_languages

通过可用文档了解所有编程语言。

📖 list_docsets_by_language

查找支持特定编程语言的所有文档集。

🏷️ list_types

以文档集/语言列出所有可用类型（类、协议、函数等）。

📋 list_entries

列出按类型和可选名称前缀筛选的条目。

📂 list_cheatsheet_categories

列出特定备忘单中的所有类别。

📄 fetch_cheatsheet

获取整个备忘单内容（建议全面访问）。

故障排除

❌ "Docset not found" error

这意味着Dash中没有安装docset。要修复：

1. 打开Dash.app
2. 转到“首选项”→ 下载
3. 下载所需的文档集
4. 重新启动MCP客户端

🔌 MCP connection failed

1. 检查安装情况：运行 pip show docsetmcp 验证安装
2. 手动测试：运行 uvx docsetmcp 在终端中-您应该看到MCP输出
3. 检查日志:

- Claude桌面：检查Console.app以获取Claude日志 - 光标：检查输出→ MCP面板

1. 验证配置路径：确保配置文件位于正确的位置

📭 No results found

• 内容可能不在您的本地达世币缓存中
• 尝试使用不同的术语或部分匹配项进行搜索
• 使用 list_available_docsets 验证是否加载了docset
• 某些文档集可能使用不同的命名约定（例如，“fs”与“filesystem”）

🐛 Other issues

1. Python版本确保你有Python 3.10或更高版本
2. 未找到UV：从安装UV包管理器
3. 权限不足：检查Dash docsets目录上的文件权限
4. 报告错误：打开一个问题

发展

从源头构建

# Clone the repository
git clone https://github.com/codybrom/docsetmcp.git
cd docsetmcp

# Install in development mode
pip install -e .

# Install all development dependencies
pip install -r requirements.txt

# Set up pre-commit hooks
pre-commit install

测试

# Run basic structure tests
pytest tests/test_docsets.py::TestDocsets::test_yaml_structure -v

# Run quick tests (structure + existence)
pytest tests/ -k "yaml_structure or test_docset_exists" -v

# Run full test suite (all docsets)
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=docsetmcp --cov-report=html -v

# Run tests in parallel
pytest tests/ -n auto -v

# Validate cheatsheets
python scripts/validate_cheatsheets.py

代码质量

# Format Python code with Black
black docsetmcp/

# Format YAML files with yamlfix
yamlfix docsetmcp/docsets/*.yaml

# Run all pre-commit hooks
pre-commit run --all-files

# Run specific hook
pre-commit run yamlfix --all-files

# Run spell check (cspell installed automatically during setup)
npm run spell

CLI命令

# Test version
docsetmcp --version

# List available docsets
docsetmcp --list-docsets

# Test server startup
docsetmcp --test-connection

# Test with custom paths
docsetmcp --docset-path "/custom/path" --list-docsets

建筑分布

# Build package
python setup.py sdist bdist_wheel

# Install from source
pip install .

建筑

核心组件

• docsetmcp/server.py：使用FastMCP实现主MCP服务器。包含DashExtractor类，该类处理：

- 苹果缓存格式（基于SHA-1 UUID，采用brotli压缩） - Tarix格式（tar.gz档案） - 用于文档查找的SQLite数据库查询 - HTML到Markdown的转换

• docsetmcp/config_loder.py：为165多个支持的文档集加载YAML配置的配置系统。提供智能默认值，并处理简单和复杂的配置格式。

• docsetmcp/docsets/：每个支持的docset的YAML配置文件，定义：

- 文档集路径和格式 - 语言变体和过滤器 - 键入搜索结果的优先级

关键实施细节

1. 多格式支持：服务器根据docset配置自动检测和处理苹果的现代缓存格式（使用基于SHA-1的UUID）和旧的tarix压缩格式。

1. 缓存策略：提取的文档缓存在内存中（苹果格式为_fs_cache，tarix格式为_html_cache），以提高重复查询的性能。

1. 搜索算法：在optimizedIndex.dsidx数据库上使用SQLite不区分大小写的LIKE查询。结果按匹配类型（精确>前缀>子字符串）排序，然后按docset配置文件中的动态类型排序。仅返回搜索词与项目名称匹配的条目。

1. 配置加载：ConfigLoader应用智能默认值，允许最小的YAML配置，同时在需要时支持复杂的覆盖。

1. 集装箱类型检测：当框架、类和模块条目包含其他成员时，它们会自动包含深入注释，引导用户搜索更具体的内容。

贡献

我们欢迎捐款！以下是您可以提供帮助的方式：

添加新的Docset支持

1. 在中创建YAML配置 docsetmcp/docsets/:

   # docsetmcp/docsets/my_docset.yaml
   name: My Docset
   description: Brief description of the docset
   docset_path: My_Docset/My_Docset.docset
   languages:
     - python
     - javascript

1. 测试您的配置：

   pytest tests/test_docsets.py -k "my_docset" -v

1. 提交拉取请求

报告问题

• 🐛 错误报告
• 💡 功能请求
• 📚 文件问题

开发指南

• 遵循PEP 8风格指南
• 为新功能添加测试
• 根据需要更新文档
• 保持提交的重点和描述性

技术架构

DocsetMCP利用达世币的内部结构实现高效的文档访问：

• 格式支持：处理苹果的现代缓存格式（基于SHA-1 UUID和brotli压缩）和传统的tarix存档
• 缓存策略：用于重复查询的内存缓存
• 数据库访问：将SQLite查询直接指向达世币的优化索引
• 内容提取：具有回退策略的智能提取
• 类型系统：更好的IDE支持的完整类型提示

许可证

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

致谢

• 多亏了 卡普利 用于创建Dash
• 建立在 模型上下文协议 标准
• 受到MCP社区和生态系统的启发