Narsil MCP

narsil-mcp

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

Ein in Rust entwickelter MCP-Server (Model Context Protocol), der KI-Assistenten durch 90 spezialisierte Werkzeuge ein tiefes Codeverständnis ermöglicht.

Warum narsil-mcp?

Funktion	narsil-mcp	XRAY	Serena	GitHub MCP
Sprachen	32	4	30+ (LSP)	N/A
Neuronale 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
Aufrufgraphen	Ja	Teilweise	Nein	Nein
Typinferenz	Ja	Nein	Nein	Nein

Kernfunktionen

• Code-Intelligenz – Symbolextraktion, semantische Suche, Aufrufgraph-Analyse
• Neuronale semantische Suche – Ähnlichen Code mittels Embeddings finden (Voyage AI, OpenAI)
• Sicherheitsanalyse – Taint-Analyse, Schwachstellenscan, OWASP/CWE-Abdeckung
• Lieferkettensicherheit – SBOM-Erstellung, Abhängigkeitsprüfung, Lizenzkonformität
• Erweiterte Analyse – Kontrollflussgraphen, Datenflussanalyse, Erkennung von totem Code

Warum narsil-mcp wählen?

• In Rust geschrieben – Extrem schnell, speichersicher, einzelne Binärdatei (~30 MB)
• Tree-sitter-basiert – Präzises, inkrementelles Parsen für 32 Sprachen
• Keine Konfiguration nötig – Auf Repositories 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 via Rayon
• Intelligente Ausschnitte – Erweitert auf vollständige syntaktische Bereiche
• Sicherheit zuerst – Integrierte Schwachstellenerkennung und Taint-Analyse
• Neuronale Embeddings – Optionale semantische Suche mit Voyage AI oder OpenAI
• WASM-Unterstützung – Ausführung im Browser mit WebAssembly-Build
• Echtzeit-Streaming – Ergebnisse während der Indizierung für große Repositories

Unterstützte Sprachen

Sprache	Erweiterungen	Extrahierte Symbole
Rust	.rs	Funktionen, Structs, Enums, Traits, Impls, Module
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	Bindungen
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: Das PowerShell-Installationsprogramm bietet bessere Fehlermeldungen und native Windows-Integration. Es konfiguriert automatisch Ihren PATH und prüft auf erforderliche Build-Tools, wenn aus dem Quellcode gebaut wird.

Aus dem Quellcode

Voraussetzungen:

• Rust 1.70 oder neuer
• Unter Windows: Visual Studio Build Tools mit „Desktopentwicklung mit 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

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

# For browser/WASM usage
cargo build --release --target wasm32-unknown-unknown --features wasm

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

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

Detaillierte Installationsanweisungen, Fehlerbehebung und plattformspezifische Anleitungen finden Sie unter 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ändiger Funktionsumfang

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)-Werkzeuge, aber nur, wenn die Binärdatei mit --features graph gebaut wurde. Die Standard-Binärdatei enthält dieses Feature nicht. Wenn Sie SPARQL/CCG-Funktionen benötigen, bauen Sie aus dem Quellcode mit:

cargo build --release --features graph

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

Hinweis: Neuronale Embeddings erfordern einen API-Schlüssel (oder einen benutzerdefinierten Endpunkt). Der einfachste Weg zur Einrichtung 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
• Ihn automatisch zur MCP-Konfiguration Ihres Editors hinzufügen

Alternativ können Sie eine dieser Umgebungsvariablen manuell setzen:

• EMBEDDING_API_KEY – Allgemeiner 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 eine fein abgestimmte Kontrolle über Werkzeuge und Leistung ein. Alle bestehenden Verwendungen funktionieren 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 eine optimale Voreinstellung an:

Editor	Voreinstellung	Werkzeuge	Kontext-Tokens	Grund
Zed	Minimal	26	~4.686	Schneller Start, minimaler Kontext
VS Code	Ausgewogen	51	~8.948	Gute Funktionsbalance
Claude Desktop	Voll	90	~12.001	Maximale Fähigkeiten

Token-Einsparungen:

• Minimale Voreinstellung: 61 % weniger Tokens gegenüber Voll
• Ausgewogene Voreinstellung: 25 % weniger Tokens gegenüber Voll

