Narsil MCP

narsil-mcp

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

Ein in Rust entwickelter MCP (Model Context Protocol)-Server, 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

Hauptfunktionen

• 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-Generierung, 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 - Auf Repositories verweisen 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 Auszüge - 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 - Im Browser mit WebAssembly-Build ausführbar
• 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, 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	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 höher
• Unter Windows: Visual Studio Build Tools mit "Desktopentwicklung mit 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

# 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

Voller 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 manuell eine dieser Umgebungsvariablen 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 granulare 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	Warum
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 vs. Voll
• Ausgewogene Voreinstellung: 25 % weniger Tokens vs. 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 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:

• 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 Graph-Ansichten:

Ansicht	Beschreibung
Aufrufgraph	Funktionsaufrufbeziehungen mit Tiefensteuerung und Richtungsfilterung
Importgraph	Dateiimport-Abhä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ätsmetrik-Overlay mit Farbcodierung (grün/gelb/orange/rot)
• Sicherheitslücken-Overlay, das Taint-Quellen und -Senken hervorhebt
• Sechs Layout-Algorithmen (dagre, force-directed, breadthfirst, concentric, circle, grid)
• Dateibaum-Seitenleiste mit syntaxhervorgehobenem Code-Viewer
• URL-gesteuerter Zustand (teilbare Links, Browser-Vor/Zurück)
• Dark-Mode-Unterstützung
• Knoten-Detailpanel 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 mit neuronalen Embeddings - selbst wenn Variablennamen und Struktur abweichen.

# 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 abrufen
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 Workflows 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

LLM, yazılan JavaScript'i, korumalı bir V8 izolatı içindeki tipli proxy nesneleri aracılığıyla çağırır — kimlik bilgileri, dosya yolları ve dahili durum asla ana bilgisayarı terk etmez. Bu yaklaşım, özellikle birden fazla MCP sunucusuyla aynı anda çalışırken faydalıdır, çünkü toplam araç bağlamını küçük ve öngörülebilir tutar.

MCP Yapılandırması

Bir yapılandırma dosyası oluşturarak narsil-mcp'yi AI asistanınıza ekleyin. Önerilen kurulumlar şunlardır:

---

Claude Code (proje kökünde .mcp.json - Önerilir):

Proje dizininizde proje bazlı yapılandırma için .mcp.json oluşturun:

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

Ardından projenizde Claude Code'u başlatın:

cd /path/to/project
claude

--repos için . kullanmak, geçerli dizini otomatik olarak indeksler. Claude artık 90 kod zekası aracına erişebilir.

İpucu: Sonraki çalıştırmalarda daha hızlı başlangıç için --persist --index-path .claude/cache ekleyin.

Genel yapılandırma için bunun yerine ~/.claude/settings.json düzenleyin. Gelişmiş kurulumlar için Claude Code Entegrasyonu bölümüne bakın.

---

Cursor (.cursor/mcp.json):

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

---

VS Code + GitHub Copilot (.vscode/mcp.json):

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

Copilot Enterprise için Not: MCP desteği, VS Code 1.102+ gerektirir ve kuruluş yöneticiniz tarafından etkinleştirilmelidir.

---

Claude Desktop (claude_desktop_config.json):

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

---

Zed (settings.json → Bağlam Sunucuları):

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

Zed için Not: narsil-mcp hemen başlar ve arka planda indeksleme yaparak başlatma zaman aşımlarını önler.

---

Claude Code Eklentisi

Claude Code kullanıcıları için, etkili araç kullanımı için eğik çizgi komutları ve bir beceri içeren bir eklenti sağlıyoruz.

Marketplace Üzerinden Kurulum (Önerilir):

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

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

Veya doğrudan GitHub'dan kurulum:

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

Dahil olanlar:

Bileşen	Açıklama
/narsil:security-scan	Kapsamlı güvenlik denetimleri çalıştırın
/narsil:explore	Bilinmeyen kod tabanlarını keşfedin
/narsil:analyze-function	Belirli işlevlere derinlemesine dalın
/narsil:find-feature	Özelliklerin nerede uygulandığını bulun
/narsil:supply-chain	Tedarik zinciri güvenliğini analiz edin
Beceri	Claude'a 90 aracı etkili bir şekilde kullanması için rehberlik eder
MCP Yapılandırması	narsil-mcp'yi makul varsayılanlarla otomatik başlatır

