Narsil MCP

🚀 narsil-mcp

narsil-mcp 是一款由 Rust 驅動的 MCP（模型上下文協議）服務器，它藉助 76 種專業工具，為 AI 助手提供深入的代碼理解能力，具有速度快、注重隱私等特點。

🚀 快速開始

narsil-mcp 是一款強大的 MCP 服務器。若要使用它，你可以按照以下步驟進行安裝和配置：

1. 依據你的操作系統和偏好選擇合適的安裝方法（具體安裝步驟見下文“📦 安裝指南”）。
2. 安裝完成後，通過命令行工具啟動服務器，指定要索引的代碼倉庫路徑（具體命令見下文“💻 使用示例”）。

✨ 主要特性

代碼智能方面

• 符號提取：能夠精準提取代碼中的各類符號，如函數、結構體、枚舉等。
• 語義搜索：藉助先進的算法實現語義層面的代碼搜索，讓查找更高效。
• 調用圖分析：深入分析代碼中函數之間的調用關係，助力代碼理解與優化。

搜索能力方面

• 神經語義搜索：利用嵌入技術（如 Voyage AI、OpenAI）查找相似代碼，即使代碼結構和變量名不同也能精準定位。

安全分析方面

• 汙點分析：有效檢測代碼中可能存在的安全漏洞，如 SQL 注入、XSS 等。
• 漏洞掃描：全面掃描代碼，發現潛在的安全隱患。
• OWASP/CWE 覆蓋：遵循行業安全標準，確保代碼安全性。

供應鏈安全方面

• SBOM 生成：自動生成軟件物料清單，清晰展示代碼依賴關係。
• 依賴審計：對代碼依賴進行審查，及時發現存在安全風險的依賴項。
• 許可證合規：確保代碼使用的許可證符合相關規定。

高級分析方面

• 控制流圖分析：清晰呈現代碼的控制流程，便於理解和調試。
• 數據流分析：深入分析數據在代碼中的流動情況，發現潛在問題。
• 死代碼檢測：找出代碼中未被使用的部分，提高代碼質量。

其他優勢方面

• 採用 Rust 編寫：具備極快的運行速度，保證了內存安全，且生成的單個二進制文件體積僅約 30MB。
• 由 Tree-sitter 驅動：能夠精確、漸進地解析 16 種編程語言。
• 零配置：只需指定代碼倉庫路徑即可開始使用。
• 符合 MCP 標準：可與 Claude、Cursor、VS Code Copilot、Zed 等多種 MCP 客戶端無縫協作。
• 注重隱私：完全在本地運行，不會將數據傳輸到外部。
• 並行索引：通過 Rayon 充分利用多核處理器的性能，加快索引速度。
• 智能摘錄：能夠自動擴展到完整的語法範圍，提供更有價值的代碼片段。
• 安全優先：內置漏洞檢測和汙點分析功能，保障代碼安全。
• 支持神經嵌入：可選擇使用 Voyage AI 或 OpenAI 進行語義搜索。
• 支持 WASM：可以通過 WebAssembly 在瀏覽器中運行。
• 實時流式處理：對於大型代碼倉庫，在索引過程中即可實時獲取結果。

📦 安裝指南

通過包管理器安裝（推薦）

• macOS / Linux (Homebrew)：

brew tap postrv/narsil
brew install narsil-mcp

• Windows (Scoop)：

scoop bucket add narsil https://github.com/postrv/scoop-narsil
scoop install narsil-mcp

• Arch Linux (AUR)：

yay -S narsil-mcp-bin  # 二進制版本，安裝更快
# 或者
yay -S narsil-mcp      # 從源代碼構建

• Rust/Cargo (所有平臺)：

cargo install narsil-mcp

• Node.js/npm (所有平臺)：

npm install -g narsil-mcp
# 或者
yarn global add narsil-mcp
# 或者
pnpm add -g narsil-mcp

一鍵安裝腳本

