Narsil MCP

официальный

Невероятно быстрый 🔥 лучший в своем классе MCP-сервер на Rust 🦀 с нейронным движком, профилированием безопасности и опциональным графовым интерфейсом

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-сервер для глубокого анализа кода

MCP-сервер (Model Context Protocol) на Rust, предоставляющий ИИ-ассистентам глубокое понимание кода через 90 специализированных инструментов.

Почему narsil-mcp?

Возможность	narsil-mcp	XRAY	Serena	GitHub MCP
Языки	32	4	30+ (LSP)	Н/Д
Нейропоиск	Да	Нет	Нет	Нет
Анализ путей данных	Да	Нет	Нет	Нет
SBOM/Лицензии	Да	Нет	Нет	Частично
Офлайн/Локально	Да	Да	Да	Нет
WASM/Браузер	Да	Нет	Нет	Нет
Графы вызовов	Да	Частично	Нет	Нет
Вывод типов	Да	Нет	Нет	Нет

Ключевые возможности

Анализ кода — Извлечение символов, семантический поиск, анализ графа вызовов
Нейросемантический поиск — Поиск похожего кода с использованием эмбеддингов (Voyage AI, OpenAI)
Анализ безопасности — Анализ путей данных, сканирование уязвимостей, покрытие OWASP/CWE
Безопасность цепочки поставок — Генерация SBOM, аудит зависимостей, проверка лицензий
Продвинутый анализ — Графы потока управления, анализ потоков данных, обнаружение мёртвого кода

Почему стоит выбрать narsil-mcp?

Написан на Rust — Молниеносная скорость, безопасная работа с памятью, единый бинарный файл (~30 МБ)
На базе 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-сервер со всеми инструментами	~30 МБ
`graph`	+ Граф знаний RDF, SPARQL, инструменты CCG	~35 МБ
`frontend`	+ Встроенный веб-интерфейс визуализации	~31 МБ
`neural`	+ Векторный поиск TF-IDF, API эмбеддингов	~32 МБ
`neural-onnx`	+ Локальный вывод моделей ONNX	~50 МБ
`wasm`	Сборка для браузера (без файловой системы, git)	~3 МБ

Важно: Флаг CLI --graph требует, чтобы бинарный файл был собран с --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 и инструменты Code Context Graph (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 — Специфичный ключ API Voyage AI
OPENAI_API_KEY — Специфичный ключ API OpenAI
EMBEDDING_SERVER_ENDPOINT — URL пользовательской конечной точки API эмбеддингов (опционально, позволяет использовать собственные модели)

Конфигурация

Версия 1.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, force-directed, breadthfirst, concentric, circle, grid)
Боковая панель с деревом файлов и просмотрщиком кода с подсветкой синтаксиса
Состояние, управляемое через 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):

