Octocode MCP Server

社区

为 AI 代理提供结构化代码智能：语义搜索、知识图谱与内置 MCP 服务器，一个 Rust 二进制搞定。

分类: 开发工具第 95 / 438
Stars: ★ 518 非常热门
传输方式: stdio（本地进程）
运行环境: 预编译二进制
凭据: 可选 API Key
许可证: Apache-2.0
最近提交: 4 天前
工具数: 10

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 密钥，适合重视隐私与结构理解的开发团队；但它是社区项目而非官方产品，且需要运行本地索引与可选云密钥，采用前应评估数据出网与索引权限。

最强项 · 文档质量 15/20 最弱项 · 可靠性 9/20

可靠性

9/20

安全与权限

12/20

维护活跃度

13/20

文档质量

15/20

安装易用性

13/20

查看各项评分依据

可靠性 9/20: 静态审查只能看到 README 与 server.json，未提供任何实际源码、CI workflow 文件内容或已提交测试；因此无法验证 MCP 初始化与工具列表握手是否干净、声明的 semantic_search/view_signatures/graphrag/structural_search 是否与真实行为一致。README 宣称支持 17 种语言的 tree-sitter 解析、LSP 工具需 --with-lsp，并附有自建 benchmark 结果，但这些均为不可信的自述证据，且 benchmark 不覆盖 MCP 协议层。错误处理、索引失败、嵌入提供商不可用时的降级路径均无证据。按静态校准上限 12 条，无源码级执行证据，故给 9。
安全与权限 12/20: READM E 声明本地优先、API key 存本地、尊重 .gitignore、MCP 服务仅本地且搜索不外发网络，方向正确；但仅凭 README 无法核实：嵌入 chunks 会发送到云端提供商（Voyage/OpenAI/JINA/Google），数据边界披露较笼统；LSP 工具与 MCP 服务器会读取并暴露整个代码库内容给客户端；未见凭证存储实现、权限范围限制或危险操作确认机制的证据。没有发现恶意、窃取凭证、隐蔽外传或安装示例含真实 token 等红线迹象，故不触发 0-4 红线区间，但由于权限最小化、确认流程与数据流细节均缺证据，给 12。
维护活跃度 13/20: GitHub 元数据显示 475 stars、仅 5 个开放 issue、未归档，License 为 Apache-2.0，README 有 CI 与覆盖率徽章、Crates.io 发布、版本 0.26.1，说明有持续发布节奏。但审查材料中没有任何提交历史、issue 响应时间、依赖更新记录或安全响应渠道（如 SECURITY.md）的直接证据，治理与版本策略仅靠自述徽章支撑。活跃度可见但治理与安全响应路径证据不足，故给 13。
文档质量 15/20: 文档层次较完整：README 覆盖安装（多平台、Homebrew、crates.io、二进制）、API key 配置与多嵌入提供商、索引与搜索命令、MCP 客户端配置示例（Claude Desktop/Cursor/Windsurf/Claude Code）、17 种语言支持表、隐私安全说明、benchmark 方法论与完整指标、以及指向 doc/ 目录下多个指南的链接。局限性也有披露（本地栈为下限、通用 reranker 反而下降）。扣分点在于：MCP 工具的完整参数说明、错误码、成本细节与故障排查主要指向外部文件而未在材料中呈现，无法审查其准确性；benchmark 结果属自述、无法验证。文档可用且分层，但存在需跳转外部文档的核查缺口，给 15。
安装易用性 13/20: 安装路径清晰：提供 curl 一键安装脚本、Homebrew、cargo install、GitHub Releases 四种方式，随后三步（配置可选 API key、octocode index、octocode search）即可运行，并给出 Claude/Cursor/Windsurf 的 JSON 配置片段与 Claude Code 的 CLI 命令，主体客户端接入示例较完整。但默认嵌入需联网下载 fastembed 模型，LSP 工具需另行传入 --with-lsp 并自备语言服务器，属额外手动步骤；各平台（尤其 Windows 与 macOS Gatekeeper）兼容性仅在文档中被提及而未见验证。按静态校准上限 15，缺少文件级执行证据，给 13。

