Narsil MCP

narsil-mcp

Le serveur MCP ultra-rapide et respectueux de la vie privée pour une intelligence du code approfondie

Un serveur MCP (Model Context Protocol) développé en Rust, offrant aux assistants IA une compréhension approfondie du code via 90 outils spécialisés.

Pourquoi narsil-mcp ?

Fonctionnalité	narsil-mcp	XRAY	Serena	GitHub MCP
Langages	32	4	30+ (LSP)	N/A
Recherche neuronale	Oui	Non	Non	Non
Analyse de contamination	Oui	Non	Non	Non
SBOM/Licences	Oui	Non	Non	Partiel
Hors ligne/Local	Oui	Oui	Oui	Non
WASM/Navigateur	Oui	Non	Non	Non
Graphes d'appel	Oui	Partiel	Non	Non
Inférence de types	Oui	Non	Non	Non

Fonctionnalités clés

• Intelligence du code - Extraction de symboles, recherche sémantique, analyse de graphe d'appel
• Recherche sémantique neuronale - Trouver du code similaire en utilisant des embeddings (Voyage AI, OpenAI)
• Analyse de sécurité - Analyse de contamination, scan de vulnérabilités, couverture OWASP/CWE
• Sécurité de la chaîne d'approvisionnement - Génération de SBOM, audit des dépendances, conformité des licences
• Analyse avancée - Graphes de flux de contrôle, analyse de flux de données, détection de code mort

Pourquoi choisir narsil-mcp ?

• Écrit en Rust - Extrêmement rapide, sûr en mémoire, binaire unique (~30 Mo)
• Propulsé par Tree-sitter - Analyse précise et incrémentale pour 32 langages
• Zéro configuration - Pointez vers des dépôts et c'est parti
• Conforme MCP - Fonctionne avec Claude, Cursor, VS Code Copilot, Zed et tout client MCP
• Respect de la vie privée - Entièrement local, aucune donnée ne quitte votre machine
• Indexation parallèle - Utilise tous les cœurs via Rayon
• Extraits intelligents - S'étend aux portées syntaxiques complètes
• Sécurité d'abord - Détection intégrée des vulnérabilités et analyse de contamination
• Embeddings neuronaux - Recherche sémantique optionnelle avec Voyage AI ou OpenAI
• Support WASM - Fonctionne dans le navigateur avec une version WebAssembly
• Streaming en temps réel - Résultats au fur et à mesure de l'indexation pour les grands dépôts

Langages supportés

Langage	Extensions	Symboles extraits
Rust	.rs	fonctions, structs, enums, traits, impls, mods
Python	.py, .pyi	fonctions, classes
JavaScript	.js, .jsx, .mjs	fonctions, classes, méthodes, variables
TypeScript	.ts, .tsx	fonctions, classes, interfaces, types, enums
Go	.go	fonctions, méthodes, types
C	.c, .h	fonctions, structs, enums, typedefs
C++	.cpp, .cc, .hpp	fonctions, classes, structs, espaces de noms
Java	.java	méthodes, classes, interfaces, enums
C#	.cs	méthodes, classes, interfaces, structs, enums, délégués, espaces de noms
Bash	.sh, .bash, .zsh	fonctions, variables
Ruby	.rb, .rake, .gemspec	méthodes, classes, modules
Kotlin	.kt, .kts	fonctions, classes, objets, interfaces
PHP	.php, .phtml	fonctions, méthodes, classes, interfaces, traits
Swift	.swift	classes, structs, enums, protocoles, fonctions
Verilog/SystemVerilog	.v, .vh, .sv, .svh	modules, tâches, fonctions, interfaces, classes
Scala	.scala, .sc	classes, objets, traits, fonctions, vals
Lua	.lua	fonctions, méthodes
Haskell	.hs, .lhs	fonctions, types de données, classes de types
Elixir	.ex, .exs	modules, fonctions
Clojure	.clj, .cljs, .cljc, .edn	listes (AST de base)
Dart	.dart	fonctions, classes, méthodes
Julia	.jl	fonctions, modules, structs
R	.R, .r, .Rmd	fonctions
Perl	.pl, .pm, .t	fonctions, paquets
Zig	.zig	fonctions, variables
Erlang	.erl, .hrl	fonctions, modules, enregistrements
Elm	.elm	fonctions, types
Fortran	.f90, .f95, .f03, .f08, .f, .for, .fpp	programmes, sous-routines, fonctions, modules
PowerShell	.ps1, .psm1, .psd1	fonctions, classes, enums
Nix	.nix	liaisons
Groovy	.groovy, .gradle	méthodes, classes, interfaces, enums, fonctions

Installation

Via les gestionnaires de paquets (recommandé)

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 (toutes plateformes) :