{
  "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 Automation

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>

Ralph корректно деградирует, когда narsil-mcp недоступен — все основные функции автоматизации работают без него.

Документация: См. 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');

Полная документация: См. docs/wasm.md для инструкций по сборке, примеров React и справки по API.

Доступные инструменты (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`	Найти семантические клоны функции типа 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`	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`	Выполнить запрос SPARQL к графу знаний RDF
`list_sparql_templates`	Список доступных шаблонов запросов SPARQL
`run_sparql_template`	Выполнить предопределённый шаблон SPARQL с параметрами

Граф контекста кода (CCG) (требуется `--graph`)

CCG предоставляет стандартизированные, пригодные для использования ИИ представления кодовых баз на многоуровневых слоях.

Инструмент	Описание
`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`	Запросить CCG с помощью SPARQL
`get_ccg_acl`	Сгенерировать контроль доступа WebACL для слоёв CCG
`get_ccg_access_info`	Получить информацию об уровне доступа CCG
`import_ccg`	Импортировать слой CCG из URL или файла
`import_ccg_from_registry`	Импортировать CCG из реестра codecontextgraph.com

Правила безопасности

narsil-mcp включает встроенные правила безопасности в rules/:

Основные наборы правил:

owasp-top10.yaml — Шаблоны уязвимостей OWASP Top 10 2021
cwe-top25.yaml — 25 самых опасных слабостей CWE
crypto.yaml — Криптографические проблемы (слабые алгоритмы, жёстко закодированные ключи)
secrets.yaml — Обнаружение секретов (API-ключи, пароли, токены) Правила для конкретных языков:
rust.yaml - Паттерны безопасности Rust (небезопасное преобразование transmute, границы FFI, инъекция команд, TOCTOU)
elixir.yaml - Паттерны Elixir/BEAM (исчерпание атомов, binary_to_term, Code.eval, SQL-инъекции Ecto)
go.yaml - Паттерны безопасности Go (SQL-инъекции, TLS, инъекция команд)
java.yaml - Уязвимости Java (XXE, десериализация, LDAP-инъекции)
csharp.yaml - Проблемы безопасности C# (десериализация, XSS, обход пути)
kotlin.yaml - Паттерны Kotlin/Android (WebView, намерения, секреты)
bash.yaml - Уязвимости скриптов оболочки (инъекция команд, 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 КБ	131 мкс	1,98 ГиБ/с
Rust (средний файл)	27 КБ	13,5 мкс	1,89 ГиБ/с
Python	~4 КБ	16,7 мкс	-
TypeScript	~5 КБ	13,9 мкс	-
Смешанный (5 файлов)	~15 КБ	57 мкс	-

Задержка поиска

Операция	Размер корпуса	Время
Точное совпадение символа	1 000 символов	483 нс
Совпадение по префиксу символа	1 000 символов	2,7 мкс
Нечёткое совпадение символа	1 000 символов	16,5 мкс
Полнотекстовый BM25	1 000 документов	80 мкс
Сходство TF-IDF	1 000 документов	130 мкс
Гибридный (BM25+TF-IDF)	1 000 документов	151 мкс

Сквозное индексирование

Репозиторий	Файлы	Символы	Время	Память
narsil-mcp (этот репозиторий)	53	1 733	220 мс	~50 МБ
rust-analyzer	2 847	~50K	2,1 с	89 МБ
ядро linux	78 000+	~500K	45 с	2,1 ГБ

Ключевые показатели:

Парсинг Tree-sitter: ~2 ГиБ/с устойчивой пропускной способности
Поиск символа: <1 мкс для точного совпадения
Полнотекстовый поиск: <1 мс для большинства запросов
Гибридный поиск выполняет BM25 + TF-IDF параллельно через rayon

Разработка

# 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 добавляет базу данных RDF Oxigraph (~5 МБ дополнительного размера двоичного файла), которая не нужна для большинства случаев использования. Она оставлена опциональной, чтобы сохранить двоичный файл по умолчанию меньше.

Как проверить, включён ли граф: Посмотрите на журналы запуска:

graph=true означает, что функция скомпилирована И включена
graph=false означает, что либо функция не скомпилирована, ЛИБО --graph не был передан

Дорожная карта

Завершено

Что нового

v1.6.x (Текущая)

Устойчивое к сбоям разбиение на чанки - Исправлена небезопасная нарезка строк на уровне байтов в chunk_file() и extract_signature(), которая вызывала сбои hybrid_search, search_chunks и get_chunk_stats при обработке файлов с многобайтовыми символами UTF-8 (эмодзи, CJK, символы с диакритикой). Вся нарезка байтов теперь использует безопасный content.get() с резервным вариантом.
Операции сортировки, безопасные для NaN - Исправлено 5 мест в модулях поиска, эмбеддингов, git, индекса и извлечения, где partial_cmp().unwrap() вызывал панику при значениях float NaN. Все сортировки теперь используют unwrap_or(Ordering::Equal).
Эшелонированная защита разбиения на чанки - Добавлены обёртки catch_unwind вокруг всех циклов chunk_file() в масштабе репозитория, чтобы паника в одном файле пропускала его, а не обрушивала весь сервер MCP.
Переработка фронтенда визуализации - Полноценное SPA с маршрутизацией HashRouter, боковой панелью дерева файлов, средством просмотра кода с подсветкой синтаксиса, панелью мониторинга и страницами обзора для каждого репозитория
Производительность просмотра графа - Граф импорта теперь использует кэшированные данные индекса вместо обхода файловой системы; граф символов итерирует файловый кэш напрямую вместо обходных путей через markdown; все представления учитывают max_nodes для досрочного завершения
Реальные графы потока управления - Представление потока теперь использует реальный построитель CFG (cfg::analyze_function) с правильными базовыми блоками, условиями ветвления и обратными рёбрами циклов вместо заглушки из одного блока
Разделение бюджета гибридного графа - Гибридное представление распределяет бюджет узлов 60/40 между графами вызовов и импорта для сбалансированных результатов
Исправление #14: настраиваемые размерности эмбеддингов - Добавлен аргумент CLI --neural-dimension и поиск default_dimension_for_model(), чтобы модели, такие как text-embedding-3-large, использовали правильные размерности (3072) вместо жёстко заданных 1536
Исправление #13: сборка фронтенда Nix - Добавлено порождение frontendDist в flake.nix с использованием buildNpmPackage, чтобы 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, SQL-инъекции Ecto, XSS Phoenix, безопасность распределённой Erlang
Миграция с serde_yaml на serde-saphyr - Устаревший serde_yaml заменён на активно поддерживаемую, свободную от паник библиотеку 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 - Запрос данных интеллектуального анализа кода с помощью SPARQL через Oxigraph
Граф контекста кода (CCG) - 12 инструментов для стандартизированных, пригодных для использования ИИ представлений кодовой базы с многоуровневыми слоями (L0-L3)
Анализ безопасности с учётом типов - Улучшенное отслеживание путей распространения данных с выводом типов и реализациями типажей
Многоязыковые CFG/DFG - Анализ потока управления и потока данных расширен на Go, Java, C#, Kotlin
Сканирование инфраструктуры как кода - Новые правила iac.yaml для Terraform, CloudFormation, Kubernetes
Правила безопасности для конкретных языков - Новые правила для Go, Java, C#, Kotlin, Bash
6 новых языков - Erlang, Elm, Fortran, PowerShell, Nix, Groovy
Всего 90 инструментов - Увеличено с 79 с новыми возможностями 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 License, Version 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 - Сериализация