• macOS / Linux：

curl -fsSL https://raw.githubusercontent.com/postrv/narsil-mcp/main/install.sh | bash

• Windows (PowerShell)：

irm https://raw.githubusercontent.com/postrv/narsil-mcp/main/install.ps1 | iex

• Windows (Git Bash / MSYS2)：

curl -fsSL https://raw.githubusercontent.com/postrv/narsil-mcp/main/install.sh | bash

⚠️ 重要提示

Windows 用戶請注意：使用 PowerShell 安裝程序能提供更詳細的錯誤信息，並實現更好的本地 Windows 集成。若從源代碼構建，它會自動配置你的 PATH 環境變量，並檢查所需的構建工具。

從源代碼安裝

前提條件：

• Rust 版本 1.70 或更高。
• 在 Windows 系統上：需要安裝 Visual Studio Build Tools 並選擇“使用 C++ 的桌面開發”。

# 克隆倉庫並構建
git clone git@github.com:postrv/narsil-mcp.git
cd narsil-mcp
cargo build --release

# 生成的二進制文件位置：
# - macOS/Linux: target/release/narsil-mcp
# - Windows: target/release/narsil-mcp.exe

特性構建

narsil-mcp 支持根據不同的使用場景選擇不同的特性集進行構建：

# 默認構建 - 原生 MCP 服務器（約 30MB）
cargo build --release

# 啟用神經向量搜索（約 18MB） - 增加 TF-IDF 相似度搜索功能
cargo build --release --features neural

# 支持 ONNX 模型（約 50MB） - 增加本地神經嵌入功能
cargo build --release --features neural-onnx

# 嵌入可視化前端（約 31MB）
cargo build --release --features frontend

# 用於瀏覽器/WASM 的構建
cargo build --release --target wasm32-unknown-unknown --features wasm

特性	描述	大小
native（默認）	包含所有工具的完整 MCP 服務器	~30MB
frontend	增加嵌入式可視化 Web UI	~31MB
neural	增加 TF-IDF 向量搜索和 API 嵌入功能	~32MB
neural-onnx	增加本地 ONNX 模型推理功能	~50MB
wasm	瀏覽器版本（無文件系統和 git 支持）	~3MB

💡 使用建議

如需詳細的安裝說明、故障排除和特定平臺的指南，請參考 docs/INSTALL.md。

💻 使用示例

基礎用法

• macOS / Linux：

# 索引單個代碼倉庫
narsil-mcp --repos /path/to/your/project

# 索引多個代碼倉庫
narsil-mcp --repos ~/projects/project1 --repos ~/projects/project2

# 啟用詳細日誌記錄
narsil-mcp --repos /path/to/project --verbose

# 啟動時強制重新索引
narsil-mcp --repos /path/to/project --reindex

• Windows (PowerShell / CMD)：

# 索引單個代碼倉庫
narsil-mcp --repos C:\Users\YourName\Projects\my-project

# 索引多個代碼倉庫
narsil-mcp --repos C:\Projects\project1 --repos C:\Projects\project2

# 啟用詳細日誌記錄
narsil-mcp --repos C:\Projects\my-project --verbose

# 啟動時強制重新索引
narsil-mcp --repos C:\Projects\my-project --reindex

完整功能集

narsil-mcp \
  --repos ~/projects/my-app \
  --git \           # 啟用 git blame、歷史記錄和貢獻者信息
  --call-graph \    # 啟用函數調用分析
  --persist \       # 將索引保存到磁盤，實現快速啟動
  --watch \         # 文件更改時自動重新索引
  --lsp \           # 啟用 LSP 以支持懸停提示、跳轉到定義等功能
  --streaming \     # 流式處理大型結果集
  --remote \        # 啟用 GitHub 遠程倉庫支持
  --neural \        # 啟用神經語義嵌入
  --neural-backend api \  # 後端選擇："api"（Voyage/OpenAI）或 "onnx"
  --neural-model voyage-code-2  # 使用的模型