静态评测 · 未实际运行收录于 2026-09-18

查看 FMRS 评分方法 →

选型与风险

能访问什么读取本地文件执行命令或代码

适合谁

希望让 Claude、Cursor、Windsurf 等 MCP 客户端深入理解代码库结构与依赖关系的开发者。
关心隐私、希望使用本地嵌入与本地 MCP 服务的团队。
使用 Rust、Python、TypeScript/JavaScript、Go、PHP、C++ 等受支持语言的工程团队。
需要语义搜索、符号图谱和 LSP 精确导航组合能力的代码智能场景。

不适合谁

仅需简单文本 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）在代码检索上可能反而降低效果，需使用代码感知的重排序器。

安装接入

准备工作

运行环境：预编译二进制

VOYAGE_API_KEY 可选密钥可选的云端 embedding 提供商密钥，在 voyageai.com 注册获取（有免费额度）；不设置时默认使用本地 FastEmbed，无需密钥。

OPENROUTER_API_KEY 可选密钥可选，用于 LLM 功能（如提交信息生成、代码审查），在 openrouter.ai 获取。

OPENAI_API_KEY 可选密钥可选，使用 OpenAI embedding 模型（如 text-embedding-3-small）时需要，在 platform.openai.com 获取。

JINA_API_KEY 可选密钥可选，使用 Jina embedding 模型（如 jina-embeddings-v3）时需要，在 jina.ai 获取。

GOOGLE_API_KEY 可选密钥可选，使用 Google embedding 模型（如 text-embedding-005）时需要，在 Google AI Studio 获取。

安装：使用通用安装脚本 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"
      ]
    }
  }
}

以 Claude Desktop 为例。其他客户端的配置文件位置或字段可能不同（如 VS Code 使用 servers 字段），可用下方配置生成器转换。

.vscode/mcp.json

{
  "servers": {
    "octocode": {
      "command": "octocode",
      "args": [
        "mcp",
        "--path",
        "/your/project"
      ]
    }
  }
}

写入项目的 .vscode/mcp.json（VS Code 使用 servers 字段）。

Terminal

claude mcp add octocode -- octocode mcp --path /your/project

在终端运行；先把 <…> 占位符换成你自己的值。

生成并校验客户端配置

验证是否装好

按配置添加 octocode MCP 服务器后，重启客户端并确认工具列表中出现 semantic_search、graphrag、structural_search 等工具；然后询问“认证逻辑在哪里？”——若 AI 能通过 semantic_search 返回具体文件路径，即说明连接成功。

常见排障

确认 `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 助手这样说：

我的代码库中是在哪里处理用户认证的？
哪些文件依赖 payment 模块？
找出 process_payment 函数的所有调用位置
在 API 层搜索所有 .unwrap() 调用

工具能力 10

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 启动）。

展开其余 2 个工具

lsp_workspace_symbols 只读

在整个工作区中按名称搜索符号（需使用 --with-lsp 启动）。

lsp_completion 只读

为指定位置提供代码补全建议（需使用 --with-lsp 启动）。

使用场景

让 AI 助手按语义而非关键字查找代码，例如“认证中间件在哪”。

查询文件之间的依赖关系，例如“哪些文件依赖支付模块”。

在不读取整个文件的情况下查看函数签名与文件结构。

用 AST 模式匹配查找 .unwrap() 等潜在风险调用。

结合 LSP 精确定位定义、查找引用、查看类型与文档。

在本地或云端嵌入提供方之间切换，对代码库与提交历史做混合检索。

支持客户端

Claude Desktop

Claude Code

Cursor

Windsurf

Octomind

Cline

Continue

Zed

Replit

依据项目文档列出，未经本站实测。

详细介绍

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 许可。