Narsil MCP

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 не был передан

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

Завершено

• Извлечение символов для нескольких языков (32 языка)
• Полнотекстовый поиск с Tantivy (ранжирование BM25)
• Гибридный поиск (BM25 + TF-IDF с RRF)
• Разбиение кода на чанки с учётом AST
• Интеграция Git blame/истории
• Анализ графа вызовов с метриками сложности
• Анализ графа потока управления (CFG)
• Анализ потока данных (DFG) с достигающими определениями
• Обнаружение мёртвого кода и мёртвых сохранений
• Анализ путей распространения данных для уязвимостей инъекций
• Движок правил безопасности (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() вызывал панику при значениях 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 - Сериализация