Narsil MCP

官方

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

GitHub
185

你可以用 Narsil MCP 做什么？

  • 探索代码库 — 让您的助手绘制不熟悉项目的结构图、查找符号，并使用 find_symbols 和 find_references 跨 32 种语言追踪引用。

  • 分析安全漏洞 — 请求污点分析、OWASP Top 10 扫描或 CWE 检查，以识别注入点并通过 scan_security 和 suggest_fix 获取修复建议。

  • 追踪函数关系 — 使用 get_call_graph 和 find_call_path 可视化调用图、查找调用者/被调用者，或定位函数之间的路径，以理解执行流程。

  • 审计供应链风险 — 使用 generate_sbom、check_dependencies 和 check_licenses 生成 SBOM、对照 OSV 检查依赖项，并验证许可证合规性。

  • 检测代码质量问题 — 使用 find_dead_code 和 check_type_errors 识别 Python、JavaScript 和 TypeScript 中的死代码、未初始化变量或类型不匹配。

文档

narsil-mcp

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

License Rust Tests MCP

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

为什么选择 narsil-mcp？

特性narsil-mcpXRAYSerenaGitHub MCP
语言支持32430+ (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 利用所有 CPU 核心
  • 智能摘录 - 自动扩展至完整语法作用域
  • 安全优先 - 内置漏洞检测和污点分析
  • 神经嵌入 - 可选使用 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（此版本已通过 Rust 1.98 和 1.99 验证）
  • Windows 上：Visual Studio 构建工具，需包含"使用 C++ 的桌面开发"工作负载
# 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

# Experimental browser/WASM source build (not release-qualified)
cargo build --release --target wasm32-unknown-unknown --no-default-features --features wasm
功能描述大小
native（默认）包含所有工具的完整 MCP 服务器约 30MB
graph+ RDF 知识图谱、SPARQL、CCG 工具约 35MB
frontend+ 嵌入式可视化 Web UI约 31MB
neural+ TF-IDF 向量搜索、API 嵌入约 32MB
neural-onnx+ 本地 ONNX 模型推理约 50MB
wasm实验性浏览器源码构建（无文件系统、git）未达到发布标准

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

完整文档： 请参阅 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 令牌减少到约 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 编写的 JavaScript 通过沙箱化 V8 隔离环境中的类型化代理对象进行调用——凭据、文件路径和内部状态永远不会离开宿主。这种方法在同时使用多个 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（浏览器）使用

该仓库包含实验性 WebAssembly 源码和本地构建脚本。 @narsil-mcp/wasm 未发布到 npm，也不是 1.7.1 CLI 版本的发布渠道。 WASM 构建和示例不在其发布资格范围内。实验性源码工作流程请参阅 docs/wasm.md。

可用工具（93 个）

仓库与文件管理

工具描述
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_searchBM25 + 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 gzip 压缩的 N-Quads）
export_ccg_full第 3 层完整详情（约 1-20MB gzip 压缩的 N-Quads）
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 安全模式（unsafe transmute、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、intents、secrets）
  • 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 浮点值上会 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 库取代
  • 自定义 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）
  • 类型感知安全分析 - 增强的污点跟踪，具有类型推断和 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 模板

许可证

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

由您选择。

致谢

使用以下工具构建：