cargo install narsil-mcp

Node.js/npm (toutes plateformes) :

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

Script d'installation en un clic

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

Note pour les utilisateurs Windows : L'installateur PowerShell fournit de meilleurs messages d'erreur et une intégration native à Windows. Il configurera automatiquement votre PATH et vérifiera les outils de construction requis si vous compilez depuis les sources.

Depuis les sources

Prérequis :

• Rust 1.70 ou ultérieur
• Sur Windows : Visual Studio Build Tools avec « Développement Desktop en 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

Versions avec fonctionnalités

narsil-mcp prend en charge différents ensembles de fonctionnalités pour différents cas d'usage :

# 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

Fonctionnalité	Description	Taille
native (défaut)	Serveur MCP complet avec tous les outils	~30 Mo
graph	+ Graphe de connaissances RDF, SPARQL, outils CCG	~35 Mo
frontend	+ Interface web de visualisation embarquée	~31 Mo
neural	+ Recherche vectorielle TF-IDF, embeddings API	~32 Mo
neural-onnx	+ Inférence de modèle ONNX local	~50 Mo
wasm	Version navigateur (pas de système de fichiers, git)	~3 Mo

Important : Le drapeau CLI --graph nécessite que le binaire soit compilé avec --features graph. Si vous passez --graph à un binaire compilé sans cette fonctionnalité, vous verrez un avertissement et les outils SPARQL/CCG ne seront pas disponibles. Voir Dépannage ci-dessous.

Pour des instructions d'installation détaillées, le dépannage et des guides spécifiques à la plateforme, voir docs/INSTALL.md.

Utilisation

Utilisation de base

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

Ensemble complet de fonctionnalités

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)

Note à propos de --graph : Ce drapeau active les requêtes SPARQL et les outils Code Context Graph (CCG), mais uniquement si le binaire a été compilé avec --features graph. Le binaire par défaut n'inclut pas cette fonctionnalité. Si vous avez besoin des capacités SPARQL/CCG, compilez depuis les sources avec :

cargo build --release --features graph

Si vous passez --graph à un binaire sans la fonctionnalité, vous verrez un avertissement au démarrage et le serveur continuera sans les outils SPARQL/CCG.

Note : Les embeddings neuronaux nécessitent une clé API (ou un point de terminaison personnalisé). Le moyen le plus simple de configurer ceci est d'utiliser l'assistant interactif :

# Run the neural API key setup wizard
narsil-mcp config init --neural

L'assistant va :

• Détecter votre éditeur (Claude Desktop, Claude Code, Zed, VS Code, JetBrains)
• Demander votre fournisseur d'API (Voyage AI, OpenAI, ou personnalisé)
• Valider votre clé API
• L'ajouter automatiquement à la configuration MCP de votre éditeur

Alternativement, vous pouvez définir manuellement l'une de ces variables d'environnement :