Tam belgeler için narsil-plugin/README.md bölümüne bakın.

Ralph Otomasyon Entegrasyonu

Ralph, otonom kod geliştirme için bir Claude Code otomasyon paketidir. narsil-mcp mevcut olduğunda, Ralph gelişmiş kod zekası yetenekleri kazanır:

Özellik	narsil-mcp olmadan	narsil-mcp ile
Güvenlik taraması	Temel (clippy)	OWASP/CWE güvenlik açığı tespiti
Kod anlama	Dosya tabanlı	Çağrı grafikleri, sembol referansları
Mimari analizi	Manuel	CCG L0/L1/L2 otomatik katmanlar
Bağımlılık analizi	cargo tree	İçe aktarma grafikleri, döngüsel tespit

Kurulum:

# Install narsil-mcp (Ralph auto-detects it)
cargo install narsil-mcp

# Ralph's quality gates use these tools:
narsil-mcp scan_security --repo <name>
narsil-mcp check_type_errors --repo <name> --path src
narsil-mcp find_injection_vulnerabilities --repo <name>

Ralph, narsil-mcp kullanılamadığında zarif bir şekilde düşüş gösterir - tüm temel otomasyon özellikleri onsuz çalışır.

Belgeler: Tam entegrasyon ayrıntıları için Ralph README bölümüne bakın.

Kılavuzlar ve Eğitimler

Pratik kullanım kılavuzları için docs/playbooks bölümüne bakın:

Kılavuz	Açıklama
Başlarken	Hızlı kurulum ve ilk araç çağrıları
Bir Kod Tabanını Anlama	Bilinmeyen projeleri keşfedin
Bir Hatayı Düzeltme	Çağrı grafikleri ve leke analizi ile hata ayıklayın
Güvenlik Denetimi	OWASP/CWE taraması ile güvenlik açıklarını bulun
Kod İncelemesi	Değişiklikleri etkili bir şekilde inceleyin

Her kılavuz, Claude'un sorularınızı yanıtlamak için kullandığı tam araç zincirlerini gösterir.

WebAssembly (Tarayıcı) Kullanımı

narsil-mcp, WebAssembly aracılığıyla tamamen tarayıcıda çalışabilir - tarayıcı tabanlı IDE'ler, kod inceleme araçları veya eğitim platformları için mükemmeldir.

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

Tam belgeler: Derleme talimatları, React örnekleri ve API referansı için docs/wasm.md bölümüne bakın.

Mevcut Araçlar (90)

Depo ve Dosya Yönetimi

Araç	Açıklama
list_repos	Tüm indekslenmiş depoları meta verilerle listele
get_project_structure	Dosya simgeleri ve boyutlarıyla dizin ağacını al
get_file	İsteğe bağlı satır aralığıyla dosya içeriklerini al
get_excerpt	Belirli satırların etrafındaki kodu bağlamla çıkar
reindex	Depoların yeniden indekslenmesini tetikle
discover_repos	Bir dizindeki depoları otomatik keşfet
validate_repo	Yolun geçerli bir depo olup olmadığını kontrol et
get_index_status	İndeks istatistiklerini ve etkin özellikleri göster

Sembol Arama ve Gezinme

Araç	Açıklama
find_symbols	Tür/kalıba göre yapıları, sınıfları, işlevleri bul
get_symbol_definition	Çevreleyen bağlamla sembol kaynağını al
find_references	Bir sembole yapılan tüm referansları bul
get_dependencies	İçe aktarmaları ve bağımlıları analiz et
workspace_symbol_search	Çalışma alanı genelinde bulanık sembol araması
find_symbol_usages	İçe aktarmalarla dosyalar arası sembol kullanımı
get_export_map	Bir dosyadan/modülden dışa aktarılan sembolleri al

