CodeGraph Rust MCP

CodeGraph

CodeGraph

你的代码库，明白了。

CodeGraph将您的整个代码库转换为语义可搜索的知识图，AI代理实际上可以 *原因* 不仅仅是快速通过。

准备好开始了吗？ 跳到 安装指南 有关分步设置说明。 已经设置好了吗？ 看 使用指南 获取有关使用AI助手充分利用CodeGraph的提示。

______________________________________________________________________

问题

AI编码助手功能强大，但它们是盲目的。他们一次看到一个文件，grep模式，并燃烧令牌试图理解您的架构。每一次对话都是从零开始的。

如果你的AI助手已经知道你的代码库怎么办？

______________________________________________________________________

CodeGraph有什么不同

1.图形+嵌入=真正的理解

大多数语义搜索工具都会创建嵌入，并就此结束。CodeGraph构建了一个 真实知识图:

Your Code → Build Context → AST + FastML → LSP Resolution → Enrichment → Graph + Embeddings
              ↓               ↓              ↓              ↓              ↓         ↓
          Packages        Nodes/edges    Type-aware     API surface      Graph    Semantic
          Features        Fast patterns  linking        Module graph   traversal   search
          Targets         Spans          Definitions    Dataflow/Docs             (hybrid)

当你搜索时，你不仅会得到“类似的代码”，还会得到带有 关系完好与查询匹配的函数，加上调用它的内容、它所依赖的内容以及它在架构中的位置。

索引丰富增加了：

• 用于跨文件导航的模块节点和模块级导入/包含边缘
• Rust本地数据流边(defines, uses, flows_to, returns, mutates)用于影响分析
• 文档/规范节点链接到中的回溯符号 README.md, docs/**/*.md，以及 schema/**/*.surql
• 架构信号（封装周期+可选边界违规）

索引层次（速度与丰富性）

索引是分层的，因此您可以在速度/存储和图形丰富性之间进行选择。默认值为 快.

层级行为详细信息：

• fast：禁用构建上下文、LSP、丰富、模块链接、数据流、文档/契约和架构；过滤掉 Uses/References 边缘。
• balanced：启用构建上下文、LSP符号、丰富、模块链接和文档/合同；过滤掉 References 边缘。
• full：启用所有分析器和LSP定义；无边缘滤波。

配置层：

• CLI： codegraph index --index-tier balanced
• 环境： CODEGRAPH_INDEX_TIER=balanced
• 配置： [indexing] tier = "balanced"

索引先决条件（启用LSP的层）

当该层启用LSP时(balanced/full)，索引 快速失败 如果缺少所需的外部工具。

按语言列出的所需工具：

• 锈蚀： rust-analyzer
• Types/JavaScript： node 和 typescript-language-server
• python node 和 pyright-langserver
• 去： gopls
• Java jdtls
• C/C++： clangd

如果索引在LSP解析过程中出现停滞，您可以调整每个请求的超时时间：

• CODEGRAPH_LSP_REQUEST_TIMEOUT_SECS （默认值 600，最小值 5)

如果LSP解析立即失败，并且错误包括以下内容 Unknown binary 'rust-analyzer' in official toolchain ...，你的 rust-analyzer 是一个没有安装二进制文件的生锈垫片。安装可运行的 rust-analyzer （例如通过 brew install rust-analyzer 或者通过切换到提供它的工具链）。

可选架构边界规则

如果您希望CodeGraph标记禁止的包依赖关系，请添加 codegraph.boundaries.toml 在项目根：

[[deny]]
from = "your_crate"
to = "forbidden_crate"
reason = "explain the boundary"

索引将发出 violates_boundary 当a depends_on 关系符合拒绝规则。

2.代理工具，而不仅仅是搜索

CodeGraph不返回文件列表，祝你好运。它运送 4个整合的代理工具 他们这样想：

每个工具都接受一个可选 focus 需要时用于精度的参数：

每个工具运行一个 推理代理 它计划、搜索、分析图形关系，并综合一个答案。不是搜索结果 *回答*.

查看代理上下文收集流 -交互式图表，显示代理如何使用图形工具收集上下文。

AgenticArchitectures

Agent体系结构

CodeGraph使用以下方式实现代理 钻机 默认和推荐选择（遗留 react 和 lats 使用自动代理实现仍然有效）。运行时可通过以下方式选择 CODEGRAPH_AGENT_ARCHITECTURE=rig:

为什么Rig是默认设置： 基于Rig的后端通过现代思维和推理模型提供了最佳性能。它是一个原生Rust实现，支持内部子架构，并提供以下功能 真正的令牌流 和 自动恢复.

内部钻机子架构： 使用时 rig 后端，系统会自动映射 整合的代理工具 最有效的推理策略：

• LATS（树木搜索）：用于复杂、非线性任务的深度多路径探索。

