Narsil MCP

narsil-mcp

Server MCP yang sangat cepat dan mengutamakan privasi untuk inteligensi kode mendalam

Server MCP (Model Context Protocol) yang dibangun dengan Rust, memberikan asisten AI pemahaman kode mendalam melalui 90 alat khusus.

Mengapa narsil-mcp?

Fitur	narsil-mcp	XRAY	Serena	GitHub MCP
Bahasa	32	4	30+ (LSP)	N/A
Pencarian Neural	Ya	Tidak	Tidak	Tidak
Analisis Taint	Ya	Tidak	Tidak	Tidak
SBOM/Lisensi	Ya	Tidak	Tidak	Sebagian
Offline/Lokal	Ya	Ya	Ya	Tidak
WASM/Browser	Ya	Tidak	Tidak	Tidak
Grafik Panggilan	Ya	Sebagian	Tidak	Tidak
Inferensi Tipe	Ya	Tidak	Tidak	Tidak

Fitur Utama

• Inteligensi Kode - Ekstraksi simbol, pencarian semantik, analisis grafik panggilan
• Pencarian Semantik Neural - Temukan kode serupa menggunakan embeddings (Voyage AI, OpenAI)
• Analisis Keamanan - Analisis taint, pemindaian kerentanan, cakupan OWASP/CWE
• Keamanan Rantai Pasokan - Pembuatan SBOM, audit dependensi, kepatuhan lisensi
• Analisis Lanjutan - Grafik aliran kontrol, analisis aliran data, deteksi kode mati

Mengapa Memilih narsil-mcp?

• Ditulis dalam Rust - Sangat cepat, aman memori, biner tunggal (~30MB)
• Didukung Tree-sitter - Parsing inkremental yang akurat untuk 32 bahasa
• Tanpa konfigurasi - Arahkan ke repositori dan jalankan
• Kompatibel MCP - Bekerja dengan Claude, Cursor, VS Code Copilot, Zed, dan klien MCP lainnya
• Mengutamakan privasi - Sepenuhnya lokal, tidak ada data yang meninggalkan mesin Anda
• Indeksasi paralel - Menggunakan semua inti melalui Rayon
• Kutipan cerdas - Memperluas ke cakupan sintaksis lengkap
• Mengutamakan keamanan - Deteksi kerentanan dan analisis taint bawaan
• Embeddings neural - Pencarian semantik opsional dengan Voyage AI atau OpenAI
• Dukungan WASM - Jalankan di browser dengan build WebAssembly
• Streaming waktu nyata - Hasil muncul seiring indeksasi berjalan untuk repositori besar

Bahasa yang Didukung

Bahasa	Ekstensi	Simbol yang Diekstrak
Rust	.rs	fungsi, struct, enum, trait, impl, mod
Python	.py, .pyi	fungsi, kelas
JavaScript	.js, .jsx, .mjs	fungsi, kelas, metode, variabel
TypeScript	.ts, .tsx	fungsi, kelas, antarmuka, tipe, enum
Go	.go	fungsi, metode, tipe
C	.c, .h	fungsi, struct, enum, typedef
C++	.cpp, .cc, .hpp	fungsi, kelas, struct, namespace
Java	.java	metode, kelas, antarmuka, enum
C#	.cs	metode, kelas, antarmuka, struct, enum, delegasi, namespace
Bash	.sh, .bash, .zsh	fungsi, variabel
Ruby	.rb, .rake, .gemspec	metode, kelas, modul
Kotlin	.kt, .kts	fungsi, kelas, objek, antarmuka
PHP	.php, .phtml	fungsi, metode, kelas, antarmuka, trait
Swift	.swift	kelas, struct, enum, protokol, fungsi
Verilog/SystemVerilog	.v, .vh, .sv, .svh	modul, tugas, fungsi, antarmuka, kelas
Scala	.scala, .sc	kelas, objek, trait, fungsi, val
Lua	.lua	fungsi, metode
Haskell	.hs, .lhs	fungsi, tipe data, kelas tipe
Elixir	.ex, .exs	modul, fungsi
Clojure	.clj, .cljs, .cljc, .edn	daftar (AST dasar)
Dart	.dart	fungsi, kelas, metode
Julia	.jl	fungsi, modul, struct
R	.R, .r, .Rmd	fungsi
Perl	.pl, .pm, .t	fungsi, paket
Zig	.zig	fungsi, variabel
Erlang	.erl, .hrl	fungsi, modul, record
Elm	.elm	fungsi, tipe
Fortran	.f90, .f95, .f03, .f08, .f, .for, .fpp	program, subrutin, fungsi, modul
PowerShell	.ps1, .psm1, .psd1	fungsi, kelas, enum
Nix	.nix	binding
Groovy	.groovy, .gradle	metode, kelas, antarmuka, enum, fungsi