Voreinstellungen

Wählen Sie eine Voreinstellung 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 Repository-Stamm):

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 Arbeitsbereiche mit mehreren Repositories:

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:

• Konfigurationshandbuch – Vollständige Konfigurationsreferenz
• Installationshandbuch – Plattformspezifische Installation

Visualisierungs-Frontend

Erkunden Sie Aufrufgraphen, 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 Graphansichten:

Ansicht	Beschreibung
Aufrufgraph	Funktionsaufrufbeziehungen mit Tiefensteuerung und Richtungsfilterung
Importgraph	Dateibasierte Importabhängigkeiten in der gesamten Codebasis
Symbolgraph	Alle Referenzen auf ein Symbol, mit Dateigruppierung
Hybrid	Kombinierter Aufruf- + Importgraph mit aufgeteiltem Budget
Kontrollfluss	Echter CFG mit Basisblöcken, Verzweigungen und Schleifenrückkanten

Funktionen:

• Interaktive Cytoscape.js-Graphen mit Ziehen, Zoomen und Doppelklick-Drilldown
• Komplexitätsmetriken-Overlay mit Farbcodierung (grün/gelb/orange/rot)
• Sicherheitslücken-Overlay, das Taint-Quellen und -Senken hervorhebt
• Sechs Layout-Algorithmen (dagre, kraftgerichtet, breadthfirst, concentric, circle, grid)
• Dateibaum-Seitenleiste mit syntaxhervorgehobenem Code-Viewer
• URL-gesteuerter Zustand (teilbare Links, Browser-Vor/Zurück)
• Unterstützung für den dunklen Modus
• Knoten-Detailpanel mit Code-Ausschnitten 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 mit neuronalen Embeddings – selbst wenn sich Variablennamen und Struktur unterscheiden.

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

Werkzeug	Beschreibung
infer_types	Abgerufene Typen für alle Variablen in einer Funktion
check_type_errors	Potenzielle Typinkonsistenzen 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 Arbeitsabläufe kann narsil-mcp über Forgemax verwendet werden – ein Code Mode MCP-Gateway, das alle 90 Werkzeuge auf nur 2 reduziert (search + execute), wodurch der Werkzeugschema-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 Standardeinstellungen:

[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

Das LLM schreibt JavaScript, das über typisierte Proxy-Objekte innerhalb einer sandboxed V8-Isolate aufruft – Anmeldeinformationen, Dateipfade und interner Zustand verlassen den Host niemals. Dieser Ansatz ist besonders nützlich, wenn mit mehreren MCP-Servern gleichzeitig gearbeitet wird, da er den gesamten Werkzeugkontext klein und vorhersagbar 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 eine projektbezogene 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-Intelligence-Werkzeuge.

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

Für eine globale Konfiguration bearbeiten Sie stattdessen ~/.claude/settings.json. Siehe Claude Code Integration für erweiterte 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 → Kontextserver):