- 自动用于： agentic_architecture （结构）， agentic_quality，以及 agentic_context （问题）。

• ReAct（线性）：用于直接数据查找的高速、集中推理。

- 自动用于： agentic_context （搜索/构建器）， agentic_impact，以及 agentic_architecture （api_surface）。

• 反射（自动恢复）：如果主要策略无法找到答案，则自动启动的自我纠正回退。它分析失败并使用改进的计划重试。

代理引导上下文

代理可以从轻量级项目上下文开始，这样他们的第一次工具调用就不会盲目。通过env启用：

• CODEGRAPH_ARCH_BOOTSTRAP=true --在代理的初始上下文中包含一个简短的目录/结构引导+README.md和CLAUDE.md+AGENTS.md或GEMINI.md（如果存在）的内容。
• `CODEGRAPH_ARCH_PRIMER="

"` --在启动说明中注入可选的自定义底漆（例如要关注的区域）。

为什么？更快、更相关的早期步骤，更少浪费的图/语义查询，以及大型存储库上更好的架构答案。

笔记：

• Bootstrap很小（顶部目录摘要），不能替代图查询。
• 使用与索引相同的项目选择(CODEGRAPH_PROJECT_ID 或当前工作目录）。

# Use Rig for best performance with thinking and reasoning models (recommended)
CODEGRAPH_AGENT_ARCHITECTURE=rig ./codegraph start stdio

# Use default ReAct for traditional instruction models
./codegraph start stdio

# Use LATS for complex analysis
CODEGRAPH_AGENT_ARCHITECTURE=lats ./codegraph start stdio

所有架构都使用相同的4个整合的代理工具（由6个内部图分析工具支持）和层感知提示——只是推理策略不同。

3.分层感知智能

这里有一个巧妙的方法：CodeGraph会根据您为CodeGraph代理配置的LLM上下文窗口自动调整其行为。

运行一个小型本地模型？获得专注、高效的查询。

使用GPT-5.1还是Claude在20万的上下文中？进行全面的探索性分析。

在2M上下文中使用grok-4-1快速推理？通过智能结果管理获得详细分析。

Agent只使用生成答案所需的步骤数，因此工具执行时间会根据查询和数据库中索引的数据量而变化。

在开发过程中，代理平均使用3-6个步骤为测试场景生成答案。

代理是无状态的，它只在工具执行期间有会话内存，它不会在多个链式工具调用中积累上下文/内存，这已经由您选择的客户端处理了，它积累了上下文，因此代码图只需要提供答案。

硬帽： 无论级别如何，最多8步（10步，带有环境覆盖）。这可以防止失控的成本和上下文溢出，同时仍然允许进行彻底的分析。

相同的工具，自动针对您的设置进行优化。

4.上下文溢出保护

CodeGraph包括防止上下文溢出的多层保护，防止工具结果超过模型限制时出现代价高昂的故障。

每个工具结果截断：

• 根据您配置的上下文窗口，每个工具的结果都是有限的
• 大型结果（例如，具有1000多个节点的依赖树）被智能截断
• 截断的结果包括 _truncated: true 元数据，以便代理知道数据已被剪切
• 数组结果将最相关的项目保持在限制范围内

上下文累积保护：

• 监控跨多步推理的总累积上下文
• 如果累积的工具结果超过安全阈值，则快速失败并显示明确的错误消息
• 阈值：80%的上下文窗口×4（对令牌开销的保守估计）

通过环境配置：

# CRITICAL: Set this to match your agent's LLM context window
CODEGRAPH_CONTEXT_WINDOW=128000  # Default: 128K

# Per-tool result limit derived automatically: context_window × 2 bytes
# Accumulation limit derived automatically: context_window × 4 × 0.8 bytes

为什么这很重要： 没有这些警卫，一个 agentic_impact 对大型代码库的查询可能会返回600多万个令牌，远远超过大多数模型的限制，并导致代价高昂的失败。

5.真正有效的混合搜索

在“嵌入与关键字”的争论中，我们不会偏袒任何一方。CodeGraph结合了：

• 70%矢量相似性 （语义理解）
• 30%词汇搜索 （精确匹配很重要）
• 图的遍历 （关系和背景）
• 可选重新银行 （交叉编码器精度）

结果如何？你发现 handleUserAuth 当您搜索“登录逻辑”时，以及搜索“handleUserAuth”时。

______________________________________________________________________

Intelligence

为什么这对AI编码很重要

当您将CodeGraph连接到Claude Code、Cursor或任何MCP兼容代理时：

之前： 你的AI一个接一个地读取文件，四处乱跑，在上下文收集时燃烧令牌。

之后： 你的AI呼叫 agentic_impact({"query": "UserService"}) 如果你重构它，它会立刻知道什么会坏。

这不是渐进式的改进。这就是AI之间的区别 *搜索* 你的代码和一个 *理解* 它

为什么这对代码代理很强大

CodeGraph改变了 *认知负荷* （搜索+相关性+依赖性推理）到CodeGraph的代理工具中，这样你的代码代理就可以把上下文预算花在 *做出改变*，不 *发现要改变什么*.

代理工具返回什么（示例）

agentic_impact 返回结构化输出（文件路径、行号和有界代码段/突出显示）加上分析：

{
  "analysis_type": "dependency_analysis",
  "query": "PromptSelector",
  "structured_output": {
    "analysis": "…what depends on PromptSelector and why…",
    "highlights": [
      { "file_path": "crates/codegraph-mcp-server/src/prompt_selector.rs", "line_number": 42, "snippet": "pub struct PromptSelector { … }" }
    ],
    "next_steps": ["…"]
  },
  "steps_taken": "5",
  "tool_use_count": 5
}

否则代码代理必须做什么

如果没有CodeGraph的代理工具，代码代理通常需要多个“单一目的”调用才能达到相同的置信度：

• 搜索符号（通常采用多种策略：文本+语义+ripgrep风格搜索）
• 打开并读取多个文件（定义+用法+调用者+相关模块）
• 从部分证据中重构依赖/调用图
• 当猜测错误时重复（读取次数越多，标记越多）

这会迅速烧毁上下文：读取“仅仅”少数中等大小的文件+周围的上下文很容易消耗数万个令牌，而更大的存储库可以推送到数十万个，具体取决于有多少代码被拉入上下文。

使用CodeGraph，代理可以获得 *精确的位置和关系* （加上有界上下文），并且可以为规划和实施更改保留更多的上下文窗口。

______________________________________________________________________

快速开始

1.安装

# Clone and build with all features
git clone https://github.com/yourorg/codegraph-rust
cd codegraph-rust
./install-codegraph-full-features.sh

macOS更快的构建（LLVM lld）

如果你在macOS上开发，你可以选择使用LLVM lld 用于更快链接的链接器：

# Install LLVM so ld64.lld is on PATH (Homebrew)
brew install llvm

# Use the repo-provided Makefile targets
make build-llvm
make test-llvm

2.启动SurrealDB

# Local persistent storage
surreal start --bind 0.0.0.0:3004 --user root --pass root file://$HOME/.codegraph/surreal.db

3.应用架构

cd schema && ./apply-schema.sh

4.将代码编入索引

codegraph index /path/to/project -r -l rust,typescript,python

🔒 安全说明： 索引自动遵守 .gitignore 并过滤掉常见的秘密模式(.env, credentials.json, *.pem、API密钥等）。你的秘密不会被嵌入或暴露给特工。

5.连接到克劳德代码

添加到MCP配置中：

{
  "mcpServers": {
    "codegraph": {
      "command": "/full/path/to/codegraph",
      "args": ["start", "stdio", "--watch"]
    }
  }
}

就这样 你的AI现在理解你的代码库。

______________________________________________________________________

体系结构

查看交互式架构图 -通过可点击组件和图层过滤探索完整的工作空间结构。

┌─────────────────────────────────────────────────────────────────┐
│                         Claude Code / MCP Client                │
└─────────────────────────────────┬───────────────────────────────┘
                                  │ MCP Protocol
                                  ▼
┌─────────────────────────────────────────────────────────────────┐
│                        CodeGraph MCP Server                     │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                    Agentic Tools Layer                    │  │
│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────────────┐  │  │
│  │  │  Rig    │ │ ReAct   │ │  LATS   │ │ Tool Execution  │  │  │
│  │  │ Agent   │ │ Agent   │ │  Agent  │ │    Pipeline     │  │  │
│  │  └────┬────┘ └────┬────┘ └────┬────┘ └────────┬────────┘  │  │
│  └───────┼───────────┼───────────┼───────────────┼───────────┘  │
│          └───────────┴───────────┴───────────────┘              │
│                              │                                  │
│  ┌───────────────────────────┼───────────────────────────────┐  │
│  │                  Inner Graph Tools                        │  │
│  │  ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐   │  │
│  │  │ Transitive   │ │    Call      │ │     Coupling     │   │  │
│  │  │ Dependencies │ │   Chains     │ │     Metrics      │   │  │
│  │  └──────────────┘ └──────────────┘ └──────────────────┘   │  │
│  │  ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐   │  │
│  │  │   Reverse    │ │    Cycle     │ │       Hub        │   │  │
│  │  │    Deps      │ │  Detection   │ │      Nodes       │   │  │
│  │  └──────────────┘ └──────────────┘ └──────────────────┘   │  │
│  └───────────────────────────┬───────────────────────────────┘  │
└──────────────────────────────┼──────────────────────────────────┘
                               │
┌──────────────────────────────┼──────────────────────────────────┐
│                         SurrealDB                               │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
│  │   Nodes     │  │    Edges    │  │   Chunks + Embeddings   │  │
│  │  (AST +     │  │  (calls,    │  │   (HNSW vector index)   │  │
│  │   FastML)   │  │   imports)  │  │                         │  │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘  │
│                                                                 │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │              SurrealQL Graph Functions                     │ │
│  │   fn::semantic_search_nodes_via_chunks                     │ │
│  │   fn::semantic_search_chunks_with_context                  │ │
│  │   fn::get_transitive_dependencies                          │ │
│  │   fn::trace_call_chain                                     │ │
│  │   fn::calculate_coupling_metrics                           │ │
│  └────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

关键见解： 代理工具不仅仅调用一个函数。他们 *原因* 关于要执行哪些图操作，将它们链接在一起，并综合结果。一个 agentic_impact 呼叫可能：

1. 从语义上搜索目标组件
2. 获取其直接依赖关系
3. 跟踪传递依赖关系
4. 检查循环依赖关系
5. 计算耦合度量
6. 识别可能受影响的集线器节点
7. 将所有发现综合成可操作的答案

______________________________________________________________________

支持的语言

CodeGraph使用树形图进行初始解析，并使用FastML算法增强结果，并支持：

Rust•Python•TypeScript•JavaScript•Go•Java•C++•C•Swift•Kotlin•C#•Ruby•PHP•Dart

______________________________________________________________________

提供商灵活性

嵌入

使用尺寸为384-4096的任何型号：

• 当地： Ollama，LM工作室，ONNX运行时
• 云： OpenAI、Jina AI

法学硕士（用于代理推理）

• 当地： Ollama，LM工作室
• 云： 克洛德，OpenAI，xAI Grok，符合OpenAI标准

数据库

• SurrealDB 具有HNSW矢量索引（2-5ms查询）
• 免费云层可在 surraldb.com/cloud

______________________________________________________________________

配置

全局配置 ~/.codegraph/config.toml:

[embedding]
provider = "ollama"
model = "qwen3-embedding:0.6b"
dimension = 1024

[llm]
provider = "anthropic"
model = "claude-sonnet-4"

[database.surrealdb]
connection = "ws://localhost:3004"
namespace = "ouroboros"
database = "codegraph"

看 安装指南.md 了解完整的配置选项。

实验图模式（可选）

CodeGraph可以在实验性的SurrealDB上运行 graphdb样式模式 (schema/codegraph_graph_experimental.surql)它可以与现有的CodeGraph工具和索引管道互操作。

与关系/香草模式相比(schema/codegraph.surql)，实验模式旨在对大型代码库进行更快、更高效的图查询操作（遍历、邻域扩展和工具驱动的图分析）。

要使用它：

1. 将架构加载到专用数据库中（一次）：

# Example (SurrealDB CLI)
surreal sql --conn ws://localhost:3004 --ns ouroboros --db codegraph_experimental < schema/codegraph_graph_experimental.surql

1. 在该数据库上点CodeGraph：

CODEGRAPH_USE_GRAPH_SCHEMA=true
CODEGRAPH_GRAPH_DB_DATABASE=codegraph_experimental

笔记：

• 模式文件为多个嵌入维度（384-4096）定义了HNSW索引，因此您可以在不重新设计数据库的情况下切换嵌入模型。
• 当前运行时没有自动执行架构加载；你必须申请 .surql 在索引之前，将文件保存到目标数据库。
• CODEGRAPH_GRAPH_DB_DATABASE 控制在以下情况下使用哪些Surreal数据库索引/工具 CODEGRAPH_USE_GRAPH_SCHEMA=true.

______________________________________________________________________

守护程序模式

自动保持索引新鲜：

# With MCP server (recommended)
codegraph start stdio --watch

# Standalone daemon
codegraph daemon start /path/to/project --languages rust,typescript

在后台检测、取消公告和重新索引更改。

______________________________________________________________________

接下来是什么

• \[\]更多语言支持
• \[\]跨存储库分析
• \[\]自定义图形模式
• \[\]自定义分析器的插件系统

______________________________________________________________________

哲学

CodeGraph的存在是因为我们认为AI编码助手应该 *增强的*，未被替换。当人工智能对你正在使用的东西有深入的了解时，最好的人工智能与人类的协作就会发生。

我们不会试图替换您的IDE、类型检查器或测试。我们正在为你的人工智能提供它真正需要帮助的背景。

你的代码库是一个图形。让你的AI这样看待它。

______________________________________________________________________

许可证

麻省理工学院

______________________________________________________________________

链接

• 安装指南
• SurrealDB云 （免费套餐）
• 名称 AI （免费API代币）
• 奥拉玛 （本地模型）

______________________________________________________________________

CodeGraph