Narsil MCP

narsil-mcp

Молниеносно быстрый, ориентированный на конфиденциальность MCP-сервер для глубокого анализа кода

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

Почему narsil-mcp?

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

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

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

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

• Написан на Rust — Молниеносно быстрый, безопасный по памяти, один бинарный файл (~30MB)
• На базе Tree-sitter — Точный инкрементальный парсинг для 32 языков
• Ноль конфигурации — Укажите репозитории и работайте
• Соответствие MCP — Работает с Claude, Cursor, VS Code Copilot, Zed и любым MCP-клиентом
• Конфиденциальность прежде всего — Полностью локально, данные не покидают вашу машину
• Параллельная индексация — Использует все ядра через Rayon
• Умные выдержки — Расширяется до полных синтаксических областей
• Безопасность прежде всего — Встроенное обнаружение уязвимостей и анализ потоков данных
• Нейронные эмбеддинги — Опциональный семантический поиск с Voyage AI или OpenAI
• Поддержка WASM — Запуск в браузере с помощью сборки WebAssembly
• Потоковая передача в реальном времени — Результаты по мере индексации для больших репозиториев

Поддерживаемые языки

Язык	Расширения	Извлекаемые символы
Rust	.rs	функции, структуры, перечисления, трейты, реализации, модули
Python	.py, .pyi	функции, классы
JavaScript	.js, .jsx, .mjs	функции, классы, методы, переменные
TypeScript	.ts, .tsx	функции, классы, интерфейсы, типы, перечисления
Go	.go	функции, методы, типы
C	.c, .h	функции, структуры, перечисления, typedef
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 Build Tools с компонентом "Разработка классических приложений на 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	+ Встроенный веб-интерфейс визуализации	~31MB
neural	+ TF-IDF векторный поиск, API эмбеддинги	~32MB
neural-onnx	+ Локальный вывод моделей ONNX	~50MB
wasm	Экспериментальная сборка для браузера (без файловой системы, git)	Не соответствует уровню релиза

Важно: Флаг 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 пользовательской конечной точки эмбеддингов (опционально, позволяет использовать самостоятельно размещённые модели)

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

Версия 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, 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 — шлюз MCP в режиме Code Mode, который сокращает все 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 в вашего ИИ-ассистента, создав файл конфигурации. Вот рекомендуемые настройки:

---

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 (браузер)

Репозиторий содержит экспериментальный исходный код WebAssembly и локальный скрипт сборки. @narsil-mcp/wasm не опубликован на npm и не является каналом распространения релиза CLI 1.7.1. Сборка 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_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 gzip)
export_ccg_full	Полная детализация слоя 3 (~1-20MB N-Quads gzip)
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 — CWE Top 25 самых опасных слабостей
• crypto.yaml — Криптографические проблемы (слабые алгоритмы, жестко заданные ключи)
• secrets.yaml — Обнаружение секретов (ключи API, пароли, токены) Правила для конкретных языков:
• rust.yaml — паттерны безопасности Rust (unsafe 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 — уязвимости 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 КБ	131 мкс	1,98 ГиБ/с
Rust (средний файл)	27 КБ	13,5 мкс	1,89 ГиБ/с
Python	~4 КБ	16,7 мкс	-
TypeScript	~5 КБ	13,9 мкс	-
Смешанный (5 файлов)	~15 КБ	57 мкс	-

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

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

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

Репозиторий	Файлы	Символы	Время	Память
narsil-mcp (этот репозиторий)	53	1733	220 мс	~50 МБ
rust-analyzer	2847	~50 тыс.	2,1 с	89 МБ
ядро linux	78 000+	~500 тыс.	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 не был передан

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

Завершено

• Извлечение символов на нескольких языках (32 языка)
• Полнотекстовый поиск с Tantivy (ранжирование BM25)
• Гибридный поиск (BM25 + TF-IDF с RRF)
• Чанкинг кода с учётом AST
• Интеграция Git blame/истории
• Анализ графа вызовов с метриками сложности
• Анализ графа потока управления (CFG)
• Анализ потока данных (DFG) с достигающими определениями
• Обнаружение мёртвого кода и мёртвых хранилищ
• Анализ заражения (taint) для уязвимостей внедрения
• Механизм правил безопасности (OWASP, CWE, криптография, секреты)
• Генерация SBOM (CycloneDX, SPDX)
• Проверка уязвимостей зависимостей (OSV)
• Анализ соответствия лицензиям
• Граф импортов с обнаружением циклических зависимостей
• Разрешение символов между языками
• Инкрементальное индексирование с деревьями Меркла
• Персистентность индекса
• Режим наблюдения за изменениями файлов
• Интеграция LSP
• Поддержка удалённых репозиториев
• Потоковые ответы

Что нового

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() вызывал панику при значениях 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)
• Количество тестов увеличено с 1611 до 1763 (+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 (LICENSE-MIT или http://opensource.org/licenses/MIT)

на ваш выбор.

Благодарности

Создано с помощью:

• tree-sitter — Инкрементальный парсинг
• tantivy — Полнотекстовый поиск
• tokio — Асинхронная среда выполнения
• rayon — Параллелизм данных
• serde — Сериализация