🧠 RuvScan - MCP 服务器用于智能 GitHub 发现

赋予 Claude 发现 GitHub 工具的能力，具有亚线性智能。

RuvScan 是一个 模型上下文协议 (MCP) 服务器，连接到 Claude Code CLI、Codex 和 Claude Desktop。它将 GitHub 转变为你的 AI 的个人创新侦察员——寻找工具、框架和解决方案，这些是你从未想过要搜索的。

哦，这是一个正在进行的工作——所以提出更改建议以使其更好。

它附带了 RUVNET 仓库，但你可以添加任何其他仓库，如 Andrej Karpathy 的或其他在你工作领域前沿的人的仓库。

---

🎯 这是什么？

一个真正理解你想构建什么的 GitHub 搜索。

问题

你在构建一些新的东西（应用程序或功能）。你知道可能有一个库、框架或算法可以让你的项目提升十倍。但是：

• 🔍 搜索是无效的 - 你需要知道确切的关键字
• 📚 选项太多 - 数百万个仓库，大多数都无关紧要
• 🎯 错误的领域 - 最好的解决方案可能在一个完全不同的领域
• ⏰ 耗时过长 - 浏览文档和 README 需要数小时

解决方案

RuvScan 像一个有创意的开发者一样思考，而不是搜索引擎：

你：我在构建一个 AI 应用程序。上下文检索太慢了。

RuvScan：这里有一个亚线性时间求解器，可以替换你的向量数据库查询。它来自科学计算，但 O(log n) 算法完美地适用于语义搜索。这里是集成方法……

它找到：

• ✨ 突破常规的解决方案 - 来自其他领域的工具，适用于你的领域
• ⚡ 性能提升 - 你不知道存在的算法
• 🔧 易于集成 - 它会告诉你如何使用它找到的东西
• 🧠 创意转移 - “这解决了 X，但你可以用它来解决 Y”

如何表述你的请求有助于该工具提供直接的帮助或边缘解决方案。这里有一些更多的例子，展示如何表述以显示不同的解决方案。（更多示例稍后）

示例请求

实际响应将以易于理解的纯英语给出，并建议最先进的内容。

1. “我只是想要一个可以直接插入的脚本，下载我的收件箱并将每个邮件保存为 JSON——我应该尝试什么？” → byroot/mail 或 DusanKasan/parsemail 用于简单的 IMAP/MIME 到结构化 JSON。
2. “给我一个已经监视 Gmail 并将摘要写入 Notion 页面的起始仓库。” → openai/gpt-email-summarizer-style 模板或 lucasmic/imap-to-webhook 用于即插即用的工作流。
3. “展示我可以插入 Python 摘要器的开源电子邮件解析器——IMAP 获取，MIME 解码，没有什么花哨的。” → DusanKasan/parsemail 或 inboxkitten/mail-parser 用于一键式 IMAP/MIME 处理。
4. “我在便宜的 Chromebook 上总结电子邮件。哪些仓库包括小嵌入或近似搜索，以便我可以在 1 GB 内存下运行？” → ruvnet/sublinear-time-solver 或 facebook/faiss-lite 以在低内存硬件上插入亚线性相似度。
5. “需要带有清晰审计轨迹的政策/合规主题检测器。指向为电子邮件流构建的基于规则或可解释的 NLP 项目。” → ruvnet/FACT 加上 CaselawAccessProject/legal-topic-models 用于确定性缓存加上透明分类器。
6. *“我的管道只能看到一次消息。找到与电子邮件摘要器搭配良好的流式处理或增量 NLP 算法（蓄水池抽样、在线转换器、CRDT 日志）。” → ruvnet/MidStream 或 openmessaging/stream-query 用于单次通过、蓄水池样式的处理。
7. “新闻通讯占我收件箱的 90%。推荐 DOM 先或布局感知提取工具包，我可以在总结之前链接它们，这样表格和部分可以存活。” → postlight/mercury-parser 或 mozilla/readability 以剥离并结构化 HTML 以便总结。
8. “法律要求可重复的摘要。显示那些备忘 LLM 调用（FACT 样式哈希，确定性代理）的仓库，以便相同的线程始终产生相同的文本。” → ruvnet/FACT 或 explosion/spaCy-ray 模式，对嵌入/结果进行哈希处理以生成审计轨迹。
9. *“如果能解释如何加速大规模电子邮件摘要，我愿意重新利用异国情调的工具——亚线性求解器、稀疏矩阵 DOM 行走者、基于流的流引擎。我应该调查什么？” → ruvnet/sublinear-time-solver（DOM 行走模式）、apache/arrow（列式电子邮件批次）和 ruvnet/flow-nexus（批量总结的成本传播）作为创意转移。

---

⚡ 在 30 秒内安装

RuvScan 与 Claude Code CLI、Codex CLI 和 Claude Desktop 兼容。选择你的平台：

注意：为了使它正常工作，必须发生两件事。

