Muvon/octocode

Structural code intelligence for AI agents — semantic search, knowledge graphs, and a built-in MCP server in one Rust binary. Give Claude, Cursor, and any MCP client a deep understanding of your codebase.

Octocode – 面向 AI 代理的结构化代码智能

是什么 – Octocode 是一个开源的 Rust 工具，可将代码库转换为实时可查询的知识图谱。它自带一个 MCP 服务器（Claude Desktop、Cursor、Windsurf 等使用的 Model-Center-Protocol），使 AI 助手能够像人类一样搜索、导航并推理项目结构。

为何重要 – 传统的检索增强生成（RAG）将源文件视为扁平的文本块，丢失了导入、函数调用、继承和模块边界之间的关系。Octocode 提取一个基于 AST 的符号图，具有确定性的边（imports、calls、extends、implements 等），并将其图谱和语义搜索功能暴露给任何 MCP 兼容的代理。结果是，AI 可以给出代码感知的回答，例如“认证逻辑在哪里处理？”或“哪些文件依赖支付模块？”，而无需通过关键词匹配猜测。

核心功能

功能	你将获得
语义搜索	自然语言查询使用 BM25 关键词匹配和向量嵌入（Voyage、OpenAI、Jina 等）的混合方式返回最相关的文件。
实时 AST 图	Tree-sitter 将当前源码树解析为节点（文件、符号）和边（`imports`、`calls` 等），始终保持最新状态——无需单独索引。
GraphRAG（可选）	可选的持久化图在确定性图之上添加 LLM 生成的描述和更广泛的架构关系。
LSP 集成	启动时使用 `--with-lsp`，服务器将 `goto-definition`、`find-references`、`hover`、`completion` 等请求转发给你的语言服务器（如 rust-analyzer）。
结构化搜索	AST 模式匹配可定位特定代码模式（例如所有 `.unwrap()` 调用）。
多语言支持	16 种语言原生支持（Rust、Python、TypeScript/JS、Go、PHP、C++、Ruby、Elixir、Java、Swift、Svelte、Lua、CSS、JSON、Bash、Markdown）。
本地优先 & 隐私优先	可通过 fastembed 本地生成嵌入；云服务为可选，仅查看你明确发送的片段。

工作原理（高层次流程）

Tree-sitter 解析 每个源文件 → 生成文件、函数、类等节点。
实时符号图 从这些节点构建，具有确定性边（contains、imports、calls 等）。
可选索引：为每个文件（或符号）计算嵌入并存储；可选 LLM 可添加文本描述。
MCP 服务器 暴露 RPC 工具（semantic_search、view_signatures、graphrag、structural_search、LSP 辅助工具），AI 代理调用。
混合检索 结合 BM25 关键词得分与向量相似度（RRF 融合）对结果进行排序。

快速开始（安装 → 索引 → 查询）

# 安装（curl 安装器、Homebrew 或 cargo）
curl -fsSL https://raw.githubusercontent.com/Muvon/octocode/master/install.sh | sh
# 或：brew install muvon/tap/octocode
# 或：cargo install octocode

# 设置嵌入提供者（Voyage AI 密钥示例）
export VOYAGE_API_KEY="your-key"

# 索引项目
cd /path/to/your/project
octocode index   # 处理每个文件并构建实时图谱

# 自然语言搜索
octocode search "authentication middleware"

连接 AI 助手（MCP 客户端）

在客户端的 mcpServers 配置中添加服务器条目，例如 Claude Desktop：

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

现在助手可以调用 `semantic_search` 或 `graphrag` 等工具，并以具体位置和调用图回答代码库问题。

检索质量（基准测试）

Octocode 随附一个可复现的基准测试（127 个代码搜索查询），在自身源码树上运行。使用简单的混合策略（BM25 0.3 + 向量 0.7）达到：

Hit@5 = 0.732
Hit@10 = 0.835
MRR = 0.572
Recall@10 = 0.807 关键词加权可使 Hit@5 比仅使用密集检索提升 +22%。基准测试还表明，通用代码重排序器（bge-reranker-base）会降低性能，表明需要专用代码重排序器。

谁可能使用它

开发者：希望其 LLM 驱动的助手（Claude、Cursor 等）理解仓库实际架构的人。
团队：构建需要可靠、隐私保护代码导航的内部 AI 代理的人。
工具制作者：寻找即用型 MCP 服务器，提供 LSP 级精度而无需重新实现 AST 解析的人。

许可与社区

许可证：Apache 2.0（宽松，适合商业使用）。
仓库活跃度：CI 指示器、覆盖率指示器、crates.io 发布、持续增长的星标数。
支持：GitHub Issues、讨论区、联系邮箱（opensource@muvon.io）。

总结：Octocode 是一个真实、生产级别的 Rust 项目，为 AI 代理提供代码的结构化、基于图的视图，实现精确、上下文感知的辅助，同时将所有内容保留在本地并完全受控。