narsil-mcp

The blazing-fast, privacy-first MCP server for deep code intelligence

A Rust-powered MCP (Model Context Protocol) server providing AI assistants with deep code understanding through 90 specialized tools.

Why narsil-mcp?

Feature	narsil-mcp	XRAY	Serena	GitHub MCP
Languages	32	4	30+ (LSP)	N/A
Neural Search	Yes	No	No	No
Taint Analysis	Yes	No	No	No
SBOM/Licenses	Yes	No	No	Partial
Offline/Local	Yes	Yes	Yes	No
WASM/Browser	Yes	No	No	No
Call Graphs	Yes	Partial	No	No
Type Inference	Yes	No	No	No

Key Features

• Code Intelligence - Symbol extraction, semantic search, call graph analysis
• Neural Semantic Search - Find similar code using embeddings (Voyage AI, OpenAI)
• Security Analysis - Taint analysis, vulnerability scanning, OWASP/CWE coverage
• Supply Chain Security - SBOM generation, dependency auditing, license compliance
• Advanced Analysis - Control flow graphs, data flow analysis, dead code detection

Why Choose narsil-mcp?

• Written in Rust - Blazingly fast, memory-safe, single binary (~30MB)
• Tree-sitter powered - Accurate, incremental parsing for 32 languages
• Zero config - Point at repos and go
• MCP compliant - Works with Claude, Cursor, VS Code Copilot, Zed, and any MCP client
• Privacy-first - Fully local, no data leaves your machine
• Parallel indexing - Uses all cores via Rayon
• Smart excerpts - Expands to complete syntactic scopes
• Security-first - Built-in vulnerability detection and taint analysis
• Neural embeddings - Optional semantic search with Voyage AI or OpenAI
• WASM support - Run in browser with WebAssembly build
• Real-time streaming - Results as indexing progresses for large repos

Supported Languages

Language	Extensions	Symbols Extracted
Rust	.rs	functions, structs, enums, traits, impls, mods
Python	.py, .pyi	functions, classes
JavaScript	.js, .jsx, .mjs	functions, classes, methods, variables
TypeScript	.ts, .tsx	functions, classes, interfaces, types, enums
Go	.go	functions, methods, types
C	.c, .h	functions, structs, enums, typedefs
C++	.cpp, .cc, .hpp	functions, classes, structs, namespaces
Java	.java	methods, classes, interfaces, enums
C#	.cs	methods, classes, interfaces, structs, enums, delegates, namespaces
Bash	.sh, .bash, .zsh	functions, variables
Ruby	.rb, .rake, .gemspec	methods, classes, modules
Kotlin	.kt, .kts	functions, classes, objects, interfaces
PHP	.php, .phtml	functions, methods, classes, interfaces, traits
Swift	.swift	classes, structs, enums, protocols, functions
Verilog/SystemVerilog	.v, .vh, .sv, .svh	modules, tasks, functions, interfaces, classes
Scala	.scala, .sc	classes, objects, traits, functions, vals
Lua	.lua	functions, methods
Haskell	.hs, .lhs	functions, data types, type classes
Elixir	.ex, .exs	modules, functions
Clojure	.clj, .cljs, .cljc, .edn	lists (basic AST)
Dart	.dart	functions, classes, methods
Julia	.jl	functions, modules, structs
R	.R, .r, .Rmd	functions
Perl	.pl, .pm, .t	functions, packages
Zig	.zig	functions, variables
Erlang	.erl, .hrl	functions, modules, records
Elm	.elm	functions, types
Fortran	.f90, .f95, .f03, .f08	programs, subroutines, functions, modules
PowerShell	.ps1, .psm1, .psd1	functions, classes, enums
Nix	.nix	bindings
Groovy	.groovy, .gradle	methods, classes, interfaces, enums, functions

Installation

Via Package Managers (Recommended)

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

Arch Linux (AUR):

yay -S narsil-mcp-bin  # Binary release (faster)
# or
yay -S narsil-mcp      # Build from source

Rust/Cargo (all platforms):

cargo install narsil-mcp

