Corpus

Corpus 聚合了你组织中所有仓库的文档，使用 Spotify Backstage 目录实体构建实时系统地图，并将其全部置于一个强大的**模型上下文协议（MCP）**服务器之后。

让你的 AI 代理（Claude、Copilot 等）获得理解架构、服务归属、文档和代码所需的整体上下文——全部集中在一处！

✨ 功能特性

• 🗺️ 自动生成实体关系图：完整解析 Backstage catalog-info.yaml 实体（组件、API、系统、用户），并使用公认的关系（例如 ownerOf/ownedBy、providesApi/apiProvidedBy）生成双向关系图。

• 📖 集中式文档搜索：在整个组织中快速进行词法搜索，覆盖 README.md、docs/**/*.md、adr/**/*.md 以及 AI 技能。

• 🔍 全局代码搜索：通过 GitHub 代码搜索 API 在所有组织仓库中进行关键词搜索。

• 💬 Issue 与 PR 上下文：代理 GitHub 的搜索 API，在整个组织中查找讨论、PR 和 issue（search_issues_and_prs）。

• 📄 文件读取：直接从任何仓库分支或提交中访问精确的文件内容。

• ⚙️ API 模式聚合：自动索引 openapi 和 swagger 文件，使代理能够立即获取端点契约（list_api_schemas）。

• 🚀 零配置启动：启动时自动运行缺失的构建。如果你有凭据，只需运行 npm start，服务器就会获取并索引所有内容。

• 🐞 差距报告：可选功能，当文档无法回答代理的问题时，自动提交 GitHub issue。

Related MCP server: repovine

🛠️ 快速开始

1. 前置条件

• Node.js v22+

• GitHub PAT（个人访问令牌）：

  • 经典令牌：需要 repo（用于读取私有仓库）和 read:org（如果查询组织）。

  • 细粒度令牌：需要对所有仓库具有 Contents: Read-only 和 Metadata: Read-only 权限。如果启用 ENABLE_GAP_REPORTING，还需要对目标仓库具有 Issues: Read & Write 权限。

2. 配置环境变量

在根目录中创建 .env 文件：

GIT_ORG=your-github-org-or-username
GIT_PAT=your-github-personal-access-token

# Optional
ENABLE_GAP_REPORTING=false
GITHUB_PROJECT=your-github-org/doc-gaps-repo

3. 构建与运行

本地执行：

npm install
npm run build
npm start

注意：如果尚未运行过语料库和系统地图生成脚本，npm start 会自动触发它们。

Docker 执行：

docker build -t corpus-mcp .
docker run -i -e GIT_ORG=your-github-org -e GIT_PAT=your-github-pat corpus-mcp

🤖 注册到 AI 客户端

Antigravity

Antigravity 原生支持 MCP。通过将其添加到 ~/.gemini/config/mcp_config.json 来全局配置服务器：

{
  "mcpServers": {
    "corpus": {
      "command": "node",
      "args": ["/absolute/path/to/code-context-mcp/dist/src/index.js"],
      "env": {
        "GIT_ORG": "your-github-org",
        "DOTENV_CONFIG_PATH": "/absolute/path/to/code-context-mcp/.env",
        "CORPUS_DIR": "/absolute/path/to/code-context-mcp/corpus"
      }
    }
  }
}

Claude Desktop

将此内容添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "corpus": {
      "command": "node",
      "args": ["/absolute/path/to/code-context-mcp/dist/src/index.js"],
      "env": {
        "GIT_ORG": "your-github-org",
        "GIT_PAT": "your-github-pat",
        "CORPUS_DIR": "/absolute/path/to/code-context-mcp/corpus"
      }
    }
  }
}

Claude Code

在项目根目录中运行以下命令：

claude mcp add corpus "node $(pwd)/dist/src/index.js"

🏗️ 架构与命令

• npm run build:corpus：爬取 GitHub 组织并将文档和目录数据下载到 corpus/manifest.json。

• npm run build:map：将清单转换为活动依赖关系图，保存到 corpus/system-map.yaml。

• npm run build：运行完整流水线并编译 TypeScript。

• npm run test：使用 Node.js 原生测试运行器运行单元测试。

🧩 系统地图与 catalog-info.yaml

Corpus 会自动生成组织服务的全局依赖关系图。要参与系统地图，每个仓库的根目录应包含一个 catalog-info.yaml 文件，符合 Backstage 描述符格式。

由于 Corpus 的行为类似于 Backstage 目录处理器，它会提取任何实体类型（组件、API、系统、组）并自动建立双向关系。如果你的 Component 定义了 owner: group:auth-team 和 providesApis: [api:auth-api]，Corpus 会自动生成 ownedBy/ownerOf 和 providesApi/apiProvidedBy 边，使 AI 代理能够原生遍历你组织的整个服务图。

catalog-info.yaml 示例：

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-auth-service
  description: Handles user authentication and token generation
spec:
  type: service
  lifecycle: production
  owner: group:auth-team
  providesApis:
    - api:auth-api
  dependsOn:
    - component:user-database
    - component:email-service

💡 最佳实践与理念

为了充分利用 Corpus 和你的 AI 代理，我们推荐以下生态系统实践：

1. 让文档贴近代码：文档应存放在代码旁边的仓库中。记录系统如何工作的最佳位置就是系统本身旁边。Corpus 会自动获取所有仓库中的 docs/**/*.md 和 adr/**/*.md。

2. 集中式 Wiki 仓库：如果你有跨系统的公司级架构决策、RFC 或代码质量标准，请将它们以 Markdown 文件的形式保存在一个集中的"Wiki"仓库中。Corpus 会完美地聚合它们。

3. 与 Spotify Backstage 协同：如果你使用 Backstage，Corpus 是完美的伴侣。

   • Backstage 是一个为人类构建的内部开发者门户（IDP），提供丰富的 Web UI。

   • Corpus 是一个为AI 代理构建的 IDP，通过 MCP 暴露完全相同的上下文。 由于 Corpus 原生解析标准的 catalog-info.yaml 文件，因此零重复工作。如果你的团队已经在为 Backstage 定义 dependsOn、lifecycle 和 owner 标签，Corpus 会自动收集它们并将其转换为 AI 代理可以遍历的活动图。

4. 频繁的自动化更新：Corpus 旨在成为你组织的活生生的快照。运行构建脚本（npm run build）会重新获取并重建本地语料库。由于它是一个简单的 API 抓取脚本，构建过程消耗零 LLM 令牌。理想情况下，Corpus 应部署在公司内部集中位置，使用 cron 作业（如 GitHub Action）每晚重建 manifest.json 并分发给开发者。

🤝 贡献

我们欢迎贡献！请参阅我们的贡献指南，了解如何开始、设置开发环境以及提交 Pull Request 的详细信息。

本项目强制使用 Conventional Commits。预提交钩子会自动使用 Prettier 格式化代码并使用 ESLint 检查代码。

有关更多详细信息，请参阅设置技能指南。

📄 许可证

Corpus 可免费使用。所有知识产权归 Sayam Hussain 所有。

本项目基于 MIT 许可证 授权。