Narsil MCP

官方

基于Rust语言构建的极速MCP服务器，配备神经引擎、安全分析功能及可选的图形化前端界面

GitHub

168

你可以用 Narsil MCP 做什么？

Find symbols across 32 languages — Search for functions, classes, or interfaces by name or pattern using find_symbols or workspace_symbol_search.
Trace tainted data for security audits — Follow user input through the codebase with trace_taint and detect injection vulnerabilities like SQLi or XSS.
Analyze function call relationships — Map callers, callees, and paths between functions with get_call_graph, get_callers, and find_call_path.
Generate a software bill of materials — Export a CycloneDX or SPDX SBOM and check dependencies against the OSV database with generate_sbom and check_dependencies.
Infer types without external checkers — Get inferred types for Python, JavaScript, or TypeScript variables using infer_types and find potential type errors.
Query the codebase as a knowledge graph — Run SPARQL queries against the RDF graph or export tiered CCG layers for AI consumption with sparql_query and export_ccg.

文档

narsil-mcp

极速、隐私优先的深度代码智能 MCP 服务器

一个由 Rust 驱动的 MCP（模型上下文协议）服务器，通过 90 个专用工具为 AI 助手提供深度代码理解能力。

为什么选择 narsil-mcp？

特性	narsil-mcp	XRAY	Serena	GitHub MCP
语言	32	4	30+ (LSP)	不适用
神经搜索	是	否	否	否
污点分析	是	否	否	否
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`	函数、结构体、枚举、类型定义
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`	类、对象、特征、函数、值
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 并检查所需的构建工具。

从源码构建

先决条件：

Rust 1.70 或更高版本
Windows 上：Visual Studio Build Tools，包含“使用 C++ 的桌面开发”

# Clone and build
git clone [email protected]: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`	+ 嵌入式可视化 Web 界面	~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 会检测你的编辑器并自动应用最佳预设：

编辑器	预设	工具数	上下文令牌数	原因
Zed	最小	26	~4,686	快速启动，最小上下文
VS Code	平衡	51	~8,948	良好的功能平衡
Claude Desktop	完整	90	~12,001	最大能力

令牌节省：

最小预设： 相比完整预设减少 61% 的令牌
平衡预设： 相比完整预设减少 25% 的令牌

预设

根据你的用例选择预设：

# 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 驱动状态（可分享链接、浏览器前进/后退）
深色模式支持
节点详情面板，包含代码摘录和导航到源代码

完整文档： 有关设置、API 端点和开发模式，请参阅 docs/frontend.md。

神经语义搜索

使用神经嵌入查找相似代码 - 即使变量名和结构不同。

# 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 个令牌减少到约 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 隔离环境中，通过类型化代理对象编写并调用 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 用户，我们提供了一个包含斜杠命令和技能的插件，以便有效使用工具。

通过市场安装（推荐）：

# 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：

指南	描述
入门指南	快速设置和首次工具调用
理解代码库	探索不熟悉的项目
修复 Bug	使用调用图和污点分析进行调试
安全审计	通过 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_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`	获取显示基本块和分支的 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_status`	默克尔树和变更统计

安全分析 - 污点追踪

工具	描述
`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、Intent、密钥）
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 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 kernel	78,000+	~500K	45s	2.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

路线图

已完成

新增功能

v1.6.x（当前版本）

防崩溃分块 - 修复了 chunk_file() 和 extract_signature() 中不安全的字节级字符串切片问题，该问题导致 hybrid_search、search_chunks 和 get_chunk_stats 在处理包含多字节 UTF-8 字符（表情符号、中日韩文字、重音字符）的文件时崩溃。所有字节切片现在使用安全的 content.get() 并带有回退机制。
NaN 安全排序操作 - 修复了搜索、嵌入、git、索引和提取模块中 5 处 partial_cmp().unwrap() 在 NaN 浮点值上会 panic 的位置。所有排序现在使用 unwrap_or(Ordering::Equal)。
纵深防御分块 - 在所有仓库范围的 chunk_file() 循环周围添加了 catch_unwind 包装器，以便一个文件中的 panic 会跳过它，而不是使整个 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），涵盖命令注入、transmute、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 被积极维护、无 panic 的 YAML 库取代
自定义网站图标 - 前端现在使用 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）
类型感知安全分析 - 通过类型推断和 trait 实现增强污点跟踪
多语言 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 模板

许可证

根据以下任一许可证授权：

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 - 序列化

Narsil MCP

你可以用 Narsil MCP 做什么？

文档

narsil-mcp

为什么选择 narsil-mcp？

核心特性

为什么选择 narsil-mcp？

支持的语言

安装

通过包管理器（推荐）

一键安装脚本

从源码构建

功能构建

用法

基本用法

完整功能集

配置

快速入门

自动编辑器检测

预设

配置文件

环境变量

CLI 命令

可视化前端

神经语义搜索

类型推断

Forgemax 集成（实验性）

MCP 配置

Claude Code 插件

Ralph 自动化集成

操作手册与教程

WebAssembly（浏览器）用法

可用工具（90 个）

仓库与文件管理

符号搜索与导航

代码搜索

AST 感知分块

神经语义搜索（需要 --neural）

调用图分析（需要 --call-graph）

控制流分析

数据流分析

类型推断（Python/JavaScript/TypeScript）

导入/依赖图

安全分析 - 污点追踪

安全分析 - 规则引擎

供应链安全

Git 集成（需要 --git）

LSP 集成（需要 --lsp）

远程仓库支持（需要 --remote）

指标

SPARQL / 知识图谱（需要 --graph）

代码上下文图（CCG）（需要 --graph）

安全规则

架构

性能

解析吞吐量

搜索延迟

端到端索引

开发

故障排除

Tree-sitter 构建错误

神经搜索 API 错误

索引未找到文件

大型仓库的内存问题

图功能不工作

路线图

已完成

新增功能

v1.6.x（当前版本）

v1.5.x

v1.4.x

v1.2.x

v1.1.x

v1.0.x

许可证

致谢

神经语义搜索（需要 `--neural`）

调用图分析（需要 `--call-graph`）

Git 集成（需要 `--git`）

LSP 集成（需要 `--lsp`）

远程仓库支持（需要 `--remote`）

SPARQL / 知识图谱（需要 `--graph`）

代码上下文图（CCG）（需要 `--graph`）