Narsil MCP

narsil-mcp

Der blitzschnelle, datenschutzorientierte MCP-Server für tiefe Code-Intelligenz

Ein in Rust entwickelter MCP-Server (Model Context Protocol), der KI-Assistenten durch 90 spezialisierte Tools ein tiefes Code-Verständnis bietet.

Warum narsil-mcp?

Funktion	narsil-mcp	XRAY	Serena	GitHub MCP
Sprachen	32	4	30+ (LSP)	N/A
Neurale Suche	Ja	Nein	Nein	Nein
Taint-Analyse	Ja	Nein	Nein	Nein
SBOM/Lizenzen	Ja	Nein	Nein	Teilweise
Offline/Lokal	Ja	Ja	Ja	Nein
WASM/Browser	Ja	Nein	Nein	Nein
Call-Graphen	Ja	Teilweise	Nein	Nein
Typinferenz	Ja	Nein	Nein	Nein

Hauptfunktionen

• Code-Intelligenz – Symbol-Extraktion, semantische Suche, Call-Graphen-Analyse
• Neurale semantische Suche – Ähnlichen Code mithilfe von Embeddings finden (Voyage AI, OpenAI)
• Sicherheitsanalyse – Taint-Analyse, Schwachstellenscan, OWASP/CWE-Abdeckung
• Supply-Chain-Sicherheit – SBOM-Erstellung, Abhängigkeitsprüfung, Lizenz-Compliance
• Erweiterte Analyse – Kontrollflussgraphen, Datenflussanalyse, Erkennung von totem Code

Warum narsil-mcp wählen?

• In Rust geschrieben – Blitzschnell, speichersicher, einzelne Binärdatei (~30MB)
• Tree-sitter-basiert – Präzises, inkrementelles Parsing für 32 Sprachen
• Null Konfiguration – Auf Repos zeigen und loslegen
• MCP-konform – Funktioniert mit Claude, Cursor, VS Code Copilot, Zed und jedem MCP-Client
• Datenschutz zuerst – Vollständig lokal, keine Daten verlassen Ihren Rechner
• Parallele Indizierung – Nutzt alle Kerne über Rayon
• Intelligente Auszüge – Erweitert auf vollständige syntaktische Bereiche
• Sicherheit zuerst – Integrierte Schwachstellenerkennung und Taint-Analyse
• Neurale Embeddings – Optionale semantische Suche mit Voyage AI oder OpenAI
• WASM-Unterstützung – Im Browser mit WebAssembly-Build ausführen
• Echtzeit-Streaming – Ergebnisse während der Indizierung für große Repos

Unterstützte Sprachen

Sprache	Erweiterungen	Extrahierte Symbole
Rust	.rs	Funktionen, Structs, Enums, Traits, Impls, Mods
Python	.py, .pyi	Funktionen, Klassen
JavaScript	.js, .jsx, .mjs	Funktionen, Klassen, Methoden, Variablen
TypeScript	.ts, .tsx	Funktionen, Klassen, Interfaces, Typen, Enums
Go	.go	Funktionen, Methoden, Typen
C	.c, .h	Funktionen, Structs, Enums, Typedefs
C++	.cpp, .cc, .hpp	Funktionen, Klassen, Structs, Namespaces
Java	.java	Methoden, Klassen, Interfaces, Enums
C#	.cs	Methoden, Klassen, Interfaces, Structs, Enums, Delegates, Namespaces
Bash	.sh, .bash, .zsh	Funktionen, Variablen
Ruby	.rb, .rake, .gemspec	Methoden, Klassen, Module
Kotlin	.kt, .kts	Funktionen, Klassen, Objekte, Interfaces
PHP	.php, .phtml	Funktionen, Methoden, Klassen, Interfaces, Traits
Swift	.swift	Klassen, Structs, Enums, Protokolle, Funktionen
Verilog/SystemVerilog	.v, .vh, .sv, .svh	Module, Tasks, Funktionen, Interfaces, Klassen
Scala	.scala, .sc	Klassen, Objekte, Traits, Funktionen, Vals
Lua	.lua	Funktionen, Methoden
Haskell	.hs, .lhs	Funktionen, Datentypen, Typklassen
Elixir	.ex, .exs	Module, Funktionen
Clojure	.clj, .cljs, .cljc, .edn	Listen (grundlegender AST)
Dart	.dart	Funktionen, Klassen, Methoden
Julia	.jl	Funktionen, Module, Structs
R	.R, .r, .Rmd	Funktionen
Perl	.pl, .pm, .t	Funktionen, Pakete
Zig	.zig	Funktionen, Variablen
Erlang	.erl, .hrl	Funktionen, Module, Records
Elm	.elm	Funktionen, Typen
Fortran	.f90, .f95, .f03, .f08, .f, .for, .fpp	Programme, Subroutinen, Funktionen, Module
PowerShell	.ps1, .psm1, .psd1	Funktionen, Klassen, Enums
Nix	.nix	Bindings
Groovy	.groovy, .gradle	Methoden, Klassen, Interfaces, Enums, Funktionen