{
  "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 Fähigkeit zur effektiven Werkzeugnutzung.

Installation über 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

Enthaltene Bestandteile:

Komponente	Beschreibung
/narsil:security-scan	Umfassende Sicherheitsaudits durchführen
/narsil:explore	Unbekannte Codebasen erkunden
/narsil:analyze-function	Tiefgehende Analyse spezifischer Funktionen
/narsil:find-feature	Finden, wo Funktionen implementiert sind
/narsil:supply-chain	Lieferkettensicherheit analysieren
Fähigkeit	Leitet Claude bei der effektiven Nutzung von 90 Werkzeugen an
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 autonome Codeentwicklung. Wenn narsil-mcp verfügbar ist, erhält Ralph erweiterte Code-Intelligence-Funktionen:

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

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 ordnungsgemäß, wenn narsil-mcp nicht verfügbar ist – alle Kernautomatisierungsfunktionen funktionieren ohne.

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

Playbooks & Tutorials

Siehe docs/playbooks für praktische Anleitungen:

Anleitung	Beschreibung
Erste Schritte	Schnelle Einrichtung und erste Werkzeugaufrufe
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 Werkzeugketten, die Claude verwendet, um Ihre Fragen zu beantworten.

WebAssembly (Browser)-Nutzung

narsil-mcp kann vollständig im Browser über WebAssembly ausgeführt werden – perfekt für browserbasierte IDEs, Code-Review-Tools oder Bildungsplattformen.

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

Vollständige Dokumentation: Siehe docs/wasm.md für Build-Anweisungen, React-Beispiele und API-Referenz.

Verfügbare Werkzeuge (90)

Repository- & Dateiverwaltung

Werkzeug	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	Neuindizierung 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	Indexstatistiken und aktivierte Funktionen anzeigen

Symbolsuche & Navigation

Werkzeug	Beschreibung
find_symbols	Strukturen, 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ängige analysieren
workspace_symbol_search	Fuzzy-Suche nach Symbolen im Arbeitsbereich
find_symbol_usages	Dateiübergreifende Symbolnutzung mit Importen
get_export_map	Exportierte Symbole aus einer Datei/einem Modul abrufen

Codesuche

Werkzeug	Beschreibung
search_code	Stichwortsuche mit Relevanzranking
semantic_search	BM25-gereihte semantische Suche
hybrid_search	Kombinierte BM25 + TF-IDF mit Rangfusion
search_chunks	Suche über AST-bewusste Code-Abschnitte
find_similar_code	Ähnlichen Code zu einem Snippet finden (TF-IDF)
find_similar_to_symbol	Ähnlichen Code zu einem Symbol finden

AST-bewusste Aufteilung

Werkzeug	Beschreibung
get_chunks	AST-bewusste Abschnitte für eine Datei abrufen
get_chunk_stats	Statistiken über Code-Abschnitte
get_embedding_stats	Embedding-Index-Statistiken

Neuronale semantische Suche (erfordert --neural)

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

Aufrufgraph-Analyse (erfordert --call-graph)

Werkzeug	Beschreibung
get_call_graph	Aufrufgraph 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 vernetzte Funktionen finden

Kontrollflussanalyse

Werkzeug	Beschreibung
get_control_flow	CFG mit Basisblöcken und Verzweigungen abrufen
find_dead_code	Nicht erreichbare Codeblöcke finden

Datenflussanalyse

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

Typinferenz (Python/JavaScript/TypeScript)

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

Import-/Abhängigkeitsgraph

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

Sicherheitsanalyse – Taint-Tracking

Werkzeug	Beschreibung
find_injection_vulnerabilities	SQL-Injection, XSS, Command Injection, Path Traversal finden
trace_taint	Verfolgung des Taint-Datenflusses von einer Quelle
get_taint_sources	Taint-Quellen auflisten (Benutzereingabe, Dateien, Netzwerk)
get_security_summary	Umfassende Sicherheitsrisikobewertung

Sicherheitsanalyse – Regel-Engine

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

Lieferkettensicherheit

Werkzeug	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 anfällige Abhängigkeiten finden

Git-Integration (erfordert --git)

Werkzeug	Beschreibung
get_blame	Git-Blame für Datei
get_file_history	Commit-Verlauf für Datei
get_recent_changes	Letzte Commits im Repository
get_hotspots	Dateien mit hoher Änderungshäufigkeit und Komplexität
get_contributors	Repository-/Datei-Mitwirkende
get_commit_diff	Diff für einen bestimmten Commit
get_symbol_history	Commits, die ein Symbol geändert haben
get_branch_info	Aktueller Branch und Status
get_modified_files	Änderungen im Arbeitsverzeichnis

LSP-Integration (erfordert --lsp)

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

Unterstützung für entfernte Repositories (erfordert --remote)

Werkzeug	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

Werkzeug	Beschreibung
get_metrics	Leistungsstatistiken und Zeitmessung

SPARQL / Wissensgraph (erfordert --graph)

Werkzeug	Beschreibung
sparql_query	SPARQL-Abfrage gegen RDF-Wissensgraph 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 gestaffelten Ebenen.

Werkzeug	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 gzipped)
export_ccg_full	Ebene-3-Vollständige Details (~1-20MB N-Quads gzipped)
export_ccg	Alle CCG-Ebenen als Bündel exportieren
query_ccg	CCG mit SPARQL abfragen
get_ccg_acl	WebACL-Zugriffskontrolle für CCG-Ebenen generieren
get_ccg_access_info	CCG-Zugriffsebeneninformationen abrufen
import_ccg	CCG-Ebene von URL oder Datei importieren
import_ccg_from_registry	CCG aus der codecontextgraph.com-Registry importieren

