Narsil MCP

官方

以 Rust 🦀 打造的極速 🔥 頂尖 MCP 伺服器，具備神經引擎、安全分析功能，並可選用圖形前端介面。

GitHub
177

你可以用 Narsil MCP 做什麼？

  • 跨 32 種語言搜尋符號 — 使用 find_symbols 或 workspace_symbol_search 依名稱或模式搜尋函式、類別或介面。
  • 追蹤受污染資料以進行安全稽核 — 透過 trace_taint 追蹤使用者輸入在程式碼庫中的流向，並偵測 SQL 注入或 XSS 等注入漏洞。
  • 分析函式呼叫關係 — 使用 get_call_graph、get_callers 和 find_call_path 繪製呼叫者、被呼叫者及函式間的路徑。
  • 生成軟體物料清單 — 匯出 CycloneDX 或 SPDX 格式的 SBOM，並透過 generate_sbom 和 check_dependencies 比對 OSV 資料庫檢查相依性。
  • 無需外部檢查器即可推斷型別 — 使用 infer_types 取得 Python、JavaScript 或 TypeScript 變數的推定型別，並找出潛在的型別錯誤。
  • 將程式碼庫作為知識圖譜查詢 — 對 RDF 圖執行 SPARQL 查詢，或使用 sparql_query 和 export_ccg 匯出分層 CCG 層供 AI 使用。

文件

narsil-mcp

極速、隱私優先的 MCP 伺服器，提供深度程式碼智慧

License Rust Tests MCP

一個以 Rust 驅動的 MCP（模型上下文協定）伺服器，透過 90 個專業工具為 AI 助理提供深度的程式碼理解。

為何選擇 narsil-mcp？

功能narsil-mcpXRAYSerenaGitHub MCP
語言32430+ (LSP)N/A
神經搜尋是否否否
汙染分析是否否否
SBOM/授權是否否部分
離線/本地是是是否
WASM/瀏覽器是否否否
呼叫圖是部分否否
型別推斷是否否否

主要功能

  • 程式碼智慧 - 符號提取、語意搜尋、呼叫圖分析
  • 神經語意搜尋 - 使用嵌入向量尋找相似程式碼（Voyage AI、OpenAI）
  • 安全分析 - 汙染分析、漏洞掃描、OWASP/CWE 涵蓋範圍
  • 供應鏈安全 - SBOM 生成、依賴稽核、授權合規
  • 進階分析 - 控制流圖、資料流分析、死碼偵測

為何選擇 narsil-mcp？

  • 以 Rust 撰寫 - 極速、記憶體安全、單一二進位檔（約 30MB）
  • Tree-sitter 驅動 - 對 32 種語言進行精確的增量解析
  • 零配置 - 指向儲存庫即可開始
  • 符合 MCP 規範 - 可與 Claude、Cursor、VS Code Copilot、Zed 及任何 MCP 客戶端搭配使用
  • 隱私優先 - 完全本地執行，資料不會離開你的機器
  • 平行索引 - 透過 Rayon 使用所有核心
  • 智慧摘錄 - 擴展至完整的語法作用域
  • 安全優先 - 內建漏洞偵測與汙染分析
  • 神經嵌入 - 可選用 Voyage AI 或 OpenAI 進行語意搜尋
  • WASM 支援 - 可透過 WebAssembly 建置在瀏覽器中執行
  • 即時串流 - 大型儲存庫的索引進度會即時顯示結果

支援的語言

語言副檔名提取的符號
Rust.rs函式、結構體、列舉、特徵、實作、模組
Python.py, .pyi函式、類別
JavaScript.js, .jsx, .mjs函式、類別、方法、變數
TypeScript.ts, .tsx函式、類別、介面、型別、列舉
Go.go函式、方法、型別
C.c, .h函式、結構體、列舉、typedef
C++.cpp, .cc, .hpp函式、類別、結構體、命名空間
Java.java方法、類別、介面、列舉
C#.cs方法、類別、介面、結構體、列舉、委派、命名空間
Bash.sh, .bash, .zsh函式、變數
Ruby.rb, .rake, .gemspec方法、類別、模組
Kotlin.kt, .kts函式、類別、物件、介面
PHP.php, .phtml函式、方法、類別、介面、特徵
Swift.swift類別、結構體、列舉、協定、函式
Verilog/SystemVerilog.v, .vh, .sv, .svh模組、任務、函式、介面、類別
Scala.scala, .sc類別、物件、特徵、函式、vals
Lua.lua函式、方法
Haskell.hs, .lhs函式、資料型別、型別類別
Elixir.ex, .exs模組、函式
Clojure.clj, .cljs, .cljc, .edn列表（基本 AST）
Dart.dart函式、類別、方法
Julia.jl函式、模組、結構體
R.R, .r, .Rmd函式
Perl.pl, .pm, .t函式、套件
Zig.zig函式、變數
Erlang.erl, .hrl函式、模組、記錄
Elm.elm函式、型別
Fortran.f90, .f95, .f03, .f08, .f, .for, .fpp程式、子程式、函式、模組
PowerShell.ps1, .psm1, .psd1函式、類別、列舉
Nix.nix繫結
Groovy.groovy, .gradle方法、類別、介面、列舉、函式