Installation

Über Paketmanager (Empfohlen)

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 (alle Plattformen):

cargo install narsil-mcp

Node.js/npm (alle Plattformen):

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

Ein-Klick-Installationsskript

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

Hinweis für Windows-Benutzer: Der PowerShell-Installer bietet bessere Fehlermeldungen und native Windows-Integration. Er konfiguriert automatisch Ihren PATH und prüft auf erforderliche Build-Tools, falls Sie aus dem Quellcode bauen.

Aus dem Quellcode

Voraussetzungen:

• Aktuelles stabiles Rust (diese Version wurde mit Rust 1.98 und 1.99 verifiziert)
• Unter Windows: Visual Studio Build Tools mit „Desktop development with 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

Feature-Builds

narsil-mcp unterstützt verschiedene Feature-Sets für unterschiedliche Anwendungsfälle:

# 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

Feature	Beschreibung	Größe
native (Standard)	Vollständiger MCP-Server mit allen Tools	~30MB
graph	+ RDF-Wissensgraph, SPARQL, CCG-Tools	~35MB
frontend	+ Eingebettete Visualisierungs-Web-UI	~31MB
neural	+ TF-IDF-Vektorsuche, API-Embeddings	~32MB
neural-onnx	+ Lokale ONNX-Modellinferenz	~50MB
wasm	Experimenteller Browser-Quellcode-Build (kein Dateisystem, kein Git)	Nicht release-qualifiziert

Wichtig: Das --graph-CLI-Flag erfordert, dass die Binärdatei mit --features graph gebaut wurde. Wenn Sie --graph an eine Binärdatei ohne dieses Feature übergeben, sehen Sie eine Warnung und SPARQL/CCG-Tools sind nicht verfügbar. Siehe Fehlerbehebung unten.

Für detaillierte Installationsanweisungen, Fehlerbehebung und plattformspezifische Anleitungen siehe docs/INSTALL.md.

Verwendung

Grundlegende Verwendung

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

Vollständiges Feature-Set

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)

Hinweis zu --graph: Dieses Flag aktiviert SPARQL-Abfragen und Code Context Graph (CCG)-Tools, aber nur wenn die Binärdatei mit --features graph gebaut wurde. Die Standard-Binärdatei enthält dieses Feature nicht. Wenn Sie SPARQL/CCG-Fähigkeiten benötigen, bauen Sie aus dem Quellcode mit:

cargo build --release --features graph

Wenn Sie --graph an eine Binärdatei ohne das Feature übergeben, sehen Sie eine Warnung beim Start und der Server läuft ohne SPARQL/CCG-Tools weiter.

Hinweis: Neuronale Embeddings erfordern einen API-Schlüssel (oder einen benutzerdefinierten Endpunkt). Der einfachste Weg, dies einzurichten, ist der interaktive Assistent:

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

Der Assistent wird:

• Ihren Editor erkennen (Claude Desktop, Claude Code, Zed, VS Code, JetBrains)
• Nach Ihrem API-Anbieter fragen (Voyage AI, OpenAI oder benutzerdefiniert)
• Ihren API-Schlüssel validieren
• Automatisch zur MCP-Konfiguration Ihres Editors hinzufügen

Alternativ können Sie eine dieser Umgebungsvariablen manuell setzen:

• EMBEDDING_API_KEY – Generischer API-Schlüssel für jeden Anbieter
• VOYAGE_API_KEY – Voyage AI-spezifischer API-Schlüssel
• OPENAI_API_KEY – OpenAI-spezifischer API-Schlüssel
• EMBEDDING_SERVER_ENDPOINT – Benutzerdefinierte Embedding-API-Endpunkt-URL (optional, ermöglicht selbst gehostete Modelle)

Konfiguration

v1.1.0+ führt optionale Konfiguration für feingranulare Kontrolle über Tools und Leistung ein. Die gesamte bestehende Verwendung funktioniert weiterhin – Konfiguration ist vollständig optional!

Schnellstart

# 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

Automatische Editor-Erkennung

narsil-mcp erkennt Ihren Editor und wendet automatisch ein optimales Preset an:

Editor	Preset	Tools	Kontext-Tokens	Warum
Zed	Minimal	26	~4.686	Schneller Start, minimaler Kontext
VS Code	Ausgewogen	51	~8.948	Gute Funktionsbalance
Claude Desktop	Vollständig	90	~12.001	Maximale Fähigkeiten

Token-Ersparnis:

• Minimales Preset: 61% weniger Tokens gegenüber Vollständig
• Ausgewogenes Preset: 25% weniger Tokens gegenüber Vollständig

Presets

Wählen Sie ein Preset basierend auf Ihrem Anwendungsfall:

# 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

Konfigurationsdateien

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

Projektkonfiguration (.narsil.yaml im Repo-Stammverzeichnis):

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

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