⚠️ 重要提示

神經嵌入功能需要 API 密鑰（或自定義端點）。最簡單的設置方法是使用交互式嚮導：

# 運行神經 API 密鑰設置嚮導
narsil-mcp config init --neural

該向導將：

• 檢測你的編輯器（Claude Desktop、Claude Code、Zed、VS Code、JetBrains）。
• 提示你輸入 API 提供商（Voyage AI、OpenAI 或自定義）。
• 驗證你的 API 密鑰。
• 自動將其添加到你編輯器的 MCP 配置中。

或者，你也可以手動設置以下環境變量之一：

• EMBEDDING_API_KEY - 適用於任何提供商的通用 API 密鑰。
• VOYAGE_API_KEY - Voyage AI 特定的 API 密鑰。
• OPENAI_API_KEY - OpenAI 特定的 API 密鑰。
• EMBEDDING_SERVER_ENDPOINT - 自定義嵌入 API 端點 URL（可選，支持使用自託管模型）。

配置

從 v1.1.0 版本開始，引入了可選配置，可對工具和性能進行細粒度控制。所有現有的使用方式仍然有效，配置是完全可選的！

快速開始

# 交互式生成默認配置
narsil-mcp config init

# 列出可用工具
narsil-mcp tools list

# 通過命令行應用預設配置
narsil-mcp --repos ~/project --preset minimal

自動檢測編輯器

narsil-mcp 會自動檢測你的編輯器，並應用最佳預設配置：

編輯器	預設	工具數量	上下文令牌數量	原因
Zed	最小化	26	~4,686	快速啟動，最小化上下文
VS Code	平衡	51	~8,948	功能平衡良好
Claude Desktop	完整	75+	~12,001	最大功能支持

令牌節省情況：

• 最小化預設：與完整預設相比，令牌使用量減少 61%。
• 平衡預設：與完整預設相比，令牌使用量減少 25%。

預設選擇

你可以根據自己的使用場景選擇合適的預設：

# 最小化 - 快速、輕量級（適用於 Zed、Cursor）
narsil-mcp --repos ~/project --preset minimal

# 平衡 - 良好的默認配置（適用於 VS Code、IntelliJ）
narsil-mcp --repos ~/project --preset balanced --git --call-graph

# 完整 - 所有功能（適用於 Claude Desktop、全面分析）
narsil-mcp --repos ~/project --preset full --git --call-graph

# 安全優先 - 專注於安全和供應鏈工具
narsil-mcp --repos ~/project --preset security-focused

配置文件

• 用戶配置 (~/.config/narsil-mcp/config.yaml)：

version: "1.0"
preset: "balanced"

tools:
  # 禁用較慢的工具
  overrides:
    neural_search:
      enabled: false
      reason: "交互使用時速度太慢"

performance:
  max_tool_count: 50  # 限制工具總數

• 項目配置 (.narsil.yaml 在倉庫根目錄)：

version: "1.0"
preset: "security-focused"  # 覆蓋用戶預設

tools:
  categories:
    Security:
      enabled: true
    SupplyChain:
      enabled: true

優先級順序：命令行標誌 > 環境變量 > 項目配置 > 用戶配置 > 默認配置

環境變量

# 應用預設
export NARSIL_PRESET=minimal

# 啟用特定類別
export NARSIL_ENABLED_CATEGORIES=Repository,Symbols,Search

# 禁用特定工具
export NARSIL_DISABLED_TOOLS=neural_search,generate_sbom

命令行命令

# 查看有效配置
narsil-mcp config show

# 驗證配置文件
narsil-mcp config validate ~/.config/narsil-mcp/config.yaml

# 按類別列出工具
narsil-mcp tools list --category Search

# 搜索工具
narsil-mcp tools search "git"

# 導出配置
narsil-mcp config export > my-config.yaml

💡 使用建議