Node.js/npm (all platforms):

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

One-Click Install Script

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

Note for Windows users: The PowerShell installer provides better error messages and native Windows integration. It will automatically configure your PATH and check for required build tools if building from source.

From Source

Prerequisites:

• Rust 1.70 or later
• On Windows: Visual Studio Build Tools with "Desktop development with C++"

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

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

Feature Builds

narsil-mcp supports different feature sets for different use cases:

# 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	Description	Size
native (default)	Full MCP server with all tools	~30MB
graph	+ RDF knowledge graph, SPARQL, CCG tools	~35MB
frontend	+ Embedded visualization web UI	~31MB
neural	+ TF-IDF vector search, API embeddings	~32MB
neural-onnx	+ Local ONNX model inference	~50MB
wasm	Browser build (no file system, git)	~3MB

Important: The --graph CLI flag requires the binary to be built with --features graph. If you pass --graph to a binary built without this feature, you'll see a warning and SPARQL/CCG tools won't be available. See Troubleshooting below.

For detailed installation instructions, troubleshooting, and platform-specific guides, see docs/INSTALL.md.

Usage

Basic Usage

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

Full Feature Set

narsil-mcp \
  --repos ~/projects/my-app \
  --git \           # Enable git blame, history, contributors
  --call-graph \    # Enable function call analysis
  --persist \       # Save index to disk for fast startup
  --watch \         # Auto-reindex on file changes
  --lsp \           # Enable LSP for hover, go-to-definition
  --streaming \     # Stream large result sets
  --remote \        # Enable GitHub remote repo support
  --neural \        # Enable neural semantic embeddings
  --neural-backend api \  # Backend: "api" (Voyage/OpenAI) or "onnx"
  --neural-model voyage-code-2 \  # Model to use
  --graph           # Enable SPARQL/RDF knowledge graph and CCG tools (requires --features graph build)

Note about --graph: This flag enables SPARQL queries and Code Context Graph (CCG) tools, but only if the binary was built with --features graph. The default binary does not include this feature. If you need SPARQL/CCG capabilities, build from source with:

cargo build --release --features graph

If you pass --graph to a binary without the feature, you'll see a warning at startup and the server will continue without SPARQL/CCG tools.

Note: Neural embeddings require an API key (or custom endpoint). The easiest way to set this up is with the interactive wizard:

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

The wizard will:

• Detect your editor (Claude Desktop, Claude Code, Zed, VS Code, JetBrains)
• Prompt for your API provider (Voyage AI, OpenAI, or custom)
• Validate your API key
• Automatically add it to your editor's MCP config

Alternatively, you can manually set one of these environment variables:

• EMBEDDING_API_KEY - Generic API key for any provider
• VOYAGE_API_KEY - Voyage AI specific API key
• OPENAI_API_KEY - OpenAI specific API key
• EMBEDDING_SERVER_ENDPOINT - Custom embedding API endpoint URL (optional, allows using self-hosted models)

Configuration

v1.1.0+ introduces optional configuration for fine-grained control over tools and performance. All existing usage continues to work - configuration is completely optional!

Quick Start

# 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

Automatic Editor Detection

narsil-mcp detects your editor and applies an optimal preset automatically:

Editor	Preset	Tools	Context Tokens	Why
Zed	Minimal	26	~4,686	Fast startup, minimal context
VS Code	Balanced	51	~8,948	Good feature balance
Claude Desktop	Full	75+	~12,001	Maximum capabilities

Token Savings:

• Minimal preset: 61% fewer tokens vs Full
• Balanced preset: 25% fewer tokens vs Full

Presets

Choose a preset based on your use case:

# 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

Configuration Files

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

Project config (.narsil.yaml in repo root):

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

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

Priority: CLI flags > Environment vars > Project config > User config > Defaults

Environment Variables

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

# 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

Learn More:

• Configuration Guide - Full configuration reference
• Installation Guide - Platform-specific installation

Visualization Frontend

Explore call graphs, imports, and code structure interactively in your 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

Features: interactive graphs, complexity overlays, security highlighting, multiple layouts.