Kod Arama

Araç	Açıklama
search_code	Alaka düzeyi sıralamasıyla anahtar kelime araması
semantic_search	BM25 sıralamalı anlamsal arama
hybrid_search	Sıra birleştirme ile birleşik BM25 + TF-IDF
search_chunks	AST farkında kod parçaları üzerinde arama
find_similar_code	Bir parçaya benzer kod bul (TF-IDF)
find_similar_to_symbol	Bir sembole benzer kod bul

AST Farkında Parçalama

Araç	Açıklama
get_chunks	Bir dosya için AST farkında parçaları al
get_chunk_stats	Kod parçaları hakkında istatistikler
get_embedding_stats	Gömme indeksi istatistikleri

Nöral Anlamsal Arama (--neural gerektirir)

Araç	Açıklama
neural_search	Nöral gömmeler kullanarak anlamsal arama (farklı adlarla bile benzer kodu bulur)
find_semantic_clones	Bir işlevin Tip-3/4 anlamsal klonlarını bul
get_neural_stats	Nöral gömme indeksi istatistikleri

Çağrı Grafiği Analizi (--call-graph gerektirir)

Araç	Açıklama
get_call_graph	Depo/işlev için çağrı grafiğini al
get_callers	Bir işlevi çağıran işlevleri bul
get_callees	Bir işlev tarafından çağrılan işlevleri bul
find_call_path	İki işlev arasındaki yolu bul
get_complexity	Döngüsel/bilişsel karmaşıklığı al
get_function_hotspots	Yüksek bağlantılı işlevleri bul

Kontrol Akışı Analizi

Araç	Açıklama
get_control_flow	Temel blokları ve dalları gösteren CFG'yi al
find_dead_code	Ulaşılamayan kod bloklarını bul

Veri Akışı Analizi

Araç	Açıklama
get_data_flow	Değişken tanımları ve kullanımları
get_reaching_definitions	Hangi atamaların her noktaya ulaştığı
find_uninitialized	Başlatmadan önce kullanılan değişkenler
find_dead_stores	Hiç okunmayan atamalar

Tip Çıkarımı (Python/JavaScript/TypeScript)

Araç	Açıklama
infer_types	Harici tip denetleyicileri olmadan bir işlevdeki değişkenler için tipleri çıkar
check_type_errors	mypy/tsc çalıştırmadan potansiyel tip hatalarını bul
get_typed_taint_flow	Veri akışını tip çıkarımı ile birleştiren gelişmiş leke analizi

İçe Aktarma/Bağımlılık Grafiği

Araç	Açıklama
get_import_graph	İçe aktarma grafiğini oluştur ve analiz et
find_circular_imports	Döngüsel bağımlılıkları tespit et
get_incremental_status	Merkle ağacı ve değişiklik istatistikleri

Güvenlik Analizi - Leke Takibi

Araç	Açıklama
find_injection_vulnerabilities	SQL enjeksiyonu, XSS, komut enjeksiyonu, yol geçişini bul
trace_taint	Bir kaynaktan lekeli veri akışını izle
get_taint_sources	Leke kaynaklarını listele (kullanıcı girdisi, dosyalar, ağ)
get_security_summary	Kapsamlı güvenlik riski değerlendirmesi

Güvenlik Analizi - Kurallar Motoru

Araç	Açıklama
scan_security	Güvenlik kurallarıyla tara (OWASP, CWE, kripto, sırlar)
check_owasp_top10	OWASP Top 10 2021 güvenlik açıkları için tara
check_cwe_top25	CWE Top 25 Zayıflıkları için tara
explain_vulnerability	Ayrıntılı güvenlik açığı açıklaması al
suggest_fix	Bulgular için düzeltme önerileri al

Tedarik Zinciri Güvenliği

Araç	Açıklama
generate_sbom	SBOM oluştur (CycloneDX/SPDX/JSON)
check_dependencies	Bilinen güvenlik açıklarını kontrol et (OSV veritabanı)
check_licenses	Uyumluluk sorunları için lisansları analiz et
find_upgrade_path	Güvenlik açığı olan bağımlılıklar için güvenli yükseltme yolları bul