安裝

透過套件管理器（建議）

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

Rust/Cargo（所有平台）：

cargo install narsil-mcp

Node.js/npm（所有平台）：

npm install -g narsil-mcp
# or
yarn global add narsil-mcp
# or
pnpm add -g narsil-mcp

Nix：

# Run directly without installing
nix run github:postrv/narsil-mcp -- --repos ./my-project

# Install to profile
nix profile install github:postrv/narsil-mcp

# With web visualization frontend
nix profile install github:postrv/narsil-mcp#with-frontend

# Development shell
nix develop github:postrv/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 並檢查必要的建置工具。

從原始碼建置

先決條件：

# Clone and build
git clone git@github.com:postrv/narsil-mcp.git
cd narsil-mcp
cargo build --release

# Binary will be at:
# - macOS/Linux: target/release/narsil-mcp
# - Windows: target/release/narsil-mcp.exe

功能建置

narsil-mcp 針對不同使用情境支援不同的功能集：

# Default build - native MCP server (~30MB)
cargo build --release

# With RDF knowledge graph and CCG tools (~35MB) - SPARQL queries, Code Context Graph
cargo build --release --features graph

# With neural vector search (~32MB) - adds TF-IDF similarity
cargo build --release --features neural

# With ONNX model support (~50MB) - adds local neural embeddings
cargo build --release --features neural-onnx

# With embedded visualization frontend (~31MB)
cargo build --release --features frontend

# Full-featured build with graph + frontend (~40MB)
cargo build --release --features graph,frontend

# For browser/WASM usage
cargo build --release --target wasm32-unknown-unknown --features wasm
功能說明大小
native（預設）包含所有工具的完整 MCP 伺服器~30MB
graph+ RDF 知識圖譜、SPARQL、CCG 工具~35MB
frontend+ 嵌入式視覺化網頁 UI~31MB
neural+ TF-IDF 向量搜尋、API 嵌入~32MB
neural-onnx+ 本地 ONNX 模型推論~50MB
wasm瀏覽器建置（無檔案系統、git）~3MB

重要： --graph CLI 旗標要求二進位檔必須以 --features graph 建置。如果你將 --graph 傳遞給未包含此功能的二進位檔，你會看到一個警告，且 SPARQL/CCG 工具將無法使用。請參閱下方的疑難排解。

如需詳細的安裝說明、疑難排解和特定平台指南，請參閱 docs/INSTALL.md。

使用方式

基本用法

macOS / Linux：

# Index a single repository
narsil-mcp --repos /path/to/your/project

# Index multiple repositories
narsil-mcp --repos ~/projects/project1 --repos ~/projects/project2

# Enable verbose logging
narsil-mcp --repos /path/to/project --verbose

# Force re-index on startup
narsil-mcp --repos /path/to/project --reindex

Windows (PowerShell / CMD)：

# Index a single repository
narsil-mcp --repos C:\Users\YourName\Projects\my-project

# Index multiple repositories
narsil-mcp --repos C:\Projects\project1 --repos C:\Projects\project2

# Enable verbose logging
narsil-mcp --repos C:\Projects\my-project --verbose

# Force re-index on startup
narsil-mcp --repos C:\Projects\my-project --reindex

完整功能集