Full documentation: See docs/frontend.md for setup, API endpoints, and development mode.

Neural Semantic Search

Find similar code using neural embeddings - even when variable names and structure differ.

# 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

Supports Voyage AI, OpenAI, custom endpoints, and local ONNX models.

Full documentation: See docs/neural-search.md for setup, backends, and use cases.

Type Inference

Built-in type inference for Python, JavaScript, and TypeScript - no mypy or tsc required.

Tool	Description
infer_types	Get inferred types for all variables in a function
check_type_errors	Find potential type mismatches
get_typed_taint_flow	Enhanced security analysis with type info

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

MCP Configuration

Add narsil-mcp to your AI assistant by creating a configuration file. Here are the recommended setups:

---

Claude Code (.mcp.json in project root - Recommended):

Create .mcp.json in your project directory for per-project configuration:

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

Then start Claude Code in your project:

cd /path/to/project
claude

Using . for --repos automatically indexes the current directory. Claude now has access to 76 code intelligence tools.

Tip: Add --persist --index-path .claude/cache for faster startup on subsequent runs.

For global configuration, edit ~/.claude/settings.json instead. See Claude Code Integration for advanced setups.

---

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

Note for Copilot Enterprise: MCP support requires VS Code 1.102+ and must be enabled by your organization administrator.

---

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

Note for Zed: narsil-mcp starts immediately and indexes in the background, preventing initialization timeouts.

---

Claude Code Plugin

For Claude Code users, we provide a plugin with slash commands and a skill for effective tool usage.

Install via Marketplace (Recommended):

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

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

Or install directly from GitHub:

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

What's included:

Component	Description
/narsil:security-scan	Run comprehensive security audits
/narsil:explore	Explore unfamiliar codebases
/narsil:analyze-function	Deep dive on specific functions
/narsil:find-feature	Find where features are implemented
/narsil:supply-chain	Analyze supply chain security
Skill	Guides Claude on using 90 tools effectively
MCP Config	Auto-starts narsil-mcp with sensible defaults

See narsil-plugin/README.md for full documentation.

Ralph Automation Integration

Ralph is a Claude Code automation suite for autonomous code development. When narsil-mcp is available, Ralph gains enhanced code intelligence capabilities:

Feature	Without narsil-mcp	With narsil-mcp
Security scanning	Basic (clippy)	OWASP/CWE vulnerability detection
Code understanding	File-based	Call graphs, symbol references
Architecture analysis	Manual	CCG L0/L1/L2 automatic layers
Dependency analysis	cargo tree	Import graphs, circular detection

Setup:

# 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 gracefully degrades when narsil-mcp is unavailable - all core automation features work without it.

Documentation: See Ralph README for full integration details.

Playbooks & Tutorials

See docs/playbooks for practical usage guides:

Guide	Description
Getting Started	Quick setup and first tool calls
Understand a Codebase	Explore unfamiliar projects
Fix a Bug	Debug with call graphs and taint analysis
Security Audit	Find vulnerabilities with OWASP/CWE scanning
Code Review	Review changes effectively

Each playbook shows the exact tool chains Claude uses to answer your questions.

WebAssembly (Browser) Usage

narsil-mcp can run entirely in the browser via WebAssembly - perfect for browser-based IDEs, code review tools, or educational platforms.

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

Full documentation: See docs/wasm.md for build instructions, React examples, and API reference.

Available Tools (90)

Repository & File Management

Tool	Description
list_repos	List all indexed repositories with metadata
get_project_structure	Get directory tree with file icons and sizes
get_file	Get file contents with optional line range
get_excerpt	Extract code around specific lines with context
reindex	Trigger re-indexing of repositories
discover_repos	Auto-discover repositories in a directory
validate_repo	Check if path is a valid repository
get_index_status	Show index stats and enabled features

Symbol Search & Navigation

Tool	Description
find_symbols	Find structs, classes, functions by type/pattern
get_symbol_definition	Get symbol source with surrounding context
find_references	Find all references to a symbol
get_dependencies	Analyze imports and dependents
workspace_symbol_search	Fuzzy search symbols across workspace
find_symbol_usages	Cross-file symbol usage with imports
get_export_map	Get exported symbols from a file/module