Git Entegrasyonu (--git gerektirir)

Araç	Açıklama
get_blame	Dosya için Git blame
get_file_history	Dosya için commit geçmişi
get_recent_changes	Depodaki son commit'ler
get_hotspots	Yüksek değişim ve karmaşıklığa sahip dosyalar
get_contributors	Depo/dosya katkıda bulunanlar
get_commit_diff	Belirli bir commit için fark
get_symbol_history	Bir sembolü değiştiren commit'ler
get_branch_info	Geçerli dal ve durum
get_modified_files	Çalışma ağacı değişiklikleri

LSP Entegrasyonu (--lsp gerektirir)

Araç	Açıklama
get_hover_info	Tip bilgisi ve belgeler
get_type_info	Kesin tip bilgisi
go_to_definition	Tanım konumunu bul

Uzak Depo Desteği (--remote gerektirir)

Araç	Açıklama
add_remote_repo	GitHub deposunu klonla ve indeksle
list_remote_files	GitHub API aracılığıyla dosyaları listele
get_remote_file	GitHub API aracılığıyla dosya getir

Metrikler

Araç	Açıklama
get_metrics	Performans istatistikleri ve zamanlama

SPARQL / Bilgi Grafiği (--graph gerektirir)

Araç	Açıklama
sparql_query	RDF bilgi grafiğine karşı SPARQL sorgusu yürüt
list_sparql_templates	Mevcut SPARQL sorgu şablonlarını listele
run_sparql_template	Parametrelerle önceden tanımlanmış SPARQL şablonunu yürüt

Kod Bağlam Grafiği (CCG) (--graph gerektirir)

CCG, kod tabanlarının katmanlı seviyelerde standartlaştırılmış, AI tarafından tüketilebilir temsillerini sağlar.

Araç	Açıklama
get_ccg_manifest	Katman 0 manifestosu (~1-2KB JSON-LD) - depo kimliği, sayılar
export_ccg_manifest	Katman 0 manifestosunu dosyaya aktar
export_ccg_architecture	Katman 1 mimarisi (~10-50KB JSON-LD) - modüller, API
export_ccg_index	Katman 2 sembol indeksi (~100-500KB N-Quads sıkıştırılmış)
export_ccg_full	Katman 3 tam detay (~1-20MB N-Quads sıkıştırılmış)
export_ccg	Tüm CCG katmanlarını bir paket olarak dışa aktar
query_ccg	SPARQL kullanarak CCG'yi sorgula
get_ccg_acl	CCG katmanları için WebACL erişim kontrolü oluştur
get_ccg_access_info	CCG erişim katmanı bilgilerini al
import_ccg	URL veya dosyadan CCG katmanını içe aktar
import_ccg_from_registry	codecontextgraph.com kayıt defterinden CCG'yi içe aktar

Güvenlik Kuralları

narsil-mcp, rules/ içinde yerleşik güvenlik kuralları içerir:

Temel Kural Kümeleri:

• owasp-top10.yaml - OWASP Top 10 2021 güvenlik açığı kalıpları
• cwe-top25.yaml - CWE Top 25 En Tehlikeli Zayıflıklar
• crypto.yaml - Kriptografik sorunlar (zayıf algoritmalar, sabit kodlanmış anahtarlar)
• secrets.yaml - Sır tespiti (API anahtarları, parolalar, belirteçler) Dile Özgü Kurallar:
• rust.yaml - Rust güvenlik desenleri (unsafe transmute, FFI sınırları, komut enjeksiyonu, TOCTOU)
• elixir.yaml - Elixir/BEAM desenleri (atom tükenmesi, binary_to_term, Code.eval, Ecto SQL enjeksiyonu)
• go.yaml - Go güvenlik desenleri (SQL enjeksiyonu, TLS, komut enjeksiyonu)
• java.yaml - Java güvenlik açıkları (XXE, seri kaldırma, LDAP enjeksiyonu)
• csharp.yaml - C# güvenlik sorunları (seri kaldırma, XSS, yol dolaşımı)
• kotlin.yaml - Kotlin/Android desenleri (WebView, intent'ler, gizli anahtarlar)
• bash.yaml - Kabuk betiği güvenlik açıkları (komut enjeksiyonu, eval)

Altyapı & Yapılandırma:

• iac.yaml - Kod Olarak Altyapı (Terraform, CloudFormation, Kubernetes)
• config.yaml - Yapılandırma dosyası güvenliği (sabit kodlanmış kimlik bilgileri, güvensiz ayarlar)

Özel kurallar scan_security --ruleset /path/to/rules.yaml ile yüklenebilir.

Mimari

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

Performans

Apple M1 üzerinde ölçümlenmiştir (criterion.rs):

Ayrıştırma Verimi

Dil	Girdi Boyutu	Süre	Verim
Rust (büyük dosya)	278 KB	131 µs	1.98 GiB/s
Rust (orta dosya)	27 KB	13.5 µs	1.89 GiB/s
Python	~4 KB	16.7 µs	-
TypeScript	~5 KB	13.9 µs	-
Karma (5 dosya)	~15 KB	57 µs	-

Arama Gecikmesi

İşlem	Derlem Boyutu	Süre
Sembol tam eşleşme	1.000 sembol	483 ns
Sembol önek eşleşme	1.000 sembol	2.7 µs
Sembol bulanık eşleşme	1.000 sembol	16.5 µs
BM25 tam metin	1.000 döküman	80 µs
TF-IDF benzerlik	1.000 döküman	130 µs
Hibrit (BM25+TF-IDF)	1.000 döküman	151 µs

Uçtan Uca Dizinleme

Depo	Dosyalar	Semboller	Süre	Bellek
narsil-mcp (bu depo)	53	1.733	220 ms	~50 MB
rust-analyzer	2.847	~50K	2.1s	89 MB
linux çekirdeği	78.000+	~500K	45s	2.1 GB

Temel metrikler:

• Tree-sitter ayrıştırma: ~2 GiB/s sürekli verim
• Sembol arama: Tam eşleşme için <1µs
• Tam metin arama: Çoğu sorgu için <1ms
• Hibrit arama, rayon aracılığıyla BM25 + TF-IDF'i paralel çalıştırır

Geliştirme

# 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

Sorun Giderme

Tree-sitter Derleme Hataları

Derleme sırasında eksik C derleyicileri veya tree-sitter ile ilgili hatalar görürseniz:

# macOS
xcode-select --install

# Ubuntu/Debian
sudo apt install build-essential

# For WASM builds
brew install emscripten  # macOS

Sinirsel Arama API Hataları

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

Dizin Dosyaları Bulmuyor

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

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

Büyük Depolarda Bellek Sorunları

# 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

Graf Özelliği Çalışmıyor

Eğer --graph geçirirseniz ve şöyle bir uyarı görürseniz:

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

Bu, graph özelliği ile derlenmemiş bir ikili dosya kullandığınız anlamına gelir. Düzeltmek için:

# 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

Bu neden ayrı bir özellik? graph özelliği, çoğu kullanım durumu için gerekli olmayan Oxigraph RDF veritabanını (~5MB ek ikili boyutu) ekler. Varsayılan ikili dosyayı daha küçük tutmak için isteğe bağlı tutulmuştur.

Grafın etkin olup olmadığı nasıl kontrol edilir: Başlangıç günlüklerine bakın:

• graph=true özelliğin derlendiği VE etkinleştirildiği anlamına gelir
• graph=false özelliğin derlenmediği VEYA --graph geçirilmediği anlamına gelir

Yol Haritası

Tamamlandı

• Çok dilli sembol çıkarımı (32 dil)
• Tantivy ile tam metin arama (BM25 sıralaması)
• Hibrit arama (RRF ile BM25 + TF-IDF)
• AST-farkında kod parçalama
• Git blame/geçmiş entegrasyonu
• Karmaşıklık metrikleri ile çağrı grafı analizi
• Kontrol akış grafı (CFG) analizi
• Ulaşan tanımlar ile veri akış analizi (DFG)
• Ölü kod ve ölü atama tespiti
• Enjeksiyon güvenlik açıkları için leke analizi
• Güvenlik kuralları motoru (OWASP, CWE, kripto, gizli anahtarlar)
• SBOM oluşturma (CycloneDX, SPDX)
• Bağımlılık güvenlik açığı kontrolü (OSV)
• Lisans uyumluluk analizi
• Dairesel bağımlılık tespiti ile içe aktarma grafı
• Diller arası sembol çözümleme
• Merkle ağaçları ile artımlı dizinleme
• Dizin kalıcılığı
• Dosya değişiklikleri için izleme modu
• LSP entegrasyonu
• Uzak depo desteği
• Akış yanıtları

Yenilikler

v1.6.x (Güncel)

• Çökmeye dayanıklı parçalama - Çok baytlı UTF-8 karakterleri (emoji, CJK, aksanlı karakterler) içeren dosyalar işlenirken hybrid_search, search_chunks ve get_chunk_stats'in çökmesine neden olan chunk_file() ve extract_signature()'teki güvensiz bayt düzeyinde dize dilimleme düzeltildi. Tüm bayt dilimleme artık geri dönüşlü güvenli content.get() kullanıyor.
• NaN-güvenli sıralama işlemleri - partial_cmp().unwrap()'in NaN kayan nokta değerlerinde panik yaptığı arama, gömme, git, dizin ve çıkarma modüllerindeki 5 konum düzeltildi. Tüm sıralamalar artık unwrap_or(Ordering::Equal) kullanıyor.
• Derinlemesine savunma parçalama - Bir dosyadaki paniğin tüm MCP sunucusunu çökertmesi yerine atlaması için depo çapındaki tüm chunk_file() döngülerinin etrafına catch_unwind sarmalayıcıları eklendi.
• Görselleştirme ön yüz yenilemesi - HashRouter yönlendirme, dosya ağacı kenar çubuğu, sözdizimi vurgulu kod görüntüleyici, pano ve depo başına genel bakış sayfaları ile tam SPA
• Graf görünümü performansı - İçe aktarma grafı artık dosya sistemi yürümeleri yerine önbelleğe alınmış dizin verilerini kullanıyor; sembol grafı markdown gidiş-dönüşleri yerine doğrudan dosya önbelleğini yineliyor; tüm görünümler erken sonlandırma için max_nodes'e uyuyor
• Gerçek kontrol akış grafları - Akış görünümü artık tek bloklu taslak yerine uygun temel bloklar, dallanma koşulları ve döngü geri kenarları ile gerçek CFG oluşturucuyu (cfg::analyze_function) kullanıyor
• Hibrit graf bütçe bölme - Hibrit görünüm, dengeli sonuçlar için çağrı ve içe aktarma grafları arasında 60/40 düğüm bütçesi ayırıyor
• Düzeltme #14: yapılandırılabilir gömme boyutları - text-embedding-3-large gibi modellerin sabit kodlanmış 1536 yerine doğru boyutları (3072) kullanması için --neural-dimension CLI argümanı ve default_dimension_for_model() araması eklendi
• Düzeltme #13: Nix ön yüz derlemesi - nix profile install github:postrv/narsil-mcp#with-frontend'in çalışması için buildNpmPackage kullanarak flake.nix'e frontendDist türetimi eklendi
• Rust güvenlik kuralları - Komut enjeksiyonu, transmute, FFI sınırları, TOCTOU, ReDoS, static mut, SSRF ve daha fazlasını kapsayan 18 yeni kural (RUST-004 ila RUST-021)
• Elixir güvenlik kuralları - Atom tükenmesi, binary_to_term seri kaldırma, Code.eval enjeksiyonu, Ecto SQL enjeksiyonu, Phoenix XSS, Erlang dağıtım güvenliğini kapsayan 18 yeni kural (EX-001 ila EX-018)
• serde_yaml'ten serde-saphyr'e geçiş - Kullanımdan kaldırılan serde_yaml, aktif olarak bakımı yapılan, panik içermeyen YAML kütüphanesi ile değiştirildi
• Özel favicon - Ön yüz artık varsayılan Vite logosu yerine narsil-mcp marka simgesini kullanıyor
• Bağımlılık güvenliği - time 0.3.47'ye (RUSTSEC-2026-0009), bytes 1.11.1'e (RUSTSEC-2026-0007) güncellendi
• Test sayısı 1.611'den 1.763'e yükseldi (+152 test)

v1.5.x

• Deterministik çağrı grafı çözümlemesi - Kapsam ipucu yayılımı, çağrılan çözümlemesini netleştirir (örn., App::run() doğru şekilde src/app/mod.rs::run'a çözümlenir)
• 8 graf analizi düzeltmesi - Nitelikli düğüm anahtarları, etkin nokta filtreleme, CFG ifade işleme, içe aktarma yolu ayrıştırma
• Nix flake iyileştirmeleri - DRY mkPkg yardımcısı, gereksiz macOS çerçeveleri kaldırıldı, korumalı alan derlemeleri için --lib test stratejisi

v1.4.x

• SPARQL / RDF Bilgi Grafı - Oxigraph aracılığıyla SPARQL ile kod zekası verilerini sorgulayın
• Kod Bağlam Grafı (CCG) - Katmanlı seviyeler (L0-L3) ile standartlaştırılmış, AI tarafından tüketilebilir kod tabanı temsilleri için 12 araç
• Tür-farkında güvenlik analizi - Tür çıkarımı ve özellik uygulamaları ile gelişmiş leke takibi
• Çok dilli CFG/DFG - Kontrol akışı ve veri akışı analizi Go, Java, C#, Kotlin'e genişletildi
• Kod Olarak Altyapı taraması - Terraform, CloudFormation, Kubernetes için yeni iac.yaml kuralları
• Dile özgü güvenlik kuralları - Go, Java, C#, Kotlin, Bash için yeni kurallar
• 6 yeni dil - Erlang, Elm, Fortran, PowerShell, Nix, Groovy
• Toplam 90 araç - Yeni SPARQL, CCG ve analiz yetenekleriyle 79'dan yukarı

v1.2.x

• exclude_tests parametresi - 22 araç test dosyalarını filtrelemeyi destekler
• npm paketi - npm install -g narsil-mcp ile kurulum

v1.1.x

• Çok platformlu dağıtım - Homebrew, Scoop, npm, Cargo veya doğrudan indirme ile kurulum
• Yapılandırılabilir araç ön ayarları - Minimal, dengeli, tam ve güvenlik odaklı ön ayarlar
• Otomatik düzenleyici algılama - Zed, VS Code, Claude Desktop için optimal varsayılanlar
• Etkileşimli kurulum sihirbazı - Kolay yapılandırma için narsil-mcp config init
• 32 dil desteği - Dart, Julia, R, Perl, Zig ve daha fazlası eklendi
• İyileştirilmiş performans - Arka planda dizinleme ile daha hızlı başlangıç

v1.0.x

• Sinirsel anlamsal arama - Voyage AI veya OpenAI gömme vektörleri kullanarak benzer kod bulun
• Tür çıkarımı - Harici araçlar olmadan Python/JavaScript/TypeScript'te türleri çıkarın
• Çok dilli leke analizi - PHP, Java, C#, Ruby, Kotlin için güvenlik taraması
• WASM derlemesi - Kod oyun alanları ve eğitim araçları için tarayıcıda çalıştırın
• 147 paketlenmiş güvenlik kuralı - OWASP, CWE, kripto, gizli anahtarlar, Rust, Elixir tespiti
• IDE yapılandırmaları dahil - Claude Desktop, Cursor, VS Code, Zed şablonları

Lisans

Aşağıdakilerden biri altında lisanslanmıştır:

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

tercihinize bağlı olarak.

Katkıda Bulunanlar

Şunlarla inşa edildi:

• tree-sitter - Artımlı ayrıştırma
• tantivy - Tam metin arama
• tokio - Async çalışma zamanı
• rayon - Veri paralelliği
• serde - Serileştirme