1. 后端（Docker）必须在单独的终端窗口中运行。
2. 必须将 MCP 添加到你的 CLI 或 Claude。
3. 安装后执行 /MCP 并检查是否正确安装（你会看到一个 x 或更糟的情况，没有工具显示）。如果是这种情况，请问 Claude - 你好，修复我的 RuvScan MCP 服务器。

对于 Claude Code CLI

# 1. 启动 RuvScan 后端
git clone https://github.com/ruvnet/ruvscan.git && cd ruvscan
docker compose up -d

# 2. 将 MCP 服务器添加到 Claude
claude mcp add ruvscan --scope user --env GITHUB_TOKEN=ghp_your_token -- uvx ruvscan-mcp

# 3. 开始使用！
claude

对于 Codex CLI（快速安装）

# 1. 启动 RuvScan 后端
git clone https://github.com/ruvnet/ruvscan.git && cd ruvscan
docker compose up -d

# 2. 使用 pipx 全局安装
pipx install -e .

# 3. 配置 ~/.codex/config.toml
# 请参阅下面的“对于 Codex CLI”部分以获取配置详情

# 4. 开始使用！
codex

ℹ️ 需要 GitHub 个人访问令牌。 RuvScan 会大量调用 GitHub API；如果没有令牌，你将立即达到匿名速率限制，扫描将失败。创建一个具有 repo（读取）和 read:org 范围的细粒度或经典令牌，然后在运行 MCP 客户端和后端的所有地方暴露它为 GITHUB_TOKEN。

对于 Claude Desktop

1. 启动后端：

git clone https://github.com/ruvnet/ruvscan.git && cd ruvscan
docker compose up -d

2. 添加到配置（macOS 上的 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "ruvscan": {
      "command": "uvx",
      "args": ["ruvscan-mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_github_token_here"
      }
    }
  }
}

3. 重启 Claude Desktop（Cmd+Q 并重新打开）

对于 Codex CLI

Codex CLI 使用相同的 MCP 协议。启动 Docker 后端之后：

步骤 1：全局安装 RuvScan

cd ruvscan
pipx install -e .

步骤 2：配置 Codex

编辑 ~/.codex/config.toml 并添加：

[mcp_servers.ruvscan]
command = "ruvscan-mcp"

[mcp_servers.ruvscan.env]
GITHUB_TOKEN = "ghp_your_github_token_here"
RUVSCAN_API_URL = "http://localhost:8000"

步骤 3：测试是否工作

# 从任何目录
cd /tmp
codex mcp list | grep ruvscan
# 应该显示：ruvscan  ruvscan-mcp  -  GITHUB_TOKEN=*****, RUVSCAN_API_URL=*****  -  enabled

# 开始对话
codex
> 你能扫描 Anthropic 的 GitHub 组织吗？

✅ 全局安装：RuvScan 现在在所有项目和目录中都可以使用！

---

替代方案：使用 codex mcp add（如果可用）

如果你的 Codex 构建包括 mcp add 命令：

codex mcp add --env GITHUB_TOKEN=ghp_your_token --env RUVSCAN_API_URL=http://localhost:8000 -- ruvscan-mcp ruvscan

🧪 当实验 mcp dev 时，运行 mcp dev --transport sse src/ruvscan_mcp/mcp_stdio_server.py。 服务器现在会执行健康检查，并且如果五分钟后没有客户端完成握手，则会关闭并给出明确的解释（例如，当传输不匹配时）。

---

Codex CLI 故障排除

检查 MCP 服务器状态：

codex mcp list

验证命令是否存在：

which ruvscan-mcp
# 应输出：/home/your-user/.local/bin/ruvscan-mcp

直接测试命令：

ruvscan-mcp --help

查看 Codex 日志：

tail -f ~/.codex/log/codex-tui.log

📚 详细的 Codex 设置指南：docs/CODEX_CLI_SETUP.md

GitHub 令牌检查清单

• 创建一个个人访问令牌（经典或细粒度），具有对你关心的仓库的读取权限以及 read:org。GitHub 的操作指南在这里：https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic
• 在运行 docker compose、uvicorn 或 codex/claude mcp add 之前，在你的 shell 中导出它（export GITHUB_TOKEN=ghp_...），以便后端可以认证 API 调用。
• 对于基于 Docker 的运行，复制 .env.example 到 .env 并在那里放置令牌，以便容器继承它。
• 可选地将相同值添加到 .env.local；scripts/seed_database.py 在播种时会自动拾取它。
• 成本：GitHub 不收取发行或使用 PAT 的费用。你的扫描仅消耗创建令牌账户的 API 额度；标准速率限制每小时刷新一次。如果你使用的是企业计划，使用量只是滚入组织的正常 API 允许额度。
• 将令牌视为密码。将其存储在你的秘密管理器中，并在泄露时从 https://github.com/settings/tokens 中撤销它。

docker compose up 运行的内容

