Codegraph Rust

🚀 CodeGraph CLI MCP 服务器

🚀 一款高性能的命令行工具，用于管理 MCP 服务器并对代码库进行索引，具备先进的架构分析能力。

🚀 快速开始

CodeGraph 是一款强大的命令行工具，它将 MCP（模型上下文协议）服务器管理与复杂的代码分析功能相结合。它提供了一个统一的接口，用于对项目进行索引、管理嵌入向量，并以多种传输选项运行 MCP 服务器。现在，你只需要一个或多个代理，就可以创建自己的深度代码和项目知识合成系统！

初始化新项目

# 在当前目录初始化 CodeGraph
codegraph init

# 使用项目名称进行初始化
codegraph init --name my-project

索引代码库

# 索引当前目录
codegraph index .

# 索引指定语言的代码
codegraph index . --languages rust,python,typescript

# 在 OSX 系统上使用更多选项进行索引
RUST_LOG=info,codegraph_vector=debug codegraph index . --workers 10 --batch-size 256 --max-seq-len 512 --force                                                    

# 开启文件监控进行索引
codegraph index . --watch

启动 MCP 服务器

# 使用 STDIO 传输启动（默认）
codegraph start stdio

# 使用 HTTP 传输启动
codegraph start http --port 3000

# 使用双传输模式启动
codegraph start dual --port 3000

（可选）使用本地嵌入向量启动

# 构建时启用该功能（见安装步骤），然后：
export CODEGRAPH_EMBEDDING_PROVIDER=local
export CODEGRAPH_LOCAL_MODEL=sentence-transformers/all-MiniLM-L6-v2
cargo run -p codegraph-api --features codegraph-vector/local-embeddings

搜索代码

# 语义搜索
codegraph search "authentication handler"

# 精确匹配搜索
codegraph search "fn authenticate" --search-type exact

# 基于 AST 的搜索
codegraph search "function with async keyword" --search-type ast

✨ 主要特性

核心特性

• 🔍 高级代码分析：使用 Tree-sitter 跨多种语言解析和分析代码。
• 🚄 双传输支持：可以通过 STDIO、HTTP 或同时使用两者来运行 MCP 服务器。
• 🎯 向量搜索：使用基于 FAISS 的向量嵌入进行语义代码搜索。
• 📊 基于图的架构：借助 RocksDB 支持的图存储来导航代码关系。
• ⚡ 高性能：通过并行处理和批量嵌入针对大型代码库进行了优化。
• 🔧 灵活配置：提供丰富的嵌入模型配置选项和性能调优功能。

原始性能表现 ✨✨✨

在 M3 Pro 32GB 配置下，使用 Qdrant/all-MiniLM-L6-v2-onnx 模型，在 CPU 上不使用 Metal 加速：

• 0.49 秒内处理 170K 行 Rust 代码！
• 3 分 24 秒内生成 21024 个嵌入向量！

