Narsil MCP

narsil-mcp

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

Un serveur MCP (Model Context Protocol) propulsé par Rust, offrant aux assistants IA une compréhension approfondie du code grâce à 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 flux de données sensibles	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'appels	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 graphes d'appels
• Recherche sémantique neuronale - Trouvez du code similaire grâce aux embeddings (Voyage AI, OpenAI)
• Analyse de sécurité - Analyse de flux de données sensibles, analyse 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 incrémentale et précise pour 32 langages
• Zéro configuration - Pointez vers les 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 flux de données sensibles
• Embeddings neuronaux - Recherche sémantique optionnelle avec Voyage AI ou OpenAI
• Support WASM - Exécution dans le navigateur avec la version WebAssembly
• Streaming en temps réel - Résultats au fur et à mesure de l'indexation pour les grands dépôts

Langages pris en charge

Langage	Extensions	Symboles extraits
Rust	.rs	fonctions, structures, énumérations, traits, implémentations, modules
Python	.py, .pyi	fonctions, classes
JavaScript	.js, .jsx, .mjs	fonctions, classes, méthodes, variables
TypeScript	.ts, .tsx	fonctions, classes, interfaces, types, énumérations
Go	.go	fonctions, méthodes, types
C	.c, .h	fonctions, structures, énumérations, typedefs
C++	.cpp, .cc, .hpp	fonctions, classes, structures, espaces de noms
Java	.java	méthodes, classes, interfaces, énumérations
C#	.cs	méthodes, classes, interfaces, structures, énumérations, 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, structures, énumérations, 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, structures
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-programmes, fonctions, modules
PowerShell	.ps1, .psm1, .psd1	fonctions, classes, énumérations
Nix	.nix	liaisons
Groovy	.groovy, .gradle	méthodes, classes, interfaces, énumérations, 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

Remarque 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 compilation requis si vous compilez à partir des sources.

À partir des sources

Prérequis :

• Version stable actuelle de Rust (cette version a été vérifiée avec Rust 1.98 et 1.99)
• Sur Windows : Visual Studio Build Tools avec « Développement Desktop en 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

Compilations par fonctionnalités

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

# 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

