Narsil MCP

narsil-mcp

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

Server MCP (Model Context Protocol) bertenaga Rust yang menyediakan pemahaman kode mendalam bagi asisten AI 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

• Kecerdasan Kode - Ekstraksi simbol, pencarian semantik, analisis grafik panggilan
• Pencarian Semantik Neural - Temukan kode serupa menggunakan embedding (Voyage AI, OpenAI)
• Analisis Keamanan - Analisis taint, pemindaian kerentanan, cakupan OWASP/CWE
• Keamanan Rantai Pasok - 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 akurat dan inkremental untuk 32 bahasa
• Tanpa konfigurasi - Arahkan ke repositori dan jalankan
• Sesuai MCP - Bekerja dengan Claude, Cursor, VS Code Copilot, Zed, dan klien MCP apa pun
• Mengutamakan privasi - Sepenuhnya lokal, tidak ada data yang meninggalkan mesin Anda
• Pengindeksan paralel - Menggunakan semua inti melalui Rayon
• Kutipan cerdas - Memperluas ke cakupan sintaksis lengkap
• Mengutamakan keamanan - Deteksi kerentanan dan analisis taint bawaan
• Embedding neural - Pencarian semantik opsional dengan Voyage AI atau OpenAI
• Dukungan WASM - Berjalan di browser dengan build WebAssembly
• Streaming waktu nyata - Hasil seiring berjalannya pengindeksan untuk repositori besar

Bahasa yang Didukung

Bahasa	Ekstensi	Simbol yang Diekstrak
Rust	.rs	fungsi, struct, enum, trait, impl, modul
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, delegat, 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 Instal 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 menyediakan pesan kesalahan yang lebih baik dan integrasi Windows asli. Ini akan secara otomatis mengonfigurasi PATH Anda dan memeriksa alat build yang diperlukan jika membangun dari sumber.

Dari Sumber

Prasyarat:

• Rust 1.70 atau lebih baru
• Di Windows: Visual Studio Build Tools dengan "Desktop development with C++"

# Clone and build
git clone git@github.com:postrv/narsil-mcp.git
cd narsil-mcp
cargo build --release

# Binary will be at:
# - macOS/Linux: target/release/narsil-mcp
# - Windows: target/release/narsil-mcp.exe

Build Fitur

narsil-mcp mendukung set fitur yang berbeda untuk kasus penggunaan yang berbeda:

# 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

Fitur	Deskripsi	Ukuran
native (default)	Server MCP penuh dengan semua alat	~30MB
graph	+ Graf pengetahuan RDF, SPARQL, alat CCG	~35MB
frontend	+ UI web visualisasi tertanam	~31MB
neural	+ Pencarian vektor TF-IDF, embedding API	~32MB
neural-onnx	+ Inferensi model ONNX lokal	~50MB
wasm	Build browser (tanpa sistem file, git)	~3MB

Penting: Bendera CLI --graph memerlukan biner yang dibangun dengan --features graph. Jika Anda memberikan --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 petunjuk instalasi terperinci, pemecahan masalah, dan panduan spesifik 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 memberikan --graph ke biner tanpa fitur tersebut, Anda akan melihat peringatan saat startup dan server akan melanjutkan tanpa alat SPARQL/CCG.

Catatan: Embedding 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
• Secara otomatis menambahkannya ke konfigurasi MCP editor Anda

Atau, Anda dapat mengatur salah satu variabel lingkungan ini secara manual:

• EMBEDDING_API_KEY - Kunci API generik untuk penyedia apa 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	Mengapa
Zed	Minimal	26	~4.686	Startup cepat, konteks minimal
VS Code	Seimbang	51	~8.948	Keseimbangan fitur yang baik
Claude Desktop	Penuh	90	~12.001	Kemampuan maksimal

Penghematan Token:

• Preset minimal: Token 61% lebih sedikit vs Penuh
• Preset seimbang: Token 25% lebih sedikit vs Penuh

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 repo):

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-repo:

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 > Var 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 spesifik 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 penyaringan arah
Grafik Impor	Ketergantungan impor tingkat file di seluruh basis kode
Grafik Simbol	Semua referensi ke simbol, dengan pengelompokan file
Hibrida	Grafik panggilan + impor gabungan dengan anggaran terpisah
Aliran Kontrol	CFG nyata dengan blok dasar, cabang, dan tepi balik loop

Fitur:

• Grafik Cytoscape.js interaktif dengan seret, zoom, dan klik dua kali untuk memperdalam
• 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)
• Sidebar pohon file dengan penampil kode yang disorot sintaks
• Status berbasis URL (tautan yang dapat dibagikan, browser mundur/maju)
• Dukungan mode gelap
• Panel detail simpul 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 embedding 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 - tidak perlu mypy atau tsc.