Benannte Repository-Profile sind nützlich für Multi-Repo-Arbeitsbereiche:

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ät: CLI-Flags > Umgebungsvariablen > Projektkonfiguration > Benutzerkonfiguration > Standardwerte

Umgebungsvariablen

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

# 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

Mehr erfahren:

• Konfigurationsanleitung – Vollständige Konfigurationsreferenz
• Installationsanleitung – Plattformspezifische Installation

Visualisierungs-Frontend

Entdecken Sie Call-Graphen, Importe, Symbolreferenzen und Kontrollfluss interaktiv in Ihrem Browser.

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

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

Fünf Graph-Ansichten:

Ansicht	Beschreibung
Call-Graph	Funktionsaufruf-Beziehungen mit Tiefensteuerung und Richtungsfilterung
Import-Graph	Datei-Level-Importabhängigkeiten im gesamten Codebestand
Symbol-Graph	Alle Referenzen auf ein Symbol, mit Dateiclusterung
Hybrid	Kombinierter Call- + Import-Graph mit geteiltem Budget
Kontrollfluss	Echter CFG mit Basisblöcken, Verzweigungen und Schleifen-Rückkanten

Funktionen:

• Interaktive Cytoscape.js-Graphen mit Ziehen, Zoomen und Doppelklick-Drilldown
• Komplexitätsmetrik-Overlay mit Farbcodierung (grün/gelb/orange/rot)
• Sicherheits-Schwachstellen-Overlay, das Taint-Quellen und -Senken hervorhebt
• Sechs Layout-Algorithmen (dagre, kraftbasiert, breitenorientiert, konzentrisch, Kreis, Raster)
• Dateibaum-Seitenleiste mit syntaxhervorgehobenem Code-Viewer
• URL-gesteuerter Zustand (teilbare Links, Browser-Zurück/Vorwärts)
• Dunkelmodus-Unterstützung
• Knotendetail-Panel mit Code-Auszügen und Navigation zur Quelle

Vollständige Dokumentation: Siehe docs/frontend.md für Einrichtung, API-Endpunkte und Entwicklungsmodus.

Neuronale semantische Suche

Finden Sie ähnlichen Code mithilfe neuronaler Embeddings – selbst wenn Variablennamen und Struktur unterschiedlich sind.

# 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

Unterstützt Voyage AI, OpenAI, benutzerdefinierte Endpunkte und lokale ONNX-Modelle.

Vollständige Dokumentation: Siehe docs/neural-search.md für Einrichtung, Backends und Anwendungsfälle.

Typinferenz

Integrierte Typinferenz für Python, JavaScript und TypeScript – kein mypy oder tsc erforderlich.

Tool	Beschreibung
infer_types	Inferierte Typen für alle Variablen in einer Funktion abrufen
check_type_errors	Potenzielle Typkonflikte finden
get_typed_taint_flow	Erweiterte Sicherheitsanalyse mit Typinformationen

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

Forgemax-Integration (Experimentell)

Für groß angelegte agentische Workflows kann narsil-mcp über Forgemax verwendet werden – ein Code-Mode-MCP-Gateway, das alle 90 Tools auf nur 2 reduziert (search + execute), wodurch der Tool-Schema-Overhead von ~12.000 Tokens auf ~1.000 reduziert wird.

# Install Forgemax
cargo install forgemax

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

Die enthaltene forge.toml konfiguriert narsil-mcp mit sinnvollen Standardwerten:

[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

Der LLM schreibt JavaScript, das über typisierte Proxy-Objekte innerhalb einer sandboxed V8-Isolate aufruft – Anmeldedaten, Dateipfade und interner Zustand verlassen niemals den Host. Dieser Ansatz ist besonders nützlich, wenn man mit mehreren MCP-Servern gleichzeitig arbeitet, da er den gesamten Tool-Kontext klein und vorhersehbar hält.

MCP-Konfiguration

Fügen Sie narsil-mcp zu Ihrem KI-Assistenten hinzu, indem Sie eine Konfigurationsdatei erstellen. Hier sind die empfohlenen Einrichtungen:

---

Claude Code (.mcp.json im Projektstamm - Empfohlen):

Erstellen Sie .mcp.json in Ihrem Projektverzeichnis für die projektspezifische Konfiguration:

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

Starten Sie dann Claude Code in Ihrem Projekt:

cd /path/to/project
claude

Die Verwendung von . für --repos indiziert automatisch das aktuelle Verzeichnis. Claude hat nun Zugriff auf 90 Code-Intelligenz-Tools.

Tipp: Fügen Sie --persist --index-path .claude/cache hinzu für einen schnelleren Start bei späteren Ausführungen.

Für die globale Konfiguration bearbeiten Sie stattdessen ~/.claude/settings.json. Siehe Claude Code Integration für fortgeschrittene Einrichtungen.

---

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

Hinweis für Copilot Enterprise: MCP-Unterstützung erfordert VS Code 1.102+ und muss von Ihrem Organisationsadministrator aktiviert werden.

---

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

Hinweis für Zed: narsil-mcp startet sofort und indiziert im Hintergrund, wodurch Initialisierungs-Timeouts vermieden werden.

---

Claude Code Plugin

Für Claude Code-Benutzer bieten wir ein Plugin mit Slash-Befehlen und einer Skill für effektive Tool-Nutzung.

Installation über den Marketplace (Empfohlen):

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

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

Oder direkt von GitHub installieren:

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

Was enthalten ist:

Komponente	Beschreibung
/narsil:security-scan	Umfassende Sicherheitsaudits durchführen
/narsil:explore	Unbekannte Codebasen erkunden
/narsil:analyze-function	Tiefer Einblick in bestimmte Funktionen
/narsil:find-feature	Herausfinden, wo Funktionen implementiert sind
/narsil:supply-chain	Supply-Chain-Sicherheit analysieren
Skill	Führt Claude bei der effektiven Nutzung der 90 Tools
MCP-Konfiguration	Startet narsil-mcp automatisch mit sinnvollen Standardeinstellungen

Siehe narsil-plugin/README.md für die vollständige Dokumentation.

Ralph-Automatisierungsintegration

Ralph ist eine Claude-Code-Automatisierungssuite für die autonome Codeentwicklung. Wenn narsil-mcp verfügbar ist, erhält Ralph erweiterte Code-Intelligenz-Fähigkeiten:

Funktion	Ohne narsil-mcp	Mit narsil-mcp
Sicherheitsscanning	Basis (clippy)	OWASP/CWE-Schwachstellenerkennung
Codeverständnis	Dateibasiert	Aufrufgraphen, Symbolreferenzen
Architekturanalyse	Manuell	CCG L0/L1/L2 automatische Ebenen
Abhängigkeitsanalyse	cargo tree	Importgraphen, Zirkularerkennung

Einrichtung:

# 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 degradiert elegant, wenn narsil-mcp nicht verfügbar ist – alle Kernautomatisierungsfunktionen funktionieren auch ohne es.

Dokumentation: Siehe Ralph README für vollständige Integrationsdetails.

Playbooks & Tutorials

Siehe docs/playbooks für praktische Nutzungsanleitungen:

Anleitung	Beschreibung
Erste Schritte	Schnelle Einrichtung und erste Tool-Aufrufe
Eine Codebasis verstehen	Unbekannte Projekte erkunden
Einen Fehler beheben	Debugging mit Aufrufgraphen und Taint-Analyse
Sicherheitsaudit	Schwachstellen mit OWASP/CWE-Scanning finden
Code-Review	Änderungen effektiv überprüfen

Jedes Playbook zeigt die genauen Tool-Ketten, die Claude verwendet, um Ihre Fragen zu beantworten.

WebAssembly (Browser)-Nutzung

Das Repository enthält experimentellen WebAssembly-Quellcode und ein lokales Build-Skript. @narsil-mcp/wasm ist nicht auf npm veröffentlicht und kein Vertriebskanal für die 1.7.1-CLI-Version. Der WASM-Build und die Beispiele sind nicht durch deren Release-Qualifizierung abgedeckt. Siehe docs/wasm.md für den experimentellen Quellcode-Workflow.

Verfügbare Tools (93)

Repository- & Dateiverwaltung

Tool	Beschreibung
list_repos	Alle indizierten Repositories mit Metadaten auflisten
get_project_structure	Verzeichnisbaum mit Dateisymbolen und -größen abrufen
get_file	Dateiinhalte mit optionalem Zeilenbereich abrufen
get_excerpt	Code um bestimmte Zeilen mit Kontext extrahieren
reindex	Neu-Indizierung von Repositories auslösen
discover_repos	Repositories in einem Verzeichnis automatisch erkennen
validate_repo	Prüfen, ob ein Pfad ein gültiges Repository ist
get_index_status	Index-Statistiken und aktivierte Funktionen anzeigen

Symbolsuche & Navigation

Tool	Beschreibung
find_symbols	Structs, Klassen, Funktionen nach Typ/Muster finden
get_symbol_definition	Symbolquelle mit umgebendem Kontext abrufen
find_references	Alle Referenzen auf ein Symbol finden
get_dependencies	Importe und Abhängigkeiten analysieren
workspace_symbol_search	Fuzzy-Suche nach Symbolen im gesamten Workspace
find_symbol_usages	Dateiübergreifende Symbolnutzung mit Importen
get_export_map	Exportierte Symbole aus einer Datei/einem Modul abrufen

Codesuche

Tool	Beschreibung
search_code	Stichwortsuche mit Relevanz-Ranking
semantic_search	BM25-bewertete semantische Suche
hybrid_search	Kombinierte BM25 + TF-IDF mit Rang-Fusion
search_chunks	Suche über AST-bewusste Code-Chunks
find_similar_code	Code ähnlich zu einem Snippet finden (TF-IDF)
find_similar_to_symbol	Code ähnlich zu einem Symbol finden

AST-bewusstes Chunking

Tool	Beschreibung
get_chunks	AST-bewusste Chunks für eine Datei abrufen
get_chunk_stats	Statistiken über Code-Chunks
get_embedding_stats	Einbettungsindex-Statistiken

Neuronale semantische Suche (erfordert --neural)

Tool	Beschreibung
neural_search	Semantische Suche mit neuronalen Einbettungen (findet ähnlichen Code auch bei unterschiedlichen Namen)
find_semantic_clones	Typ-3/4-semantische Klone einer Funktion finden
get_neural_stats	Neuronale Einbettungsindex-Statistiken

Aufrufgraphen-Analyse (erfordert --call-graph)

Tool	Beschreibung
get_call_graph	Aufrufgraphen für Repository/Funktion abrufen
get_callers	Funktionen finden, die eine Funktion aufrufen
get_callees	Funktionen finden, die von einer Funktion aufgerufen werden
find_call_path	Pfad zwischen zwei Funktionen finden
get_complexity	Zyklomatische/kognitive Komplexität abrufen
get_function_hotspots	Stark verbundene Funktionen finden

Kontrollflussanalyse

Tool	Beschreibung
get_control_flow	CFG mit Basisblöcken und Verzweigungen abrufen
find_dead_code	Unerreichbare Codeblöcke finden

Datenflussanalyse

Tool	Beschreibung
get_data_flow	Variablendefinitionen und -verwendungen
get_reaching_definitions	Welche Zuweisungen erreichen jeden Punkt
find_uninitialized	Variablen, die vor der Initialisierung verwendet werden
find_dead_stores	Zuweisungen, die nie gelesen werden

Typinferenz (Python/JavaScript/TypeScript)

Tool	Beschreibung
infer_types	Typen für Variablen in einer Funktion ohne externe Typprüfer ableiten
check_type_errors	Potenzielle Typfehler ohne Ausführung von mypy/tsc finden
get_typed_taint_flow	Erweiterte Taint-Analyse, die Datenfluss mit Typinferenz kombiniert

Import-/Abhängigkeitsgraph

Tool	Beschreibung
get_import_graph	Importgraphen erstellen und analysieren
find_circular_imports	Zirkuläre Abhängigkeiten erkennen
get_incremental_status	Merkle-Baum und Änderungsstatistiken

Sicherheitsanalyse - Taint-Tracking

Tool	Beschreibung
find_injection_vulnerabilities	SQL-Injection, XSS, Command-Injection, Path-Traversal finden
trace_taint	Tainted-Datenfluss von einer Quelle verfolgen
get_taint_sources	Taint-Quellen auflisten (Benutzereingaben, Dateien, Netzwerk)
get_security_summary	Umfassende Sicherheitsrisikobewertung

Sicherheitsanalyse - Regeln-Engine

Tool	Beschreibung
scan_security	Mit Sicherheitsregeln scannen (OWASP, CWE, Krypto, Geheimnisse)
check_owasp_top10	Auf OWASP Top 10 2021-Schwachstellen scannen
check_cwe_top25	Auf CWE Top 25-Schwachstellen scannen
explain_vulnerability	Detaillierte Schwachstellenerklärung abrufen
suggest_fix	Behebungsvorschläge für Befunde abrufen

Supply-Chain-Sicherheit

Tool	Beschreibung
generate_sbom	SBOM generieren (CycloneDX/SPDX/JSON)
check_dependencies	Auf bekannte Schwachstellen prüfen (OSV-Datenbank)
check_licenses	Lizenzen auf Compliance-Probleme analysieren
find_upgrade_path	Sichere Upgrade-Pfade für verwundbare Abhängigkeiten finden

Git-Integration (erfordert --git)

Tool	Beschreibung
get_blame	Git blame für Datei
get_file_history	Commit-Verlauf für Datei
get_recent_changes	Aktuelle Commits im Repository
get_hotspots	Dateien mit hoher Änderungsrate und Komplexität
get_contributors	Repository-/Datei-Mitwirkende
get_commit_diff	Diff für bestimmten Commit
get_symbol_history	Commits, die ein Symbol geändert haben
get_branch_info	Aktueller Branch und Status
get_modified_files	Änderungen im Arbeitsbaum

LSP-Integration (erfordert --lsp)

Tool	Beschreibung
get_hover_info	Typinformationen und Dokumentation
get_type_info	Präzise Typinformationen
go_to_definition	Definitionsort finden

Remote-Repository-Unterstützung (erfordert --remote)

Tool	Beschreibung
add_remote_repo	GitHub-Repository klonen und indizieren
list_remote_files	Dateien über die GitHub-API auflisten
get_remote_file	Datei über die GitHub-API abrufen

Metriken

Tool	Beschreibung
get_metrics	Leistungsstatistiken und Timing

SPARQL / Wissensgraph (erfordert --graph)

Tool	Beschreibung
sparql_query	SPARQL-Abfrage gegen RDF-Wissensgraphen ausführen
list_sparql_templates	Verfügbare SPARQL-Abfragevorlagen auflisten
run_sparql_template	Vordefinierte SPARQL-Vorlage mit Parametern ausführen

Code Context Graph (CCG) (erfordert --graph)

CCG bietet standardisierte, KI-konsumierbare Darstellungen von Codebasen in gestuften Ebenen.

Tool	Beschreibung
get_ccg_manifest	Ebene-0-Manifest (~1-2KB JSON-LD) - Repo-Identität, Zählungen
export_ccg_manifest	Ebene-0-Manifest in Datei exportieren
export_ccg_architecture	Ebene-1-Architektur (~10-50KB JSON-LD) - Module, API
export_ccg_index	Ebene-2-Symbolindex (~100-500KB N-Quads gzip)
export_ccg_full	Ebene-3-Vollständige Details (~1-20MB N-Quads gzip)
export_ccg	Alle CCG-Ebenen als Bundle exportieren
query_ccg	CCG mit SPARQL abfragen
get_ccg_acl	WebACL-Zugriffskontrolle für CCG-Ebenen generieren
get_ccg_access_info	CCG-Zugriffsstufeninformationen abrufen
import_ccg	CCG-Ebene von URL oder Datei importieren
import_ccg_from_registry	CCG aus codecontextgraph.com-Registry importieren

Sicherheitsregeln

narsil-mcp enthält integrierte Sicherheitsregeln in rules/:

Kern-Regelsätze:

• owasp-top10.yaml - OWASP Top 10 2021-Schwachstellenmuster
• cwe-top25.yaml - CWE Top 25 Gefährlichste Schwachstellen
• crypto.yaml - Kryptografische Probleme (schwache Algorithmen, hartcodierte Schlüssel)
• secrets.yaml - Geheimniserkennung (API-Schlüssel, Passwörter, Tokens) Sprachspezifische Regeln:
• rust.yaml - Rust-Sicherheitsmuster (unsafe transmute, FFI-Grenzen, Command Injection, TOCTOU)
• elixir.yaml - Elixir/BEAM-Muster (Atom-Erschöpfung, binary_to_term, Code.eval, Ecto-SQL-Injection)
• go.yaml - Go-Sicherheitsmuster (SQL-Injection, TLS, Command Injection)
• java.yaml - Java-Schwachstellen (XXE, Deserialisierung, LDAP-Injection)
• csharp.yaml - C#-Sicherheitsprobleme (Deserialisierung, XSS, Path Traversal)
• kotlin.yaml - Kotlin/Android-Muster (WebView, Intents, Secrets)
• bash.yaml - Shell-Skript-Schwachstellen (Command Injection, eval)

Infrastruktur & Konfiguration:

• iac.yaml - Infrastructure as Code (Terraform, CloudFormation, Kubernetes)
• config.yaml - Konfigurationsdatei-Sicherheit (hartcodierte Anmeldedaten, unsichere Einstellungen)

Benutzerdefinierte Regeln können mit scan_security --ruleset /path/to/rules.yaml geladen werden.

Architektur

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

Leistung

Benchmark auf Apple M1 (criterion.rs):

Parsing-Durchsatz

Sprache	Eingabegröße	Zeit	Durchsatz
Rust (große Datei)	278 KB	131 µs	1,98 GiB/s
Rust (mittlere Datei)	27 KB	13,5 µs	1,89 GiB/s
Python	~4 KB	16,7 µs	-
TypeScript	~5 KB	13,9 µs	-
Gemischt (5 Dateien)	~15 KB	57 µs	-

Suchlatenz

Operation	Korpusgröße	Zeit
Symbol exakte Übereinstimmung	1.000 Symbole	483 ns
Symbol Präfix-Übereinstimmung	1.000 Symbole	2,7 µs
Symbol Fuzzy-Übereinstimmung	1.000 Symbole	16,5 µs
BM25-Volltext	1.000 Dokumente	80 µs
TF-IDF-Ähnlichkeit	1.000 Dokumente	130 µs
Hybrid (BM25+TF-IDF)	1.000 Dokumente	151 µs

End-to-End-Indizierung

Repository	Dateien	Symbole	Zeit	Speicher
narsil-mcp (dieses Repo)	53	1.733	220 ms	~50 MB
rust-analyzer	2.847	~50K	2,1 s	89 MB
Linux-Kernel	78.000+	~500K	45 s	2,1 GB

Wichtige Kennzahlen:

• Tree-sitter-Parsing: ~2 GiB/s anhaltender Durchsatz
• Symbolsuche: <1µs für exakte Übereinstimmung
• Volltextsuche: <1ms für die meisten Abfragen
• Hybridsuche führt BM25 + TF-IDF parallel über rayon aus

Entwicklung

# 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

Fehlerbehebung

Tree-sitter-Build-Fehler

Wenn während des Builds Fehler zu fehlenden C-Compilern oder tree-sitter auftreten:

# macOS
xcode-select --install

# Ubuntu/Debian
sudo apt install build-essential

# For WASM builds
brew install emscripten  # macOS

Fehler der Neural-Search-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-"

Index findet keine Dateien

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

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

Speicherprobleme bei großen Repos

# 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-Funktion funktioniert nicht

Wenn Sie --graph übergeben und eine Warnung wie diese sehen:

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

Das bedeutet, dass Sie eine Binärdatei verwenden, die nicht mit dem graph-Feature kompiliert wurde. Zur Behebung:

# 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

Warum ist das ein separates Feature? Das graph-Feature fügt die Oxigraph-RDF-Datenbank hinzu (~5 MB zusätzliche Binärgröße), die für die meisten Anwendungsfälle nicht benötigt wird. Es bleibt optional, um die Standard-Binärdatei kleiner zu halten.

So prüfen Sie, ob Graph aktiviert ist: Achten Sie auf die Startprotokolle:

• graph=true bedeutet, dass das Feature kompiliert UND aktiviert ist
• graph=false bedeutet, dass entweder das Feature nicht kompiliert ist ODER --graph nicht übergeben wurde

Roadmap

Abgeschlossen

• Mehrsprachige Symbol-Extraktion (32 Sprachen)
• Volltextsuche mit Tantivy (BM25-Ranking)
• Hybridsuche (BM25 + TF-IDF mit RRF)
• AST-bewusstes Code-Chunking
• Git-Blame/History-Integration
• Call-Graph-Analyse mit Komplexitätsmetriken
• Kontrollflussgraph-Analyse (CFG)
• Datenflussanalyse (DFG) mit erreichenden Definitionen
• Erkennung von totem Code und toten Speicherstellen
• Taint-Analyse für Injection-Schwachstellen
• Sicherheitsregel-Engine (OWASP, CWE, Krypto, Secrets)
• SBOM-Erzeugung (CycloneDX, SPDX)
• Prüfung auf Abhängigkeits-Schwachstellen (OSV)
• Lizenz-Compliance-Analyse
• Importgraph mit Erkennung zirkulärer Abhängigkeiten
• Sprachübergreifende Symbolauflösung
• Inkrementelle Indizierung mit Merkle-Bäumen
• Index-Persistenz
• Watch-Modus für Dateiänderungen
• LSP-Integration
• Unterstützung für Remote-Repositories
• Streaming-Antworten

Neuerungen

v1.6.x (aktuell)

• Absturzsicheres Chunking - Behobenes unsicheres Byte-Level-String-Slicing in chunk_file() und extract_signature(), das hybrid_search, search_chunks und get_chunk_stats zum Absturz brachte, wenn Dateien mit mehrbyteigen UTF-8-Zeichen (Emoji, CJK, akzentuierte Zeichen) verarbeitet wurden. Alle Byte-Slicing-Operationen verwenden jetzt sicheres content.get() mit Fallback.
• NaN-sichere Sortieroperationen - 5 Stellen in den Modulen für Suche, Embeddings, Git, Index und Extraktion behoben, an denen partial_cmp().unwrap() bei NaN-Gleitkommawerten einen Panik auslöste. Alle Sortierungen verwenden jetzt unwrap_or(Ordering::Equal).
• Verteidigung in der Tiefe beim Chunking - catch_unwind-Wrapper um alle repo-weiten chunk_file()-Schleifen hinzugefügt, sodass ein Panik in einer Datei diese überspringt, anstatt den gesamten MCP-Server zum Absturz zu bringen.
• Überarbeitung der Visualisierungs-Frontend - Vollständige SPA mit HashRouter-Routing, Dateibaum-Seitenleiste, syntaxhervorgehobenem Code-Viewer, Dashboard und Übersichtsseiten pro Repo
• Graph-Ansicht-Leistung - Importgraph verwendet jetzt gecachte Indexdaten anstelle von Dateisystem-Durchläufen; Symbolgraph iteriert direkt über den Dateicache anstelle von Markdown-Roundtrips; alle Ansichten respektieren max_nodes für die vorzeitige Beendigung
• Echte Kontrollflussgraphen - Die Flow-Ansicht verwendet jetzt den echten CFG-Builder (cfg::analyze_function) mit korrekten Basisblöcken, Verzweigungsbedingungen und Schleifen-Rückkanten anstelle des Einzelblock-Stubs
• Hybrides Graph-Budget-Splitting - Die Hybrid-Ansicht verteilt das Knotenbudget im Verhältnis 60/40 zwischen Call- und Importgraphen für ausgewogene Ergebnisse
• Fix #14: konfigurierbare Embedding-Dimensionen - --neural-dimension-CLI-Argument und default_dimension_for_model()-Lookup hinzugefügt, sodass Modelle wie text-embedding-3-large die korrekten Dimensionen (3072) anstelle der hartcodierten 1536 verwenden
• Fix #13: Nix-Frontend-Build - frontendDist-Derivation in flake.nix unter Verwendung von buildNpmPackage hinzugefügt, sodass nix profile install github:postrv/narsil-mcp#with-frontend funktioniert
• Rust-Sicherheitsregeln - 18 neue Regeln (RUST-004 bis RUST-021) für Command Injection, transmute, FFI-Grenzen, TOCTOU, ReDoS, static mut, SSRF und mehr
• Elixir-Sicherheitsregeln - 18 neue Regeln (EX-001 bis EX-018) für Atom-Erschöpfung, binary_to_term-Deserialisierung, Code.eval-Injection, Ecto-SQL-Injection, Phoenix-XSS, Erlang-Distribution-Sicherheit
• Migration von serde_yaml zu serde-saphyr - Veraltetes serde_yaml durch aktiv gepflegte, panikfreie YAML-Bibliothek ersetzt
• Benutzerdefiniertes Favicon - Das Frontend verwendet jetzt das narsil-mcp-Branding-Icon anstelle des Standard-Vite-Logos
• Abhängigkeitssicherheit - time auf 0.3.47 (RUSTSEC-2026-0009), bytes auf 1.11.1 (RUSTSEC-2026-0007) aktualisiert
• Testanzahl von 1.611 auf 1.763 erhöht (+152 Tests)

v1.5.x

• Deterministische Call-Graph-Auflösung - Scope-Hint-Propagation disambiguiert die Callee-Auflösung (z. B. löst App::run() korrekt zu src/app/mod.rs::run auf)
• 8 Graph-Analyse-Fixes - Qualifizierte Knotenschlüssel, Hotspot-Filterung, CFG-Ausdrucksbehandlung, Importpfad-Parsing
• Nix-Flake-Verbesserungen - DRY mkPkg-Helfer, unnötige macOS-Frameworks entfernt, --lib-Teststrategie für Sandbox-Builds

v1.4.x

• SPARQL / RDF-Wissensgraph - Code-Intelligence-Daten mit SPARQL über Oxigraph abfragen
• Code-Context-Graph (CCG) - 12 Tools für standardisierte, KI-konsumierbare Codebasis-Darstellungen mit abgestuften Ebenen (L0-L3)
• Typbewusste Sicherheitsanalyse - Verbessertes Taint-Tracking mit Typinferenz und Trait-Implementierungen
• Mehrsprachiges CFG/DFG - Kontrollfluss- und Datenflussanalyse auf Go, Java, C#, Kotlin erweitert
• Infrastructure-as-Code-Scanning - Neue iac.yaml-Regeln für Terraform, CloudFormation, Kubernetes
• Sprachspezifische Sicherheitsregeln - Neue Regeln für Go, Java, C#, Kotlin, Bash
• 6 neue Sprachen - Erlang, Elm, Fortran, PowerShell, Nix, Groovy
• 90 Tools insgesamt - Gegenüber 79 mit neuen SPARQL-, CCG- und Analysefunktionen

v1.2.x

• exclude_tests-Parameter - 22 Tools unterstützen das Herausfiltern von Testdateien
• npm-Paket - Installation über npm install -g narsil-mcp

v1.1.x

• Multi-Plattform-Verteilung - Installation über Homebrew, Scoop, npm, Cargo oder direkten Download
• Konfigurierbare Tool-Presets - Minimale, ausgewogene, vollständige und sicherheitsfokussierte Presets
• Automatische Editor-Erkennung - Optimale Standardeinstellungen für Zed, VS Code, Claude Desktop
• Interaktiver Setup-Assistent - narsil-mcp config init für einfache Konfiguration
• 32-Sprachunterstützung - Dart, Julia, R, Perl, Zig und mehr hinzugefügt
• Verbesserte Leistung - Schnellerer Start mit Hintergrund-Indizierung

v1.0.x

• Neuronale semantische Suche - Ähnlichen Code mit Voyage AI oder OpenAI-Embeddings finden
• Typinferenz - Typen in Python/JavaScript/TypeScript ohne externe Tools ableiten
• Mehrsprachige Taint-Analyse - Sicherheitsscanning für PHP, Java, C#, Ruby, Kotlin
• WASM-Build - Im Browser für Code-Playgrounds und Bildungstools ausführen
• 147 gebündelte Sicherheitsregeln - OWASP-, CWE-, Krypto-, Secrets-, Rust-, Elixir-Erkennung
• IDE-Konfigurationen enthalten - Claude Desktop, Cursor, VS Code, Zed-Vorlagen

Lizenz

Lizenziert unter einer der folgenden Lizenzen:

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

nach Ihrer Wahl.

Danksagungen

Erstellt mit:

• tree-sitter - Inkrementelles Parsing
• tantivy - Volltextsuche
• tokio - Async-Runtime
• rayon - Datenparallelität
• serde - Serialisierung