适合谁
- 希望让 Claude、Cursor、Windsurf 等 MCP 客户端深入理解代码库结构与依赖关系的开发者。
- 关心隐私、希望使用本地嵌入与本地 MCP 服务的团队。
- 使用 Rust、Python、TypeScript/JavaScript、Go、PHP、C++ 等受支持语言的工程团队。
- 需要语义搜索、符号图谱和 LSP 精确导航组合能力的代码智能场景。
O
62FMRS · C
Octocode 是 Muvon 用 Rust 开发的开源代码智能工具（Apache-2.0），以单个二进制的形式提供语义搜索、基于 tree-sitter 的符号/文件知识图谱，以及内置 MCP 服务器，可接入 Claude Desktop、Cursor、Windsurf、Claude Code、Octomind 等客户端。它的差异化在于理解代码结构（imports、calls、extends、implements）而非把代码当作扁平文本块，并通过可选 LSP 支持提供定义跳转、引用查找等精确定位能力。项目提供可复现的检索基准，显示针对关键字调优的混合检索能显著提升 Hit@5 与 Recall@10。它本地优先、默认无需 API 密钥，适合重视隐私与结构理解的开发团队；但它是社区项目而非官方产品，且需要运行本地索引与可选云密钥，采用前应评估数据出网与索引权限。
Octocode 是一个用 Rust 编写的代码智能工具，把一个项目转化为可导航的知识图谱，让 Claude、Cursor 等 MCP 客户端能够搜索、理解并浏览代码库结构。它通过 tree-sitter AST 解析从当前源码实时构建文件与符号图，包含确定的 contains、imports、calls、extends、implements 关系；MCP 的 graphrag 工具无需索引、嵌入或 LLM 即可使用这套图谱。可选的索引式 GraphRAG 会叠加语义文件匹配、LLM 描述和更宏观的文件级架构关系。检索层面采用混合搜索：语义相似度结合 BM25 全文检索与重排序。项目完全本地优先，内置 fastembed，无需 API 密钥即可在本地生成嵌入，也支持 Voyage、OpenAI、Jina、Google 等云嵌入提供方。支持 17 种语言的完整 tree-sitter AST 解析，采用 Apache-2.0 许可。
工具能力
semantic_search
按含义而非关键字查找代码，例如“认证流程”“错误处理”“数据库查询”。
view_signatures
查看文件结构：函数签名、类定义和导入。
graphrag
始终可用的文件/符号图谱：搜索节点、查看关系并查找路径，无需索引。
structural_search
AST 模式匹配，用于查找 .unwrap() 调用、new 实例化等特定模式。
lsp_goto_definition
跳转到符号的定义处（需使用 --with-lsp 启动）。
lsp_find_references
在整个工作区查找某个符号的所有用法（需使用 --with-lsp 启动）。
lsp_hover
查看符号的类型信息和文档（需使用 --with-lsp 启动）。
lsp_document_symbols
列出单个文件中的符号（需使用 --with-lsp 启动）。
lsp_workspace_symbols
在整个工作区中按名称搜索符号（需使用 --with-lsp 启动）。
lsp_completion
为指定位置提供代码补全建议（需使用 --with-lsp 启动）。
安装接入
- 安装：使用通用安装脚本
curl -fsSL https://raw.githubusercontent.com/Muvon/octocode/master/install.sh | sh，或 macOS 上执行brew install muvon/tap/octocode，也可cargo install octocode或从源码cargo install --git https://github.com/Muvon/octocode，或从 GitHub Releases 下载二进制。 - API 密钥（可选）：嵌入默认使用本地 FastEmbed，无需密钥；如需云端嵌入或 LLM，可设置 VOYAGE_API_KEY、OPENROUTER_API_KEY 等，例如
export VOYAGE_API_KEY="your-voyage-api-key"。 - 索引代码库：
cd /your/project后运行octocode index。 - 搜索代码：
octocode search "authentication middleware"，可用--language rust过滤语言，或用--mode commits搜索提交历史。 - 连接 AI 助手：在 MCP 客户端配置中加入
{"mcpServers":{"octocode":{"command":"octocode","args":["mcp","--path","/your/project"]}}}。Claude Code 可直接运行claude mcp add octocode -- octocode mcp --path /path/to/your/project。 - （可选）启用 LSP 工具：
octocode mcp --path /your/project --with-lsp="rust-analyzer"。 - （可选）启用索引式 GraphRAG：
octocode config --graphrag-enabled true后重新运行octocode index。
claude_desktop_config.json
{
"mcpServers": {
"octocode": {
"command": "octocode",
"args": [
"mcp",
"--path",
"/your/project"
]
}
}
}
选型与风险
不适合谁
- 仅需简单文本 grep、不需要结构理解的场景。
- 不使用任何 MCP 客户端、只想要传统 IDE 索引的用户。
- 需要官方产品支持或 SLA 保障的企业采购（本项目为 Muvon 维护的社区开源项目）。
- 对代码绝不能离开本机、但又不愿使用本地嵌入模型的场景。
所需权限
- 读取指定项目路径下的源代码文件（默认遵循 .gitignore，不索引敏感文件）。
- 在项目内写入/更新本地索引数据。
- 读取本地 API 密钥配置与环境变量（VOYAGE_API_KEY、OPENROUTER_API_KEY、OPENAI_API_KEY、JINA_API_KEY、GOOGLE_API_KEY 等，均为可选）。
- 启用 --with-lsp 时会启动并调用指定的本地语言服务器（如 rust-analyzer）。
- 作为本地 MCP 服务器运行，搜索过程不进行外部网络访问。
风险与副作用
- 启用云端嵌入提供方时，仅被嵌入的代码分块会发送给该提供方；若要完全离线，应使用本地模型。
- 索引会把项目内容写入本地索引存储，需要确认存储位置与权限符合团队要求。
- LSP 工具依赖外部语言服务器，其配置错误或崩溃会影响这些工具可用性，但不影响图谱与语义搜索。
- 语义搜索结果只是相关性排序的候选，AI 可能基于不完整结果给出结论，重要改动仍需人工核对。
- 通用型交叉编码器重排序器（如 bge-reranker-base）在代码检索上可能反而降低效果，需使用代码感知的重排序器。
常见排障
- 确认 `octocode` 可执行文件在 PATH 中，MCP 客户端配置里的 command 才能正确启动。
- 检查 `--path` 是否指向正确的项目目录，路径错误会导致图谱与搜索结果为空。
- 若使用云端嵌入或 LLM，确认对应 API 密钥已设置且未超出速率限制（参见 GETTING_STARTED 中的速率限制说明）。
- LSP 相关工具不可用时，检查启动参数是否包含 --with-lsp 以及语言服务器是否已安装并可运行。
- graphrag 工具无需索引即可用，但索引式 GraphRAG 需先执行 `octocode config --graphrag-enabled true` 并重新 `octocode index`。
- 检索效果不理想时可尝试调整混合搜索权重或更换代码感知的重排序模型，参考 benchmark/RESULTS.md 中的对比数据。
使用场景
让 AI 助手按语义而非关键字查找代码，例如“认证中间件在哪”。
查询文件之间的依赖关系，例如“哪些文件依赖支付模块”。
在不读取整个文件的情况下查看函数签名与文件结构。
用 AST 模式匹配查找 .unwrap() 等潜在风险调用。
结合 LSP 精确定位定义、查找引用、查看类型与文档。
在本地或云端嵌入提供方之间切换，对代码库与提交历史做混合检索。
支持客户端
Claude Desktop完整支持
Claude Code完整支持
Cursor完整支持
Windsurf完整支持
Octomind完整支持
VS Code (Cline/Continue)完整支持
Zed完整支持
Replit完整支持