如需瞭解更多信息，請參考：

• 配置指南 - 完整的配置參考。
• 安裝指南 - 特定平臺的安裝說明。

可視化前端

你可以在瀏覽器中交互式地探索調用圖、導入關係和代碼結構。

# 構建時嵌入前端
cargo build --release --features frontend

# 啟動 HTTP 服務器
narsil-mcp --repos ~/project --http --call-graph
# 打開 http://localhost:3000

該前端具有交互式圖表、複雜度覆蓋顯示、安全高亮標記和多種佈局等功能。

💡 使用建議

如需完整文檔，請參考 docs/frontend.md 以瞭解設置、API 端點和開發模式。

神經語義搜索

使用神經嵌入技術查找相似代碼，即使變量名和代碼結構不同也能找到。

# 使用嚮導快速設置
narsil-mcp config init --neural

# 或者手動設置 Voyage AI
export VOYAGE_API_KEY="your-key"
narsil-mcp --repos ~/project --neural --neural-model voyage-code-2

該功能支持 Voyage AI、OpenAI、自定義端點和本地 ONNX 模型。

💡 使用建議

如需完整文檔，請參考 docs/neural-search.md 以瞭解設置、後端和使用場景。

類型推斷

內置的類型推斷功能適用於 Python、JavaScript 和 TypeScript，無需使用 mypy 或 tsc。

工具	描述
infer_types	獲取函數中所有變量的推斷類型
check_type_errors	查找潛在的類型不匹配問題
get_typed_taint_flow	結合類型信息進行增強的安全分析

def process(data):
    result = data.split(",")  # result: list[str]
    count = len(result)       # count: int
    return count * 2          # returns: int

MCP 配置

通過創建配置文件，將 narsil-mcp 添加到你的 AI 助手。以下是推薦的設置：

Claude Code

在項目根目錄創建 .mcp.json 文件進行項目級配置：

{
  "mcpServers": {
    "narsil-mcp": {
      "command": "narsil-mcp",
      "args": ["--repos", ".", "--git", "--call-graph"]
    }
  }
}

然後在項目中啟動 Claude Code：

cd /path/to/project
claude

使用 . 作為 --repos 參數會自動索引當前目錄。Claude 現在可以使用 76 種代碼智能工具。

💡 使用建議

建議添加 --persist --index-path .claude/cache 以在後續運行時實現更快的啟動速度。

如需全局配置，可編輯 ~/.claude/settings.json。更多高級設置請參考 Claude Code 集成。

Cursor

在 .cursor/mcp.json 文件中配置：

{
  "mcpServers": {
    "narsil-mcp": {
      "command": "narsil-mcp",
      "args": ["--repos", ".", "--git", "--call-graph"]
    }
  }
}

VS Code + GitHub Copilot

在 .vscode/mcp.json 文件中配置：

{
  "servers": {
    "narsil-mcp": {
      "command": "narsil-mcp",
      "args": ["--repos", ".", "--git", "--call-graph"]
    }
  }
}

⚠️ 重要提示

對於 Copilot Enterprise，需要 VS Code 1.102 或更高版本，並且必須由組織管理員啟用 MCP 支持。

Claude Desktop

在 claude_desktop_config.json 文件中配置：

{
  "mcpServers": {
    "narsil-mcp": {
      "command": "narsil-mcp",
      "args": ["--repos", "/path/to/your/projects", "--git"]
    }
  }
}

Zed

在 settings.json 的 Context Servers 部分配置：

{
  "context_servers": {
    "narsil-mcp": {
      "command": "narsil-mcp",
      "args": ["--repos", ".", "--git"]
    }
  }
}

⚠️ 重要提示

對於 Zed，narsil-mcp 會立即啟動並在後臺進行索引，避免初始化超時問題。

Claude Code 插件

對於 Claude Code 用戶，我們提供了一個插件，包含斜槓命令和技能，可有效利用工具。