Sicherheitsregeln

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

Kernregelsätze:

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

Infrastruktur & Konfiguration:

• iac.yaml – Infrastructure as Code (Terraform, CloudFormation, Kubernetes)
• config.yaml – Sicherheit von Konfigurationsdateien (hartkodierte Anmeldeinformationen, 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-Exact-Match	1.000 Symbole	483 ns
Symbol-Präfix-Match	1.000 Symbole	2,7 µs
Symbol-Fuzzy-Match	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,1s	89 MB
Linux-Kernel	78.000+	~500K	45s	2,1 GB

Wichtige Metriken:

• Tree-sitter-Parsing: ~2 GiB/s anhaltender Durchsatz
• Symbolsuche: <1µs für Exact Match
• Volltextsuche: <1ms für die meisten Abfragen
• Hybride Suche 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 Sie während des Builds Fehler über fehlende C-Compiler oder Tree-sitter sehen:

# macOS
xcode-select --install

# Ubuntu/Debian
sudo apt install build-essential

# For WASM builds
brew install emscripten  # macOS

Neuronale Such-API-Fehler

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

Bedeutet dies, dass Sie eine Binärdatei verwenden, die nicht mit der graph-Funktion 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 dies eine separate Funktion? Die graph-Funktion 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. Sie wird optional gehalten, um die Standardbinärdatei kleiner zu halten.

So überprüfen Sie, ob Graph aktiviert ist: Sehen Sie sich die Startprotokolle an:

• graph=true bedeutet, dass die Funktion einkompiliert UND aktiviert ist
• graph=false bedeutet, dass entweder die Funktion nicht einkompiliert ist ODER --graph nicht übergeben wurde

Roadmap

Abgeschlossen

• Mehrsprachige Symbolextraktion (32 Sprachen)
• Volltextsuche mit Tantivy (BM25-Ranking)
• Hybride Suche (BM25 + TF-IDF mit RRF)
• AST-bewusstes Code-Chunking
• Git-Blame/History-Integration
• Aufrufgraph-Analyse mit Komplexitätsmetriken
• Kontrollflussgraph-Analyse (CFG)
• Datenflussanalyse (DFG) mit erreichbaren Definitionen
• Erkennung von totem Code und toten Speicherungen
• Taint-Analyse für Injektionsschwachstellen
• Sicherheitsregel-Engine (OWASP, CWE, Krypto, Secrets)
• SBOM-Generierung (CycloneDX, SPDX)
• Prüfung von Abhängigkeitsschwachstellen (OSV)
• Lizenzkonformitätsanalyse
• 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 entfernte Repositories
• Streaming-Antworten

Was ist neu

v1.6.x (Aktuell)

• Absturzsicheres Chunking – Unsichehere Byte-Level-String-Slicing in chunk_file() und extract_signature() behoben, das hybrid_search, search_chunks und get_chunk_stats zum Absturz brachte, wenn Dateien mit mehrbyte-UTF-8-Zeichen (Emoji, CJK, akzentuierte Zeichen) verarbeitet wurden. Jegliches Byte-Slicing verwendet jetzt sicheres content.get() mit Fallback.
• NaN-sichere Sortieroperationen – 5 Stellen in den Modulen Suche, Embeddings, Git, Index und Extraktion behoben, an denen partial_cmp().unwrap() bei NaN-Float-Werten abstürzte. Alle Sortierungen verwenden jetzt unwrap_or(Ordering::Equal).
• Defense-in-Depth-Chunking – catch_unwind-Wrapper um alle repo-weiten chunk_file()-Schleifen hinzugefügt, sodass ein Absturz in einer Datei diese überspringt, anstatt den gesamten MCP-Server zum Absturz zu bringen.
• Überarbeitung des Visualisierungs-Frontends – Vollständige SPA mit HashRouter-Routing, Dateibaum-Seitenleiste, syntaxhervorgehobenem Code-Viewer, Dashboard und Übersichtsseiten pro Repo
• Graphansicht-Leistung – Importgraph verwendet jetzt zwischengespeicherte Indexdaten anstelle von Dateisystem-Durchläufen; Symbolgraph iteriert direkt über den Dateicache anstelle von Markdown-Roundtrips; alle Ansichten respektieren max_nodes für vorzeitige Beendigung
• Echte Kontrollflussgraphen – Die Flussansicht verwendet jetzt den echten CFG-Builder (cfg::analyze_function) mit korrekten Basisblöcken, Verzweigungsbedingungen und Schleifenrückkanten anstelle des Einzelblock-Stubs
• Hybrides Graph-Budget-Splitting – Die Hybridansicht weist ein 60/40-Knotenbudget zwischen Aufruf- und Importgraphen für ausgewogene Ergebnisse zu
• Fix #14: konfigurierbare Embedding-Dimensionen – CLI-Argument --neural-dimension und default_dimension_for_model()-Suche hinzugefügt, sodass Modelle wie text-embedding-3-large korrekte Dimensionen (3072) anstelle von hartkodierten 1536 verwenden
• Fix #13: Nix-Frontend-Build – frontendDist-Ableitung 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 Befehlsinjektion, 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-Verteilungssicherheit
• Migration von serde_yaml zu serde-saphyr – Veraltetes serde_yaml durch aktiv gewartete, absturzfreie YAML-Bibliothek ersetzt
• Benutzerdefiniertes Favicon – Frontend verwendet jetzt das narsil-mcp-Branding-Symbol 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 Aufrufgraph-Auflösung – Scope-Hint-Propagation disambiguiert die Callee-Auflösung (z. B. App::run() wird korrekt zu src/app/mod.rs::run aufgelöst)
• 8 Graphanalyse-Korrekturen – Qualifizierte Knotenschlüssel, Hotspot-Filterung, CFG-Ausdrucksbehandlung, Importpfad-Parsing
• Nix-Flake-Verbesserungen – DRY mkPkg-Hilfsfunktion, unnötige macOS-Frameworks entfernt, --lib-Teststrategie für Sandbox-Builds

v1.4.x

• SPARQL / RDF Knowledge Graph – Code-Intelligence-Daten mit SPARQL über Oxigraph abfragen
• Code Context Graph (CCG) – 12 Werkzeuge für standardisierte, KI-konsumierbare Codebase-Darstellungen mit gestaffelten Ebenen (L0-L3)
• Typbewusste Sicherheitsanalyse – Verbessertes Taint-Tracking mit Typinferenz und Trait-Implementierungen
• Mehrsprachige CFG/DFG – Kontrollfluss- und Datenflussanalyse erweitert auf Go, Java, C#, Kotlin
• 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 Werkzeuge insgesamt – Gegenüber 79 mit neuen SPARQL-, CCG- und Analysefunktionen

v1.2.x

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

v1.1.x

• Multi-Plattform-Distribution – Installation über Homebrew, Scoop, npm, Cargo oder direkten Download
• Konfigurierbare Werkzeugvoreinstellungen – Minimal, Ausgewogen, Vollständig und sicherheitsfokussierte Voreinstellungen
• Automatische Editor-Erkennung – Optimale Standardeinstellungen für Zed, VS Code, Claude Desktop
• Interaktiver Einrichtungsassistent – narsil-mcp config init für einfache Konfiguration
• 32 Sprachen unterstützt – Dart, Julia, R, Perl, Zig und mehr hinzugefügt
• Verbesserte Leistung – Schnellerer Start durch Hintergrundindizierung

v1.0.x

• Neuronale semantische Suche – Ähnlichen Code mit Voyage AI- oder OpenAI-Embeddings finden
• Typinferenz – Typen in Python/JavaScript/TypeScript ohne externe Werkzeuge ableiten
• Mehrsprachige Taint-Analyse – Sicherheitsscans für PHP, Java, C#, Ruby, Kotlin
• WASM-Build – Im Browser für Code-Spielplätze und Bildungswerkzeuge 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:

• 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-Laufzeitumgebung
• rayon – Datenparallelität
• serde – Serialisierung