Octocode

面向 AI Agent 的结构化代码智能 — MCP 服务 + 知识图谱 + 语义搜索

为你的代码库赋予 AI 助手一个大脑。 Octocode 会将你的项目转换为可导航的知识图谱，让 Claude、Cursor 和其他 AI Agent 能够搜索、理解并浏览其中的内容。

🚀 快速开始 • 🤖 MCP 集成 • 📖 文档 • 🌐 网站

🤖 为 AI Agent 打造

问题： AI 助手无法洞察你的代码库。它们不能搜索文件、理解依赖关系，也无法在不同会话间记住上下文。

解决方案： Octocode 的 MCP 服务为 AI Agent 提供：

• 🔍 语义搜索 — 按含义而非关键词查找代码
• 🕸️ 知识图谱 — 浏览导入、调用和依赖关系
• 📝 代码签名 — 无需读取完整文件即可查看其结构
• 🧭 LSP 精确定位 — 通过语言服务实现转到定义、查找引用和悬停文档

适用于： Claude Desktop • Cursor • Windsurf • 任何兼容 MCP 的 AI

现在，你的 AI 助手可以：

You: "Where is authentication handled?"
AI: *searches your codebase* "Authentication is in src/middleware/auth.rs,
    which imports jwt.rs for token validation and calls user_store.rs for lookup."

You: "What files depend on the payment module?"
AI: *queries knowledge graph* "src/api/handlers/payment.rs imports payment/mod.rs,
    which is also used by src/workers/refund.rs and src/cron/billing.rs"

You: "Find every call site of this function"
AI: *uses LSP find-references* "process_payment() is called from 4 places:
    checkout.rs:87, refund.rs:134, billing.rs:56, and tests/payment_test.rs:23"

🤔 为什么选择 Octocode？

标准 RAG 会将代码视为扁平的文本片段。 它能找到相似的片段，却不知道 auth_middleware.rs 导入了 jwt.rs、调用了 user_store.rs，并接入了 router.rs。Octocode 理解结构。

# Semantic search finds the right code
octocode search "authentication middleware"
→ src/middleware/auth.rs — Similarity: 0.9234

# The GraphRAG CLI queries the optional persisted graph
octocode config --graphrag-enabled true
octocode index
octocode graphrag get-relationships --node-id src/middleware/auth.rs
Outgoing:
  imports → jwt (src/auth/jwt.rs): token validation logic
  calls   → user_store (src/db/user_store.rs): user lookup by token
Incoming:
  imports ← router (src/router.rs): wires auth into the request pipeline

Octocode 使用 tree-sitter AST 解析，构建包含文件、符号、导入、调用、继承和实现关系的实时图谱。MCP graphrag 工具无需索引、嵌入或大模型，即可根据当前源代码树按需构建此图谱。可选的索引式 GraphRAG 还能提供语义文件发现、描述和更广泛的架构关系。

🔬 工作原理

Current Source → Tree-sitter AST → Live Symbol Graph ──────────────→ MCP `graphrag`
                                           ↑                              ↑
Indexed Code → Embeddings + Optional LLM → Persisted File Enrichment ─────┘

1. 实时 AST 图谱 — tree-sitter 直接从当前源代码中提取文件和符号节点，以及确定性的 contains、imports、calls、extends 和 implements 关系
2. 始终可用的图谱导航 — 即使设置 [graphrag].enabled = false，也可以通过 MCP 查询图谱、遍历关系、查找路径和查看概览
3. 可选增强 — 启用索引式 GraphRAG 后，可叠加语义文件匹配、大模型生成的描述，以及更广泛的文件级架构关系；符号不会被嵌入，也不会由大模型生成
4. 混合搜索 — 语义相似度 + BM25 全文搜索 + 重排序，分别处理基于含义的代码检索
5. MCP 服务 — 向任何兼容 MCP 的客户端提供 semantic_search、view_signatures、graphrag 和 structural_search

✨ 与众不同之处

文档工具为 AI 提供你所用库的使用手册。Octocode 则为 AI 提供你如何组合这些库的蓝图。

使用 Rust 构建，性能出色。本地优先，保护隐私。开源（Apache 2.0），透明可信。

📊 检索质量

Octocode 提供了一套可复现的检索基准测试（benchmark/）：包含 127 条精心整理的代码搜索查询及其行范围标准答案，并针对 octocode 自身源码运行（固定在 b1771ba，确保标注不会偏移）。下方数据使用完全本地、无需 API 密钥的技术栈 — 通过 fastembed 使用 jina-embeddings-v2-base-code，不使用重排器 — 因此这些数据代表基线，而非上限：

提高 RRF 融合中 BM25/关键词信号的权重 — 代码中的精确标识符对此尤为重要 — 可在零额外成本下将 Hit@5 提升 +22%，并将 Recall@10 提升 +20%。

基准测试还指出了哪些方法在这里_不起作用_（benchmark/RESULTS.md 中提供完整的 6 种变体对照）：通用的本地交叉编码器重排器（bge-reranker-base）实际上会导致结果变差（Hit@5 从 0.732 降至 0.598）——代码检索需要_了解代码的_重排器（例如 voyage:rerank-2.5），而非现成的通用重排器。

git clone https://github.com/Muvon/octocode && cd octocode
git worktree add /tmp/corpus b1771ba   # pin the corpus to the ground-truth commit
CORPUS=/tmp/corpus python3 benchmark/run_matrix.py   # set OCTO_BIN to use a custom binary