Instalasi

Melalui Manajer Paket (Direkomendasikan)

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 (semua platform):

cargo install narsil-mcp

Node.js/npm (semua platform):

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

Skrip Instalasi Sekali Klik

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

Catatan untuk pengguna Windows: Penginstal PowerShell memberikan pesan kesalahan yang lebih baik dan integrasi Windows asli. Penginstal ini akan mengonfigurasi PATH Anda secara otomatis dan memeriksa alat build yang diperlukan jika membangun dari sumber.

Dari Sumber

Prasyarat:

• Rust stabil saat ini (rilis ini diverifikasi dengan Rust 1.98 dan 1.99)
• Di Windows: Visual Studio Build Tools dengan "Pengembangan desktop dengan 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

Build Fitur

narsil-mcp mendukung berbagai set fitur untuk berbagai kasus penggunaan:

# 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

Fitur	Deskripsi	Ukuran
native (default)	Server MCP lengkap dengan semua alat	~30MB
graph	+ Grafik pengetahuan RDF, SPARQL, alat CCG	~35MB
frontend	+ UI web visualisasi tertanam	~31MB
neural	+ Pencarian vektor TF-IDF, embeddings API	~32MB
neural-onnx	+ Inferensi model ONNX lokal	~50MB
wasm	Build sumber browser eksperimental (tanpa sistem file, git)	Tidak memenuhi syarat rilis

Penting: Bendera CLI --graph memerlukan biner yang dibangun dengan --features graph. Jika Anda meneruskan --graph ke biner yang dibangun tanpa fitur ini, Anda akan melihat peringatan dan alat SPARQL/CCG tidak akan tersedia. Lihat Pemecahan Masalah di bawah.

Untuk instruksi instalasi terperinci, pemecahan masalah, dan panduan khusus platform, lihat docs/INSTALL.md.

Penggunaan

Penggunaan Dasar

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

Set Fitur Lengkap

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)

Catatan tentang --graph: Bendera ini mengaktifkan kueri SPARQL dan alat Code Context Graph (CCG), tetapi hanya jika biner dibangun dengan --features graph. Biner default tidak menyertakan fitur ini. Jika Anda memerlukan kemampuan SPARQL/CCG, bangun dari sumber dengan:

cargo build --release --features graph

Jika Anda meneruskan --graph ke biner tanpa fitur tersebut, Anda akan melihat peringatan saat startup dan server akan berlanjut tanpa alat SPARQL/CCG.

Catatan: Embeddings neural memerlukan kunci API (atau endpoint kustom). Cara termudah untuk mengaturnya adalah dengan wizard interaktif:

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

Wizard akan:

• Mendeteksi editor Anda (Claude Desktop, Claude Code, Zed, VS Code, JetBrains)
• Meminta penyedia API Anda (Voyage AI, OpenAI, atau kustom)
• Memvalidasi kunci API Anda
• Menambahkannya secara otomatis ke konfigurasi MCP editor Anda

Alternatifnya, Anda dapat mengatur salah satu variabel lingkungan berikut secara manual:

• EMBEDDING_API_KEY - Kunci API generik untuk penyedia mana pun
• VOYAGE_API_KEY - Kunci API khusus Voyage AI
• OPENAI_API_KEY - Kunci API khusus OpenAI
• EMBEDDING_SERVER_ENDPOINT - URL endpoint API embedding kustom (opsional, memungkinkan penggunaan model yang dihosting sendiri)

Konfigurasi

v1.1.0+ memperkenalkan konfigurasi opsional untuk kontrol yang lebih terperinci atas alat dan kinerja. Semua penggunaan yang ada tetap berfungsi - konfigurasi sepenuhnya opsional!

Mulai Cepat

# 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

Deteksi Editor Otomatis

narsil-mcp mendeteksi editor Anda dan menerapkan preset optimal secara otomatis:

Editor	Preset	Alat	Token Konteks	Alasan
Zed	Minimal	26	~4.686	Startup cepat, konteks minimal
VS Code	Seimbang	51	~8.948	Keseimbangan fitur yang baik
Claude Desktop	Lengkap	90	~12.001	Kemampuan maksimal

Penghematan Token:

• Preset Minimal: 61% lebih sedikit token vs Lengkap
• Preset Seimbang: 25% lebih sedikit token vs Lengkap

Preset

Pilih preset berdasarkan kasus penggunaan Anda:

# 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

File Konfigurasi

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

Konfigurasi proyek (.narsil.yaml di root repositori):

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

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

Profil repositori bernama berguna untuk ruang kerja multi-repositori:

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

Prioritas: Bendera CLI > Variabel lingkungan > Konfigurasi proyek > Konfigurasi pengguna > Default