通過市場安裝（推薦）：

# 添加 narsil-mcp 市場
/plugin marketplace add postrv/narsil-mcp

# 安裝插件
/plugin install narsil@narsil-mcp

或者直接從 GitHub 安裝：

/plugin install github:postrv/narsil-mcp/narsil-plugin

插件包含內容：

組件	描述
/narsil:security-scan	運行全面的安全審計
/narsil:explore	探索陌生的代碼庫
/narsil:analyze-function	深入分析特定函數
/narsil:find-feature	查找功能的實現位置
/narsil:supply-chain	分析供應鏈安全
技能	指導 Claude 有效使用 76 種工具
MCP 配置	以合理的默認值自動啟動 narsil-mcp

如需完整文檔，請參考 narsil-plugin/README.md。

操作指南與教程

請參考 docs/playbooks 獲取實際使用指南：

指南	描述
入門指南	快速設置並進行首次工具調用
理解代碼庫	探索陌生項目
修復漏洞	使用調用圖和汙點分析進行調試
安全審計	使用 OWASP/CWE 掃描查找漏洞
代碼審查	有效審查代碼更改

每個操作指南都展示了 Claude 用於回答問題的具體工具鏈。

WebAssembly（瀏覽器）使用方法

narsil-mcp 可以通過 WebAssembly 完全在瀏覽器中運行，非常適合基於瀏覽器的 IDE、代碼審查工具或教育平臺。

npm install @narsil-mcp/wasm

import { CodeIntelClient } from '@narsil-mcp/wasm';

const client = new CodeIntelClient();
await client.init();
client.indexFile('src/main.rs', rustSourceCode);
const symbols = client.findSymbols('Handler');

💡 使用建議

如需完整文檔，請參考 docs/wasm.md 以瞭解構建說明、React 示例和 API 參考。

📚 詳細文檔

可用工具（76 種）

倉庫與文件管理

工具	描述
list_repos	列出所有已索引的倉庫及其元數據
get_project_structure	獲取目錄樹，包含文件圖標和大小信息
get_file	獲取文件內容，可選擇指定行範圍
get_excerpt	提取特定行周圍的代碼，幷包含上下文信息
reindex	觸發倉庫的重新索引操作
discover_repos	自動發現指定目錄中的倉庫
validate_repo	檢查路徑是否為有效的倉庫
get_index_status	顯示索引統計信息和啟用的功能

符號搜索與導航

工具	描述
find_symbols	按類型或模式查找結構體、類、函數等符號
get_symbol_definition	獲取符號的源代碼及周圍上下文
find_references	查找符號的所有引用位置
get_dependencies	分析導入關係和依賴項
workspace_symbol_search	在工作空間中進行符號的模糊搜索
find_symbol_usages	跨文件查找符號的使用情況，包括導入關係
get_export_map	獲取文件或模塊導出的符號

代碼搜索

工具	描述
search_code	關鍵詞搜索，按相關性排序
semantic_search	BM25 排序的語義搜索
hybrid_search	結合 BM25 和 TF-IDF 進行排序融合的搜索
search_chunks	在 AST 感知的代碼塊中進行搜索
find_similar_code	查找與代碼片段相似的代碼（基於 TF-IDF）
find_similar_to_symbol	查找與符號相似的代碼

AST 感知代碼塊

工具	描述
get_chunks	獲取文件的 AST 感知代碼塊
get_chunk_stats	獲取代碼塊的統計信息
get_embedding_stats	獲取嵌入索引的統計信息

神經語義搜索（需要 --neural 選項）

工具	描述
neural_search	使用神經嵌入進行語義搜索，即使名稱不同也能找到相似代碼
find_semantic_clones	查找函數的 Type-3/4 語義克隆
get_neural_stats	獲取神經嵌入索引的統計信息

調用圖分析（需要 --call-graph 選項）