narsil-mcp \
  --repos ~/projects/my-app \
  --git \           # Enable git blame, history, contributors
  --call-graph \    # Enable function call analysis
  --persist \       # Save index to disk for fast startup
  --watch \         # Auto-reindex on file changes
  --lsp \           # Enable LSP for hover, go-to-definition
  --streaming \     # Stream large result sets
  --remote \        # Enable GitHub remote repo support
  --neural \        # Enable neural semantic embeddings
  --neural-backend api \  # Backend: "api" (Voyage/OpenAI) or "onnx"
  --neural-model voyage-code-2 \  # Model to use
  --neural-dimension 3072 \  # Override embedding dimensions (auto-detected per model)
  --graph           # Enable SPARQL/RDF knowledge graph and CCG tools (requires --features graph build)

關於 --graph 的注意事項： 此旗標會啟用 SPARQL 查詢和程式碼上下文圖（CCG）工具，但僅限於二進位檔是以 --features graph 建置時。預設的二進位檔不包含此功能。如果你需要 SPARQL/CCG 功能，請從原始碼建置：

cargo build --release --features graph

如果你將 --graph 傳遞給未包含此功能的二進位檔，啟動時會看到一個警告，且伺服器將在不包含 SPARQL/CCG 工具的情況下繼續執行。

注意： 神經嵌入需要 API 金鑰（或自訂端點）。最簡單的設定方式是使用互動式精靈：

# Run the neural API key setup wizard
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+ 引入了選用設定，可對工具和效能進行精細控制。所有現有的使用方式都繼續有效 - 設定完全是選用的！

快速入門

# Generate default config interactively
narsil-mcp config init

# List available tools
narsil-mcp tools list

# Apply a preset via CLI
narsil-mcp --repos ~/project --preset minimal

自動編輯器偵測

narsil-mcp 會偵測你的編輯器並自動套用最佳預設集：

編輯器預設集工具數上下文 Token 數原因
Zed最小26~4,686快速啟動，最小上下文
VS Code平衡51~8,948良好的功能平衡
Claude Desktop完整90~12,001最大功能

節省的 Token 數：

  • 最小預設集： 相較於完整版節省 61% 的 token
  • 平衡預設集： 相較於完整版節省 25% 的 token

預設集

根據你的使用情境選擇一個預設集：

# Minimal - Fast, lightweight (Zed, Cursor)
narsil-mcp --repos ~/project --preset minimal

# Balanced - Good defaults (VS Code, IntelliJ)
narsil-mcp --repos ~/project --preset balanced --git --call-graph

# Full - All features (Claude Desktop, comprehensive analysis)
narsil-mcp --repos ~/project --preset full --git --call-graph

# Security-focused - Security and supply chain tools
narsil-mcp --repos ~/project --preset security-focused

設定檔

使用者設定 (~/.config/narsil-mcp/config.yaml)：

version: "1.0"
preset: "balanced"

tools:
  # Disable slow tools
  overrides:
    neural_search:
      enabled: false
      reason: "Too slow for interactive use"

performance:
  max_tool_count: 50  # Limit total tools

專案設定（儲存庫根目錄中的 .narsil.yaml）：

version: "1.0"
preset: "security-focused"  # Override user preset

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

具名儲存庫設定檔適用於多儲存庫工作區：

version: "1.0"
profiles:
  platform:
    repos:
      - ~/src/api
      - ~/src/web
    git: true
    call_graph: true
    persist: true
    preset: balanced

narsil-mcp --profile platform
narsil-mcp config profiles

優先順序： CLI 旗標 > 環境變數 > 專案設定 > 使用者設定 > 預設值

環境變數

# Select repos/profile
export NARSIL_REPOS=~/src/api,~/src/web
export NARSIL_PROFILE=platform

# Apply preset
export NARSIL_PRESET=minimal

# Enable specific categories
export NARSIL_ENABLED_CATEGORIES=Repository,Symbols,Search

# Disable specific tools
export NARSIL_DISABLED_TOOLS=neural_search,generate_sbom

CLI 指令

# View effective config
narsil-mcp config show

# Validate config file
narsil-mcp config validate ~/.config/narsil-mcp/config.yaml

# List tools by category
narsil-mcp tools list --category Search

# Search for tools
narsil-mcp tools search "git"

# Export config
narsil-mcp config export > my-config.yaml

# List named repository profiles
narsil-mcp config profiles

了解更多：

視覺化前端

在瀏覽器中以互動方式探索呼叫圖、匯入、符號參考和控制流。

# Build with embedded frontend
cargo build --release --features frontend

# Run with HTTP server
narsil-mcp --repos ~/project --http --call-graph
# Open http://localhost:3000

