适合谁
- 使用 AI 编程代理的大型本地代码库。
- 需要变更影响分析和安全重构的开发团队。
- 需要架构治理、代码健康度和审计证据的项目。
- 希望在无 API 密钥条件下进行本地代码分析的用户。
R
69FMRS · C
Roam Code MCP Server 是一个基于 stdio 的本地代码智能服务器，适合让 AI 编程代理查询代码图、依赖、架构和变更风险。其优势是本地运行、无需 API 密钥、工具集丰富并提供安全门与证据机制；但它是静态分析系统，结果依赖索引质量，部分安全和框架检测仍需人工复核。
Roam Code 是一个本地代码库智能 CLI 和 MCP 服务器。它使用 SQLite 代码图分析符号、调用、导入、架构、Git 历史、风险和测试影响，支持 28 种语言及 244 个 MCP 工具。默认 core 预设包含 17 个工具。分析在本机进行，不需要 API 密钥，并提供变更安全门、验证结果和审计证据。
工具能力
roam_alerts
查询代码库告警和发现。
roam_ask
将自然语言代码库问题路由到图分析查询。
roam_batch_search
批量执行代码库搜索。
roam_coupling
分析文件或符号之间的变更耦合关系。
roam_dead_code
检测可能未使用的代码。
roam_deps
查询文件或符号的依赖关系。
roam_diagnose_issue
对代码问题进行根因排序和诊断。
roam_fetch_handle
获取此前查询返回的结果句柄。
roam_file_info
获取文件结构、定义和健康信息。
roam_grep
执行带有代码图上下文的文本搜索。
roam_metrics
查询代码库指标。
roam_prepare_change
为代码变更准备影响和安全上下文。
roam_search_symbol
按符号搜索代码定义。
roam_taint
执行基于代码图的污点分析。
roam_understand
生成代码库的整体简报，包括技术栈、架构、健康度和入口点。
roam_uses
查询符号的精确引用，避免字符串匹配误报。
roam_expand_toolset
扩展到其他 Roam MCP 工具预设。
安装接入
需要 Python 3.10+。先运行 pip install "roam-code[mcp]"，进入目标代码库后运行 roam init 建立 .roam/index.db，再运行 roam mcp 启动 stdio MCP 服务器。也可以在 Claude Code、Claude Desktop、Cursor 或 VS Code 的 MCP 配置中使用 command 为 roam、args 为 ["mcp"]。可通过 ROAM_MCP_PRESET 选择 core、review、refactor、debug、architecture、compliance、compile-curated 或 full。
claude_desktop_config.json
{"mcpServers":{"roam-code":{"command":"roam","args":["mcp"]}}}
选型与风险
不适合谁
- 需要实时类型检查的场景；来源建议使用 LSP。
- 少于约 10 个文件的小型脚本。
- 只需要原始文本搜索的简单任务。
- 把污点或长尾检测结果视为完整安全保证的场景。
所需权限
- 需要访问本地代码库以发现、解析和分析源文件。
- 需要在代码库中创建本地 .roam/index.db 及相关分析状态。
- 使用写入、持久化或变更相关工具时，可能需要更新 .roam 控制文件、运行记录或证据文件。
- 默认不需要 API 密钥或云端登录。
风险与副作用
- 索引过时、缺失或部分完成时，分析结果可能不完整；应检查返回的状态和错误信号。
- 静态分析和框架惯用法检测并不等同于实时类型检查或深度 SAST；部分检测结果仅供调查。
- full 预设包含 244 个工具，可能扩大代理提示词表面。
- 首次使用 tree-sitter-language-pack 时可能下载经校验的平台语法包；其他联网命令和网络标志需要显式启用。
- 写入或自动化代理模式可能产生实际文件和运行记录变更。
常见排障
- 确认已安装 Python 3.10+，且 roam 位于 PATH 中。
- 确认先在目标代码库运行 roam init，并检查 .roam/index.db 是否存在。
- 如果服务器无法启动，直接运行 roam mcp 检查命令是否可用。
- 如果结果为空或不完整，检查索引是否缺失、过时或被中断，并重新建立索引。
- 确认客户端配置使用 command 为 roam、args 为 ["mcp"]，并为 Claude Desktop 设置正确的 cwd。
- 检查 ROAM_MCP_PRESET 是否选择了所需工具集。
使用场景
在修改符号前查询调用方、依赖关系、影响范围和受影响测试。
为 AI 编程代理提供代码库结构、上下文和架构事实。
执行死代码、污点、耦合、指标和代码搜索分析。
为代码审查、重构和 CI 安全门提供结构化证据。
支持客户端
Claude Code完整支持
Claude Desktop完整支持
Cursor完整支持
VS Code with Copilot完整支持