Arc Memory MCP Server
Arc Memory MCP Server 是一个桥梁，它将本地 Arc Memory 时序知识图谱（TKG）的结构化、可验证的上下文和查询能力暴露给兼容 MCP 的客户端（如 VS Code Agent Mode 中的 AI 代理、Claude Desktop、Cursor、Windsurf 以及其他代码生成代理）。
概述
与仅依赖向量数据库进行语义相似性检索的典型 RAG 系统不同，Arc Memory MCP Server 提供了对知识图谱中显式、结构化、时序性和关系性溯源数据的访问。它不仅关注语义内容，还关注代码的历史和关系（如提交记录、PR、问题、ADRs、文件修改等）。
Arc Memory MCP Server 是 Arc Memory 生态系统的核心组件，旨在为 AI 辅助开发提供记忆层。在开发者工作流中，它作为混合 RAG 系统的知识图谱（KG）访问点。
架构
Arc Memory MCP Server 位于 Arc Memory 生态系统的中心，将时序知识图谱与各种 AI 助手和开发工具连接起来：
该图展示了：
- 数据源（Git、GitHub、ADRs 等）通过 Arc Memory SDK 处理，构建时序知识图谱。
- Arc Memory MCP Server 通过标准化的 MCP 工具暴露该知识图谱。
- AI 助手（如 Claude Desktop、VS Code Agent Mode、Cursor、Windsurf 等）连接到服务器以访问知识图谱。
- 这使得 AI 助手能够基于项目的实际历史和决策提供上下文感知的辅助。
功能
该服务器使用最新的 MCP SDK（1.6.0）实现了以下工具，并增强了错误处理和上下文管理：
- arc_trace_history：追踪文件中某一行代码的决策历史。
- arc_get_entity_details：检索特定实体的详细信息。
- arc_find_related_entities：查找与给定实体直接相关的实体。
- arc_blame_line：获取某一行代码的最后修改提交 SHA、作者和日期。
要求
- Python 3.10 或更高版本
mcpPython SDK（>=1.6.0）
arc-memoryPython 包（>=0.2.2）
安装
- 安装 uv（如果尚未安装）：
- 安装所需的包：
- 克隆本仓库：
- 安装服务器：
使用
前提条件
在使用服务器之前，请确保：
- 已安装
arc-memorySDK（版本 0.2.2 或更高）：
- 使用
arc auth gh进行 GitHub 认证（如果你有 GitHub OAuth 凭证）：
- 使用
arc build构建知识图谱：
这将从本地 Git 仓库构建知识图谱，包括提交记录、文件及其之间的关系。数据库将存储在
~/.arc/graph.db。运行服务器
运行以下命令启动服务器：
服务器使用
stdio 传输机制，这意味着它设计为由 MCP 客户端（如 Claude Desktop 或 VS Code Agent Mode）启动。测试
要测试服务器，可以使用提供的测试脚本：
这将启动服务器并运行一系列测试，以验证所有工具是否正常工作。
使用模拟数据测试
如果尚未设置本地 Arc Memory 数据库，可以使用模拟数据测试服务器：
- 编辑
tests/test.py以使用模拟服务器：
- 运行测试脚本：
这将使用模拟服务器，返回预定义的数据，而不是查询实际数据库。
使用真实数据测试
服务器已成功测试了从本仓库构建的真实 Arc Memory 数据库。数据库包括：
- Git 提交历史
- 文件关系
- 架构决策记录（ADRs）
- GitHub 提交和 PRs
使用
arc build 构建自己的知识图谱时，系统会自动检测并包含匹配模式 **/adr/**/*.md 的 ADR 文件。与 Claude Desktop 集成
要在 Claude Desktop 中使用服务器：
- 打开 Claude Desktop 配置文件：
- macOS：
~/Library/Application Support/Claude/claude_desktop_config.json - Windows：
%APPDATA%\Claude\claude_desktop_config.json
- 使用 uv 添加服务器配置（推荐）：
或者，可以使用
fastmcp CLI 直接安装服务器：- 重启 Claude Desktop
与 VS Code Agent Mode 集成
要在 VS Code Agent Mode 中使用服务器：
- 在 VS Code 设置中配置 MCP 服务器：
与 Cursor 集成
要在 Cursor 中使用服务器：
- 打开 Cursor 设置并导航到 AI 设置
- 在 Cursor 设置中配置 MCP 服务器（类似于 VS Code 配置）
- 重启 Cursor
与 Windsurf 集成
要在 Windsurf 中使用服务器，请遵循 Windsurf 文档中关于配置 MCP 服务器的说明。
工具文档
arc_trace_history
追踪文件中某一行代码的决策历史（溯源）。
参数：
file_path：文件路径，相对于仓库根目录
line_number：文件中的行号（从 1 开始）
max_hops（可选）：图遍历的最大跳数（默认：2）
max_results（可选）：返回的最大结果数（默认：3）
返回值：
表示实体摘要列表的 JSON 字符串。
arc_get_entity_details
从 Arc Memory TKG 中检索特定实体的详细信息。
参数：
entity_id：实体的唯一 ID（如 'commit:abc123', 'pr:42', 'file:src/main.py'）
返回值：
表示详细实体对象的 JSON 字符串。
arc_find_related_entities
在 Arc Memory TKG 中查找与给定实体 ID 直接相关的实体。
参数：
entity_id：起始实体的唯一 ID
relationship_type（可选）：按关系类型过滤（'MODIFIES', 'MENTIONS', 'MERGES', 'DECIDES'）
direction（可选）：关系方向（'outgoing', 'incoming', 'both'）。默认 'both'
max_results（可选）：返回的最大相关实体数（默认：10）
返回值：
表示相关实体摘要列表的 JSON 字符串。
arc_blame_line
获取某一行代码的最后修改提交 SHA、作者和日期。
参数：
file_path：文件路径，相对于仓库根目录
line_number：文件中的行号（从 1 开始）
返回值：
表示提交 SHA、作者和日期的 JSON 字符串。
错误处理
所有工具在失败时都会返回结构化的 JSON 错误，其中包含
error 字段，描述错误信息。使用场景
Arc Memory MCP Server 为 AI 辅助开发提供了多种强大的使用场景：
1. 带历史上下文的代码理解
当 AI 助手被要求解释某段代码时，它可以使用 Arc Memory MCP Server：
- 使用
arc_trace_history追踪代码的历史
- 理解代码的编写时间和原因
- 参考导致代码创建的 PR 讨论和问题
- 基于实际开发历史提供解释
示例提示：
"为什么这个认证逻辑这么复杂？它看起来有点复杂。"
2. 智能代码审查
AI 助手可以通过以下方式提供更有洞察力的代码审查：
- 使用
arc_blame_line识别代码的特定部分的作者
- 使用
arc_find_related_entities参考相关的 PRs 和问题
- 理解历史上下文和设计决策
- 提出符合项目既定模式的改进建议
示例提示：
"审查这个 PR，并突出显示与我们既定模式不一致的地方。"
3. 决策考古
当开发者需要理解过去的决策时，AI 可以：
- 追踪文件或特定代码行的历史
- 查找相关的 ADRs（架构决策记录）
- 连接问题、PRs 和提交，提供完整的背景
- 解释特定设计选择的原因
示例提示：
"为什么我们选择了这个数据库模式？考虑了哪些替代方案？"
4. 上下文感知的代码生成
当 AI 代码生成能够：
- 参考代码库中的类似模式
- 理解项目的历史和演变
- 基于实际项目决策提出建议
- 引用项目历史中的具体示例时，代码生成会更符合项目标准
示例提示：
"生成一个新的 API 端点，遵循我们在错误处理方面的既定模式。"
5. 新团队成员的知识传递
新开发者可以通过以下方式更快上手：
- 询问代码的历史和原因
- AI 基于实际项目历史提供上下文解释
- 理解设计决策，而无需追踪团队成员
- 通过历史上下文学习项目模式
示例提示：
"我是团队的新成员。你能解释一下认证流程及其设计原因吗？"
当前状态
Arc Memory MCP Server 已成功实现，并使用模拟数据和真实 Arc Memory 数据库进行了测试。所有四个工具均正常运行，并可集成到各种 MCP 客户端中。
许可证
MIT 许可证
- Author:waytomcp
- URL:https://www.waytomcp.com/article/Arc-Computer/arc-mcp-server
- Copyright:All articles in this blog, except for special statements, adopt BY-NC-SA agreement. Please indicate the source!