五種圖形檢視：

檢視說明
呼叫圖具有深度控制和方向篩選的函式呼叫關係
匯入圖跨程式碼庫的檔案層級匯入依賴關係
符號圖符號的所有參考，包含檔案叢集
混合圖結合呼叫圖和匯入圖，並分配預算
控制流包含基本區塊、分支和迴圈回邊的真實 CFG

功能：

  • 互動式 Cytoscape.js 圖形，支援拖曳、縮放和雙擊深入探索
  • 複雜度指標疊加層，以顏色編碼（綠色/黃色/橙色/紅色）
  • 安全性漏洞疊加層，突顯汙染來源和匯點
  • 六種佈局演算法（dagre、力導向、廣度優先、同心圓、圓形、網格）
  • 檔案樹側邊欄，附帶語法突顯的程式碼檢視器
  • URL 驅動的狀態（可分享的連結、瀏覽器上一頁/下一頁）
  • 深色模式支援
  • 節點詳細資訊面板，包含程式碼摘錄和導覽至原始碼

完整文件： 請參閱 docs/frontend.md 了解設定、API 端點和開發模式。

神經語意搜尋

使用神經嵌入尋找相似的程式碼 - 即使變數名稱和結構不同也能找到。

# Quick setup with wizard
narsil-mcp config init --neural

# Or manually with 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

Forgemax 整合（實驗性）

對於大規模的代理工作流程，narsil-mcp 可以透過 Forgemax 使用 — 這是一個 Code Mode MCP 閘道，可將所有 90 個工具合併為僅 2 個（search + execute），將工具綱要的開銷從約 12,000 個 token 減少到約 1,000 個。

# Install Forgemax
cargo install forgemax

# Run narsil-mcp through Forgemax (uses forge.toml in repo root)
forgemax

內含的 forge.toml 使用合理的預設值來設定 narsil-mcp：

[servers.narsil]
command = "narsil-mcp"
args = ["--repos", ".", "--git", "--call-graph", "--persist", "--watch"]
transport = "stdio"

[sandbox]
timeout_secs = 10
max_heap_mb = 64
max_concurrent = 8

LLM 會在沙箱化的 V8 isolate 中，透過型別化代理物件寫入 JavaScript 來進行呼叫——憑證、檔案路徑和內部狀態永遠不會離開主機。這種方法在同時使用多個 MCP 伺服器時特別有用，因為它能讓整體工具環境保持精簡且可預測。

MCP 設定

透過建立設定檔，將 narsil-mcp 加入你的 AI 助理。以下是建議的設定方式：

Claude Code（專案根目錄中的 .mcp.json - 建議）：

在你的專案目錄中建立 .mcp.json 以進行專案層級設定：

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

然後在你的專案中啟動 Claude Code：

cd /path/to/project
claude

使用 . 作為 --repos 會自動索引當前目錄。Claude 現在可以存取 90 個程式碼智慧工具。

提示：加入 --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 注意事項：MCP 支援需要 VS Code 1.102 以上版本，且必須由你的組織管理員啟用。

Claude Desktop (claude_desktop_config.json)：

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

Zed (settings.json → 內容伺服器)：

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

Zed 注意事項：narsil-mcp 會立即啟動並在背景索引，避免初始化逾時。

Claude Code 外掛程式

針對 Claude Code 使用者，我們提供了一個包含斜線指令和技能的外掛程式，以便有效使用工具。

透過 Marketplace 安裝（建議）：

# Add the narsil-mcp marketplace
/plugin marketplace add postrv/narsil-mcp

# Install the plugin
/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 有效使用 90 個工具
MCP 設定以合理的預設值自動啟動 narsil-mcp

完整文件請參閱 narsil-plugin/README.md。

Ralph 自動化整合

Ralph 是一個用於自主程式碼開發的 Claude Code 自動化套件。當 narsil-mcp 可用時，Ralph 可獲得增強的程式碼智慧功能：

功能無 narsil-mcp有 narsil-mcp
安全掃描基本（clippy）OWASP/CWE 漏洞偵測
程式碼理解基於檔案呼叫圖、符號參考
架構分析手動CCG L0/L1/L2 自動分層
相依性分析cargo tree匯入圖、循環相依性偵測

設定：

# Install narsil-mcp (Ralph auto-detects it)
cargo install narsil-mcp