• mcp-server（Python/FastAPI） - 在端口 8000 上托管 MCP HTTP API，读取 GITHUB_TOKEN，将数据写入 ./data/ruvscan.db，并公开 /scan、/query、/compare 和 /analyze 端点。
• scanner（Go） - 后台工作者（主机上的端口 8081 ↔ 容器内的端口 8080）调用 GitHub REST API，获取 README/主题元数据，并将结果 POST 回 MCP 服务器的 /ingest。
• rust-engine（Rust） - 用于 Johnson–Lindenstrauss O(log n) 相似性的可选 gRPC 服务，默认情况下禁用，只有当你运行 docker compose --profile rust-debug up 时才会启动。
• 共享卷 - ./data 和 ./logs 绑定挂载，因此你的 SQLite 数据库和日志在容器重启之间持久存在。

📖 完整安装指南：docs/MCP_INSTALL.md

---

🌱 示例数据及可选播种

开箱即用，RuvScan 已经包含了一个 data/ruvscan.db 文件，其中填充了大约 100 个来自 ruvnet 组织的公共仓库。这意味着新鲜克隆的 MCP 服务器启动后可以立即回答诸如“我们有什么实时流媒体工具？”等问题——无需额外步骤。

我什么时候会运行播种脚本？

• 刷新包含的目录（获取新的 ruvnet 仓库或 README 更改）。
• 添加另一个用户/组织，让你的本地 MCP 了解你自己的代码。
• 重建数据库，在删除 data/ruvscan.db 后。

# 刷新捆绑的 ruvnet 数据集
python3 scripts/seed_database.py --org ruvnet

# 添加不同的组织或用户（例如 OpenAI）
python3 scripts/seed_database.py --org openai --limit 30

# 跳过 README 下载，进行快速元数据传递
python3 scripts/seed_database.py --no-readmes

更喜欢点击而不是脚本？告诉你的 MCP 客户端：

• Claude / Codex 提示：“使用 scan_github 在组织 anthropics 上限为 25。”
• CLI：./scripts/ruvscan scan org anthropics --limit 25

任一途径都会将新仓库存储在预加载的 ruvnet 条目旁边，因此每次未来的查询都可以参考它们。

检查里面有什么：

sqlite3 data/ruvscan.db "SELECT COUNT(*), MIN(org), MAX(org) FROM repos;"

RuvScan 本地存储什么？

• 所有内容都存在于 data/ruvscan.db SQLite 文件中。每一行捕获仓库的所有者、名称、描述、主题、README 文本、星数、主要语言以及 last_scan 时间戳，以便我们知道何时获取它。
• MCP 工具只读取此文件；新仓库出现的唯一方式是当你播种或运行 scan_github 命令（无论是通过 CLI 还是 Claude）。
• 扫描完成后不会发生后台互联网爬取——你看到的就是存储在 SQLite 中的内容。

我如何查看哪些仓库被缓存？

# 显示当前目录中的每个组织/用户
sqlite3 data/ruvscan.db "
  SELECT org, COUNT(*) AS repos
  FROM repos
  GROUP BY org
  ORDER BY repos DESC;"

# 查看最新的条目以确认哪些是最新的
sqlite3 data/ruvscan.db "
  SELECT full_name, stars, datetime(last_scan) AS last_seen
  FROM repos
  ORDER BY last_scan DESC
  LIMIT 10;"

更喜欢友好的视图？运行 ./scripts/ruvscan cards --limit 20 列出顶级缓存的仓库及其摘要。

我如何清除目录并重新开始？

1. 停止与 RuvScan 通信的任何内容（docker compose down 或 Ctrl-C 开发服务器）。
2. （可选）备份旧数据库：cp data/ruvscan.db data/ruvscan.db.bak。
3. 删除文件：rm -f data/ruvscan.db。
4. 使用你想要的任何范围重新播种：

python3 scripts/seed_database.py --org ruvnet --limit 100
# 或
./scripts/ruvscan scan org my-company --limit 50

重新启动 MCP 服务器，它只会知道你刚刚播种或扫描的仓库。

⚠️ 提醒：数据库保留 last_scan 时间戳。更新同一个组织只是刷新行，而不是复制它们。如果你依赖捆绑的样本数据，请考虑每月重新运行刷新，以确保目录保持最新。

📚 完整指南：Database Seeding Documentation

---

🤔 RuvScan 如何建议某些工具（而跳过其他工具）

RuvScan 使用三个简单的信号对每个缓存的仓库进行评分，以匹配你的意图：

1. 标记重叠 - 仓库描述/README 是否提到你键入的概念？
2. 效率提升 - 对“优化”、“流式处理”、“亚线性”等词给予额外加分。
3. 现实检查 - 星数和最近的扫描推动成熟的维护项目向上。

目标是突出显然有用的仓库，而不让你过度拉伸。

实际示例：“扫描电子邮件以查找政策更新”

• 你的请求：“构建一个工具，扫描传入的电子邮件以查找重要的政策更新和合规要求。”
• 浮现的仓库：freeCodeCamp/mail-for-good、DusanKasan/parsemail、ruvnet/FACT 等。这些仓库讨论了 电子邮件解析、活动管道 和 确定性摘要——关键词几乎完美地匹配请求。
• 你可能期望的：ruvnet/sublinear-time-solver（其中包括一个可以咀嚼大型 HTML 存档