Github Second Brain

近期重大更新

本项目于 2025 年 6 月 8 日进行了重大重构（https://github.com/baonguyen09/github-second-brain/issues/42）。

• 旧版：可在 legacy/v1-archive 分支中获取
• 当前版本：主分支（v2.0+）
• 迁移指南：参见 MIGRATION.md

分支信息

• main - 当前重构版本
• legacy/v1-archive - 原始架构（已冻结）

项目介绍

为什么？

问题

当我刚开始为开源项目贡献代码以积累更多经验时，仓库对于新手来说实在太庞大，让我感到不知所措。我想借助 AI 助手来熟悉项目，但没有好的办法提供必要的上下文。

解决方案

一个可自托管的 MCP 服务，为 AI 客户端提供一组工具，让它能够自行探索和了解 GitHub 仓库。

✨ 功能

• 😎 获取任意 GitHub 项目的最新文档：让 AI 助手无缝访问 GitHub 项目的文档和代码。内置的检索工具可帮助 AI 获取目录树和特定文件内容，且不会超出上下文窗口限制！

• 🧠 告别幻觉：借助 Github Second Brain，AI 助手可以为你的问题提供准确且相关的回答。

• ✅ 开放、免费且私密：Github Second Brain 是开源软件，完全免费使用。它不会收集个人信息或存储查询内容，并且完全可自托管！

• 提取并分析 GitHub 仓库中的数据。

入门

⚙️ 前提条件

开始之前，请确保满足以下要求：

1. 若要在容器中运行服务，需要安装 Docker。
2. 安装 Docker 后，还需确保 Docker 正在运行。该镜像是公开的；如果拉取时出错，可能需要运行 docker logout ghcr.io。
3. 最后，需要创建 GitHub 个人访问令牌。 MCP 服务可以使用许多 GitHub API，因此请启用你愿意授予 AI 工具的权限（要进一步了解访问令牌，请参阅文档）。

🚀 安装

在 Claude Desktop 中使用

1. 在 Claude Desktop 中，前往 Settings > Developer > Edit Config
2. 将配置替换为：

{
  "mcpServers": {
    "github-second-brain": {
      "command": "docker",
      "args": [
          "run",
          "-i",
          "--rm",
          "-e",
          "GITHUB_PERSONAL_ACCESS_TOKEN",
          "ghcr.io/baonguyen09/github-second-brain:latest"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_PERSONAL_GITHUB_ACCESS_TOKEN"
      }
    }
  }
}

在 Cursor 中使用

更新 Cursor 配置文件 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "github-second-brain": {
      "command": "docker",
      "args": [
          "run",
          "-i",
          "--rm",
          "-e",
          "GITHUB_PERSONAL_ACCESS_TOKEN",
          "ghcr.io/baonguyen09/github-second-brain:latest"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_PERSONAL_GITHUB_ACCESS_TOKEN"
      }
    }
  }
}

⚙ 工作原理

Github Second Brain 使用 Model Context Protocol（MCP）将 AI 助手连接到 GitHub 仓库。MCP 是一种标准，让 AI 工具能够从外部来源请求更多信息。 使用 Github Second Brain 时会发生以下情况：

1. 你向 AI 助手提供一个 docker image，用于构建本地 MCP 服务，该服务会提供用于获取 issue 上下文、文件内容、目录树等的工具。
2. 向 AI 助手询问与文档或代码相关的问题。
3. 你的 AI 会向本地构建的 MCP 服务发送请求，以使用其工具（需经你批准）。
4. 本地服务执行 AI 的请求并返回所需数据。
5. 你的 AI 接收信息，并生成更准确、有依据且不会产生幻觉的回答。

🗺️ 路线图

我们持续致力于改进 GitHub Second Brain。以下是一些计划中的功能：