# Ralph's quality gates use these tools:
narsil-mcp scan_security --repo <name>
narsil-mcp check_type_errors --repo <name> --path src
narsil-mcp find_injection_vulnerabilities --repo <name>

當 narsil-mcp 無法使用時，Ralph 會優雅降級——所有核心自動化功能無需它也能運作。

文件： 完整整合細節請參閱 Ralph README。

操作手冊與教學

請參閱 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');

完整文件： 建置說明、React 範例和 API 參考請參閱 docs/wasm.md。

可用工具（90 個）

儲存庫與檔案管理

工具說明
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_searchBM25 排名的語意搜尋
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取得顯示基本區塊和分支的 CFG
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_statusMerkle 樹與變更統計資料

安全分析 - 汙染追蹤

工具說明
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效能統計資料與計時

SPARQL / 知識圖譜（需要 --graph）

工具說明
sparql_query對 RDF 知識圖譜執行 SPARQL 查詢
list_sparql_templates列出可用的 SPARQL 查詢範本
run_sparql_template使用參數執行預定義的 SPARQL 範本

程式碼上下文圖（CCG）（需要 --graph）

CCG 以分層方式提供標準化、可供 AI 使用的程式碼庫表示。

工具說明
get_ccg_manifest第 0 層清單（~1-2KB JSON-LD）- 儲存庫識別、計數
export_ccg_manifest將第 0 層清單匯出至檔案
export_ccg_architecture第 1 層架構（~10-50KB JSON-LD）- 模組、API
export_ccg_index第 2 層符號索引（~100-500KB N-Quads gzipped）
export_ccg_full第 3 層完整細節（~1-20MB N-Quads gzipped）
export_ccg將所有 CCG 層匯出為一個套件
query_ccg使用 SPARQL 查詢 CCG
get_ccg_acl為 CCG 層產生 WebACL 存取控制
get_ccg_access_info取得 CCG 存取層級資訊
import_ccg從 URL 或檔案匯入 CCG 層
import_ccg_from_registry從 codecontextgraph.com 登錄匯入 CCG

安全規則

narsil-mcp 在 rules/ 中包含內建的安全規則：

核心規則集：

  • owasp-top10.yaml - OWASP Top 10 2021 漏洞模式
  • cwe-top25.yaml - CWE Top 25 最危險弱點
  • crypto.yaml - 加密問題（弱演算法、硬編碼金鑰）
  • secrets.yaml - 機密偵測（API 金鑰、密碼、權杖） 語言特定規則：
  • rust.yaml - Rust 安全模式（不安全轉型、FFI 邊界、命令注入、TOCTOU）
  • elixir.yaml - Elixir/BEAM 模式（原子耗盡、binary_to_term、Code.eval、Ecto SQL 注入）
  • go.yaml - Go 安全模式（SQL 注入、TLS、命令注入）
  • java.yaml - Java 漏洞（XXE、反序列化、LDAP 注入）
  • csharp.yaml - C# 安全問題（反序列化、XSS、路徑遍歷）
  • kotlin.yaml - Kotlin/Android 模式（WebView、意圖、機密）
  • bash.yaml - Shell 腳本漏洞（命令注入、eval）

基礎設施與組態：

  • iac.yaml - 基礎設施即程式碼（Terraform、CloudFormation、Kubernetes）
  • config.yaml - 組態檔安全（硬編碼憑證、不安全設定）

可使用 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 KB131 µs1.98 GiB/s
Rust（中型檔案）27 KB13.5 µs1.89 GiB/s
Python~4 KB16.7 µs-
TypeScript~5 KB13.9 µs-
混合（5 個檔案）~15 KB57 µ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（此儲存庫）531,733220 ms~50 MB
rust-analyzer2,847~50K2.1s89 MB
linux kernel78,000+~500K45s2.1 GB

關鍵指標：

  • Tree-sitter 解析：~2 GiB/s 持續吞吐量
  • 符號查找：精確匹配 <1µs
  • 全文搜尋：大多數查詢 <1ms
  • 混合搜尋透過 rayon 並行執行 BM25 + TF-IDF

開發

# Run the full test suite
cargo test

# Run benchmarks (criterion.rs)
cargo bench

# Run with debug logging
RUST_LOG=debug cargo run -- --repos ./test-fixtures

# Format code
cargo fmt

# Lint
cargo clippy

# Test with MCP Inspector
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

# For WASM builds
brew install emscripten  # macOS

神經搜尋 API 錯誤