Variabel Lingkungan

# 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

Perintah CLI

# View effective config
narsil-mcp config show

# Validate config file
narsil-mcp config validate ~/.config/narsil-mcp/config.yaml

# List tools by category
narsil-mcp tools list --category Search

# Search for tools
narsil-mcp tools search "git"

# Export config
narsil-mcp config export > my-config.yaml

# List named repository profiles
narsil-mcp config profiles

Pelajari Lebih Lanjut:

• Panduan Konfigurasi - Referensi konfigurasi lengkap
• Panduan Instalasi - Instalasi khusus platform

Frontend Visualisasi

Jelajahi grafik panggilan, impor, referensi simbol, dan aliran kontrol secara interaktif di browser Anda.

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

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

Lima tampilan grafik:

Tampilan	Deskripsi
Grafik Panggilan	Hubungan panggilan fungsi dengan kontrol kedalaman dan pemfilteran arah
Grafik Impor	Dependensi impor tingkat file di seluruh basis kode
Grafik Simbol	Semua referensi ke suatu simbol, dengan pengelompokan file
Hibrida	Gabungan grafik panggilan + impor dengan anggaran terpisah
Aliran Kontrol	CFG nyata dengan blok dasar, cabang, dan tepi kembali loop

Fitur:

• Grafik Cytoscape.js interaktif dengan seret, zoom, dan penelusuran klik dua kali
• Hamparan metrik kompleksitas dengan kode warna (hijau/kuning/oranye/merah)
• Hamparan kerentanan keamanan yang menyoroti sumber dan tujuan taint
• Enam algoritma tata letak (dagre, force-directed, breadthfirst, concentric, circle, grid)
• Bilah sisi pohon file dengan penampil kode yang disorot sintaksis
• Status berbasis URL (tautan yang dapat dibagikan, tombol kembali/maju browser)
• Dukungan mode gelap
• Panel detail node dengan kutipan kode dan navigasi ke sumber

Dokumentasi lengkap: Lihat docs/frontend.md untuk pengaturan, endpoint API, dan mode pengembangan.

Pencarian Semantik Neural

Temukan kode serupa menggunakan embeddings neural - bahkan ketika nama variabel dan struktur berbeda.

# 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

Mendukung Voyage AI, OpenAI, endpoint kustom, dan model ONNX lokal.

Dokumentasi lengkap: Lihat docs/neural-search.md untuk pengaturan, backend, dan kasus penggunaan.

Inferensi Tipe

Inferensi tipe bawaan untuk Python, JavaScript, dan TypeScript - tanpa memerlukan mypy atau tsc.

Alat	Deskripsi
infer_types	Dapatkan tipe yang diinferensikan untuk semua variabel dalam suatu fungsi
check_type_errors	Temukan ketidakcocokan tipe potensial
get_typed_taint_flow	Analisis keamanan yang ditingkatkan dengan informasi tipe

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

Integrasi Forgemax (Eksperimental)

Untuk alur kerja agen skala besar, narsil-mcp dapat digunakan melalui Forgemax — gateway MCP Code Mode yang menggabungkan semua 90 alat menjadi hanya 2 (search + execute), mengurangi overhead skema alat dari ~12.000 token menjadi ~1.000.

# Install Forgemax
cargo install forgemax

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

forge.toml yang disertakan mengonfigurasi narsil-mcp dengan default yang masuk akal:

[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 menulis JavaScript yang memanggil melalui objek proxy bertipe di dalam isolate V8 yang disandbox — kredensial, jalur file, dan status internal tidak pernah meninggalkan host. Pendekatan ini sangat berguna saat bekerja dengan beberapa server MCP secara bersamaan, karena menjaga konteks alat secara keseluruhan tetap kecil dan dapat diprediksi.

Konfigurasi MCP

Tambahkan narsil-mcp ke asisten AI Anda dengan membuat file konfigurasi. Berikut adalah pengaturan yang direkomendasikan:

---

Claude Code (.mcp.json di root proyek - Direkomendasikan):

Buat .mcp.json di direktori proyek Anda untuk konfigurasi per-proyek:

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

Kemudian mulai Claude Code di proyek Anda:

cd /path/to/project
claude

Menggunakan . untuk --repos secara otomatis mengindeks direktori saat ini. Claude sekarang memiliki akses ke 90 alat intelijen kode.

Tip: Tambahkan --persist --index-path .claude/cache untuk startup yang lebih cepat pada proses berikutnya.

Untuk konfigurasi global, edit ~/.claude/settings.json sebagai gantinya. Lihat Integrasi Claude Code untuk pengaturan lanjutan.

---

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

Catatan untuk Copilot Enterprise: Dukungan MCP memerlukan VS Code 1.102+ dan harus diaktifkan oleh administrator organisasi Anda.

---

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

Catatan untuk Zed: narsil-mcp dimulai segera dan mengindeks di latar belakang, mencegah timeout inisialisasi.

---

Plugin Claude Code

Untuk pengguna Claude Code, kami menyediakan plugin dengan perintah slash dan skill untuk penggunaan alat yang efektif.

Instal melalui Marketplace (Direkomendasikan):

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

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

Atau instal langsung dari GitHub:

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

Yang termasuk:

Komponen	Deskripsi
/narsil:security-scan	Jalankan audit keamanan yang komprehensif
/narsil:explore	Jelajahi codebase yang tidak dikenal
/narsil:analyze-function	Pendalaman pada fungsi tertentu
/narsil:find-feature	Temukan di mana fitur diimplementasikan
/narsil:supply-chain	Analisis keamanan rantai pasokan
Skill	Memandu Claude dalam menggunakan 90 alat secara efektif
Konfigurasi MCP	Memulai narsil-mcp secara otomatis dengan pengaturan default yang masuk akal

Lihat narsil-plugin/README.md untuk dokumentasi lengkap.

Integrasi Ralph Automation

Ralph adalah suite otomasi Claude Code untuk pengembangan kode otonom. Saat narsil-mcp tersedia, Ralph mendapatkan kemampuan intelijen kode yang ditingkatkan:

Fitur	Tanpa narsil-mcp	Dengan narsil-mcp
Pemindaian keamanan	Dasar (clippy)	Deteksi kerentanan OWASP/CWE
Pemahaman kode	Berbasis file	Grafik panggilan, referensi simbol
Analisis arsitektur	Manual	Lapisan otomatis CCG L0/L1/L2
Analisis dependensi	cargo tree	Grafik impor, deteksi sirkular

Pengaturan:

# 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 menurun secara anggun saat narsil-mcp tidak tersedia - semua fitur otomasi inti tetap berfungsi tanpanya.

Dokumentasi: Lihat Ralph README untuk detail integrasi lengkap.

Playbooks & Tutorial

Lihat docs/playbooks untuk panduan penggunaan praktis:

Panduan	Deskripsi
Memulai	Pengaturan cepat dan panggilan alat pertama
Memahami Codebase	Jelajahi proyek yang tidak dikenal
Perbaiki Bug	Debug dengan grafik panggilan dan analisis taint
Audit Keamanan	Temukan kerentanan dengan pemindaian OWASP/CWE
Tinjauan Kode	Tinjau perubahan secara efektif

Setiap playbook menunjukkan rantai alat yang tepat yang digunakan Claude untuk menjawab pertanyaan Anda.

Penggunaan WebAssembly (Browser)

Repositori berisi sumber WebAssembly eksperimental dan skrip build lokal. @narsil-mcp/wasm tidak dipublikasikan di npm dan bukan saluran distribusi untuk rilis CLI 1.7.1. Build WASM dan contohnya tidak tercakup dalam kualifikasi rilisnya. Lihat docs/wasm.md untuk alur kerja sumber eksperimental.

Alat yang Tersedia (93)

Manajemen Repositori & File

Alat	Deskripsi
list_repos	Daftar semua repositori yang diindeks dengan metadata
get_project_structure	Dapatkan pohon direktori dengan ikon file dan ukuran
get_file	Dapatkan isi file dengan rentang baris opsional
get_excerpt	Ekstrak kode di sekitar baris tertentu dengan konteks
reindex	Picu pengindeksan ulang repositori
discover_repos	Temukan repositori secara otomatis di direktori
validate_repo	Periksa apakah jalur adalah repositori yang valid
get_index_status	Tampilkan statistik indeks dan fitur yang diaktifkan

Pencarian & Navigasi Simbol

Alat	Deskripsi
find_symbols	Temukan struct, kelas, fungsi berdasarkan tipe/pola
get_symbol_definition	Dapatkan sumber simbol dengan konteks sekitarnya
find_references	Temukan semua referensi ke simbol
get_dependencies	Analisis impor dan dependensi
workspace_symbol_search	Pencarian fuzzy simbol di seluruh workspace
find_symbol_usages	Penggunaan simbol lintas file dengan impor
get_export_map	Dapatkan simbol yang diekspor dari file/modul

Pencarian Kode

Alat	Deskripsi
search_code	Pencarian kata kunci dengan peringkat relevansi
semantic_search	Pencarian semantik dengan peringkat BM25
hybrid_search	Gabungan BM25 + TF-IDF dengan fusi peringkat
search_chunks	Pencarian atas potongan kode yang sadar-AST
find_similar_code	Temukan kode yang mirip dengan cuplikan (TF-IDF)
find_similar_to_symbol	Temukan kode yang mirip dengan simbol

Pemotongan Sadar-AST

Alat	Deskripsi
get_chunks	Dapatkan potongan sadar-AST untuk file
get_chunk_stats	Statistik tentang potongan kode
get_embedding_stats	Statistik indeks embedding

Pencarian Semantik Neural (memerlukan --neural)

Alat	Deskripsi
neural_search	Pencarian semantik menggunakan embedding neural (menemukan kode serupa bahkan dengan nama berbeda)
find_semantic_clones	Temukan klon semantik Tipe-3/4 dari fungsi
get_neural_stats	Statistik indeks embedding neural

Analisis Grafik Panggilan (memerlukan --call-graph)

Alat	Deskripsi
get_call_graph	Dapatkan grafik panggilan untuk repositori/fungsi
get_callers	Temukan fungsi yang memanggil fungsi
get_callees	Temukan fungsi yang dipanggil oleh fungsi
find_call_path	Temukan jalur antara dua fungsi
get_complexity	Dapatkan kompleksitas sikomatik/kognitif
get_function_hotspots	Temukan fungsi yang sangat terhubung

Analisis Aliran Kontrol

Alat	Deskripsi
get_control_flow	Dapatkan CFG yang menunjukkan blok dasar dan cabang
find_dead_code	Temukan blok kode yang tidak dapat dijangkau

Analisis Aliran Data

Alat	Deskripsi
get_data_flow	Definisi dan penggunaan variabel
get_reaching_definitions	Penugasan mana yang mencapai setiap titik
find_uninitialized	Variabel yang digunakan sebelum inisialisasi
find_dead_stores	Penugasan yang tidak pernah dibaca

Inferensi Tipe (Python/JavaScript/TypeScript)

Alat	Deskripsi
infer_types	Inferensi tipe untuk variabel dalam fungsi tanpa pemeriksa tipe eksternal
check_type_errors	Temukan potensi kesalahan tipe tanpa menjalankan mypy/tsc
get_typed_taint_flow	Analisis taint yang ditingkatkan menggabungkan aliran data dengan inferensi tipe

Grafik Impor/Dependensi

Alat	Deskripsi
get_import_graph	Bangun dan analisis grafik impor
find_circular_imports	Deteksi dependensi sirkular
get_incremental_status	Pohon Merkle dan statistik perubahan

Analisis Keamanan - Pelacakan Taint

Alat	Deskripsi
find_injection_vulnerabilities	Temukan SQL injection, XSS, command injection, path traversal
trace_taint	Lacak aliran data yang terkontaminasi dari sumber
get_taint_sources	Daftar sumber taint (input pengguna, file, jaringan)
get_security_summary	Penilaian risiko keamanan yang komprehensif

Analisis Keamanan - Mesin Aturan

Alat	Deskripsi
scan_security	Pindai dengan aturan keamanan (OWASP, CWE, kripto, rahasia)
check_owasp_top10	Pindai kerentanan OWASP Top 10 2021
check_cwe_top25	Pindai kelemahan CWE Top 25
explain_vulnerability	Dapatkan penjelasan kerentanan yang terperinci
suggest_fix	Dapatkan saran perbaikan untuk temuan

Keamanan Rantai Pasokan

Alat	Deskripsi
generate_sbom	Hasilkan SBOM (CycloneDX/SPDX/JSON)
check_dependencies	Periksa kerentanan yang diketahui (database OSV)
check_licenses	Analisis lisensi untuk masalah kepatuhan
find_upgrade_path	Temukan jalur peningkatan yang aman untuk dependensi rentan

Integrasi Git (memerlukan --git)

Alat	Deskripsi
get_blame	Git blame untuk file
get_file_history	Riwayat commit untuk file
get_recent_changes	Commit terbaru di repositori
get_hotspots	File dengan churn dan kompleksitas tinggi
get_contributors	Kontributor repositori/file
get_commit_diff	Diff untuk commit tertentu
get_symbol_history	Commit yang mengubah simbol
get_branch_info	Cabang dan status saat ini
get_modified_files	Perubahan pohon kerja

Integrasi LSP (memerlukan --lsp)

Alat	Deskripsi
get_hover_info	Info tipe dan dokumentasi
get_type_info	Informasi tipe yang presisi
go_to_definition	Temukan lokasi definisi

Dukungan Repositori Jarak Jauh (memerlukan --remote)

Alat	Deskripsi
add_remote_repo	Klon dan indeks repositori GitHub
list_remote_files	Daftar file melalui GitHub API
get_remote_file	Ambil file melalui GitHub API

Metrik

Alat	Deskripsi
get_metrics	Statistik kinerja dan waktu

SPARQL / Knowledge Graph (memerlukan --graph)

Alat	Deskripsi
sparql_query	Jalankan kueri SPARQL terhadap knowledge graph RDF
list_sparql_templates	Daftar template kueri SPARQL yang tersedia
run_sparql_template	Jalankan template SPARQL yang telah ditentukan dengan parameter

Grafik Konteks Kode (CCG) (memerlukan --graph)

CCG menyediakan representasi codebase yang terstandarisasi dan dapat dikonsumsi AI dalam lapisan berjenjang.

Alat	Deskripsi
get_ccg_manifest	Manifest Layer 0 (~1-2KB JSON-LD) - identitas repositori, jumlah
export_ccg_manifest	Ekspor manifest Layer 0 ke file
export_ccg_architecture	Arsitektur Layer 1 (~10-50KB JSON-LD) - modul, API
export_ccg_index	Indeks simbol Layer 2 (~100-500KB N-Quads gzip)
export_ccg_full	Detail lengkap Layer 3 (~1-20MB N-Quads gzip)
export_ccg	Ekspor semua lapisan CCG sebagai bundel
query_ccg	Kueri CCG menggunakan SPARQL
get_ccg_acl	Hasilkan kontrol akses WebACL untuk lapisan CCG
get_ccg_access_info	Dapatkan informasi tingkat akses CCG
import_ccg	Impor lapisan CCG dari URL atau file
import_ccg_from_registry	Impor CCG dari registry codecontextgraph.com

Aturan Keamanan

narsil-mcp menyertakan aturan keamanan bawaan di rules/:

Ruleset Inti:

• owasp-top10.yaml - Pola kerentanan OWASP Top 10 2021
• cwe-top25.yaml - CWE Top 25 Kelemahan Paling Berbahaya
• crypto.yaml - Masalah kriptografi (algoritma lemah, kunci hardcoded)
• secrets.yaml - Deteksi rahasia (API key, kata sandi, token) Aturan Khusus Bahasa:
• rust.yaml - Pola keamanan Rust (unsafe transmute, batas FFI, injeksi perintah, TOCTOU)
• elixir.yaml - Pola Elixir/BEAM (kehabisan atom, binary_to_term, Code.eval, injeksi SQL Ecto)
• go.yaml - Pola keamanan Go (injeksi SQL, TLS, injeksi perintah)
• java.yaml - Kerentanan Java (XXE, deserialisasi, injeksi LDAP)
• csharp.yaml - Masalah keamanan C# (deserialisasi, XSS, path traversal)
• kotlin.yaml - Pola Kotlin/Android (WebView, intent, rahasia)
• bash.yaml - Kerentanan skrip Shell (injeksi perintah, eval)

Infrastruktur & Konfigurasi:

• iac.yaml - Infrastruktur sebagai Kode (Terraform, CloudFormation, Kubernetes)
• config.yaml - Keamanan file konfigurasi (kredensial hardcoded, pengaturan tidak aman)

Aturan kustom dapat dimuat dengan scan_security --ruleset /path/to/rules.yaml.

Arsitektur

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

Performa

Diuji pada Apple M1 (criterion.rs):

Throughput Parsing

Bahasa	Ukuran Input	Waktu	Throughput
Rust (file besar)	278 KB	131 µs	1.98 GiB/s
Rust (file sedang)	27 KB	13.5 µs	1.89 GiB/s
Python	~4 KB	16.7 µs	-
TypeScript	~5 KB	13.9 µs	-
Campuran (5 file)	~15 KB	57 µs	-

Latensi Pencarian

Operasi	Ukuran Korpus	Waktu
Pencocokan tepat simbol	1.000 simbol	483 ns
Pencocokan awalan simbol	1.000 simbol	2.7 µs
Pencocokan fuzzy simbol	1.000 simbol	16.5 µs
Teks lengkap BM25	1.000 dokumen	80 µs
Kemiripan TF-IDF	1.000 dokumen	130 µs
Hibrida (BM25+TF-IDF)	1.000 dokumen	151 µs

Pengindeksan Ujung-ke-Ujung

Repositori	File	Simbol	Waktu	Memori
narsil-mcp (repo ini)	53	1.733	220 ms	~50 MB
rust-analyzer	2.847	~50K	2.1s	89 MB
kernel linux	78.000+	~500K	45s	2.1 GB

Metrik utama:

• Parsing Tree-sitter: ~2 GiB/s throughput berkelanjutan
• Pencarian simbol: <1µs untuk pencocokan tepat
• Pencarian teks lengkap: <1ms untuk sebagian besar kueri
• Pencarian hibrida menjalankan BM25 + TF-IDF secara paralel melalui rayon

Pengembangan

# 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

Pemecahan Masalah

Kesalahan Build Tree-sitter

Jika Anda melihat kesalahan tentang kompiler C yang hilang atau tree-sitter selama build:

# macOS
xcode-select --install

# Ubuntu/Debian
sudo apt install build-essential

# For WASM builds
brew install emscripten  # macOS

Kesalahan API Pencarian Neural

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

Indeks Tidak Menemukan File

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

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

Masalah Memori dengan Repo Besar

# 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

Fitur Grafik Tidak Berfungsi

Jika Anda meneruskan --graph dan melihat peringatan seperti:

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

Ini berarti Anda menggunakan biner yang tidak dikompilasi dengan fitur graph. Untuk memperbaiki:

# 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

Mengapa ini fitur terpisah? Fitur graph menambahkan database RDF Oxigraph (~5MB ukuran biner tambahan) yang tidak diperlukan untuk sebagian besar kasus penggunaan. Fitur ini dibuat opsional untuk menjaga biner default tetap lebih kecil.

Cara memeriksa apakah grafik diaktifkan: Lihat log startup:

• graph=true berarti fitur dikompilasi DAN diaktifkan
• graph=false berarti fitur tidak dikompilasi, ATAU --graph tidak diteruskan

Peta Jalan

Selesai

• Ekstraksi simbol multi-bahasa (32 bahasa)
• Pencarian teks lengkap dengan Tantivy (peringkat BM25)
• Pencarian hibrida (BM25 + TF-IDF dengan RRF)
• Pemotongan kode sadar-AST
• Integrasi git blame/sejarah
• Analisis grafik panggilan dengan metrik kompleksitas
• Analisis grafik aliran kontrol (CFG)
• Analisis aliran data (DFG) dengan definisi yang menjangkau
• Deteksi kode mati dan penyimpanan mati
• Analisis taint untuk kerentanan injeksi
• Mesin aturan keamanan (OWASP, CWE, kripto, rahasia)
• Pembuatan SBOM (CycloneDX, SPDX)
• Pemeriksaan kerentanan dependensi (OSV)
• Analisis kepatuhan lisensi
• Grafik impor dengan deteksi dependensi sirkular
• Resolusi simbol lintas bahasa
• Pengindeksan inkremental dengan pohon Merkle
• Persistensi indeks
• Mode pantau untuk perubahan file
• Integrasi LSP
• Dukungan repositori jarak jauh
• Respons streaming

Yang Baru

v1.6.x (Saat Ini)

• Pemotongan tahan-kecelakaan - Memperbaiki pemotongan string byte-level yang tidak aman di chunk_file() dan extract_signature() yang menyebabkan hybrid_search, search_chunks, dan get_chunk_stats mogok saat memproses file dengan karakter UTF-8 multi-byte (emoji, CJK, karakter beraksen). Semua pemotongan byte sekarang menggunakan content.get() yang aman dengan fallback.
• Operasi pengurutan aman-NaN - Memperbaiki 5 lokasi di modul pencarian, embeddings, git, indeks, dan ekstrak di mana partial_cmp().unwrap() akan panik pada nilai float NaN. Semua pengurutan sekarang menggunakan unwrap_or(Ordering::Equal).
• Pemotongan pertahanan berlapis - Menambahkan pembungkus catch_unwind di sekitar semua loop chunk_file() di seluruh repo sehingga panic di satu file melewatkannya alih-alih membuat seluruh server MCP mogok.
• Perombakan frontend visualisasi - SPA lengkap dengan routing HashRouter, sidebar pohon file, penampil kode dengan penyorotan sintaks, dasbor, dan halaman ringkasan per-repo
• Performa tampilan grafik - Grafik impor sekarang menggunakan data indeks cache alih-alih penelusuran filesystem; grafik simbol mengiterasi cache file secara langsung alih-alih round-trip markdown; semua tampilan menghormati max_nodes untuk penghentian awal
• Grafik aliran kontrol nyata - Tampilan aliran sekarang menggunakan pembangun CFG nyata (cfg::analyze_function) dengan blok dasar yang tepat, kondisi cabang, dan tepi kembali loop alih-alih stub blok tunggal
• Pembagian anggaran grafik hibrida - Tampilan hibrida mengalokasikan anggaran node 60/40 antara grafik panggilan dan impor untuk hasil yang seimbang
• Perbaikan #14: dimensi embedding yang dapat dikonfigurasi - Menambahkan argumen CLI --neural-dimension dan pencarian default_dimension_for_model() sehingga model seperti text-embedding-3-large menggunakan dimensi yang benar (3072) alih-alih 1536 yang di-hardcode
• Perbaikan #13: build frontend Nix - Menambahkan derivasi frontendDist di flake.nix menggunakan buildNpmPackage sehingga nix profile install github:postrv/narsil-mcp#with-frontend berfungsi
• Aturan keamanan Rust - 18 aturan baru (RUST-004 hingga RUST-021) yang mencakup injeksi perintah, transmute, batas FFI, TOCTOU, ReDoS, static mut, SSRF, dan lainnya
• Aturan keamanan Elixir - 18 aturan baru (EX-001 hingga EX-018) yang mencakup kehabisan atom, deserialisasi binary_to_term, injeksi Code.eval, injeksi SQL Ecto, XSS Phoenix, keamanan distribusi Erlang
• Migrasi dari serde_yaml ke serde-saphyr - serde_yaml yang tidak digunakan lagi diganti dengan pustaka YAML yang dipelihara secara aktif dan bebas-panic
• Favicon kustom - Frontend sekarang menggunakan ikon branding narsil-mcp alih-alih logo Vite default
• Keamanan dependensi - Memperbarui time ke 0.3.47 (RUSTSEC-2026-0009), bytes ke 1.11.1 (RUSTSEC-2026-0007)
• Jumlah pengujian meningkat dari 1.611 menjadi 1.763 (+152 pengujian)

v1.5.x

• Resolusi grafik panggilan deterministik - Propagasi petunjuk lingkup mendisambiguasi resolusi callee (misalnya, App::run() diselesaikan dengan benar ke src/app/mod.rs::run)
• 8 perbaikan analisis grafik - Kunci node yang memenuhi syarat, pemfilteran hotspot, penanganan ekspresi CFG, penguraian jalur impor
• Peningkatan flake Nix - Helper mkPkg yang DRY, menghapus framework macOS yang tidak perlu, strategi pengujian --lib untuk build sandbox

v1.4.x

• Grafik Pengetahuan SPARQL / RDF - Kueri data intelijen kode dengan SPARQL melalui Oxigraph
• Grafik Konteks Kode (CCG) - 12 alat untuk representasi basis kode standar yang dapat dikonsumsi AI dengan lapisan berjenjang (L0-L3)
• Analisis keamanan sadar-tipe - Pelacakan taint yang ditingkatkan dengan inferensi tipe dan implementasi trait
• CFG/DFG multi-bahasa - Analisis aliran kontrol dan aliran data diperluas ke Go, Java, C#, Kotlin
• Pemindaian Infrastruktur sebagai Kode - Aturan iac.yaml baru untuk Terraform, CloudFormation, Kubernetes
• Aturan keamanan khusus bahasa - Aturan baru untuk Go, Java, C#, Kotlin, Bash
• 6 bahasa baru - Erlang, Elm, Fortran, PowerShell, Nix, Groovy
• 90 alat total - Naik dari 79 dengan kemampuan SPARQL, CCG, dan analisis baru

v1.2.x

• Parameter exclude_tests - 22 alat mendukung pemfilteran file pengujian
• Paket npm - Instal melalui npm install -g narsil-mcp

v1.1.x

• Distribusi multi-platform - Instal melalui Homebrew, Scoop, npm, Cargo, atau unduhan langsung
• Pratentukan alat yang dapat dikonfigurasi - Pratentukan minimal, seimbang, lengkap, dan fokus keamanan
• Deteksi editor otomatis - Default optimal untuk Zed, VS Code, Claude Desktop
• Wizard pengaturan interaktif - narsil-mcp config init untuk konfigurasi mudah
• Dukungan 32 bahasa - Menambahkan Dart, Julia, R, Perl, Zig, dan lainnya
• Peningkatan performa - Startup lebih cepat dengan pengindeksan latar belakang

v1.0.x

• Pencarian semantik neural - Temukan kode serupa menggunakan embeddings Voyage AI atau OpenAI
• Inferensi tipe - Infer tipe di Python/JavaScript/TypeScript tanpa alat eksternal
• Analisis taint multi-bahasa - Pemindaian keamanan untuk PHP, Java, C#, Ruby, Kotlin
• Build WASM - Jalankan di browser untuk taman bermain kode dan alat pendidikan
• 147 aturan keamanan bawaan - Deteksi OWASP, CWE, kripto, rahasia, Rust, Elixir
• Konfigurasi IDE disertakan - Template Claude Desktop, Cursor, VS Code, Zed

Lisensi

Dilisensikan di bawah salah satu dari:

• Lisensi Apache, Versi 2.0 (LICENSE-APACHE atau http://www.apache.org/licenses/LICENSE-2.0)
• Lisensi MIT (LICENSE-MIT atau http://opensource.org/licenses/MIT)

sesuai pilihan Anda.

Kredit

Dibangun dengan:

• tree-sitter - Parsing inkremental
• tantivy - Pencarian teks lengkap
• tokio - Runtime asinkron
• rayon - Paralelisme data
• serde - Serialisasi