Arc Memory MCP 服务器

Arc 帮助工程团队理解其代码背后的历史和上下文。这个MCP服务器允许AI助手使用自然语言查询您的代码库的历史和关系。

"为什么我们选择了MongoDB而不是PostgreSQL？"
"认证系统是如何随着时间演变的？"
"微服务架构背后的理由是什么？"

快速开始工作流程

1. 安装依赖

   bash
   pip install mcp arc-memory

2. 通过GitHub进行身份验证

   bash
   arc auth gh

   这将引导您完成与GitHub的身份验证过程。完成后，您会看到一条成功消息。

3. 通过Linear进行身份验证（可选）

   bash
   arc auth linear

   这将引导您通过OAuth 2.0完成与Linear的身份验证。一个浏览器窗口将会打开，让您授权Arc Memory访问您的Linear数据。这一步是可选的，但如果您希望在知识图谱中包含Linear问题，则推荐执行此步骤。

4. 构建您的知识图谱

   bash
   arc build

   这将分析您的仓库并构建一个本地知识图谱。完成后，您会看到进度指示器和已摄入实体的摘要。

   要在您的知识图谱中包含Linear问题：

   bash
   arc build --linear

   这需要先完成Linear的身份验证（步骤3）。

5. 在Claude Desktop、VS Code代理模式或Cursor中配置

   请参阅下面的“集成”部分获取详细说明。

Arc的工作原理

Arc 构建了代码库历史的图谱，连接来自不同来源的结构化数据。与典型的RAG系统使用向量相似性不同，Arc专注于提交、PR、问题以及架构决策之间的实际关系。

arc_search_story 工具将自然语言问题转换为可以追踪多个连接的图查询，帮助AI助手基于项目的实际历史提供答案。

知识图谱结构

Arc 构建了一个丰富的知识图谱，包括：

• 实体：PR、提交、问题（GitHub & Linear）、ADR、文件等
• 关系：MODIFIES、MENTIONS、MERGES、DECIDES、IMPLEMENTS
• 时间上下文：更改发生的时间及其顺序
• 出处：更改的原因及由谁做出
• 跨系统连接：GitHub PR与Linear问题之间的链接

这种互连结构使得能够追溯任何代码行背后的完整故事——从初始问题，经过架构决策，到实现PR和提交。

例如，一个典型的路径可能如下所示：

bash
Linear 问题 ABC-123 (功能请求)
↓ DECIDES
架构决策记录 (ADR-42)
↓ IMPLEMENTS
GitHub 拉取请求 #456
↓ CONTAINS
提交 abc123
↓ MODIFIES
文件: src/auth/middleware.js

当您询问“为什么这样实现认证中间件？”时，Arc 可以反向遍历这条路径来提供完整的上下文。

连接不同的系统

单独使用GitHub和Linear MCP对于基本查询来说已经足够，但Arc将它们连接在一起：

1. 连接的数据：在一个图中链接来自GitHub、Linear、Git和ADR的信息
2. 跨系统连接：显示Linear问题与GitHub PR之间的关系
3. 多步路径：跟踪独立API调用可能会遗漏的连接链
4. 基于时间的上下文：维护不同系统中的事件发生时间
5. 结构化的结果：返回AI助手可用于解释关系的路径

示例问题

架构推理与决策考古

bash
"导致我们当前认证架构的安全考虑因素是什么？"
"为什么我们在2022年第三季度从单体架构迁移到微服务架构，权衡点是什么？"
"哪些性能问题促使我们从Redis切换到自定义缓存解决方案？"
"去年重大停机后，我们的API设计是如何演变的？"### 跨系统影响分析

bash
"哪些后端服务受到了支付处理重构的影响？"
"我们计划更改的身份验证中间件依赖于哪些下游组件？"
"如果我们弃用旧版API，会有多少个不同团队的代码受到影响？"
"为了解决速率限制问题，我们的基础设施中哪些部分被修改了？"

技术债务与回归预防

bash
"我们之前尝试过哪些方法来修复CI流水线中的间歇性测试失败？"
"在过去6个月里，哪些PR改动了这段脆弱的支付处理代码？"
"我们最近三次生产事故的根本原因分析是什么？"
"我们多次重新审视了哪些架构决策，这表明设计可能存在不稳定性？"

知识转移与入职培训

bash
"从初始设计到当前实现，我们的认证系统的完整历史是什么？"
"数据处理流水线每个组件的领域专家是谁？"
"在我加入团队之前，做出的关键设计决策有哪些，这些决策如何解释了我们当前的架构？"
"这段复杂的缓存逻辑背后的上下文是什么，为什么现在似乎没有人能理解它了？"

可用工具

• arc_search_story: 用于多跳问题的自然语言图查询
• arc_trace_history: 追踪文件中特定行的决策历史
• arc_get_entity_details: 获取关于特定实体的详细信息
• arc_find_related_entities: 查找直接连接到给定实体的其他实体
• arc_blame_line: 获取特定行的具体提交SHA、作者和日期