# Check your API key is set
echo $VOYAGE_API_KEY  # or $OPENAI_API_KEY

# Common issue: wrong key format
export VOYAGE_API_KEY="pa-..."  # Voyage keys start with "pa-"
export OPENAI_API_KEY="sk-..."  # OpenAI keys start with "sk-"

索引找不到檔案

# Check .gitignore isn't excluding files
narsil-mcp --repos /path --verbose  # Shows skipped files

# Force reindex
narsil-mcp --repos /path --reindex

大型儲存庫的記憶體問題

# For very large repos (>50K files), increase stack size
RUST_MIN_STACK=8388608 narsil-mcp --repos /path/to/huge-repo

# Or index specific subdirectories
narsil-mcp --repos /path/to/repo/src --repos /path/to/repo/lib

圖形功能無法運作

如果您傳遞 --graph 並看到類似以下的警告：

WARN: --graph flag was passed but the binary was built without the 'graph' feature.
SPARQL and CCG tools will not be available.

這表示您使用的二進位檔未使用 graph 功能編譯。若要修復：

# Build from source with the graph feature
cargo build --release --features graph

# Or with multiple features
cargo build --release --features graph,frontend

# Then run with --graph
./target/release/narsil-mcp --repos ~/project --graph

為什麼這是一個獨立的功能？ graph 功能新增了 Oxigraph RDF 資料庫（約增加 5MB 的二進位檔大小），這對大多數使用案例來說並非必要。將其保留為可選項，以保持預設二進位檔較小。

如何檢查圖形是否已啟用： 查看啟動日誌：

  • graph=true 表示該功能已編譯並啟用
  • graph=false 表示該功能未編譯，或未傳遞 --graph

路線圖

已完成

  • 多語言符號提取（32 種語言）
  • 使用 Tantivy 進行全文搜尋（BM25 排名）
  • 混合搜尋（BM25 + TF-IDF 搭配 RRF）
  • AST 感知程式碼分塊
  • Git blame/歷史記錄整合
  • 呼叫圖分析與複雜度指標
  • 控制流圖（CFG）分析
  • 資料流分析（DFG）與到達定義
  • 死碼和死儲存偵測
  • 注入漏洞的汙染分析
  • 安全規則引擎（OWASP、CWE、加密、機密）
  • SBOM 生成（CycloneDX、SPDX）
  • 依賴漏洞檢查（OSV）
  • 授權合規分析
  • 匯入圖與循環依賴偵測
  • 跨語言符號解析
  • 使用 Merkle 樹進行增量索引
  • 索引持久化
  • 檔案變更監控模式
  • LSP 整合
  • 遠端儲存庫支援
  • 串流回應

最新消息

v1.6.x（目前版本）

  • 防崩潰分塊 - 修復了 chunk_file() 和 extract_signature() 中不安全的位元組層級字串切片，這些切片導致 hybrid_search、search_chunks 和 get_chunk_stats 在處理包含多位元組 UTF-8 字元（表情符號、CJK、重音字元）的檔案時崩潰。所有位元組切片現在都使用安全的 content.get() 並具備回退機制。
  • NaN 安全排序操作 - 修復了搜尋、嵌入、git、索引和提取模組中 5 處 partial_cmp().unwrap() 在 NaN 浮點值上會發生恐慌的位置。所有排序現在都使用 unwrap_or(Ordering::Equal)。
  • 縱深防禦分塊 - 在所有儲存庫範圍的 chunk_file() 迴圈周圍新增了 catch_unwind 包裝器，以便某個檔案中的恐慌會跳過它，而不是使整個 MCP 伺服器崩潰。
  • 視覺化前端大修 - 完整的 SPA，具備 HashRouter 路由、檔案樹側邊欄、語法高亮程式碼檢視器、儀表板和每個儲存庫的概覽頁面
  • 圖形檢視效能 - 匯入圖現在使用快取的索引資料，而非檔案系統走訪；符號圖直接迭代檔案快取，而非 markdown 往返；所有檢視都遵守 max_nodes 以實現提前終止
  • 真實控制流圖 - 流程檢視現在使用真實的 CFG 建構器（cfg::analyze_function），具備適當的基本區塊、分支條件和迴圈回邊，而非單一區塊的存根
  • 混合圖預算分割 - 混合檢視在呼叫圖和匯入圖之間分配 60/40 的節點預算，以獲得平衡的結果
  • 修復 #14：可設定的嵌入維度 - 新增了 --neural-dimension CLI 參數和 default_dimension_for_model() 查找，以便像 text-embedding-3-large 這樣的模型使用正確的維度（3072），而非硬編碼的 1536
  • 修復 #13：Nix 前端建置 - 在 flake.nix 中使用 buildNpmPackage 新增了 frontendDist 衍生，以便 nix profile install github:postrv/narsil-mcp#with-frontend 可以運作
  • Rust 安全規則 - 18 條新規則（RUST-004 至 RUST-021），涵蓋命令注入、轉型、FFI 邊界、TOCTOU、ReDoS、static mut、SSRF 等
  • Elixir 安全規則 - 18 條新規則（EX-001 至 EX-018），涵蓋原子耗盡、binary_to_term 反序列化、Code.eval 注入、Ecto SQL 注入、Phoenix XSS、Erlang 分散式安全
  • 從 serde_yaml 遷移到 serde-saphyr - 已棄用的 serde_yaml 被積極維護、無恐慌的 YAML 函式庫取代
  • 自訂 favicon - 前端現在使用 narsil-mcp 品牌圖示，而非預設的 Vite 標誌
  • 依賴安全性 - 將 time 更新至 0.3.47（RUSTSEC-2026-0009），bytes 更新至 1.11.1（RUSTSEC-2026-0007）
  • 測試數量 從 1,611 增加到 1,763（+152 個測試）