Alat	Deskripsi
infer_types	Dapatkan tipe yang disimpulkan untuk semua variabel dalam suatu fungsi
check_type_errors	Temukan potensi ketidakcocokan tipe
get_typed_taint_flow	Analisis keamanan yang ditingkatkan dengan info 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 agentik skala besar, narsil-mcp dapat digunakan melalui Forgemax — gateway MCP Mode Kode yang menciutkan 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 isolat V8 sandbox — kredensial, jalur file, dan status internal tidak pernah meninggalkan host. Pendekatan ini sangat berguna saat bekerja dengan beberapa server MCP secara bersamaan, karena menjaga total konteks alat 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 kecerdasan kode.

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

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 → Server Konteks):

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

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

---

Plugin Claude Code

Untuk pengguna Claude Code, kami menyediakan plugin dengan perintah garis miring dan keterampilan 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

Apa yang disertakan:

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

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

Integrasi Otomatisasi Ralph

Ralph adalah rangkaian otomatisasi Claude Code untuk pengembangan kode otonom. Ketika narsil-mcp tersedia, Ralph mendapatkan kemampuan kecerdasan 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 halus ketika narsil-mcp tidak tersedia - semua fitur otomatisasi inti berfungsi tanpanya.

Dokumentasi: Lihat README Ralph untuk detail integrasi lengkap.

Playbook & Tutorial

Lihat docs/playbooks untuk panduan penggunaan praktis:

Panduan	Deskripsi
Memulai	Pengaturan cepat dan panggilan alat pertama
Memahami Basis Kode	Jelajahi proyek yang tidak dikenal
Memperbaiki 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)

narsil-mcp dapat berjalan sepenuhnya di browser melalui WebAssembly - sempurna untuk IDE berbasis browser, alat tinjauan kode, atau platform pendidikan.

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

Dokumentasi lengkap: Lihat docs/wasm.md untuk petunjuk build, contoh React, dan referensi API.

Alat yang Tersedia (90)

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 konten 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 dalam 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 dependen
workspace_symbol_search	Pencarian simbol fuzzy di seluruh ruang kerja
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 berperingkat BM25
hybrid_search	Gabungan BM25 + TF-IDF dengan fusi peringkat
search_chunks	Cari di 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 suatu 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 suatu fungsi
get_callees	Temukan fungsi yang dipanggil oleh suatu fungsi
find_call_path	Temukan jalur antara dua fungsi
get_complexity	Dapatkan kompleksitas siklomatik/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 terjangkau

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	Simpulkan 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/Ketergantungan

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

Analisis Keamanan - Pelacakan Taint

Alat	Deskripsi
find_injection_vulnerabilities	Temukan injeksi SQL, XSS, injeksi perintah, traversal jalur
trace_taint	Lacak aliran data tercemar dari sumber
get_taint_sources	Daftar sumber taint (input pengguna, file, jaringan)
get_security_summary	Penilaian risiko keamanan 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 terperinci
suggest_fix	Dapatkan saran remediasi untuk temuan

Keamanan Rantai Pasok

Alat	Deskripsi
generate_sbom	Hasilkan SBOM (CycloneDX/SPDX/JSON)
check_dependencies	Periksa kerentanan yang diketahui (basis data 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 komit untuk file
get_recent_changes	Komit terbaru di repositori
get_hotspots	File dengan churn dan kompleksitas tinggi
get_contributors	Kontributor repositori/file
get_commit_diff	Diff untuk komit tertentu
get_symbol_history	Komit yang mengubah simbol
get_branch_info	Cabang saat ini dan status
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 tepat
go_to_definition	Temukan lokasi definisi

Dukungan Repositori Jarak Jauh (memerlukan --remote)

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

Metrik

Alat	Deskripsi
get_metrics	Statistik kinerja dan waktu

SPARQL / Graf Pengetahuan (memerlukan --graph)

Alat	Deskripsi
sparql_query	Jalankan kueri SPARQL terhadap graf pengetahuan RDF
list_sparql_templates	Daftar templat kueri SPARQL yang tersedia
run_sparql_template	Jalankan templat SPARQL yang telah ditentukan dengan parameter

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

CCG menyediakan representasi basis kode yang terstandarisasi dan dapat dikonsumsi AI dalam lapisan bertingkat.

Alat	Deskripsi
get_ccg_manifest	Manifes Lapisan 0 (~1-2KB JSON-LD) - identitas repo, jumlah
export_ccg_manifest	Ekspor manifes Lapisan 0 ke file
export_ccg_architecture	Arsitektur Lapisan 1 (~10-50KB JSON-LD) - modul, API
export_ccg_index	Indeks simbol Lapisan 2 (~100-500KB N-Quads gzipped)
export_ccg_full	Detail lengkap Lapisan 3 (~1-20MB N-Quads gzipped)
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 registri codecontextgraph.com

Aturan Keamanan

narsil-mcp menyertakan aturan keamanan bawaan di rules/:

Set Aturan Inti:

• owasp-top10.yaml - Pola kerentanan OWASP Top 10 2021
• cwe-top25.yaml - Kelemahan Paling Berbahaya CWE Top 25
• crypto.yaml - Masalah kriptografi (algoritma lemah, kunci hardcode)
• secrets.yaml - Deteksi rahasia (kunci API, kata sandi, token)

Aturan Spesifik Bahasa:

• rust.yaml - Pola keamanan Rust (transmute tidak aman, batas FFI, injeksi perintah, TOCTOU)
• elixir.yaml - Pola Elixir/BEAM (atom exhaustion, 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, traversal jalur)
• 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 hardcode, 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)             |  |
|  +-----------------------------------------------------------+  |
+-----------------------------------------------------------------+

