技术文档摘要

docc-mcp

这是一个模型上下文协议（MCP）服务器，它将Apple DocC文档存档暴露给AI代理，从而实现实时访问Swift文档，而无需训练数据或大量上下文窗口。

功能

• 🔍 搜索文档：在所有DocC存档中查找符号、类型和函数
• 📖 符号详情：获取特定Swift符号的详细信息
• 📄 文章访问：获取教程和文章的详细信息
• 🗂️ 浏览存档：交互式导航DocC存档结构
• ⚡ 实时访问：查询当前文档，无过期数据
• 🎯 过滤搜索：按符号类型（类、结构体、枚举、协议等）进行搜索

安装

npm install
npm run build

使用方法

作为MCP服务器

添加到您的MCP客户端配置：

{
  "mcpServers": {
    "docc": {
      "command": "node",
      "args": [
        "/path/to/docc-mcp/dist/index.js",
        "--archive-path", "/path/to/your/docc/archives",
        "--archive-path", "~/Documents/Xcode/DerivedData"
      ]
    }
  }
}

配置选项

使用--archive-path参数配置存档路径：

单个存档目录：

{
  "mcpServers": {
    "docc": {
      "command": "node", 
      "args": [
        "/path/to/docc-mcp/dist/index.js",
        "--archive-path", "/Users/yourname/docc-archives"
      ]
    }
  }
}

多个存档目录：

{
  "mcpServers": {
    "docc": {
      "command": "node",
      "args": [
        "/path/to/docc-mcp/dist/index.js",
        "--archive-path", "/Users/yourname/Project1/docs",
        "--archive-path", "/Users/yourname/Project2/docs", 
        "--archive-path", "~/Documents/Xcode/DerivedData"
      ]
    }
  }
}

使用Xcode生成的文档：

{
  "mcpServers": {
    "docc": {
      "command": "node",
      "args": [
        "/path/to/docc-mcp/dist/index.js",
        "--archive-path", "~/Library/Developer/Xcode/DerivedData/YourApp-*/Build/Products/Debug/YourApp.doccarchive"
      ]
    }
  }
}

注意：必须至少指定一个--archive-path。如果没有提供存档路径，服务器将以错误退出。

常见的DocC存档位置

Xcode生成的文档：

• ~/Library/Developer/Xcode/DerivedData/YourApp-*/Build/Products/Debug*/Documentation/
• ~/Library/Developer/Xcode/DerivedData/YourApp-*/Build/Products/Release*/Documentation/

Swift包管理器：

• .build/plugins/Swift-DocC/outputs/YourPackage.doccarchive

手动构建DocC：

• docs/（如果您将存档组织在一个docs文件夹中）
• 在您运行swift package generate-documentation的项目根目录下

多个项目：

{
  "args": [
    "/path/to/docc-mcp/dist/index.js",
    "--archive-path", "~/MySwiftPackage1/docs",
    "--archive-path", "~/MySwiftPackage2/.build/plugins/Swift-DocC/outputs", 
    "--archive-path", "~/Library/Developer/Xcode/DerivedData"
  ]
}

可用工具

1. list_archives

列出所有可用的DocC存档及其元数据。

{
  "name": "list_archives"
}

2. search_docc

跨DocC文档进行搜索。

{
  "name": "search_docc",
  "arguments": {
    "query": "SwiftSyntax",
    "archive": "SwiftSyntax",
    "type": "struct"
  }
}

3. get_symbol

获取特定符号的详细信息。

{
  "name": "get_symbol", 
  "arguments": {
    "symbolId": "documentation/swiftsyntax/tokensyntax",
    "archive": "SwiftSyntax"
  }
}

4. get_article

获取特定文章或教程的详细信息。

{
  "name": "get_article",
  "arguments": {
    "articleId": "meetcomposablearchitecture",
    "archive": "ComposableArchitecture"
  }
}

5. browse_archive

浏览DocC存档的结构。

{
  "name": "browse_archive",
  "arguments": {
    "archive": "SwiftSyntax",
    "path": "documentation/swiftsyntax"
  }
}

存档结构

服务器期望在由--archive-path指定的目录中的DocC存档：

测试

运行测试脚本来验证功能：

node test-server.js

这将：

• 列出所有可用的存档
• 测试搜索功能
• 浏览存档结构
• 验证符号检索

示例查询

查找所有SwiftUI导航组件：

{
  "name": "search_docc",
  "arguments": {
    "query": "navigation",
    "type": "struct"
  }
}

获取TokenSyntax的详细信息：

{
  "name": "get_symbol",
  "arguments": {
    "symbolId": "documentation/swiftsyntax/tokensyntax", 
    "archive": "SwiftSyntax"
  }
}

浏览SwiftSyntax类型：

{
  "name": "browse_archive",
  "arguments": {
    "archive": "SwiftSyntax",
    "path": "documentation/swiftsyntax"
  }
}

性能

• 缓存：存档和符号被缓存以实现快速重复访问
• 搜索限制：每个查询的结果限制为50个以提高性能
• 懒加载：按需加载存档
• 文件限制：每个存档的搜索限制为100个文件以提高性能

DocC集成

此服务器与标准DocC存档兼容。要生成兼容的存档：

# 使用Swift-DocC
swift package generate-documentation --target MyLibrary

# 使用Xcode
# 产品 → 构建文档

支持的DocC特性

• ✅ 符号元数据（标题、种类、角色、平台）
• ✅ 文档层次结构
• ✅ 符号引用和关系
• ✅ 带有语法高亮的代码声明
• ✅ 摘要/总结文本
• ✅ 平台可用性信息
• ✅ 模块组织

许可证

MIT许可证