v1.5.x

  • 確定性呼叫圖解析 - 作用域提示傳播消除了被呼叫者解析的歧義（例如，App::run() 正確解析為 src/app/mod.rs::run）
  • 8 項圖形分析修復 - 合格的節點鍵、熱點過濾、CFG 表達式處理、匯入路徑解析
  • Nix flake 改進 - DRY mkPkg 輔助工具，移除了不必要的 macOS 框架，用於沙箱建置的 --lib 測試策略

v1.4.x

  • SPARQL / RDF 知識圖譜 - 透過 Oxigraph 使用 SPARQL 查詢程式碼智慧資料
  • 程式碼上下文圖（CCG） - 12 個工具，用於標準化、可供 AI 使用的程式碼庫表示，具備分層層級（L0-L3）
  • 型別感知安全分析 - 增強的汙染追蹤，具備型別推斷和特徵實作
  • 多語言 CFG/DFG - 控制流和資料流分析擴展到 Go、Java、C#、Kotlin
  • 基礎設施即程式碼掃描 - 針對 Terraform、CloudFormation、Kubernetes 的新 iac.yaml 規則
  • 語言特定安全規則 - 針對 Go、Java、C#、Kotlin、Bash 的新規則
  • 6 種新語言 - Erlang、Elm、Fortran、PowerShell、Nix、Groovy
  • 總共 90 個工具 - 從 79 個增加到 90 個，新增了 SPARQL、CCG 和分析功能

v1.2.x

  • exclude_tests 參數 - 22 個工具支援過濾掉測試檔案
  • npm 套件 - 透過 npm install -g narsil-mcp 安裝

v1.1.x

  • 多平台發行 - 透過 Homebrew、Scoop、npm、Cargo 或直接下載安裝
  • 可設定的工具預設集 - 最小、平衡、完整和安全聚焦的預設集
  • 自動編輯器偵測 - 針對 Zed、VS Code、Claude Desktop 的最佳預設值
  • 互動式設定精靈 - narsil-mcp config init 用於輕鬆設定
  • 支援 32 種語言 - 新增 Dart、Julia、R、Perl、Zig 等
  • 效能提升 - 透過背景索引加快啟動速度

v1.0.x

  • 神經語意搜尋 - 使用 Voyage AI 或 OpenAI 嵌入尋找相似程式碼
  • 型別推斷 - 無需外部工具即可在 Python/JavaScript/TypeScript 中推斷型別
  • 多語言汙染分析 - 針對 PHP、Java、C#、Ruby、Kotlin 的安全掃描
  • WASM 建置 - 在瀏覽器中執行，用於程式碼遊樂場和教育工具
  • 147 條捆綁的安全規則 - OWASP、CWE、加密、機密、Rust、Elixir 偵測
  • 包含 IDE 設定 - Claude Desktop、Cursor、VS Code、Zed 範本

授權

依據以下任一授權條款授權：

由您選擇。

致謝

使用以下技術建置：