• 添加一个 MCP 工具，用于获取指定深度的文件内容和目录树
• 添加一个 MCP 工具，用于获取 GitHub issues + pull request
• 将当前的 gitingest 处理方式改为直接使用 GitHub API，以加快响应速度
• 更改项目架构，使其完全可自托管（数据永远不会离开你的设备）

如需详细了解即将推出的功能并提出新功能建议，请查看未解决的问题和我们的项目看板。

🤝 贡献

贡献让开源社区成为一个如此适合学习、启发和创造的地方。我们非常感谢你做出的任何贡献。

非技术类贡献方式

• 给项目点个星⭐！：这有助于提升项目的可靠性和知名度，吸引更多贡献者来改进项目，从而让你受益。
• 创建 Issue：如果你发现了错误或有新功能的想法，请在 GitHub 上创建 issue。这有助于我们跟踪并确定请求的优先级。
• 传播消息：如果你喜欢 GitHub Second Brain，请与朋友、同事分享，也可以在社交媒体上分享。这有助于社区发展，并让项目变得更好。
• 使用 GitHub Second Brain：最好的反馈来自实际使用！如果你遇到任何问题或有改进建议，请在 GitHub 上创建 issue告知我们，或联系 Bao：[email protected] 。

技术类贡献方式

如果你有改进建议，请 fork 此仓库并创建 pull request。你也可以直接创建带有 "enhancement" 标签的 issue。

1. Fork 项目
2. 创建功能分支（git checkout -b feature/AmazingFeature）
3. 提交更改（git commit -m 'Add some AmazingFeature'）
4. 推送到分支（git push origin feature/AmazingFeature）
5. 创建 Pull Request

请阅读我们的贡献指南，了解如何贡献、编码规范和 pull request 流程的详细说明。此外，请阅读我们的行为准则，了解我们共同遵守的社区规范。

🛠️ 工具

Github Second Brain 为 AI 助手提供了多个实用工具，帮助它们访问、理解和查询 GitHub 仓库。

get_processed_repo（已弃用）

• 此工具会将整个代码库摄取为一个便于提示词使用的文本文件，供 AI 使用。它通过 gitingest 库摄取整个代码库，并直接提供该文件。这能让 AI 全面了解项目的内容。不过，不建议使用此工具，并且很快会将其禁用，因为它很容易让 AI 接收过多数据，超出其上下文窗口限制。

• 适用场景： 小型仓库，以及询问各种问题，例如仓库概览、如何贡献等。

get_tree_directory

• 此工具以带缩进的纯文本形式向 AI 提供代码库的完整目录树。与加载所有文档（文档可能非常庞大）不同，可以使用此工具了解代码库的概况，然后使用其他工具仅检索相关内容。

• 适用场景： 询问代码库结构时。

get_repo_contents

• 此工具返回代码库中任意文件或目录的完整内容。

• 适用场景： 询问项目中特定功能、函数、概念或文档中未涵盖的任何技术细节时。

get_issue_context

• 此工具返回任意 GitHub issue 的详细上下文，包括标题、正文、元数据以及该 issue 中的所有评论。

• 适用场景： 询问 GitHub issue 及其相关上下文时。

get_code_diff

• 此工具返回任意 GitHub pull request、不同分支、标签和提交的详细差异。

• 适用场景： 询问 GitHub pull request 或代码版本（不同分支、标签或发行版之间）时。

📝 许可证

本项目采用 Apache License 2.0 许可。

🙏 致谢

我们感谢以下个人和项目提供的贡献与启发：

• GitMCP，供我们参考
• 官方 GitHub MCP Server
• 所有出色的贡献者！

免责声明

Github Second Brain 按“原样”提供，不提供任何形式的保证。虽然我们努力确保服务的可靠性和安全性，但对于因使用本服务而可能产生的任何损害或问题，我们概不负责。通过 Github Second Brain 访问的 GitHub 项目受其各自所有者的条款和条件约束。Github Second Brain 与 GitHub 或任何提及的 AI 工具均无关联。