安装

bash

安装依赖

pip install mcp arc-memory

克隆仓库

git clone https://github.com/Arc-Computer/arc-mcp-server.git
cd arc-mcp-server

安装服务器

pip install -e .

设置

1. 使用GitHub进行身份验证（如果你有GitHub OAuth凭据）
   bash
   arc auth gh

2. 构建你的知识图谱
   bash
   arc build

   这将从你的本地Git仓库构建一个图谱，包括提交、文件、PR、问题及其关系。数据库存储在~/.arc/graph.db。

集成

Claude Desktop

1. 打开配置文件：

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%Claudeclaude_desktop_config.json

2. 添加服务器配置：
   json
   {
   "mcpServers": {
   "arc-memory": {
   "command": "python",
   "args": ["/absolute/path/to/src/arc_mcp_server.py"]
   }
   }
   }

3. 重启Claude Desktop

VS Code代理模式

1. 安装VS Code代理模式扩展

2. 在VS Code设置中配置MCP服务器：
   json
   "anthropic.agent-mode.mcp.servers": {
   "arc-memory": {
   "command": "python",
   "args": ["/absolute/path/to/src/arc_mcp_server.py"]
   }
   }

Cursor

1. 打开Cursor设置并导航到AI设置
2. 配置MCP服务器（类似于VS Code配置）
3. 重启Cursor

工具文档

arc_search_story

用于多跳问题的自然语言图查询。

参数：

• question: 要询问的自然语言问题
• max_depth (可选): 图遍历的最大深度（默认值：3）
• max_results (可选): 返回的最大结果数量（默认值：100）

返回：
json
{
"path": [
{"id": "pr:42", "type": "pr", "title": "添加新功能", "depth": 0},
{"id": "adr:123", "type": "adr", "title": "架构决策", "depth": 1},
{"id": "issue:456", "type": "issue", "title": "功能请求", "depth": 2}
],
"meta": {
"query_depth": 3,
"sql": "/* 用于调试的SQL查询 */"
}
}

AI助手如何使用这些数据当开发者询问“为什么我们从 Redis 迁移到自定义缓存解决方案？”时，AI 助手可以使用结构化的路径数据来创建如下回复：

“2023 年 7 月从 Redis 迁移到我们的自定义缓存解决方案是由三个关键因素驱动的：

1. 性能瓶颈：线性问题 PERF-387 记录了在高峰流量期间 Redis 连接池的问题，导致 2023 年第二季度观察到的 30% 的延迟峰值。平台团队在 6 月份的中断后将此问题优先级设为 P0。

2. 架构限制：由 Sarah Chen 编写的 ADR-29 详细说明了 Redis 的单线程模型无法有效处理我们日益增长的并发写入模式，特别是对于产品目录服务。该 ADR 引用了线性问题 ARCH-42，在那里首次提出了这些担忧。

3. 成本考虑：GitHub PR #1204 包含基准测试结果，显示自定义解决方案将基础设施成本降低了 42%，同时将 p99 延迟提高了 150 毫秒。此 PR 与 2023 年第三季度成本优化计划中的线性问题 COST-56 相关联。

迁移通过 7 个 GitHub PR 实施，主要由基础设施团队完成，其中库存和结账服务的变化最为显著。Alex Kim 在 PR #1209 中提出了关于数据一致性的初步担忧，通过添加 ADR-31 中记录的两阶段提交协议解决了这些问题。

自部署以来，自定义解决方案一直保持稳定，只有两次小事故（在线性中跟踪为 INC-45 和 INC-52），与缓存失效边缘情况有关，均已在后续 GitHub PR #1567 中解决。”

回复包括：

• 来自不同来源的信息（线性问题、GitHub PR、ADR、事件）
• 具体指标和度量
• 参与人员及其角色
• 事件顺序和技术细节
• 出现的问题及其解决方案
• 之后发生的情况

这之所以可行，是因为 Arc 将通常分离的不同系统中的信息连接起来。

常见用例

1. 新成员入职

当新开发者加入团队时，他们可以询问不熟悉的代码和系统的相关问题，以理解实现背后的上下文和理由。

2. 防止回归

在对复杂或关键系统进行更改之前，开发者可以探索以前问题的历史、未成功的尝试以及当前实现背后的原因。

3. 做出架构决策

在考虑对架构进行更改时，团队可以查看相关决策的历史，了解之前尝试过的方法以及选择某些方法的原因。

4. 重构遗留代码

在处理缺乏文档的老代码时，开发者可以追溯其起源，理解其目的，并在进行更改前识别其依赖关系。

未来发展

Arc 的未来计划包括：

• 对 PR 运行轻量级模拟以识别潜在问题
• 检测安全漏洞和技术债务风险
• 构建系统行为随时间变化的因果模型
• 将模拟结果反馈到知识图谱中

许可证

MIT 许可证

需要帮助？

• GitHub 问题
• 文档
• Discord 社区