Code Search

Tool	Description
search_code	Keyword search with relevance ranking
semantic_search	BM25-ranked semantic search
hybrid_search	Combined BM25 + TF-IDF with rank fusion
search_chunks	Search over AST-aware code chunks
find_similar_code	Find code similar to a snippet (TF-IDF)
find_similar_to_symbol	Find code similar to a symbol

AST-Aware Chunking

Tool	Description
get_chunks	Get AST-aware chunks for a file
get_chunk_stats	Statistics about code chunks
get_embedding_stats	Embedding index statistics

Neural Semantic Search (requires --neural)

Tool	Description
neural_search	Semantic search using neural embeddings (finds similar code even with different names)
find_semantic_clones	Find Type-3/4 semantic clones of a function
get_neural_stats	Neural embedding index statistics

Call Graph Analysis (requires --call-graph)

Tool	Description
get_call_graph	Get call graph for repository/function
get_callers	Find functions that call a function
get_callees	Find functions called by a function
find_call_path	Find path between two functions
get_complexity	Get cyclomatic/cognitive complexity
get_function_hotspots	Find highly connected functions

Control Flow Analysis

Tool	Description
get_control_flow	Get CFG showing basic blocks and branches
find_dead_code	Find unreachable code blocks

Data Flow Analysis

Tool	Description
get_data_flow	Variable definitions and uses
get_reaching_definitions	Which assignments reach each point
find_uninitialized	Variables used before initialization
find_dead_stores	Assignments that are never read

Type Inference (Python/JavaScript/TypeScript)

Tool	Description
infer_types	Infer types for variables in a function without external type checkers
check_type_errors	Find potential type errors without running mypy/tsc
get_typed_taint_flow	Enhanced taint analysis combining data flow with type inference

Import/Dependency Graph

Tool	Description
get_import_graph	Build and analyze import graph
find_circular_imports	Detect circular dependencies
get_incremental_status	Merkle tree and change statistics

Security Analysis - Taint Tracking

Tool	Description
find_injection_vulnerabilities	Find SQL injection, XSS, command injection, path traversal
trace_taint	Trace tainted data flow from a source
get_taint_sources	List taint sources (user input, files, network)
get_security_summary	Comprehensive security risk assessment

Security Analysis - Rules Engine

Tool	Description
scan_security	Scan with security rules (OWASP, CWE, crypto, secrets)
check_owasp_top10	Scan for OWASP Top 10 2021 vulnerabilities
check_cwe_top25	Scan for CWE Top 25 weaknesses
explain_vulnerability	Get detailed vulnerability explanation
suggest_fix	Get remediation suggestions for findings

Supply Chain Security

Tool	Description
generate_sbom	Generate SBOM (CycloneDX/SPDX/JSON)
check_dependencies	Check for known vulnerabilities (OSV database)
check_licenses	Analyze licenses for compliance issues
find_upgrade_path	Find safe upgrade paths for vulnerable deps

Git Integration (requires --git)

Tool	Description
get_blame	Git blame for file
get_file_history	Commit history for file
get_recent_changes	Recent commits in repository
get_hotspots	Files with high churn and complexity
get_contributors	Repository/file contributors
get_commit_diff	Diff for specific commit
get_symbol_history	Commits that changed a symbol
get_branch_info	Current branch and status
get_modified_files	Working tree changes

LSP Integration (requires --lsp)

Tool	Description
get_hover_info	Type info and documentation
get_type_info	Precise type information
go_to_definition	Find definition location

Remote Repository Support (requires --remote)

Tool	Description
add_remote_repo	Clone and index GitHub repository
list_remote_files	List files via GitHub API
get_remote_file	Fetch file via GitHub API

Metrics

Tool	Description
get_metrics	Performance stats and timing

SPARQL / Knowledge Graph (requires --graph)