Kinerja

Diukur 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 End-to-End

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

Metrik utama:

• Parsing tree-sitter: throughput berkelanjutan ~2 GiB/s
• 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 Repositori 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 memberikan --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 memperbaikinya:

# 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 basis data RDF Oxigraph (~5MB ukuran biner tambahan) yang tidak diperlukan untuk sebagian besar kasus penggunaan. Ini tetap opsional untuk menjaga biner default 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 diberikan

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/riwayat
• Analisis grafik panggilan dengan metrik kompleksitas
• Analisis grafik aliran kontrol (CFG)
• Analisis aliran data (DFG) dengan definisi yang mencapai
• 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 ketergantungan 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

Apa yang Baru

v1.6.x (Saat Ini)

• Pemotongan anti-crash - Memperbaiki pemotongan string tingkat byte yang tidak aman di chunk_file() dan extract_signature() yang menyebabkan hybrid_search, search_chunks, dan get_chunk_stats crash 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 sortir aman NaN - Memperbaiki 5 lokasi di modul pencarian, embedding, git, indeks, dan ekstrak di mana partial_cmp().unwrap() akan panik pada nilai float NaN. Semua sortir sekarang menggunakan unwrap_or(Ordering::Equal).
• Pemotongan pertahanan mendalam - Menambahkan pembungkus catch_unwind di sekitar semua loop chunk_file() di seluruh repo sehingga panik di satu file melewatkannya alih-alih membuat seluruh server MCP crash.
• Perombakan frontend visualisasi - SPA penuh dengan routing HashRouter, sidebar pohon file, penampil kode yang disorot sintaks, dasbor, dan halaman ikhtisar per repo
• Kinerja tampilan grafik - Grafik impor sekarang menggunakan data indeks yang di-cache alih-alih penelusuran sistem file; grafik simbol mengiterasi cache file secara langsung alih-alih round-trip markdown; semua tampilan menghormati max_nodes untuk penghentian dini
• Grafik aliran kontrol nyata - Tampilan aliran sekarang menggunakan pembangun CFG nyata (cfg::analyze_function) dengan blok dasar yang tepat, kondisi cabang, dan tepi balik loop alih-alih stub blok tunggal
• Pemisahan anggaran grafik hibrida - Tampilan hibrida mengalokasikan anggaran simpul 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 hardcode 1536
• 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 atom exhaustion, deserialisasi binary_to_term, injeksi Code.eval, injeksi SQL Ecto, Phoenix XSS, keamanan distribusi Erlang
• Migrasi dari serde_yaml ke serde-saphyr - serde_yaml yang usang diganti dengan pustaka YAML yang dipelihara secara aktif dan bebas panik
• Favicon kustom - Frontend sekarang menggunakan ikon merek 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 cakupan mendisambiguasi resolusi callee (mis., App::run() dengan benar diselesaikan ke src/app/mod.rs::run)
• 8 perbaikan analisis grafik - Kunci simpul yang memenuhi syarat, penyaringan hotspot, penanganan ekspresi CFG, parsing jalur impor
• Peningkatan Nix flake - Helper mkPkg DRY, menghapus kerangka kerja macOS yang tidak perlu, strategi pengujian --lib untuk build sandbox

v1.4.x

• SPARQL / Graf Pengetahuan RDF - Kueri data kecerdasan kode dengan SPARQL melalui Oxigraph
• Code Context Graph (CCG) - 12 alat untuk representasi basis kode yang terstandarisasi dan dapat dikonsumsi AI dengan lapisan bertingkat (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 spesifik bahasa - Aturan baru untuk Go, Java, C#, Kotlin, Bash
• 6 bahasa baru - Erlang, Elm, Fortran, PowerShell, Nix, Groovy
• Total 90 alat - Naik dari 79 dengan kemampuan SPARQL, CCG, dan analisis baru

v1.2.x

• Parameter exclude_tests - 22 alat mendukung penyaringan 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
• Preset alat yang dapat dikonfigurasi - Preset minimal, seimbang, penuh, 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
• Kinerja yang ditingkatkan - Startup lebih cepat dengan pengindeksan latar belakang

v1.0.x

• Pencarian semantik neural - Temukan kode serupa menggunakan embedding Voyage AI atau OpenAI
• Inferensi tipe - Simpulkan tipe di Python/JavaScript/TypeScript tanpa alat eksternal
• Analisis taint multi-bahasa - Pemindaian keamanan untuk PHP, Java, C#, Ruby, Kotlin
• Build WASM - Berjalan di browser untuk playground kode dan alat pendidikan
• 147 aturan keamanan yang dibundel - Deteksi OWASP, CWE, kripto, rahasia, Rust, Elixir
• Konfigurasi IDE disertakan - Templat 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