工具	描述
get_call_graph	獲取倉庫或函數的調用圖
get_callers	查找調用某個函數的所有函數
get_callees	查找某個函數調用的所有函數
find_call_path	查找兩個函數之間的調用路徑
get_complexity	獲取圈複雜度或認知複雜度
get_function_hotspots	查找高度關聯的函數

控制流分析

工具	描述
get_control_flow	獲取控制流圖，顯示基本塊和分支
find_dead_code	查找無法到達的代碼塊

數據流分析

工具	描述
get_data_flow	獲取變量的定義和使用情況
get_reaching_definitions	確定哪些賦值語句能夠到達每個代碼點
find_uninitialized	查找未初始化就使用的變量
find_dead_stores	查找從未被讀取的賦值語句

類型推斷（適用於 Python/JavaScript/TypeScript）

工具	描述
infer_types	在不使用外部類型檢查器的情況下，推斷函數中變量的類型
check_type_errors	在不運行 mypy/tsc 的情況下，查找潛在的類型錯誤
get_typed_taint_flow	結合數據流和類型推斷進行增強的汙點分析

導入/依賴圖

工具	描述
get_import_graph	構建並分析導入圖
find_circular_imports	檢測循環依賴
get_incremental_status	獲取 Merkle 樹和更改統計信息

安全分析 - 汙點跟蹤

工具	描述
find_injection_vulnerabilities	查找 SQL 注入、XSS、命令注入、路徑遍歷等漏洞
trace_taint	跟蹤受汙染數據的流動
get_taint_sources	列出受汙染數據的來源（如用戶輸入、文件、網絡）
get_security_summary	進行全面的安全風險評估

安全分析 - 規則引擎

工具	描述
scan_security	使用安全規則（如 OWASP、CWE、加密、密鑰檢測）進行掃描
check_owasp_top10	掃描 OWASP Top 10 2021 中的漏洞
check_cwe_top25	掃描 CWE Top 25 中的弱點
explain_vulnerability	獲取詳細的漏洞解釋
suggest_fix	獲取針對發現問題的修復建議

供應鏈安全

工具	描述
generate_sbom	生成 SBOM（CycloneDX/SPDX/JSON 格式）
check_dependencies	檢查已知的依賴項漏洞（使用 OSV 數據庫）
check_licenses	分析許可證合規性問題
find_upgrade_path	查找易受攻擊依賴項的安全升級路徑

Git 集成（需要 --git 選項）

工具	描述
get_blame	獲取文件的 Git blame 信息
get_file_history	獲取文件的提交歷史記錄
get_recent_changes	獲取倉庫中的最近提交
get_hotspots	查找變更頻繁且複雜度高的文件
get_contributors	獲取倉庫或文件的貢獻者信息
get_commit_diff	獲取特定提交的差異
get_symbol_history	獲取更改符號的提交記錄
get_branch_info	獲取當前分支和狀態信息
get_modified_files	獲取工作樹中的更改文件

LSP 集成（需要 --lsp 選項）

工具	描述
get_hover_info	獲取類型信息和文檔註釋
get_type_info	獲取精確的類型信息
go_to_definition	查找定義位置

遠程倉庫支持（需要 --remote 選項）

工具	描述
add_remote_repo	克隆並索引 GitHub 倉庫
list_remote_files	通過 GitHub API 列出文件
get_remote_file	通過 GitHub API 獲取文件

指標

工具	描述
get_metrics	獲取性能統計信息和時間數據

安全規則

narsil-mcp 在 rules/ 目錄中包含了內置的安全規則：

• owasp-top10.yaml - OWASP Top 10 2021 漏洞模式。
• cwe-top25.yaml - CWE Top 25 最危險的弱點。
• crypto.yaml - 加密問題（如弱算法、硬編碼密鑰）。
• secrets.yaml - 密鑰檢測（如 API 密鑰、密碼、令牌）。

你可以使用 scan_security --ruleset /path/to/rules.yaml 加載自定義規則。

架構