Fonctionnalité	Description	Taille
native (par 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 intégrée	~31 Mo
neural	+ Recherche vectorielle TF-IDF, embeddings API	~32 Mo
neural-onnx	+ Inférence de modèles ONNX locale	~50 Mo
wasm	Compilation expérimentale pour navigateur (sans système de fichiers, ni git)	Non qualifiée pour publication

Important : L'indicateur 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 aux plateformes, 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)

Remarque sur --graph : Cet indicateur 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 à partir des sources avec :

cargo build --release --features graph

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

Remarque : Les embeddings neuronaux nécessitent une clé API (ou un point de terminaison personnalisé). Le moyen le plus simple de configurer cela est 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 du point de terminaison d'API d'embedding personnalisé (optionnel, permet d'utiliser des modèles auto-hébergés)

Configuration

La version 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 entièrement 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 au complet
• Préréglage équilibré : 25 % de jetons en moins par rapport au complet

Préréglages

Choisissez un préréglage en fonction de votre cas d'utilisation :

# 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é : Indicateurs CLI > Variables d'environnement > Configuration projet > Configuration utilisateur > Valeurs par défaut

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 aux plateformes

Interface de visualisation

Explorez les graphes d'appels, 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 graphes :

Vue	Description
Graphe d'appels	Relations d'appels de fonctions avec contrôle de profondeur et filtrage de direction
Graphe d'imports	Dépendances d'imports au niveau des fichiers dans l'ensemble du code
Graphe de symboles	Toutes les références à un symbole, avec regroupement par fichiers
Hybride	Graphe combiné d'appels + imports 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-déposer, zoom et exploration en double-clic
• 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 les puits de données sensibles
• Six algorithmes de disposition (dagre, force-directed, breadthfirst, concentric, circle, grid)
• Barre latérale d'arborescence de fichiers avec visionneuse de code à coloration syntaxique
• État piloté par URL (liens partageables, boutons précédent/suivant du navigateur)
• Prise en charge 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 de développement.

Recherche sémantique neuronale

Trouvez du code similaire grâce aux 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'utilisation.

Inférence de types

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

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

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 Code Mode qui regroupe les 90 outils en 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 passe par des objets proxy typés dans un isolate V8 sandboxé — les identifiants, chemins de fichiers et é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 réduit 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 votre répertoire de projet pour une configuration par projet :

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

Puis lancez Claude Code dans votre projet :

cd /path/to/project
claude

L'utilisation de . pour --repos indexe automatiquement le répertoire courant. Claude a désormais accès à 90 outils d'intelligence de code.

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

Pour une configuration globale, modifiez ~/.claude/settings.json à la place. 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.

Installation via Marketplace (Recommandé) :

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

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

Ou installation directe depuis GitHub :

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

Ce qui est inclus :

Composant	Description
/narsil:security-scan	Exécute des audits de sécurité complets
/narsil:explore	Explore des bases de code inconnues
/narsil:analyze-function	Analyse approfondie de fonctions spécifiques
/narsil:find-feature	Trouve où les fonctionnalités sont implémentées
/narsil:supply-chain	Analyse la sécurité de la chaîne d'approvisionnement
Compétence	Guide Claude pour utiliser efficacement 90 outils
Config MCP	Démarre automatiquement narsil-mcp avec des paramètres par défaut sensés

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 gagne des capacités d'intelligence de code améliorées :

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

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 README Ralph pour les détails complets d'intégration.

Playbooks et 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'appels et l'analyse de flux de données
Audit de sécurité	Trouver des vulnérabilités avec l'analyse OWASP/CWE
Revue de code	Examiner les modifications efficacement

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

Utilisation WebAssembly (Navigateur)

Le dépôt contient du code source WebAssembly expérimental et un script de construction local. @narsil-mcp/wasm n'est pas publié sur npm et ne constitue pas un canal de distribution pour la version CLI 1.7.1. La construction WASM et les exemples ne sont pas couverts par sa qualification de version. Voir docs/wasm.md pour le flux de travail du code source expérimental.

Outils disponibles (93)

Gestion des dépôts et fichiers

Outil	Description
list_repos	Liste tous les dépôts indexés avec métadonnées
get_project_structure	Obtient l'arborescence des répertoires avec icônes et tailles de fichiers
get_file	Obtient le contenu des fichiers avec plage de lignes optionnelle
get_excerpt	Extrait le code autour de lignes spécifiques avec contexte
reindex	Déclenche la ré-indexation des dépôts
discover_repos	Découvre automatiquement les dépôts dans un répertoire
validate_repo	Vérifie si le chemin est un dépôt valide
get_index_status	Affiche les statistiques d'index et les fonctionnalités activées

Recherche et navigation de symboles

Outil	Description
find_symbols	Trouve les structs, classes, fonctions par type/modèle
get_symbol_definition	Obtient le code source du symbole avec contexte environnant
find_references	Trouve toutes les références à un symbole
get_dependencies	Analyse les imports et les dépendants
workspace_symbol_search	Recherche floue de symboles dans l'espace de travail
find_symbol_usages	Utilisation de symboles entre fichiers avec imports
get_export_map	Obtient les symboles exportés d'un fichier/module

Recherche de code

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

Découpage conscient de l'AST

Outil	Description
get_chunks	Obtient les morceaux conscients de l'AST pour un fichier
get_chunk_stats	Statistiques sur les morceaux 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	Trouve des clones sémantiques Type-3/4 d'une fonction
get_neural_stats	Statistiques de l'index d'embeddings neuronaux

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

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

Analyse de flux de contrôle

Outil	Description
get_control_flow	Obtient le CFG montrant les blocs de base et les branches
find_dead_code	Trouve les blocs de code inaccessibles

Analyse de flux de données

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

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

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

Graphe d'imports/dépendances

Outil	Description
get_import_graph	Construit et analyse le graphe d'imports
find_circular_imports	Détecte les dépendances circulaires
get_incremental_status	Arbre de Merkle et statistiques de modifications

Analyse de sécurité - Suivi de flux de données

Outil	Description
find_injection_vulnerabilities	Trouve les injections SQL, XSS, injections de commandes, traversées de chemins
trace_taint	Trace le flux de données contaminées depuis une source
get_taint_sources	Liste les sources de contamination (entrées 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	Analyse avec règles de sécurité (OWASP, CWE, crypto, secrets)
check_owasp_top10	Analyse des vulnérabilités OWASP Top 10 2021
check_cwe_top25	Analyse des faiblesses CWE Top 25
explain_vulnerability	Obtient une explication détaillée des vulnérabilités
suggest_fix	Obtient des suggestions de remédiation pour les résultats

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

Outil	Description
generate_sbom	Génère un SBOM (CycloneDX/SPDX/JSON)
check_dependencies	Vérifie les vulnérabilités connues (base de données OSV)
check_licenses	Analyse les licences pour les problèmes de conformité
find_upgrade_path	Trouve 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 modification et complexité élevée
get_contributors	Contributeurs du dépôt/fichier
get_commit_diff	Diff pour un commit spécifique
get_symbol_history	Commits qui ont modifié un symbole
get_branch_info	Branche courante et statut
get_modified_files	Modifications de l'arbre 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	Trouve l'emplacement de la définition

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

Outil	Description
add_remote_repo	Clone et indexe un dépôt GitHub
list_remote_files	Liste les fichiers via l'API GitHub
get_remote_file	Récupère un fichier via l'API GitHub

Métriques

Outil	Description
get_metrics	Statistiques de performance et temps

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

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

Graphe de Contexte de Code (CCG) (nécessite --graph)

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

Outil	Description
get_ccg_manifest	Manifeste de couche 0 (~1-2KB JSON-LD) - identité du dépôt, compteurs
export_ccg_manifest	Exporte le manifeste de couche 0 vers un fichier
export_ccg_architecture	Architecture de couche 1 (~10-50KB JSON-LD) - modules, API
export_ccg_index	Index de symboles de couche 2 (~100-500KB N-Quads compressés)
export_ccg_full	Détails complets de couche 3 (~1-20MB N-Quads compressés)
export_ccg	Exporte toutes les couches CCG comme un bundle
query_ccg	Interroge CCG en utilisant SPARQL
get_ccg_acl	Génère le contrôle d'accès WebACL pour les couches CCG
get_ccg_access_info	Obtient les informations de niveau d'accès CCG
import_ccg	Importe une couche CCG depuis une URL ou un fichier
import_ccg_from_registry	Importe 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 principaux :

• owasp-top10.yaml - Modèles de vulnérabilités OWASP Top 10 2021
• cwe-top25.yaml - CWE Top 25 Faiblesses les plus dangereuses
• 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 non sûr, frontières FFI, injection de commandes, TOCTOU)
• elixir.yaml - Modèles Elixir/BEAM (épuisement des 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 et configuration :

• iac.yaml - Infrastructure en tant que 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)             |  |
|  +-----------------------------------------------------------+  |
+-----------------------------------------------------------------+

Performances

Benchmarké sur Apple M1 (criterion.rs) :

Débit d'analyse syntaxique

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 de 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 documents	80 µs
Similarité TF-IDF	1 000 documents	130 µs
Hybride (BM25+TF-IDF)	1 000 documents	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,1 s	89 Mo
noyau linux	78 000+	~500K	45 s	2,1 Go

Indicateurs clés :

• Analyse syntaxique Tree-sitter : ~2 Gio/s de débit soutenu
• Recherche de symboles : <1µs pour une correspondance exacte
• Recherche en texte intégral : <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

Résolution des problèmes

Erreurs de compilation Tree-sitter

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

# macOS
xcode-select --install

# Ubuntu/Debian
sudo apt install build-essential

# For WASM builds
brew install emscripten  # macOS

Erreurs de l'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é de graphe 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 binaire supplémentaire) qui n'est pas nécessaire pour la plupart des cas d'utilisation. Elle reste optionnelle pour garder le binaire par défaut plus petit.

Comment vérifier si le graphe 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-langues (32 langages)
• Recherche en texte intégral avec Tantivy (classement BM25)
• Recherche hybride (BM25 + TF-IDF avec RRF)
• Découpage de code conscient de l'AST
• Intégration Git blame/historique
• Analyse de graphe d'appels avec métriques de complexité
• Analyse de graphe de flux de contrôle (CFG)
• Analyse de flux de données (DFG) avec définitions atteignables
• Détection de code mort et de stockage mort
• Analyse de flux de données 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'importation avec détection de dépendances circulaires
• Résolution de symboles inter-langues
• Indexation incrémentale avec arbres de Merkle
• Persistance de l'index
• Mode de surveillance des modifications de fichiers
• Intégration LSP
• Prise en charge des dépôts distants
• Réponses en streaming

Quoi de neuf

v1.6.x (Actuelle)

• Découpage à l'épreuve des crashs - Correction du découpage de chaînes au niveau octet non sûr dans chunk_file() et extract_signature() qui provoquait des 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 découpage d'octets utilise désormais content.get() sûr avec repli.
• Opérations de tri sans NaN - Correction de 5 emplacements dans les modules de recherche, embeddings, git, index et extraction où partial_cmp().unwrap() plantait sur des valeurs flottantes NaN. Tous les tris utilisent désormais unwrap_or(Ordering::Equal).
• Découpage en profondeur - Ajout de wrappers catch_unwind autour de toutes les boucles chunk_file() à l'échelle du dépôt afin qu'une panique dans un fichier le saute au lieu de faire planter tout le serveur MCP.
• Refonte du frontend de visualisation - SPA complète avec routage HashRouter, barre latérale d'arborescence de fichiers, visualiseur de code avec coloration syntaxique, tableau de bord et pages de présentation par dépôt
• Performances de la vue graphe - Le graphe d'importation utilise désormais les données d'index en cache au lieu des parcours du système de fichiers ; le graphe de symboles itère directement le cache de fichiers au lieu des allers-retours markdown ; toutes les vues respectent max_nodes pour une terminaison anticipée
• Vrais graphes de flux de contrôle - La vue Flux utilise désormais le vrai 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
• Répartition du budget du graphe hybride - La vue Hybride alloue un budget de nœuds 60/40 entre les graphes d'appels et d'importation 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() afin que des modèles comme text-embedding-3-large utilisent les bonnes dimensions (3072) au lieu de 1536 codé en dur
• Correction #13 : compilation frontend Nix - Ajout de la dérivation frontendDist dans flake.nix utilisant buildNpmPackage afin 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, les 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 des atomes, la désérialisation binary_to_term, l'injection Code.eval, l'injection SQL Ecto, XSS Phoenix, la sécurité de la 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 désormais 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 passé de 1 611 à 1 763 (+152 tests)

v1.5.x

• Résolution déterministe du graphe d'appels - La propagation d'indices de portée désambiguïse la résolution de l'appelé (par exemple, 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'importation
• Améliorations du flake Nix - Helper mkPkg DRY, suppression des frameworks macOS inutiles, stratégie de test --lib pour les compilations en bac à sable

v1.4.x

• Graphe de connaissances SPARQL / RDF - Interrogez les données d'intelligence de code avec SPARQL via Oxigraph
• Graphe de contexte de code (CCG) - 12 outils pour des représentations standardisées de codebase consommables par l'IA avec des couches hiérarchisées (L0-L3)
• Analyse de sécurité sensible au type - Suivi de flux de données amélioré avec inférence de type et implémentations de traits
• CFG/DFG multi-langues - Analyse de flux de contrôle et de flux de données étendue à Go, Java, C#, Kotlin
• Analyse de l'infrastructure en tant que 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 - Contre 79 auparavant 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é sur la sécurité
• Détection automatique de l'éditeur - Paramètres par défaut optimaux pour Zed, VS Code, Claude Desktop
• Assistant de configuration interactif - narsil-mcp config init pour une configuration facile
• Prise en charge de 32 langages - Ajout de Dart, Julia, R, Perl, Zig, et plus
• Performances améliorées - Démarrage plus rapide avec indexation en arrière-plan

v1.0.x

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

Licence

Sous licence selon l'une des options suivantes :

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

à votre choix.

Crédits

Construit avec :

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