有关方法和指标定义，请参阅 benchmark/README.md。

🚀 快速开始

1. 安装

# Universal installer (Linux, macOS, Windows)
curl -fsSL https://raw.githubusercontent.com/Muvon/octocode/master/install.sh | sh

# macOS with Homebrew
brew install muvon/tap/octocode

# From crates.io
cargo install octocode

# Or from source (latest)
cargo install --git https://github.com/Muvon/octocode

# Download binary from releases
# https://github.com/Muvon/octocode/releases

2. 设置 API 密钥

# Optional: embedding provider (defaults to local FastEmbed — no key needed)
export VOYAGE_API_KEY="your-voyage-api-key"

# Optional: LLM for commit messages, code review
export OPENROUTER_API_KEY="your-openrouter-api-key"

获取你的 Voyage API 密钥： voyageai.com（提供免费套餐）

# OpenAI
export OPENAI_API_KEY="your-key"
octocode config --code-embedding-model "openai:text-embedding-3-small"

# Jina AI
export JINA_API_KEY="your-key"
octocode config --code-embedding-model "jina:jina-embeddings-v3"

# Google
export GOOGLE_API_KEY="your-key"
octocode config --code-embedding-model "google:text-embedding-005"

3. 为代码库建立索引

cd /your/project
octocode index
# → ✓ Indexing complete! 342 of 342 files processed (342 new, 0 unchanged)

4. 搜索代码

# Natural language search
octocode search "authentication middleware"

# Multi-query for broader results
octocode search "auth" "middleware" "session"

# Filter by language
octocode search "database connection pool" --language rust

# Search commit history
octocode search "authentication refactor" --mode commits

5. 连接 AI 助手

将以下内容添加到 MCP 客户端配置中（Claude Desktop、Cursor、Windsurf）：

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

完成！现在，你的 AI 助手已能理解代码库结构。

🔌 MCP 服务集成

Octocode 内置了一个 MCP 服务，可将你的代码库作为工具提供给 AI 助手。这是使用 Octocode 的主要方式 — 让 AI 助手直接访问代码搜索和导航功能。

可用工具

使用你的语言服务器启动服务，即可启用 LSP 工具：

octocode mcp --path /your/project --with-lsp="rust-analyzer"

对话式 AI 示例

连接后，你的 AI 助手可以回答有关代码库的问题：

You: "Where is user authentication implemented?"
AI: *uses semantic_search* "Found in src/auth/login.rs. The authenticate() function
    validates credentials against the database, generates a JWT token, and stores
    the session in Redis."

You: "What files depend on the payment module?"
AI: *uses graphrag* "src/api/handlers/payment.rs imports payment/mod.rs, which is also
    used by src/workers/refund.rs and src/cron/billing.rs. The payment module exports
    process_payment() and validate_transaction() functions."

You: "Show me all error handling in the API layer"
AI: *uses structural_search* "Found 23 error handling patterns in src/api/:
    - 15 use Result<T, ApiError> with explicit error types
    - 8 use .unwrap() (potential panics in handlers/user.rs:42, handlers/auth.rs:87)
    - 3 use .expect() with custom messages"

快速设置

Octomind（推荐）——零配置，Octocode 已预先配置：

curl -fsSL https://raw.githubusercontent.com/muvon/octomind/master/install.sh | bash
octomind run developer:rust

Claude Code（CLI）——命令行设置：

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

Claude Desktop / Cursor / Windsurf——添加到配置中：

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

配置位置：

• Claude Desktop：~/Library/Application Support/Claude/claude_desktop_config.json（macOS）
• Cursor：~/.cursor/mcp.json 或“设置” → “MCP Servers”
• Windsurf：“设置” → “MCP”

📖 完整的 MCP 客户端设置指南——包含 VS Code（Cline/Continue）、Zed、Replit 等 15 多种客户端的详细说明。

🌐 支持的语言

支持 17 种语言，并提供完整的 tree-sitter AST 解析：

📚 文档

• 开始使用——入门步骤和基本工作流
• 安装指南——详细的安装方式及从源代码构建
• MCP 客户端设置——连接到 Claude、Cursor、Windsurf 等 15 多种客户端
• MCP 集成——MCP 服务详情和高级配置
• 命令参考——完整的 CLI 参考
• 配置——模板和自定义设置
• API 密钥——提供方设置指南
• 架构——深入了解其工作原理
• 参与贡献——开发环境设置

🔒 隐私与安全

• 🏠 本地优先 — 通过 fastembed 完全在本地生成嵌入（无需 API 密钥）；云端提供商为可选项
• 🔐 安全 — API 密钥存储在本地，支持环境变量
• 🚫 遵循 .gitignore — 从不索引敏感文件
• 🛡️ MCP 安全 — 仅限本地的服务，搜索不使用外部网络
• 📤 云端安全 — 云端提供商只会接收要生成嵌入的代码片段；如需完全离线索引，请使用本地模型

🤝 社区与支持

• ⭐ 在 GitHub 上给我们点星 — 这对我们帮助很大！
• 🐛 报告问题
• 💬 参与讨论
• 📧 [email protected]
• 🌐 muvon.io

⚖️ 许可证

Apache License 2.0 — 详情请参阅 LICENSE。