+-----------------------------------------------------------------+
|                         MCP Server                               |
|  +-----------------------------------------------------------+  |
|  |                   JSON-RPC over stdio                      |  |
|  +-----------------------------------------------------------+  |
|                              |                                   |
|  +---------------------------v-------------------------------+  |
|  |                   Code Intel Engine                        |  |
|  |  +------------+ +------------+ +------------------------+  |  |
|  |  |  Symbol    | |   File     | |    Search Engine       |  |  |
|  |  |  Index     | |   Cache    | |  (Tantivy + TF-IDF)    |  |  |
|  |  | (DashMap)  | | (DashMap)  | +------------------------+  |  |
|  |  +------------+ +------------+                              |  |
|  |  +------------+ +------------+ +------------------------+  |  |
|  |  | Call Graph | |  Taint     | |   Security Rules       |  |  |
|  |  |  Analysis  | |  Tracker   | |   Engine               |  |  |
|  |  +------------+ +------------+ +------------------------+  |  |
|  +-----------------------------------------------------------+  |
|                              |                                   |
|  +---------------------------v-------------------------------+  |
|  |                Tree-sitter Parser                          |  |
|  |  +------+ +------+ +------+ +------+ +------+             |  |
|  |  | Rust | |Python| |  JS  | |  TS  | | Go   | ...         |  |
|  |  +------+ +------+ +------+ +------+ +------+             |  |
|  +-----------------------------------------------------------+  |
|                              |                                   |
|  +---------------------------v-------------------------------+  |
|  |                Repository Walker                           |  |
|  |           (ignore crate - respects .gitignore)             |  |
|  +-----------------------------------------------------------+  |
+-----------------------------------------------------------------+

性能

在 Apple M1 上進行基準測試（使用 criterion.rs）：

解析吞吐量

語言	輸入大小	時間	吞吐量
Rust（大文件）	278 KB	131 µs	1.98 GiB/s
Rust（中等文件）	27 KB	13.5 µs	1.89 GiB/s
Python	~4 KB	16.7 µs	-
TypeScript	~5 KB	13.9 µs	-
混合（5 個文件）	~15 KB	57 µs	-

搜索延遲

操作	語料庫大小	時間
符號精確匹配	1,000 個符號	483 ns
符號前綴匹配	1,000 個符號	2.7 µs
符號模糊匹配	1,000 個符號	16.5 µs
BM25 全文搜索	1,000 篇文檔	80 µs
TF-IDF 相似度搜索	1,000 篇文檔	130 µs
混合搜索（BM25+TF-IDF）	1,000 篇文檔	151 µs

端到端索引

倉庫	文件數量	符號數量	時間	內存
narsil-mcp（本倉庫）	53	1,733	220 ms	~50 MB
rust-analyzer	2,847	~50K	2.1s	89 MB
linux 內核	78,000+	~500K	45s	2.1 GB

關鍵指標：

• Tree-sitter 解析：持續吞吐量約為 ~2 GiB/s。
• 符號查找：精確匹配時間 <1µs。
• 全文搜索：大多數查詢時間 <1ms。
• 混合搜索通過 rayon 並行運行 BM25 和 TF-IDF。

🔧 技術細節

開發

# 運行測試（359 個測試用例）
cargo test

# 運行基準測試（使用 criterion.rs）
cargo bench

# 以調試日誌模式運行
RUST_LOG=debug cargo run -- --repos ./test-fixtures

# 格式化代碼
cargo fmt

# 代碼檢查
cargo clippy

# 使用 MCP 檢查器進行測試
npx @modelcontextprotocol/inspector ./target/release/narsil-mcp --repos ./path/to/repo

故障排除

Tree-sitter 構建錯誤

如果你在構建過程中遇到缺少 C 編譯器或 tree-sitter 的錯誤，可以嘗試以下操作：

# macOS
xcode-select --install

# Ubuntu/Debian
sudo apt install build-essential

