金大哥 - narsil-mcp MCP 详情

article

README

🚀 narsil-mcp

narsil-mcp 是一款由 Rust 驱动的 MCP（模型上下文协议）服务器，它借助 76 种专业工具，为 AI 助手提供深入的代码理解能力，具有速度快、注重隐私等特点。

🚀 快速开始

narsil-mcp 是一款强大的 MCP 服务器。若要使用它，你可以按照以下步骤进行安装和配置：

依据你的操作系统和偏好选择合适的安装方法（具体安装步骤见下文“📦 安装指南”）。
安装完成后，通过命令行工具启动服务器，指定要索引的代码仓库路径（具体命令见下文“💻 使用示例”）。

✨ 主要特性

代码智能方面

符号提取：能够精准提取代码中的各类符号，如函数、结构体、枚举等。
语义搜索：借助先进的算法实现语义层面的代码搜索，让查找更高效。
调用图分析：深入分析代码中函数之间的调用关系，助力代码理解与优化。

搜索能力方面

神经语义搜索：利用嵌入技术（如 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 - 序列化