Tool	Description
sparql_query	Execute SPARQL query against RDF knowledge graph
list_sparql_templates	List available SPARQL query templates
run_sparql_template	Execute predefined SPARQL template with parameters

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

CCG provides standardized, AI-consumable representations of codebases in tiered layers.

Tool	Description
get_ccg_manifest	Layer 0 manifest (~1-2KB JSON-LD) - repo identity, counts
export_ccg_manifest	Export Layer 0 manifest to file
export_ccg_architecture	Layer 1 architecture (~10-50KB JSON-LD) - modules, API
export_ccg_index	Layer 2 symbol index (~100-500KB N-Quads gzipped)
export_ccg_full	Layer 3 full detail (~1-20MB N-Quads gzipped)
export_ccg	Export all CCG layers as a bundle
query_ccg	Query CCG using SPARQL
get_ccg_acl	Generate WebACL access control for CCG layers
get_ccg_access_info	Get CCG access tier information
import_ccg	Import CCG layer from URL or file
import_ccg_from_registry	Import CCG from codecontextgraph.com registry

Security Rules

narsil-mcp includes built-in security rules in rules/:

Core Rulesets:

• owasp-top10.yaml - OWASP Top 10 2021 vulnerability patterns
• cwe-top25.yaml - CWE Top 25 Most Dangerous Weaknesses
• crypto.yaml - Cryptographic issues (weak algorithms, hardcoded keys)
• secrets.yaml - Secret detection (API keys, passwords, tokens)

Language-Specific Rules:

• go.yaml - Go security patterns (SQL injection, TLS, command injection)
• java.yaml - Java vulnerabilities (XXE, deserialization, LDAP injection)
• csharp.yaml - C# security issues (deserialization, XSS, path traversal)
• kotlin.yaml - Kotlin/Android patterns (WebView, intents, secrets)
• bash.yaml - Shell script vulnerabilities (command injection, eval)

Infrastructure & Configuration:

• iac.yaml - Infrastructure as Code (Terraform, CloudFormation, Kubernetes)
• config.yaml - Configuration file security (hardcoded credentials, insecure settings)

Custom rules can be loaded with scan_security --ruleset /path/to/rules.yaml.

Architecture

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

Performance

Benchmarked on Apple M1 (criterion.rs):

Parsing Throughput

Language	Input Size	Time	Throughput
Rust (large file)	278 KB	131 µs	1.98 GiB/s
Rust (medium file)	27 KB	13.5 µs	1.89 GiB/s
Python	~4 KB	16.7 µs	-
TypeScript	~5 KB	13.9 µs	-
Mixed (5 files)	~15 KB	57 µs	-

Search Latency

Operation	Corpus Size	Time
Symbol exact match	1,000 symbols	483 ns
Symbol prefix match	1,000 symbols	2.7 µs
Symbol fuzzy match	1,000 symbols	16.5 µs
BM25 full-text	1,000 docs	80 µs
TF-IDF similarity	1,000 docs	130 µs
Hybrid (BM25+TF-IDF)	1,000 docs	151 µs

End-to-End Indexing

Repository	Files	Symbols	Time	Memory
narsil-mcp (this repo)	53	1,733	220 ms	~50 MB
rust-analyzer	2,847	~50K	2.1s	89 MB
linux kernel	78,000+	~500K	45s	2.1 GB

Key metrics:

• Tree-sitter parsing: ~2 GiB/s sustained throughput
• Symbol lookup: <1µs for exact match
• Full-text search: <1ms for most queries
• Hybrid search runs BM25 + TF-IDF in parallel via rayon

Development

# Run tests (1598+ tests)
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

Troubleshooting

Tree-sitter Build Errors

If you see errors about missing C compilers or tree-sitter during build:

# macOS
xcode-select --install

# Ubuntu/Debian
sudo apt install build-essential

# For WASM builds
brew install emscripten  # macOS

Neural Search API Errors

# Check your API key is set
echo $VOYAGE_API_KEY  # or $OPENAI_API_KEY

# Common issue: wrong key format
export VOYAGE_API_KEY="pa-..."  # Voyage keys start with "pa-"
export OPENAI_API_KEY="sk-..."  # OpenAI keys start with "sk-"