# 對於 WASM 構建
brew install emscripten  # macOS

神經搜索 API 錯誤

# 檢查 API 密鑰是否設置
echo $VOYAGE_API_KEY  # 或 $OPENAI_API_KEY

# 常見問題：密鑰格式錯誤
export VOYAGE_API_KEY="pa-..."  # Voyage 密鑰以 "pa-" 開頭
export OPENAI_API_KEY="sk-..."  # OpenAI 密鑰以 "sk-" 開頭

索引未找到文件

# 檢查 .gitignore 是否排除了文件
narsil-mcp --repos /path --verbose  # 顯示跳過的文件

# 強制重新索引
narsil-mcp --repos /path --reindex

大型倉庫的內存問題

# 對於非常大的倉庫（文件數量 >50K），增加棧大小
RUST_MIN_STACK=8388608 narsil-mcp --repos /path/to/huge-repo

# 或者只索引特定的子目錄
narsil-mcp --repos /path/to/repo/src --repos /path/to/repo/lib

路線圖

已完成

• [x] 多語言符號提取（支持 16 種語言）
• [x] 使用 Tantivy 進行全文搜索（BM25 排序）
• [x] 混合搜索（BM25 + TF-IDF 結合 RRF）
• [x] AST 感知的代碼塊處理
• [x] Git blame/歷史記錄集成
• [x] 帶有複雜度指標的調用圖分析
• [x] 控制流圖（CFG）分析
• [x] 數據流分析（DFG）及可達定義分析
• [x] 死代碼和死存儲檢測
• [x] 針對注入漏洞的汙點分析
• [x] 安全規則引擎（OWASP、CWE、加密、密鑰檢測）
• [x] SBOM 生成（CycloneDX、SPDX）
• [x] 依賴項漏洞檢查（OSV）
• [x] 許可證合規性分析
• [x] 帶有循環依賴檢測的導入圖
• [x] 跨語言符號解析
• [x] 使用 Merkle 樹進行增量索引
• [x] 索引持久化
• [x] 文件更改的監控模式
• [x] LSP 集成
• [x] 遠程倉庫支持
• [x] 流式響應

新增功能

v1.1.x（當前版本）

• 多平臺分發：支持通過 Homebrew、Scoop、npm、Cargo 或直接下載進行安裝。
• 可配置工具預設：提供最小化、平衡、完整和安全優先等預設配置。
• 自動檢測編輯器：為 Zed、VS Code、Claude Desktop 提供最佳默認配置。
• 交互式設置嚮導：使用 narsil-mcp config init 進行輕鬆配置。
• 支持 Swift 和 Verilog：現在支持 16 種語言。
• 性能提升：通過後臺索引實現更快的啟動速度。

v1.0.x

• 神經語義搜索：使用 Voyage AI 或 OpenAI 嵌入技術查找相似代碼。
• 類型推斷：無需外部工具，即可在 Python/JavaScript/TypeScript 中推斷類型。
• 多語言汙點分析：為 PHP、Java、C#、Ruby、Kotlin 提供安全掃描。
• WASM 構建：可在瀏覽器中運行，適用於代碼遊樂場和教育工具。
• 包含 111 條安全規則：涵蓋 OWASP、CWE、加密、密鑰檢測。
• 包含 IDE 配置模板：為 Claude Desktop、Cursor、VS Code、Zed 提供配置模板。

📄 許可證

本項目採用以下兩種許可證之一，你可以根據自己的需求選擇：

• Apache 許可證，版本 2.0（LICENSE-APACHE 或 http://www.apache.org/licenses/LICENSE-2.0）
• MIT 許可證（LICENSE-MIT 或 http://opensource.org/licenses/MIT）

致謝

本項目使用了以下開源項目構建：

• tree-sitter - 漸進式解析
• tantivy - 全文搜索
• tokio - 異步運行時
• rayon - 數據並行處理
• serde - 序列化