• EMBEDDING_API_KEY - Clé API générique pour tout fournisseur
• VOYAGE_API_KEY - Clé API spécifique à Voyage AI
• OPENAI_API_KEY - Clé API spécifique à OpenAI
• EMBEDDING_SERVER_ENDPOINT - URL de point de terminaison d'API d'embedding personnalisé (optionnel, permet d'utiliser des modèles auto-hébergés)

Configuration

La v1.1.0+ introduit une configuration optionnelle pour un contrôle fin des outils et des performances. Toute utilisation existante continue de fonctionner - la configuration est complètement optionnelle !

Démarrage rapide

# 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

Détection automatique de l'éditeur

narsil-mcp détecte votre éditeur et applique automatiquement un préréglage optimal :

Éditeur	Préréglage	Outils	Jetons de contexte	Pourquoi
Zed	Minimal	26	~4 686	Démarrage rapide, contexte minimal
VS Code	Équilibré	51	~8 948	Bon équilibre des fonctionnalités
Claude Desktop	Complet	90	~12 001	Capacités maximales

Économies de jetons :

• Préréglage minimal : 61 % de jetons en moins par rapport à Complet
• Préréglage équilibré : 25 % de jetons en moins par rapport à Complet

Préréglages

Choisissez un préréglage selon votre cas d'usage :

# 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

Fichiers de configuration

Configuration utilisateur (~/.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

Configuration projet (.narsil.yaml à la racine du dépôt) :

version: "1.0"
preset: "security-focused"  # Override user preset

tools:
  categories:
    Security:
      enabled: true
    SupplyChain:
      enabled: true

Les profils de dépôt nommés sont utiles pour les espaces de travail multi-dépôts :

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

Priorité : Drapeaux CLI > Variables d'env > Configuration projet > Configuration utilisateur > Défauts

Variables d'environnement

# 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

Commandes 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

En savoir plus :

• Guide de configuration - Référence complète de configuration
• Guide d'installation - Installation spécifique à la plateforme

Interface de visualisation

Explorez les graphes d'appel, les imports, les références de symboles et le flux de contrôle de manière interactive dans votre navigateur.

# Build with embedded frontend
cargo build --release --features frontend

# Run with HTTP server
narsil-mcp --repos ~/project --http --call-graph
# Open http://localhost:3000

Cinq vues de graphe :

Vue	Description
Graphe d'appel	Relations d'appel de fonctions avec contrôle de profondeur et filtrage de direction
Graphe d'import	Dépendances d'import au niveau des fichiers à travers la base de code
Graphe de symboles	Toutes les références à un symbole, avec regroupement par fichier
Hybride	Graphe combiné appel + import avec budget partagé
Flux de contrôle	CFG réel avec blocs de base, branches et arêtes de retour de boucle

Fonctionnalités :

• Graphes interactifs Cytoscape.js avec glisser, zoom et double-clic pour explorer
• Superposition de métriques de complexité avec code couleur (vert/jaune/orange/rouge)
• Superposition de vulnérabilités de sécurité mettant en évidence les sources et puits de contamination
• Six algorithmes de disposition (dagre, dirigé par la force, largeur d'abord, concentrique, cercle, grille)
• Barre latérale d'arborescence de fichiers avec visualiseur de code coloré syntaxiquement
• État piloté par URL (liens partageables, navigation avant/arrière du navigateur)
• Support du mode sombre
• Panneau de détails des nœuds avec extraits de code et navigation vers la source

Documentation complète : Voir docs/frontend.md pour la configuration, les points de terminaison API et le mode développement.

Recherche sémantique neuronale

Trouvez du code similaire en utilisant des embeddings neuronaux - même lorsque les noms de variables et la structure diffèrent.

# 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

Prend en charge Voyage AI, OpenAI, les points de terminaison personnalisés et les modèles ONNX locaux.

Documentation complète : Voir docs/neural-search.md pour la configuration, les backends et les cas d'usage.

Inférence de types

Inférence de types intégrée pour Python, JavaScript et TypeScript - pas besoin de mypy ou tsc.

Outil	Description
infer_types	Obtenir les types inférés pour toutes les variables d'une fonction
check_type_errors	Trouver les incompatibilités de type potentielles
get_typed_taint_flow	Analyse de sécurité améliorée avec informations de type

def process(data):
    result = data.split(",")  # result: list[str]
    count = len(result)       # count: int
    return count * 2          # returns: int

Intégration Forgemax (Expérimentale)

Pour les flux de travail agentiques à grande échelle, narsil-mcp peut être utilisé via Forgemax — une passerelle MCP en mode Code qui réduit les 90 outils à seulement 2 (search + execute), réduisant la surcharge du schéma d'outils d'environ 12 000 jetons à environ 1 000.

# Install Forgemax
cargo install forgemax

# Run narsil-mcp through Forgemax (uses forge.toml in repo root)
forgemax

Le forge.toml inclus configure narsil-mcp avec des valeurs par défaut sensées :

[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

Le LLM écrit du JavaScript qui appelle via des objets proxy typés à l'intérieur d'un isolat V8 sandboxé — les identifiants, les chemins de fichiers et l'état interne ne quittent jamais l'hôte. Cette approche est particulièrement utile lorsqu'on travaille avec plusieurs serveurs MCP simultanément, car elle maintient le contexte total des outils petit et prévisible.

Configuration MCP

Ajoutez narsil-mcp à votre assistant IA en créant un fichier de configuration. Voici les configurations recommandées :

---

Claude Code (.mcp.json à la racine du projet - Recommandé) :

Créez .mcp.json dans le répertoire de votre projet pour une configuration par projet :

{
  "mcpServers": {
    "narsil-mcp": {
      "command": "narsil-mcp",
      "args": ["--repos", ".", "--git", "--call-graph"]
    }
  }
}

Puis démarrez Claude Code dans votre projet :

cd /path/to/project
claude

Utiliser . pour --repos indexe automatiquement le répertoire courant. Claude a maintenant accès à 90 outils d'intelligence du code.

Astuce : Ajoutez --persist --index-path .claude/cache pour un démarrage plus rapide lors des exécutions suivantes.

Pour une configuration globale, éditez plutôt ~/.claude/settings.json. Voir Intégration Claude Code pour les configurations avancées.

---

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"]
    }
  }
}

Note pour Copilot Enterprise : Le support MCP nécessite VS Code 1.102+ et doit être activé par votre administrateur d'organisation.

---

Claude Desktop (claude_desktop_config.json) :

{
  "mcpServers": {
    "narsil-mcp": {
      "command": "narsil-mcp",
      "args": ["--repos", "/path/to/your/projects", "--git"]
    }
  }
}

---

Zed (settings.json → Serveurs de contexte) :

{
  "context_servers": {
    "narsil-mcp": {
      "command": "narsil-mcp",
      "args": ["--repos", ".", "--git"]
    }
  }
}

Note pour Zed : narsil-mcp démarre immédiatement et indexe en arrière-plan, évitant les délais d'initialisation.

---

Plugin Claude Code

Pour les utilisateurs de Claude Code, nous fournissons un plugin avec des commandes slash et une compétence pour une utilisation efficace des outils.

Installer via Marketplace (Recommandé) :

# Add the narsil-mcp marketplace
/plugin marketplace add postrv/narsil-mcp

# Install the plugin
/plugin install narsil@narsil-mcp

Ou installer directement depuis GitHub :

/plugin install github:postrv/narsil-mcp/narsil-plugin

Ce qui est inclus :

Composant	Description
/narsil:security-scan	Exécuter des audits de sécurité complets
/narsil:explore	Explorer des bases de code inconnues
/narsil:analyze-function	Plongée approfondie sur des fonctions spécifiques
/narsil:find-feature	Trouver où les fonctionnalités sont implémentées
/narsil:supply-chain	Analyser la sécurité de la chaîne d'approvisionnement
Compétence	Guide Claude sur l'utilisation efficace des 90 outils
Configuration MCP	Démarre automatiquement narsil-mcp avec des valeurs par défaut sensées

Voir narsil-plugin/README.md pour la documentation complète.

Intégration Ralph Automation

Ralph est une suite d'automatisation Claude Code pour le développement de code autonome. Lorsque narsil-mcp est disponible, Ralph bénéficie de capacités d'intelligence du code améliorées :

Fonctionnalité	Sans narsil-mcp	Avec narsil-mcp
Scan de sécurité	Basique (clippy)	Détection de vulnérabilités OWASP/CWE
Compréhension du code	Basée sur les fichiers	Graphes d'appel, références de symboles
Analyse d'architecture	Manuelle	Couches automatiques CCG L0/L1/L2
Analyse des dépendances	cargo tree	Graphes d'import, détection circulaire

Configuration :

# 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 se dégrade gracieusement lorsque narsil-mcp est indisponible - toutes les fonctionnalités d'automatisation de base fonctionnent sans lui.

Documentation : Voir Ralph README pour les détails complets d'intégration.

Playbooks & Tutoriels

Voir docs/playbooks pour des guides d'utilisation pratiques :

Guide	Description
Premiers pas	Configuration rapide et premiers appels d'outils
Comprendre une base de code	Explorer des projets inconnus
Corriger un bug	Déboguer avec des graphes d'appel et l'analyse de contamination
Audit de sécurité	Trouver des vulnérabilités avec le scan OWASP/CWE
Revue de code	Réviser les changements efficacement

Chaque playbook montre les chaînes d'outils exactes que Claude utilise pour répondre à vos questions.

Utilisation WebAssembly (Navigateur)

narsil-mcp peut fonctionner entièrement dans le navigateur via WebAssembly - parfait pour les IDE basés navigateur, les outils de revue de code ou les plateformes éducatives.

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');

Documentation complète : Voir docs/wasm.md pour les instructions de construction, les exemples React et la référence API.

Outils disponibles (90)

Gestion des dépôts et fichiers

Outil	Description
list_repos	Lister tous les dépôts indexés avec métadonnées
get_project_structure	Obtenir l'arborescence des répertoires avec icônes de fichiers et tailles
get_file	Obtenir le contenu d'un fichier avec plage de lignes optionnelle
get_excerpt	Extraire le code autour de lignes spécifiques avec contexte
reindex	Déclencher la réindexation des dépôts
discover_repos	Découvrir automatiquement les dépôts dans un répertoire
validate_repo	Vérifier si un chemin est un dépôt valide
get_index_status	Afficher les statistiques d'index et les fonctionnalités activées

Recherche et navigation de symboles

Outil	Description
find_symbols	Trouver des structs, classes, fonctions par type/motif
get_symbol_definition	Obtenir la source d'un symbole avec le contexte environnant
find_references	Trouver toutes les références à un symbole
get_dependencies	Analyser les imports et les dépendants
workspace_symbol_search	Recherche floue de symboles dans l'espace de travail
find_symbol_usages	Utilisation de symboles inter-fichiers avec imports
get_export_map	Obtenir les symboles exportés d'un fichier/module

Recherche de code

Outil	Description
search_code	Recherche par mot-clé avec classement par pertinence
semantic_search	Recherche sémantique classée BM25
hybrid_search	BM25 + TF-IDF combinés avec fusion de classement
search_chunks	Recherche sur des fragments de code conscients de l'AST
find_similar_code	Trouver du code similaire à un extrait (TF-IDF)
find_similar_to_symbol	Trouver du code similaire à un symbole

Fragmentation consciente de l'AST

Outil	Description
get_chunks	Obtenir des fragments conscients de l'AST pour un fichier
get_chunk_stats	Statistiques sur les fragments de code
get_embedding_stats	Statistiques de l'index d'embeddings

Recherche sémantique neuronale (nécessite --neural)

Outil	Description
neural_search	Recherche sémantique utilisant des embeddings neuronaux (trouve du code similaire même avec des noms différents)
find_semantic_clones	Trouver des clones sémantiques de Type-3/4 d'une fonction
get_neural_stats	Statistiques de l'index d'embeddings neuronaux

Analyse de graphe d'appel (nécessite --call-graph)

Outil	Description
get_call_graph	Obtenir le graphe d'appel pour un dépôt/fonction
get_callers	Trouver les fonctions qui appellent une fonction
get_callees	Trouver les fonctions appelées par une fonction
find_call_path	Trouver le chemin entre deux fonctions
get_complexity	Obtenir la complexité cyclomatique/cognitive
get_function_hotspots	Trouver les fonctions fortement connectées

Analyse de flux de contrôle

Outil	Description
get_control_flow	Obtenir le CFG montrant les blocs de base et les branches
find_dead_code	Trouver les blocs de code inaccessibles

Analyse de flux de données

Outil	Description
get_data_flow	Définitions et utilisations des variables
get_reaching_definitions	Quelles affectations atteignent chaque point
find_uninitialized	Variables utilisées avant initialisation
find_dead_stores	Affectations qui ne sont jamais lues

Inférence de types (Python/JavaScript/TypeScript)

Outil	Description
infer_types	Inférer les types des variables dans une fonction sans vérificateurs de types externes
check_type_errors	Trouver les erreurs de type potentielles sans exécuter mypy/tsc
get_typed_taint_flow	Analyse de contamination améliorée combinant flux de données et inférence de types

Graphe d'import/dépendances

Outil	Description
get_import_graph	Construire et analyser le graphe d'import
find_circular_imports	Détecter les dépendances circulaires
get_incremental_status	Arbre de Merkle et statistiques de changement

Analyse de sécurité - Suivi de contamination

Outil	Description
find_injection_vulnerabilities	Trouver les injections SQL, XSS, injection de commandes, traversée de chemin
trace_taint	Tracer le flux de données contaminées depuis une source
get_taint_sources	Lister les sources de contamination (entrée utilisateur, fichiers, réseau)
get_security_summary	Évaluation complète des risques de sécurité

Analyse de sécurité - Moteur de règles

Outil	Description
scan_security	Scanner avec des règles de sécurité (OWASP, CWE, crypto, secrets)
check_owasp_top10	Scanner les vulnérabilités OWASP Top 10 2021
check_cwe_top25	Scanner les faiblesses CWE Top 25
explain_vulnerability	Obtenir une explication détaillée de la vulnérabilité
suggest_fix	Obtenir des suggestions de remédiation pour les résultats

Sécurité de la chaîne d'approvisionnement

Outil	Description
generate_sbom	Générer un SBOM (CycloneDX/SPDX/JSON)
check_dependencies	Vérifier les vulnérabilités connues (base de données OSV)
check_licenses	Analyser les licences pour les problèmes de conformité
find_upgrade_path	Trouver des chemins de mise à niveau sûrs pour les dépendances vulnérables

Intégration Git (nécessite --git)

Outil	Description
get_blame	Git blame pour un fichier
get_file_history	Historique des commits pour un fichier
get_recent_changes	Commits récents dans le dépôt
get_hotspots	Fichiers avec fort taux de changement et complexité
get_contributors	Contributeurs du dépôt/fichier
get_commit_diff	Diff pour un commit spécifique
get_symbol_history	Commits qui ont changé un symbole
get_branch_info	Branche courante et statut
get_modified_files	Changements dans la copie de travail

Intégration LSP (nécessite --lsp)

Outil	Description
get_hover_info	Informations de type et documentation
get_type_info	Informations de type précises
go_to_definition	Trouver l'emplacement de la définition

Support des dépôts distants (nécessite --remote)

Outil	Description
add_remote_repo	Cloner et indexer un dépôt GitHub
list_remote_files	Lister les fichiers via l'API GitHub
get_remote_file	Récupérer un fichier via l'API GitHub

Métriques

Outil	Description
get_metrics	Statistiques de performance et chronométrage

SPARQL / Graphe de connaissances (nécessite --graph)

Outil	Description
sparql_query	Exécuter une requête SPARQL sur le graphe de connaissances RDF
list_sparql_templates	Lister les modèles de requêtes SPARQL disponibles
run_sparql_template	Exécuter un modèle SPARQL prédéfini avec des paramètres

Code Context Graph (CCG) (nécessite --graph)

CCG fournit des représentations standardisées et consommables par l'IA des bases de code en couches hiérarchisées.

Outil	Description
get_ccg_manifest	Manifeste de couche 0 (~1-2 Ko JSON-LD) - identité du dépôt, comptages
export_ccg_manifest	Exporter le manifeste de couche 0 vers un fichier
export_ccg_architecture	Architecture de couche 1 (~10-50 Ko JSON-LD) - modules, API
export_ccg_index	Index des symboles de couche 2 (~100-500 Ko N-Quads gzippé)
export_ccg_full	Détail complet de couche 3 (~1-20 Mo N-Quads gzippé)
export_ccg	Exporter toutes les couches CCG en un lot
query_ccg	Interroger le CCG en utilisant SPARQL
get_ccg_acl	Générer un contrôle d'accès WebACL pour les couches CCG
get_ccg_access_info	Obtenir les informations de niveau d'accès CCG
import_ccg	Importer une couche CCG depuis une URL ou un fichier
import_ccg_from_registry	Importer un CCG depuis le registre codecontextgraph.com

Règles de sécurité

narsil-mcp inclut des règles de sécurité intégrées dans rules/ :

Ensembles de règles de base :

• owasp-top10.yaml - Modèles de vulnérabilités OWASP Top 10 2021
• cwe-top25.yaml - Faiblesses les plus dangereuses CWE Top 25
• crypto.yaml - Problèmes cryptographiques (algorithmes faibles, clés codées en dur)
• secrets.yaml - Détection de secrets (clés API, mots de passe, jetons)

Règles spécifiques au langage :

• rust.yaml - Modèles de sécurité Rust (transmute unsafe, frontières FFI, injection de commandes, TOCTOU)
• elixir.yaml - Modèles Elixir/BEAM (épuisement d'atomes, binary_to_term, Code.eval, injection SQL Ecto)
• go.yaml - Modèles de sécurité Go (injection SQL, TLS, injection de commandes)
• java.yaml - Vulnérabilités Java (XXE, désérialisation, injection LDAP)
• csharp.yaml - Problèmes de sécurité C# (désérialisation, XSS, traversée de chemin)
• kotlin.yaml - Modèles Kotlin/Android (WebView, intents, secrets)
• bash.yaml - Vulnérabilités des scripts shell (injection de commandes, eval)

Infrastructure & Configuration :

• iac.yaml - Infrastructure as Code (Terraform, CloudFormation, Kubernetes)
• config.yaml - Sécurité des fichiers de configuration (identifiants codés en dur, paramètres non sécurisés)

Des règles personnalisées peuvent être chargées avec scan_security --ruleset /path/to/rules.yaml.

Architecture

+-----------------------------------------------------------------+
|                         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)             |  |
|  +-----------------------------------------------------------+  |
+-----------------------------------------------------------------+

Performance

Benchmarké sur Apple M1 (criterion.rs) :

Débit d'analyse

Langage	Taille d'entrée	Temps	Débit
Rust (grand fichier)	278 Ko	131 µs	1,98 Gio/s
Rust (fichier moyen)	27 Ko	13,5 µs	1,89 Gio/s
Python	~4 Ko	16,7 µs	-
TypeScript	~5 Ko	13,9 µs	-
Mixte (5 fichiers)	~15 Ko	57 µs	-

Latence de recherche

Opération	Taille du corpus	Temps
Correspondance exacte de symbole	1 000 symboles	483 ns
Correspondance par préfixe de symbole	1 000 symboles	2,7 µs
Correspondance floue de symbole	1 000 symboles	16,5 µs
Texte intégral BM25	1 000 docs	80 µs
Similarité TF-IDF	1 000 docs	130 µs
Hybride (BM25+TF-IDF)	1 000 docs	151 µs

Indexation de bout en bout

Dépôt	Fichiers	Symboles	Temps	Mémoire
narsil-mcp (ce dépôt)	53	1 733	220 ms	~50 Mo
rust-analyzer	2 847	~50K	2,1s	89 Mo
noyau linux	78 000+	~500K	45s	2,1 Go

Métriques clés :

• Analyse Tree-sitter : débit soutenu ~2 Gio/s
• Recherche de symbole : <1µs pour une correspondance exacte
• Recherche plein texte : <1ms pour la plupart des requêtes
• La recherche hybride exécute BM25 + TF-IDF en parallèle via rayon

Développement

# 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

Dépannage

Erreurs de construction Tree-sitter

Si vous voyez des erreurs concernant des compilateurs C manquants ou tree-sitter pendant la construction :

# macOS
xcode-select --install

# Ubuntu/Debian
sudo apt install build-essential

# For WASM builds
brew install emscripten  # macOS

Erreurs d'API de recherche neuronale

# 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-"

L'index ne trouve pas les fichiers

# Check .gitignore isn't excluding files
narsil-mcp --repos /path --verbose  # Shows skipped files

# Force reindex
narsil-mcp --repos /path --reindex

Problèmes de mémoire avec les grands dépôts

# 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

La fonctionnalité Graph ne fonctionne pas

Si vous passez --graph et voyez un avertissement comme :

WARN: --graph flag was passed but the binary was built without the 'graph' feature.
SPARQL and CCG tools will not be available.

Cela signifie que vous utilisez un binaire qui n'a pas été compilé avec la fonctionnalité graph. Pour corriger :

# 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

Pourquoi est-ce une fonctionnalité séparée ? La fonctionnalité graph ajoute la base de données RDF Oxigraph (~5 Mo de taille de binaire supplémentaire) qui n'est pas nécessaire pour la plupart des cas d'usage. Elle est gardée optionnelle pour maintenir le binaire par défaut plus petit.

Comment vérifier si graph est activé : Regardez les journaux de démarrage :

• graph=true signifie que la fonctionnalité est compilée ET activée
• graph=false signifie soit que la fonctionnalité n'est pas compilée, SOIT que --graph n'a pas été passé

Feuille de route

Terminé

• Extraction de symboles multi-langages (32 langages)
• Recherche plein texte avec Tantivy (classement BM25)
• Recherche hybride (BM25 + TF-IDF avec RRF)
• Fragmentation de code consciente de l'AST
• Intégration Git blame/historique
• Analyse de graphe d'appel avec métriques de complexité
• Analyse de graphe de flux de contrôle (CFG)
• Analyse de flux de données (DFG) avec définitions atteignantes
• Détection de code mort et de stockage mort
• Analyse de contamination pour les vulnérabilités d'injection
• Moteur de règles de sécurité (OWASP, CWE, crypto, secrets)
• Génération de SBOM (CycloneDX, SPDX)
• Vérification des vulnérabilités des dépendances (OSV)
• Analyse de conformité des licences
• Graphe d'import avec détection de dépendances circulaires
• Résolution de symboles inter-langages
• Indexation incrémentale avec arbres de Merkle
• Persistance de l'index
• Mode surveillance pour les changements de fichiers
• Intégration LSP
• Support des dépôts distants
• Réponses en streaming

Quoi de neuf

v1.6.x (Actuelle)

• Fragmentation à l'épreuve des crashs - Correction du découpage de chaînes au niveau des octets non sécurisé dans chunk_file() et extract_signature() qui causait le crash de hybrid_search, search_chunks et get_chunk_stats lors du traitement de fichiers avec des caractères UTF-8 multi-octets (emoji, CJK, caractères accentués). Tout le découpage d'octets utilise maintenant content.get() sécurisé avec solution de repli.
• Opérations de tri protégées contre NaN - Correction de 5 emplacements dans les modules de recherche, embeddings, git, index et extraction où partial_cmp().unwrap() paniquait sur des valeurs float NaN. Tous les tris utilisent maintenant unwrap_or(Ordering::Equal).
• Fragmentation avec défense en profondeur - Ajout d'enveloppeurs catch_unwind autour de toutes les boucles chunk_file() à l'échelle du dépôt pour qu'une panique dans un fichier le saute au lieu de planter tout le serveur MCP.
• Refonte de l'interface de visualisation - SPA complète avec routage HashRouter, barre latérale d'arborescence de fichiers, visualiseur de code coloré syntaxiquement, tableau de bord et pages de vue par dépôt
• Performance des vues de graphe - Le graphe d'import utilise maintenant les données d'index en cache au lieu de parcourir le système de fichiers ; le graphe de symboles itère directement le cache de fichiers au lieu de faire des allers-retours markdown ; toutes les vues respectent max_nodes pour une terminaison précoce
• Graphes de flux de contrôle réels - La vue de flux utilise maintenant le véritable constructeur CFG (cfg::analyze_function) avec des blocs de base appropriés, des conditions de branche et des arêtes de retour de boucle au lieu du stub à bloc unique
• Partage du budget du graphe hybride - La vue hybride alloue un budget de nœuds 60/40 entre les graphes d'appel et d'import pour des résultats équilibrés
• Correction #14 : dimensions d'embedding configurables - Ajout de l'argument CLI --neural-dimension et de la recherche default_dimension_for_model() pour que les modèles comme text-embedding-3-large utilisent les dimensions correctes (3072) au lieu de 1536 codé en dur
• Correction #13 : construction du frontend Nix - Ajout de la dérivation frontendDist dans flake.nix utilisant buildNpmPackage pour que nix profile install github:postrv/narsil-mcp#with-frontend fonctionne
• Règles de sécurité Rust - 18 nouvelles règles (RUST-004 à RUST-021) couvrant l'injection de commandes, transmute, frontières FFI, TOCTOU, ReDoS, static mut, SSRF, et plus
• Règles de sécurité Elixir - 18 nouvelles règles (EX-001 à EX-018) couvrant l'épuisement d'atomes, la désérialisation binary_to_term, l'injection Code.eval, l'injection SQL Ecto, XSS Phoenix, la sécurité de distribution Erlang
• Migration de serde_yaml vers serde-saphyr - serde_yaml obsolète remplacé par une bibliothèque YAML activement maintenue et sans panique
• Favicon personnalisé - Le frontend utilise maintenant l'icône de marque narsil-mcp au lieu du logo Vite par défaut
• Sécurité des dépendances - Mise à jour de time vers 0.3.47 (RUSTSEC-2026-0009), bytes vers 1.11.1 (RUSTSEC-2026-0007)
• Nombre de tests augmenté de 1 611 à 1 763 (+152 tests)

v1.5.x

• Résolution déterministe du graphe d'appel - La propagation d'indices de portée désambiguïse la résolution de l'appelé (par ex., App::run() se résout correctement en src/app/mod.rs::run)
• 8 corrections d'analyse de graphe - Clés de nœuds qualifiées, filtrage des points chauds, gestion des expressions CFG, analyse des chemins d'import
• Améliorations du flake Nix - Assistant mkPkg DRY, suppression des frameworks macOS inutiles, stratégie de test --lib pour les constructions sandbox

v1.4.x

• SPARQL / Graphe de connaissances RDF - Interroger les données d'intelligence du code avec SPARQL via Oxigraph
• Code Context Graph (CCG) - 12 outils pour des représentations de base de code standardisées et consommables par l'IA avec des couches hiérarchisées (L0-L3)
• Analyse de sécurité sensible aux types - Suivi de contamination amélioré avec inférence de types et implémentations de traits
• CFG/DFG multi-langages - Analyse de flux de contrôle et de données étendue à Go, Java, C#, Kotlin
• Scan Infrastructure as Code - Nouvelles règles iac.yaml pour Terraform, CloudFormation, Kubernetes
• Règles de sécurité spécifiques au langage - Nouvelles règles pour Go, Java, C#, Kotlin, Bash
• 6 nouveaux langages - Erlang, Elm, Fortran, PowerShell, Nix, Groovy
• 90 outils au total - Au lieu de 79 avec les nouvelles capacités SPARQL, CCG et d'analyse

v1.2.x

• Paramètre exclude_tests - 22 outils prennent en charge le filtrage des fichiers de test
• Paquet npm - Installation via npm install -g narsil-mcp

v1.1.x

• Distribution multi-plateforme - Installation via Homebrew, Scoop, npm, Cargo ou téléchargement direct
• Préréglages d'outils configurables - Préréglages minimal, équilibré, complet et axé sécurité
• Détection automatique de l'éditeur - Valeurs par défaut optimales pour Zed, VS Code, Claude Desktop
• Assistant de configuration interactif - narsil-mcp config init pour une configuration facile
• Support de 32 langages - Ajout de Dart, Julia, R, Perl, Zig, et plus
• Performance améliorée - Démarrage plus rapide avec indexation en arrière-plan

v1.0.x

• Recherche sémantique neuronale - Trouver du code similaire en utilisant les embeddings Voyage AI ou OpenAI
• Inférence de types - Inférer les types en Python/JavaScript/TypeScript sans outils externes
• Analyse de contamination multi-langages - Scan de sécurité pour PHP, Java, C#, Ruby, Kotlin
• Version WASM - Fonctionne dans le navigateur pour les terrains de jeu de code et les outils éducatifs
• 147 règles de sécurité groupées - Détection OWASP, CWE, crypto, secrets, Rust, Elixir
• Configurations IDE incluses - Modèles Claude Desktop, Cursor, VS Code, Zed

Licence

Sous licence de l'une ou l'autre de :

• Licence Apache, Version 2.0 (LICENSE-APACHE ou http://www.apache.org/licenses/LICENSE-2.0)
• Licence MIT (LICENSE-MIT ou http://opensource.org/licenses/MIT)

à votre choix.

Crédits

Construit avec :

• tree-sitter - Analyse incrémentale
• tantivy - Recherche plein texte
• tokio - Runtime asynchrone
• rayon - Parallélisme de données
• serde - Sérialisation