Index Not Finding Files

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

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

Memory Issues with Large Repos

# For very large repos (>50K files), increase stack size
RUST_MIN_STACK=8388608 narsil-mcp --repos /path/to/huge-repo

# Or index specific subdirectories
narsil-mcp --repos /path/to/repo/src --repos /path/to/repo/lib

Graph Feature Not Working

If you pass --graph and see a warning like:

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

This means you're using a binary that wasn't compiled with the graph feature. To fix:

# 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

Why is this a separate feature? The graph feature adds the Oxigraph RDF database (~5MB additional binary size) which isn't needed for most use cases. It's kept optional to keep the default binary smaller.

How to check if graph is enabled: Look at the startup logs:

• graph=true means the feature is compiled in AND enabled
• graph=false means either the feature isn't compiled, OR --graph wasn't passed

Roadmap

Completed

• Multi-language symbol extraction (32 languages)
• Full-text search with Tantivy (BM25 ranking)
• Hybrid search (BM25 + TF-IDF with RRF)
• AST-aware code chunking
• Git blame/history integration
• Call graph analysis with complexity metrics
• Control flow graph (CFG) analysis
• Data flow analysis (DFG) with reaching definitions
• Dead code and dead store detection
• Taint analysis for injection vulnerabilities
• Security rules engine (OWASP, CWE, crypto, secrets)
• SBOM generation (CycloneDX, SPDX)
• Dependency vulnerability checking (OSV)
• License compliance analysis
• Import graph with circular dependency detection
• Cross-language symbol resolution
• Incremental indexing with Merkle trees
• Index persistence
• Watch mode for file changes
• LSP integration
• Remote repository support
• Streaming responses

What's New

v1.4.x (Current)

• Improved --graph flag UX - Clear warning when --graph is passed but the binary wasn't built with --features graph
• Better startup diagnostics - Logs now accurately report graph=true/false based on actual feature availability

v1.3.x

• SPARQL / RDF Knowledge Graph - Query code intelligence data with SPARQL via Oxigraph
• Code Context Graph (CCG) - 12 tools for standardized, AI-consumable codebase representations with tiered layers (L0-L3)
• Type-aware security analysis - Enhanced taint tracking with type inference and trait implementations
• Multi-language CFG/DFG - Control flow and data flow analysis extended to Go, Java, C#, Kotlin
• Infrastructure as Code scanning - New iac.yaml rules for Terraform, CloudFormation, Kubernetes
• Language-specific security rules - New rules for Go, Java, C#, Kotlin, Bash
• 6 new languages - Erlang, Elm, Fortran, PowerShell, Nix, Groovy
• 90 tools total - Up from 79 with new SPARQL, CCG, and analysis capabilities

v1.2.x

• exclude_tests parameter - 22 tools support filtering out test files
• npm package - Install via npm install -g narsil-mcp

v1.1.x

• Multi-platform distribution - Install via Homebrew, Scoop, npm, Cargo, or direct download
• Configurable tool presets - Minimal, balanced, full, and security-focused presets
• Automatic editor detection - Optimal defaults for Zed, VS Code, Claude Desktop
• Interactive setup wizard - narsil-mcp config init for easy configuration
• 32 language support - Added Dart, Julia, R, Perl, Zig, and more
• Improved performance - Faster startup with background indexing

v1.0.x

• Neural semantic search - Find similar code using Voyage AI or OpenAI embeddings
• Type inference - Infer types in Python/JavaScript/TypeScript without external tools
• Multi-language taint analysis - Security scanning for PHP, Java, C#, Ruby, Kotlin
• WASM build - Run in browser for code playgrounds and educational tools
• 111 bundled security rules - OWASP, CWE, crypto, secrets detection
• IDE configs included - Claude Desktop, Cursor, VS Code, Zed templates

License

Licensed under either of:

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

at your option.

Credits

Built with:

• tree-sitter - Incremental parsing
• tantivy - Full-text search
• tokio - Async runtime
• rayon - Data parallelism
• serde - Serialization