Parsing completed: 353/353 files, 169397 lines in 0.49s (714.5 files/s, 342852 lines/s)
[00:03:24] [########################################] 21024/21024 Embeddings complete

🏗️ 架构

CodeGraph 系统架构
┌─────────────────────────────────────────────────────┐
│                   CLI 接口                          │
│                  (codegraph CLI)                    │
└─────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────┐
│                   核心引擎                          │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────┐  │
│  │   解析器    │  │  图存储     │  │   向量搜索 │  │ 
│  │ (Tree-sittr)│  │  (RocksDB)   │  │  (FAISS)   │  │
│  └─────────────┘  └──────────────┘  └────────────┘  │
└─────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────┐
│                  MCP 服务器层                       │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────┐  │
│  │    STDIO    │  │     HTTP     │  │    双模式  │  │
│  │  传输       │  │  传输       │  │            │  │
│  └─────────────┘  └──────────────┘  └────────────┘  │
└─────────────────────────────────────────────────────┘

🧠 使用 ONNX Runtime 进行嵌入（macOS）

• 默认提供程序：CPU EP。使用 Homebrew 安装的 onnxruntime 即可立即使用。
• 可选 CoreML EP：设置 CODEGRAPH_ONNX_EP=coreml，在使用包含 CoreML 的 ONNX Runtime 版本时优先使用 CoreML。
• 回退机制：如果 CoreML EP 初始化失败，CodeGraph 会记录警告并回退到 CPU。

如何使用 ONNX 嵌入向量

# 仅使用 CPU（默认）
export CODEGRAPH_EMBEDDING_PROVIDER=onnx
export CODEGRAPH_ONNX_EP=cpu
export CODEGRAPH_LOCAL_MODEL=/path/to/onnx-file

# 使用 CoreML（需要支持 CoreML 的 ORT 版本）
export CODEGRAPH_EMBEDDING_PROVIDER=onnx
export CODEGRAPH_ONNX_EP=coreml
export CODEGRAPH_LOCAL_MODEL=/path/to/onnx-file

# 安装 codegraph
cargo install --path crates/codegraph-mcp --features "embeddings,codegraph-vector/onnx,faiss"

注意事项

• Apple 平台上的 ONNX Runtime 通过 CoreML 加速，而非 Metal。如果需要在 Apple Silicon 上使用 GPU 加速，请在支持的情况下使用 CoreML。
• 如果 CoreML 不支持某些模型或操作符，它们可能仍会在 CPU 上运行。

在构建时启用 CoreML 功能

• CoreML 注册路径由 codegraph-vector 中的 Cargo 特性 onnx-coreml 控制。
• 使用以下命令进行构建：cargo build -p codegraph-vector --features "onnx,onnx-coreml"。
• 在完整的工作区构建中，可以通过消费 crate 的特性启用它，或者添加：--features codegraph-vector/onnx,codegraph-vector/onnx-coreml。
• 你仍然需要一个编译时支持 CoreML 的 ONNX Runtime 库；该特性仅在代码中启用注册调用。

📦 安装指南

方法 1：从源代码安装

# 克隆仓库
git clone https://github.com/jakedismo/codegraph-cli-mcp.git
cd codegraph-cli-mcp

# 构建项目
cargo build --release

# 全局安装
cargo install --path crates/codegraph-mcp

# 验证安装
codegraph --version

启用本地嵌入向量（可选）

如果你想使用本地嵌入模型（Hugging Face）而不是远程提供商：

1. 为使用向量搜索的 crate 构建时启用本地嵌入特性（API 和/或 CLI 服务器）：

# 构建启用本地嵌入的 API
cargo build -p codegraph-api --features codegraph-vector/local-embeddings

# （可选）如果你的 CLI 服务器 crate 依赖于向量特性，同样启用：
cargo build -p core-rag-mcp-server --features codegraph-vector/local-embeddings

2. 在运行时设置环境变量以切换提供商：

export CODEGRAPH_EMBEDDING_PROVIDER=local
# 可选：选择特定的 HF 模型（必须提供 safetensors 权重）
export CODEGRAPH_LOCAL_MODEL=sentence-transformers/all-MiniLM-L6-v2

3. 像往常一样运行（首次运行将从 Hugging Face 下载模型文件并本地缓存）：

cargo run -p codegraph-api --features codegraph-vector/local-embeddings

模型缓存位置

• 默认的 Hugging Face 缓存：~/.cache/huggingface（或 $HF_HOME），通过 hf-hub 实现。
• 你可以在首次下载后预先填充此缓存以实现离线运行。

方法 2：安装预构建二进制文件

# 下载最新版本
curl -L https://github.com/jakedismo/codegraph-cli-mcp/releases/latest/download/codegraph-$(uname -s)-$(uname -m).tar.gz | tar xz

# 移动到 PATH 路径
sudo mv codegraph /usr/local/bin/

# 验证安装
codegraph --version

方法 3：使用 Cargo 安装

# 直接从 crates.io 安装（发布后）
cargo install codegraph-mcp

# 验证安装
codegraph --version

📚 详细文档

CLI 命令

全局选项

codegraph [OPTIONS] <COMMAND>

Options:
  -v, --verbose         启用详细日志记录
  --config <PATH>       配置文件路径
  -h, --help           打印帮助信息
  -V, --version        打印版本信息

命令参考

• init - 初始化 CodeGraph 项目

codegraph init [OPTIONS] [PATH]

Arguments:
  [PATH]               项目目录（默认：当前目录）

Options:
  --name <NAME>        项目名称
  --non-interactive    跳过交互式设置

• start - 启动 MCP 服务器

codegraph start <TRANSPORT> [OPTIONS]

Transports:
  stdio                STDIO 传输（默认）
  http                 HTTP 流式传输
  dual                 同时使用 STDIO 和 HTTP

Options:
  --config <PATH>      服务器配置文件
  --daemon             在后台运行
  --pid-file <PATH>    PID 文件位置

HTTP Options:
  -h, --host <HOST>    绑定的主机（默认：127.0.0.1）
  -p, --port <PORT>    绑定的端口（默认：3000）
  --tls                启用 TLS/HTTPS
  --cert <PATH>        TLS 证书文件
  --key <PATH>         TLS 密钥文件
  --cors               启用 CORS

• stop - 停止 MCP 服务器

codegraph stop [OPTIONS]

Options:
  --pid-file <PATH>    PID 文件位置
  -f, --force          强制停止，不进行优雅关闭

• status - 检查服务器状态

codegraph status [OPTIONS]

Options:
  --pid-file <PATH>    PID 文件位置
  -d, --detailed       显示详细状态信息

• index - 索引项目

codegraph index <PATH> [OPTIONS]

Arguments:
  <PATH>               项目目录路径

Options:
  -l, --languages <LANGS>     要索引的语言（逗号分隔）
  --exclude <PATTERNS>        排除模式（gitignore 格式）
  --include <PATTERNS>        仅包含这些模式
  -r, --recursive             递归索引子目录
  --force                     强制重新索引
  --watch                     监控文件更改
  --workers <N>               并行工作线程数（默认：4）

• search - 搜索索引代码

codegraph search <QUERY> [OPTIONS]

Arguments:
  <QUERY>              搜索查询

Options:
  -t, --search-type <TYPE>    搜索类型（语义|精确|模糊|正则|AST）
  -l, --limit <N>             最大结果数（默认：10）
  --threshold <FLOAT>         相似度阈值 0.0 - 1.0（默认：0.7）
  -f, --format <FORMAT>       输出格式（人类可读|JSON|YAML|表格）

• config - 管理配置

codegraph config <ACTION> [OPTIONS]

Actions:
  show                 显示当前配置
  set <KEY> <VALUE>    设置配置值
  get <KEY>            获取配置值
  reset                重置为默认值
  validate             验证配置

Options:
  --json               以 JSON 格式输出（用于 'show'）
  -y, --yes            跳过确认（用于 'reset'）

• stats - 显示统计信息

codegraph stats [OPTIONS]

Options:
  --index              显示索引统计信息
  --server             显示服务器统计信息
  --performance        显示性能指标
  -f, --format <FMT>   输出格式（表格|JSON|YAML|人类可读）

• clean - 清理资源

codegraph clean [OPTIONS]

Options:
  --index              清理索引数据库
  --vectors            清理向量嵌入
  --cache              清理缓存文件
  --all                清理所有资源
  -y, --yes            跳过确认提示

配置

配置文件结构

创建一个 .codegraph/config.toml 文件：

# 通用配置
[general]
project_name = "my-project"
version = "1.0.0"
log_level = "info"

# 索引配置
[indexing]
languages = ["rust", "python", "typescript"]
exclude_patterns = ["**/node_modules/**", "**/target/**", "**/.git/**"]
include_patterns = ["src/**", "lib/**"]
recursive = true
workers = 4
watch_enabled = false
incremental = true

# 嵌入配置
[embedding]
model = "openai"  # 选项：openai, local, custom
dimension = 1536
batch_size = 100
cache_enabled = true
cache_size_mb = 500

# 向量搜索配置
[vector]
index_type = "flat"  # 选项：flat, ivf, hnsw
nprobe = 10
similarity_metric = "cosine"  # 选项：cosine, euclidean, inner_product

# 数据库配置
[database]
path = "~/.codegraph/db"
cache_size_mb = 128
compression = true
write_buffer_size_mb = 64

# 服务器配置
[server]
default_transport = "stdio"
http_host = "127.0.0.1"
http_port = 3000
enable_tls = false
cors_enabled = true
max_connections = 100

# 性能配置
[performance]
max_file_size_kb = 1024
parallel_threads = 8
memory_limit_mb = 2048
optimization_level = "balanced"  # 选项：speed, balanced, memory

环境变量

# 使用环境变量覆盖配置
export CODEGRAPH_LOG_LEVEL=debug
export CODEGRAPH_DB_PATH=/custom/path/db
export CODEGRAPH_EMBEDDING_MODEL=local
export CODEGRAPH_HTTP_PORT=8080

嵌入模型配置

• OpenAI 嵌入

[embedding.openai]
api_key = "${OPENAI_API_KEY}"  # 使用环境变量
model = "text-embedding-3-large"
dimension = 3072

• 本地嵌入

[embedding.local]
model_path = "~/.codegraph/models/codestral.gguf"
device = "cpu"  # 选项：cpu, cuda, metal
context_length = 8192

用户工作流

工作流 1：完整项目设置和分析

# 步骤 1：初始化项目
codegraph init --name my-awesome-project

# 步骤 2：配置设置
codegraph config set embedding.model local
codegraph config set performance.optimization_level speed

# 步骤 3：索引代码库
codegraph index . --languages rust,python --recursive

# 步骤 4：启动 MCP 服务器
codegraph start http --port 3000 --daemon

# 步骤 5：搜索和分析
codegraph search "database connection" --limit 20
codegraph stats --index --performance

工作流 2：使用监控模式进行持续开发

# 开启监控模式进行索引
codegraph index . --watch --workers 8 &

# 以双模式启动 MCP 服务器
codegraph start dual --daemon

# 监控更改
codegraph status --detailed

# 在开发过程中搜索
codegraph search "TODO" --search-type exact

工作流 3：与 AI 工具集成

# 为 Claude Desktop 或 VS Code 启动 MCP 服务器
codegraph start stdio

# 配置以集成 AI 助手
cat > ~/.codegraph/mcp-config.json << EOF
{
  "name": "codegraph-server",
  "version": "1.0.0",
  "tools": [
    {
      "name": "analyze_architecture",
      "description": "分析代码库架构"
    },
    {
      "name": "find_patterns",
      "description": "查找代码模式和反模式"
    }
  ]
}
EOF

工作流 4：大型代码库优化

# 针对大型代码库进行优化
codegraph config set performance.memory_limit_mb 8192
codegraph config set vector.index_type ivf
codegraph config set database.compression true

# 优化索引
codegraph index /path/to/large/project \
  --workers 16 \
  --exclude "**/test/**,**/vendor/**"

# 使用批量操作
codegraph search "class.*Controller" --search-type regex --limit 100

集成指南

与 Claude Desktop 集成

1. 添加到 Claude Desktop 配置：

{
  "mcpServers": {
    "codegraph": {
      "command": "codegraph",
      "args": ["start", "stdio"],
      "env": {
        "CODEGRAPH_CONFIG": "~/.codegraph/config.toml"
      }
    }
  }
}

2. 重启 Claude Desktop 以加载 MCP 服务器。

与 VS Code 集成

1. 安装 VS Code 的 MCP 扩展。
2. 添加到 VS Code 设置：

{
  "mcp.servers": {
    "codegraph": {
      "command": "codegraph",
      "args": ["start", "stdio"],
      "rootPath": "${workspaceFolder}"
    }
  }
}

API 集成

import requests
import json

# 连接到 HTTP MCP 服务器
base_url = "http://localhost:3000"

# 索引项目
response = requests.post(f"{base_url}/index", json={
    "path": "/path/to/project",
    "languages": ["python", "javascript"]
})

# 搜索代码
response = requests.post(f"{base_url}/search", json={
    "query": "async function",
    "limit": 10
})

results = response.json()

在 CI/CD 中使用

# GitHub Actions 示例
name: CodeGraph Analysis

on: [push, pull_request]

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      
      - name: 安装 CodeGraph
        run: |
          cargo install codegraph-mcp
      
      - name: 索引代码库
        run: |
          codegraph init --non-interactive
          codegraph index . --languages rust,python
      
      - name: 运行分析
        run: |
          codegraph stats --index --format json > analysis.json
      
      - name: 上传结果
        uses: actions/upload-artifact@v2
        with:
          name: codegraph-analysis
          path: analysis.json

🔧 技术细节

性能基准测试

运行可重复的端到端基准测试，测量索引速度（使用本地嵌入向量 + FAISS）、向量搜索延迟和图遍历吞吐量。

构建时启用性能特性

选择一种本地嵌入后端并启用 FAISS：

# 选项 A：ONNX Runtime（macOS 上使用 CoreML，其他系统使用 CPU）
cargo install --path crates/codegraph-mcp --features "embeddings,codegraph-vector/onnx,faiss"

# 选项 B：本地 HF + Candle（CPU/Metal/CUDA）
cargo install --path crates/codegraph-mcp --features "embeddings-local,faiss"

配置本地嵌入后端

• ONNX（CoreML/CPU）

export CODEGRAPH_EMBEDDING_PROVIDER=onnx
# macOS：使用 CoreML
export CODEGRAPH_ONNX_EP=coreml   # 或 cpu
export CODEGRAPH_LOCAL_MODEL=/path/to/model.onnx

• 本地 HF + Candle（CPU/Metal/CUDA）

export CODEGRAPH_EMBEDDING_PROVIDER=local
# 设备：cpu | metal | cuda:<id>
export CODEGRAPH_LOCAL_MODEL=sentence-transformers/all-MiniLM-L6-v2

运行基准测试

# 冷启动（清理 .codegraph），预热查询 + 定时试验
codegraph perf . \
  --langs rust,ts,go \
  --warmup 3 --trials 20 \
  --batch-size 128 --device metal \
  --clean --format json

测量内容

• 索引：解析 -> 嵌入 -> 构建 FAISS（全局 + 分片）的总时间。
• 嵌入吞吐量：每秒生成的嵌入向量数量。
• 向量搜索：重复查询的延迟（平均/中位数/95% 分位数）。
• 图遍历：广度优先搜索（BFS）深度为 2 的微基准测试。

示例输出（数字因机器和代码库而异）

{
  "env": {
    "embedding_provider": "local",
    "device": "metal",
    "features": { "faiss": true, "embeddings": true }
  },
  "dataset": {
    "path": "/repo/large-project",
    "languages": ["rust","ts","go"],
    "files": 18234,
    "lines": 2583190
  },
  "indexing": {
    "total_seconds": 186.4,
    "embeddings": 53421,
    "throughput_embeddings_per_sec": 286.6
  },
  "vector_search": {
    "queries": 100,
    "latency_ms": { "avg": 18.7, "p50": 12.3, "p95": 32.9 }
  },
  "graph": {
    "bfs_depth": 2,
    "visited_nodes": 1000,
    "elapsed_ms": 41.8
  }
}

可重复性提示

• 使用 --clean 进行冷启动测量，再次运行以获取热缓存数据。
• 关闭可能竞争 CPU/GPU 的后台进程。
• 固定版本：rustc --version、FAISS 版本和嵌入模型。
• 记录主机信息：CPU/GPU、内存、存储、操作系统版本。

故障排除

常见问题及解决方案

• 问题：服务器无法启动

# 检查端口是否已被使用
lsof -i :3000

# 杀死现有进程
codegraph stop --force

# 使用不同端口启动
codegraph start http --port 3001

• 问题：索引速度慢

# 增加工作线程数
codegraph index . --workers 16

# 排除不必要的文件
codegraph index . --exclude "**/node_modules/**,**/dist/**"

# 使用增量索引
codegraph config set indexing.incremental true

• 问题：索引过程中内存不足

# 减小批量大小
codegraph config set embedding.batch_size 50

# 限制内存使用
codegraph config set performance.memory_limit_mb 1024

# 使用流式模式
codegraph index . --streaming

• 问题：向量搜索结果不佳

# 调整相似度阈值
codegraph search "query" --threshold 0.5

# 使用更好的嵌入向量重新索引
codegraph config set embedding.model openai
codegraph index . --force

# 使用不同的搜索类型
codegraph search "query" --search-type fuzzy

• 问题：Hugging Face 模型下载失败

# 确保有网络连接且模型名称正确
export CODEGRAPH_LOCAL_MODEL=sentence-transformers/all-MiniLM-L6-v2

# 如果模型是私有的，设置 HF 令牌（如果环境需要）
export HF_TOKEN=your_hf_access_token

# 清理/检查缓存（默认）：~/.cache/huggingface
ls -lah ~/.cache/huggingface

# 注意：模型必须包含 safetensors 权重；仅支持 PyTorch .bin 文件的本地加载器不支持此类模型

• 问题：本地嵌入向量速度慢

# 通过配置或环境变量减小批量大小（CPU 默认优先考虑稳定性）
# 考虑使用较小的模型（例如 all-MiniLM-L6-v2）或启用 GPU 后端。

# 对于 Apple Silicon（Metal）或 CUDA，可以在配置中启用额外的连接。
# 当前默认使用 CPU；联系维护人员以在你的环境中启用设备选择器。

调试模式

启用调试日志以进行故障排除：

# 设置调试日志级别
export RUST_LOG=debug
codegraph --verbose index .

# 检查日志
tail -f ~/.codegraph/logs/codegraph.log

健康检查

# 检查系统健康状况
codegraph status --detailed

# 验证配置
codegraph config validate

# 测试数据库连接
codegraph test db

# 验证嵌入向量
codegraph test embeddings

🤝 贡献

我们欢迎贡献！请查看我们的 贡献指南 以获取详细信息。

开发设置

# 克隆仓库
git clone https://github.com/jakedismo/codegraph-cli-mcp.git
cd codegraph-cli-mcp

# 安装开发依赖
cargo install cargo-watch cargo-nextest

# 运行测试
cargo nextest run

# 开启监控模式运行
cargo watch -x check -x test

📄 许可证

本项目采用 MIT 和 Apache 2.0 双许可证。详情请参阅 LICENSE-MIT 和 LICENSE-APACHE。

🙏 致谢

• 使用 Rust 构建
• 由 Tree-sitter 提供支持
• 向量搜索使用 FAISS
• 图存储使用 RocksDB
• MCP 协议由 Anthropic 提供

---

由 CodeGraph 团队用心打造 ❤️