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