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 團隊用心打造 ❤️