Skip to content
Back to search

narsil-mcp

Rust MCP server for comprehensive code intelligence - 90 tools, 32 languages, security scanning, call graphs, and more

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/postrv--narsil-mcp/badge.svg)](/listings/postrv--narsil-mcp)

HTML

<a href="/listings/postrv--narsil-mcp"><img src="/api/listings/postrv--narsil-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

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

**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](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022) 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](#graph-feature-not-working) below.

> **For detailed installation instructions, troubleshooting, and platform-specific guides**, see [docs/INSTALL.md](docs/INSTALL.md).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 43 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "narsil-mcp",
  3. "owner": {
  4. "name": "postrv",
  5. "email": "contact@laurenceavent.com"
  6. },
  7. "metadata": {
  8. "description": "Code intelligence plugins for Claude Code, powered by narsil-mcp",
  9. "version": "1.0.0",
  10. "pluginRoot": "./narsil-plugin"
  11. },
  12. "plugins": [
  13. {
  14. "name": "narsil",
  15. "source": "./narsil-plugin",
  16. "description": "Code intelligence plugin with 76+ tools for security scanning, call graph analysis, symbol search, and static analysis. Includes slash commands for common workflows and a skill for effective tool usage.",
  17. "version": "1.0.0",
  18. "author": {
  19. "name": "postrv"
  20. },
  21. "homepage": "https://github.com/postrv/narsil-mcp",
  22. "repository": "https://github.com/postrv/narsil-mcp",
  23. "license": "MIT OR Apache-2.0",
  24. "keywords": [
  25. "code-intelligence",
  26. "security",
  27. "static-analysis",
  28. "call-graph",
  29. "mcp",
  30. "tree-sitter"
  31. ],
  32. "category": "development-tools",
  33. "tags": [
  34. "security-scanning",
  35. "code-analysis",
  36. "vulnerability-detection",
  37. "sbom",
  38. "owasp",
  39. "cwe"
  40. ]
  41. }
  42. ]
  43. }
README.md · README · 1,186 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # narsil-mcp
  2. > The blazing-fast, privacy-first MCP server for deep code intelligence
  3. [![License](https://img.shields.io/badge/License-MIT%20OR%20Apache--2.0-blue.svg)](LICENSE-MIT)
  4. [![Rust](https://img.shields.io/badge/rust-1.70%2B-orange.svg)](https://www.rust-lang.org)
  5. [![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)](https://github.com/postrv/narsil-mcp)
  6. [![MCP](https://img.shields.io/badge/MCP-compatible-blue.svg)](https://modelcontextprotocol.io)
  7. A Rust-powered MCP (Model Context Protocol) server providing AI assistants with deep code understanding through 90 specialized tools.
  8. ## Why narsil-mcp?
  9. | Feature | narsil-mcp | XRAY | Serena | GitHub MCP |
  10. |---------|------------|------|--------|------------|
  11. | **Languages** | 32 | 4 | 30+ (LSP) | N/A |
  12. | **Neural Search** | Yes | No | No | No |
  13. | **Taint Analysis** | Yes | No | No | No |
  14. | **SBOM/Licenses** | Yes | No | No | Partial |
  15. | **Offline/Local** | Yes | Yes | Yes | No |
  16. | **WASM/Browser** | Yes | No | No | No |
  17. | **Call Graphs** | Yes | Partial | No | No |
  18. | **Type Inference** | Yes | No | No | No |
  19. ## Key Features
  20. - **Code Intelligence** - Symbol extraction, semantic search, call graph analysis
  21. - **Neural Semantic Search** - Find similar code using embeddings (Voyage AI, OpenAI)
  22. - **Security Analysis** - Taint analysis, vulnerability scanning, OWASP/CWE coverage
  23. - **Supply Chain Security** - SBOM generation, dependency auditing, license compliance
  24. - **Advanced Analysis** - Control flow graphs, data flow analysis, dead code detection
  25. ### Why Choose narsil-mcp?
  26. - **Written in Rust** - Blazingly fast, memory-safe, single binary (~30MB)
  27. - **Tree-sitter powered** - Accurate, incremental parsing for 32 languages
  28. - **Zero config** - Point at repos and go
  29. - **MCP compliant** - Works with Claude, Cursor, VS Code Copilot, Zed, and any MCP client
  30. - **Privacy-first** - Fully local, no data leaves your machine
  31. - **Parallel indexing** - Uses all cores via Rayon
  32. - **Smart excerpts** - Expands to complete syntactic scopes
  33. - **Security-first** - Built-in vulnerability detection and taint analysis
  34. - **Neural embeddings** - Optional semantic search with Voyage AI or OpenAI
  35. - **WASM support** - Run in browser with WebAssembly build
  36. - **Real-time streaming** - Results as indexing progresses for large repos
  37. ## Supported Languages
  38. | Language | Extensions | Symbols Extracted |
  39. |----------|------------|-------------------|
  40. | Rust | `.rs` | functions, structs, enums, traits, impls, mods |
  41. | Python | `.py`, `.pyi` | functions, classes |
  42. | JavaScript | `.js`, `.jsx`, `.mjs` | functions, classes, methods, variables |
  43. | TypeScript | `.ts`, `.tsx` | functions, classes, interfaces, types, enums |
  44. | Go | `.go` | functions, methods, types |
  45. | C | `.c`, `.h` | functions, structs, enums, typedefs |
  46. | C++ | `.cpp`, `.cc`, `.hpp` | functions, classes, structs, namespaces |
  47. | Java | `.java` | methods, classes, interfaces, enums |
  48. | C# | `.cs` | methods, classes, interfaces, structs, enums, delegates, namespaces |
  49. | **Bash** | `.sh`, `.bash`, `.zsh` | functions, variables |
  50. | **Ruby** | `.rb`, `.rake`, `.gemspec` | methods, classes, modules |
  51. | **Kotlin** | `.kt`, `.kts` | functions, classes, objects, interfaces |
  52. | **PHP** | `.php`, `.phtml` | functions, methods, classes, interfaces, traits |
  53. | **Swift** | `.swift` | classes, structs, enums, protocols, functions |
  54. | **Verilog/SystemVerilog** | `.v`, `.vh`, `.sv`, `.svh` | modules, tasks, functions, interfaces, classes |
  55. | **Scala** | `.scala`, `.sc` | classes, objects, traits, functions, vals |
  56. | **Lua** | `.lua` | functions, methods |
  57. | **Haskell** | `.hs`, `.lhs` | functions, data types, type classes |
  58. | **Elixir** | `.ex`, `.exs` | modules, functions |
  59. | **Clojure** | `.clj`, `.cljs`, `.cljc`, `.edn` | lists (basic AST) |
  60. | **Dart** | `.dart` | functions, classes, methods |
  61. | **Julia** | `.jl` | functions, modules, structs |
  62. | **R** | `.R`, `.r`, `.Rmd` | functions |
  63. | **Perl** | `.pl`, `.pm`, `.t` | functions, packages |
  64. | **Zig** | `.zig` | functions, variables |
  65. | **Erlang** | `.erl`, `.hrl` | functions, modules, records |
  66. | **Elm** | `.elm` | functions, types |
  67. | **Fortran** | `.f90`, `.f95`, `.f03`, `.f08`, `.f`, `.for`, `.fpp` | programs, subroutines, functions, modules |
  68. | **PowerShell** | `.ps1`, `.psm1`, `.psd1` | functions, classes, enums |
  69. | **Nix** | `.nix` | bindings |
  70. | **Groovy** | `.groovy`, `.gradle` | methods, classes, interfaces, enums, functions |
  71. ## Installation
  72. ### Via Package Managers (Recommended)
  73. **macOS / Linux (Homebrew):**
  74. ```bash
  75. brew tap postrv/narsil
  76. brew install narsil-mcp
  77. ```
  78. **Windows (Scoop):**
  79. ```powershell
  80. scoop bucket add narsil https://github.com/postrv/scoop-narsil
  81. scoop install narsil-mcp
  82. ```
  83. **Rust/Cargo (all platforms):**
  84. ```bash
  85. cargo install narsil-mcp
  86. ```
  87. **Node.js/npm (all platforms):**
  88. ```bash
  89. npm install -g narsil-mcp
  90. # or
  91. yarn global add narsil-mcp
  92. # or
  93. pnpm add -g narsil-mcp
  94. ```
  95. **Nix:**
  96. ```bash
  97. # Run directly without installing
  98. nix run github:postrv/narsil-mcp -- --repos ./my-project
  99. # Install to profile
  100. nix profile install github:postrv/narsil-mcp
  101. # With web visualization frontend
  102. nix profile install github:postrv/narsil-mcp#with-frontend
  103. # Development shell
  104. nix develop github:postrv/narsil-mcp
  105. ```
  106. ### One-Click Install Script
  107. **macOS / Linux:**
  108. ```bash
  109. curl -fsSL https://raw.githubusercontent.com/postrv/narsil-mcp/main/install.sh | bash
  110. ```
  111. **Windows (PowerShell):**
  112. ```powershell
  113. irm https://raw.githubusercontent.com/postrv/narsil-mcp/main/install.ps1 | iex
  114. ```
  115. **Windows (Git Bash / MSYS2):**
  116. ```bash
  117. curl -fsSL https://raw.githubusercontent.com/postrv/narsil-mcp/main/install.sh | bash
  118. ```
  119. > **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.
  120. ### From Source
  121. **Prerequisites:**
  122. - Current stable Rust (this release was verified with Rust 1.98 and 1.99)
  123. - On Windows: [Visual Studio Build Tools](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022) with "Desktop development with C++"
  124. ```bash
  125. # Clone and build
  126. git clone git@github.com:postrv/narsil-mcp.git
  127. cd narsil-mcp
  128. cargo build --release
  129. # Binary will be at:
  130. # - macOS/Linux: target/release/narsil-mcp
  131. # - Windows: target/release/narsil-mcp.exe
  132. ```
  133. ### Feature Builds
  134. narsil-mcp supports different feature sets for different use cases:
  135. ```bash
  136. # Default build - native MCP server (~30MB)
  137. cargo build --release
  138. # With RDF knowledge graph and CCG tools (~35MB) - SPARQL queries, Code Context Graph
  139. cargo build --release --features graph
  140. # With neural vector search (~32MB) - adds TF-IDF similarity
  141. cargo build --release --features neural
  142. # With ONNX model support (~50MB) - adds local neural embeddings
  143. cargo build --release --features neural-onnx
  144. # With embedded visualization frontend (~31MB)
  145. cargo build --release --features frontend
  146. # Full-featured build with graph + frontend (~40MB)
  147. cargo build --release --features graph,frontend
  148. # Experimental browser/WASM source build (not release-qualified)
  149. cargo build --release --target wasm32-unknown-unknown --no-default-features --features wasm
  150. ```
  151. | Feature | Description | Size |
  152. |---------|-------------|------|
  153. | `native` (default) | Full MCP server with all tools | ~30MB |
  154. | `graph` | + RDF knowledge graph, SPARQL, CCG tools | ~35MB |
  155. | `frontend` | + Embedded visualization web UI | ~31MB |
  156. | `neural` | + TF-IDF vector search, API embeddings | ~32MB |
  157. | `neural-onnx` | + Local ONNX model inference | ~50MB |
  158. | `wasm` | Experimental browser source build (no file system, git) | Not release-qualified |
  159. > **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](#graph-feature-not-working) below.
  160. > **For detailed installation instructions, troubleshooting, and platform-specific guides**, see [docs/INSTALL.md](docs/INSTALL.md).
  161. ## Usage
  162. ### Basic Usage
  163. **macOS / Linux:**
  164. ```bash
  165. # Index a single repository
  166. narsil-mcp --repos /path/to/your/project
  167. # Index multiple repositories
  168. narsil-mcp --repos ~/projects/project1 --repos ~/projects/project2
  169. # Enable verbose logging
  170. narsil-mcp --repos /path/to/project --verbose
  171. # Force re-index on startup
  172. narsil-mcp --repos /path/to/project --reindex
  173. ```
  174. **Windows (PowerShell / CMD):**
  175. ```powershell
  176. # Index a single repository
  177. narsil-mcp --repos C:\Users\YourName\Projects\my-project
  178. # Index multiple repositories
  179. narsil-mcp --repos C:\Projects\project1 --repos C:\Projects\project2
  180. # Enable verbose logging
  181. narsil-mcp --repos C:\Projects\my-project --verbose
  182. # Force re-index on startup
  183. narsil-mcp --repos C:\Projects\my-project --reindex
  184. ```
  185. ### Full Feature Set
  186. ```bash
  187. narsil-mcp \
  188. --repos ~/projects/my-app \
  189. --git \ # Enable git blame, history, contributors
  190. --call-graph \ # Enable function call analysis
  191. --persist \ # Save index to disk for fast startup
  192. --watch \ # Auto-reindex on file changes
  193. --lsp \ # Enable LSP for hover, go-to-definition
  194. --streaming \ # Stream large result sets
  195. --remote \ # Enable GitHub remote repo support
  196. --neural \ # Enable neural semantic embeddings
  197. --neural-backend api \ # Backend: "api" (Voyage/OpenAI) or "onnx"
  198. --neural-model voyage-code-2 \ # Model to use
  199. --neural-dimension 3072 \ # Override embedding dimensions (auto-detected per model)
  200. --graph # Enable SPARQL/RDF knowledge graph and CCG tools (requires --features graph build)
  201. ```
  202. > **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:
  203. > ```bash
  204. > cargo build --release --features graph
  205. > ```
  206. > 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.
  207. **Note:** Neural embeddings require an API key (or custom endpoint). The easiest way to set this up is with the interactive wizard:
  208. ```bash
  209. # Run the neural API key setup wizard
  210. narsil-mcp config init --neural
  211. ```
  212. The wizard will:
  213. - Detect your editor (Claude Desktop, Claude Code, Zed, VS Code, JetBrains)
  214. - Prompt for your API provider (Voyage AI, OpenAI, or custom)
  215. - Validate your API key
  216. - Automatically add it to your editor's MCP config
  217. Alternatively, you can manually set one of these environment variables:
  218. - `EMBEDDING_API_KEY` - Generic API key for any provider
  219. - `VOYAGE_API_KEY` - Voyage AI specific API key
  220. - `OPENAI_API_KEY` - OpenAI specific API key
  221. - `EMBEDDING_SERVER_ENDPOINT` - Custom embedding API endpoint URL (optional, allows using self-hosted models)
  222. ### Configuration
  223. **v1.1.0+ introduces optional configuration** for fine-grained control over tools and performance. **All existing usage continues to work** - configuration is completely optional!
  224. #### Quick Start
  225. ```bash
  226. # Generate default config interactively
  227. narsil-mcp config init
  228. # List available tools
  229. narsil-mcp tools list
  230. # Apply a preset via CLI
  231. narsil-mcp --repos ~/project --preset minimal
  232. ```
  233. #### Automatic Editor Detection
  234. narsil-mcp detects your editor and applies an optimal preset automatically:
  235. | Editor | Preset | Tools | Context Tokens | Why |
  236. |--------|--------|-------|----------------|-----|
  237. | **Zed** | Minimal | 26 | ~4,686 | Fast startup, minimal context |
  238. | **VS Code** | Balanced | 51 | ~8,948 | Good feature balance |
  239. | **Claude Desktop** | Full | 90 | ~12,001 | Maximum capabilities |
  240. **Token Savings:**
  241. - **Minimal preset:** 61% fewer tokens vs Full
  242. - **Balanced preset:** 25% fewer tokens vs Full
  243. #### Presets
  244. Choose a preset based on your use case:
  245. ```bash
  246. # Minimal - Fast, lightweight (Zed, Cursor)
  247. narsil-mcp --repos ~/project --preset minimal
  248. # Balanced - Good defaults (VS Code, IntelliJ)
  249. narsil-mcp --repos ~/project --preset balanced --git --call-graph
  250. # Full - All features (Claude Desktop, comprehensive analysis)
  251. narsil-mcp --repos ~/project --preset full --git --call-graph
  252. # Security-focused - Security and supply chain tools
  253. narsil-mcp --repos ~/project --preset security-focused
  254. ```
  255. #### Configuration Files
  256. **User config** (`~/.config/narsil-mcp/config.yaml`):
  257. ```yaml
  258. version: "1.0"
  259. preset: "balanced"
  260. tools:
  261. # Disable slow tools
  262. overrides:
  263. neural_search:
  264. enabled: false
  265. reason: "Too slow for interactive use"
  266. performance:
  267. max_tool_count: 50 # Limit total tools
  268. ```
  269. **Project config** (`.narsil.yaml` in repo root):
  270. ```yaml
  271. version: "1.0"
  272. preset: "security-focused" # Override user preset
  273. tools:
  274. categories:
  275. Security:
  276. enabled: true
  277. SupplyChain:
  278. enabled: true
  279. ```
  280. **Named repository profiles** are useful for multi-repo workspaces:
  281. ```yaml
  282. version: "1.0"
  283. profiles:
  284. platform:
  285. repos:
  286. - ~/src/api
  287. - ~/src/web
  288. git: true
  289. call_graph: true
  290. persist: true
  291. preset: balanced
  292. ```
  293. ```bash
  294. narsil-mcp --profile platform
  295. narsil-mcp config profiles
  296. ```
  297. **Priority:** CLI flags > Environment vars > Project config > User config > Defaults
  298. #### Environment Variables
  299. ```bash
  300. # Select repos/profile
  301. export NARSIL_REPOS=~/src/api,~/src/web
  302. export NARSIL_PROFILE=platform
  303. # Apply preset
  304. export NARSIL_PRESET=minimal
  305. # Enable specific categories
  306. export NARSIL_ENABLED_CATEGORIES=Repository,Symbols,Search
  307. # Disable specific tools
  308. export NARSIL_DISABLED_TOOLS=neural_search,generate_sbom
  309. ```
  310. #### CLI Commands
  311. ```bash
  312. # View effective config
  313. narsil-mcp config show
  314. # Validate config file
  315. narsil-mcp config validate ~/.config/narsil-mcp/config.yaml
  316. # List tools by category
  317. narsil-mcp tools list --category Search
  318. # Search for tools
  319. narsil-mcp tools search "git"
  320. # Export config
  321. narsil-mcp config export > my-config.yaml
  322. # List named repository profiles
  323. narsil-mcp config profiles
  324. ```
  325. **Learn More:**
  326. - [Configuration Guide](docs/configuration.md) - Full configuration reference
  327. - [Installation Guide](docs/INSTALL.md) - Platform-specific installation
  328. ### Visualization Frontend
  329. Explore call graphs, imports, symbol references, and control flow interactively in your browser.
  330. ```bash
  331. # Build with embedded frontend
  332. cargo build --release --features frontend
  333. # Run with HTTP server
  334. narsil-mcp --repos ~/project --http --call-graph
  335. # Open http://localhost:3000
  336. ```
  337. **Five graph views:**
  338. | View | Description |
  339. |------|-------------|
  340. | **Call Graph** | Function call relationships with depth control and direction filtering |
  341. | **Import Graph** | File-level import dependencies across the codebase |
  342. | **Symbol Graph** | All references to a symbol, with file clustering |
  343. | **Hybrid** | Combined call + import graph with split budget |
  344. | **Control Flow** | Real CFG with basic blocks, branches, and loop back-edges |
  345. **Features:**
  346. - Interactive Cytoscape.js graphs with drag, zoom, and double-click drill-down
  347. - Complexity metrics overlay with color coding (green/yellow/orange/red)
  348. - Security vulnerability overlay highlighting taint sources and sinks
  349. - Six layout algorithms (dagre, force-directed, breadthfirst, concentric, circle, grid)
  350. - File tree sidebar with syntax-highlighted code viewer
  351. - URL-driven state (shareable links, browser back/forward)
  352. - Dark mode support
  353. - Node detail panel with code excerpts and navigation to source
  354. > **Full documentation:** See [docs/frontend.md](docs/frontend.md) for setup, API endpoints, and development mode.
  355. ### Neural Semantic Search
  356. Find similar code using neural embeddings - even when variable names and structure differ.
  357. ```bash
  358. # Quick setup with wizard
  359. narsil-mcp config init --neural
  360. # Or manually with Voyage AI
  361. export VOYAGE_API_KEY="your-key"
  362. narsil-mcp --repos ~/project --neural --neural-model voyage-code-2
  363. ```
  364. Supports Voyage AI, OpenAI, custom endpoints, and local ONNX models.
  365. > **Full documentation:** See [docs/neural-search.md](docs/neural-search.md) for setup, backends, and use cases.
  366. ### Type Inference
  367. Built-in type inference for Python, JavaScript, and TypeScript - no mypy or tsc required.
  368. | Tool | Description |
  369. |------|-------------|
  370. | `infer_types` | Get inferred types for all variables in a function |
  371. | `check_type_errors` | Find potential type mismatches |
  372. | `get_typed_taint_flow` | Enhanced security analysis with type info |
  373. ```python
  374. def process(data):
  375. result = data.split(",") # result: list[str]
  376. count = len(result) # count: int
  377. return count * 2 # returns: int
  378. ```
  379. ### Forgemax Integration (Experimental)
  380. For large-scale agentic workflows, narsil-mcp can be used through [Forgemax](https://github.com/postrv/forgemax) — a Code Mode MCP gateway that collapses all 90 tools into just 2 (`search` + `execute`), reducing tool schema overhead from ~12,000 tokens to ~1,000.
  381. ```bash
  382. # Install Forgemax
  383. cargo install forgemax
  384. # Run narsil-mcp through Forgemax (uses forge.toml in repo root)
  385. forgemax
  386. ```
  387. The included `forge.toml` configures narsil-mcp with sensible defaults:
  388. ```toml
  389. [servers.narsil]
  390. command = "narsil-mcp"
  391. args = ["--repos", ".", "--git", "--call-graph", "--persist", "--watch"]
  392. transport = "stdio"
  393. [sandbox]
  394. timeout_secs = 10
  395. max_heap_mb = 64
  396. max_concurrent = 8
  397. ```
  398. The LLM writes JavaScript that calls through typed proxy objects inside a sandboxed V8 isolate — credentials, file paths, and internal state never leave the host. This approach is particularly useful when working with multiple MCP servers simultaneously, as it keeps the total tool context small and predictable.
  399. ### MCP Configuration
  400. Add narsil-mcp to your AI assistant by creating a configuration file. Here are the recommended setups:
  401. ---
  402. **Claude Code** (`.mcp.json` in project root - Recommended):
  403. Create `.mcp.json` in your project directory for per-project configuration:
  404. ```json
  405. {
  406. "mcpServers": {
  407. "narsil-mcp": {
  408. "command": "narsil-mcp",
  409. "args": ["--repos", ".", "--git", "--call-graph"]
  410. }
  411. }
  412. }
  413. ```
  414. Then start Claude Code in your project:
  415. ```bash
  416. cd /path/to/project
  417. claude
  418. ```
  419. Using `.` for `--repos` automatically indexes the current directory. Claude now has access to 90 code intelligence tools.
  420. > **Tip**: Add `--persist --index-path .claude/cache` for faster startup on subsequent runs.
  421. For global configuration, edit `~/.claude/settings.json` instead. See [Claude Code Integration](docs/playbooks/integrations/claude-code.md) for advanced setups.
  422. ---
  423. **Cursor** (`.cursor/mcp.json`):
  424. ```json
  425. {
  426. "mcpServers": {
  427. "narsil-mcp": {
  428. "command": "narsil-mcp",
  429. "args": ["--repos", ".", "--git", "--call-graph"]
  430. }
  431. }
  432. }
  433. ```
  434. ---
  435. **VS Code + GitHub Copilot** (`.vscode/mcp.json`):
  436. ```json
  437. {
  438. "servers": {
  439. "narsil-mcp": {
  440. "command": "narsil-mcp",
  441. "args": ["--repos", ".", "--git", "--call-graph"]
  442. }
  443. }
  444. }
  445. ```
  446. > **Note for Copilot Enterprise**: MCP support requires VS Code 1.102+ and must be enabled by your organization administrator.
  447. ---
  448. **Claude Desktop** (`claude_desktop_config.json`):
  449. ```json
  450. {
  451. "mcpServers": {
  452. "narsil-mcp": {
  453. "command": "narsil-mcp",
  454. "args": ["--repos", "/path/to/your/projects", "--git"]
  455. }
  456. }
  457. }
  458. ```
  459. ---
  460. **Zed** (`settings.json` → Context Servers):
  461. ```json
  462. {
  463. "context_servers": {
  464. "narsil-mcp": {
  465. "command": "narsil-mcp",
  466. "args": ["--repos", ".", "--git"]
  467. }
  468. }
  469. }
  470. ```
  471. > **Note for Zed**: narsil-mcp starts immediately and indexes in the background, preventing initialization timeouts.
  472. ---
  473. ### Claude Code Plugin
  474. For **Claude Code** users, we provide a plugin with slash commands and a skill for effective tool usage.
  475. **Install via Marketplace (Recommended):**
  476. ```shell
  477. # Add the narsil-mcp marketplace
  478. /plugin marketplace add postrv/narsil-mcp
  479. # Install the plugin
  480. /plugin install narsil@narsil-mcp
  481. ```
  482. **Or install directly from GitHub:**
  483. ```shell
  484. /plugin install github:postrv/narsil-mcp/narsil-plugin
  485. ```
  486. **What's included:**
  487. | Component | Description |
  488. |-----------|-------------|
  489. | `/narsil:security-scan` | Run comprehensive security audits |
  490. | `/narsil:explore` | Explore unfamiliar codebases |
  491. | `/narsil:analyze-function` | Deep dive on specific functions |
  492. | `/narsil:find-feature` | Find where features are implemented |
  493. | `/narsil:supply-chain` | Analyze supply chain security |
  494. | **Skill** | Guides Claude on using 90 tools effectively |
  495. | **MCP Config** | Auto-starts narsil-mcp with sensible defaults |
  496. See [narsil-plugin/README.md](narsil-plugin/README.md) for full documentation.
  497. ### Ralph Automation Integration
  498. [Ralph](https://github.com/postrv/ralphing-la-vida-locum) is a Claude Code automation suite for autonomous code development. When narsil-mcp is available, Ralph gains enhanced code intelligence capabilities:
  499. | Feature | Without narsil-mcp | With narsil-mcp |
  500. |---------|-------------------|-----------------|
  501. | Security scanning | Basic (clippy) | OWASP/CWE vulnerability detection |
  502. | Code understanding | File-based | Call graphs, symbol references |
  503. | Architecture analysis | Manual | CCG L0/L1/L2 automatic layers |
  504. | Dependency analysis | cargo tree | Import graphs, circular detection |
  505. **Setup:**
  506. ```bash
  507. # Install narsil-mcp (Ralph auto-detects it)
  508. cargo install narsil-mcp
  509. # Ralph's quality gates use these tools:
  510. narsil-mcp scan_security --repo <name>
  511. narsil-mcp check_type_errors --repo <name> --path src
  512. narsil-mcp find_injection_vulnerabilities --repo <name>
  513. ```
  514. Ralph gracefully degrades when narsil-mcp is unavailable - all core automation features work without it.
  515. > **Documentation:** See [Ralph README](https://github.com/postrv/ralphing-la-vida-locum) for full integration details.
  516. ### Playbooks & Tutorials
  517. See **[docs/playbooks](docs/playbooks/)** for practical usage guides:
  518. | Guide | Description |
  519. |-------|-------------|
  520. | [Getting Started](docs/playbooks/getting-started.md) | Quick setup and first tool calls |
  521. | [Understand a Codebase](docs/playbooks/workflows/understand-codebase.md) | Explore unfamiliar projects |
  522. | [Fix a Bug](docs/playbooks/workflows/fix-a-bug.md) | Debug with call graphs and taint analysis |
  523. | [Security Audit](docs/playbooks/workflows/security-audit.md) | Find vulnerabilities with OWASP/CWE scanning |
  524. | [Code Review](docs/playbooks/workflows/code-review.md) | Review changes effectively |
  525. Each playbook shows the exact tool chains Claude uses to answer your questions.
  526. ### WebAssembly (Browser) Usage
  527. The repository contains experimental WebAssembly source and a local build script.
  528. `@narsil-mcp/wasm` is not published on npm and is not a distribution channel for
  529. the 1.7.1 CLI release. The WASM build and examples are not covered by its release
  530. qualification. See [docs/wasm.md](docs/wasm.md) for the experimental source workflow.
  531. ## Available Tools (93)
  532. ### Repository & File Management
  533. | Tool | Description |
  534. |------|-------------|
  535. | `list_repos` | List all indexed repositories with metadata |
  536. | `get_project_structure` | Get directory tree with file icons and sizes |
  537. | `get_file` | Get file contents with optional line range |
  538. | `get_excerpt` | Extract code around specific lines with context |
  539. | `reindex` | Trigger re-indexing of repositories |
  540. | `discover_repos` | Auto-discover repositories in a directory |
  541. | `validate_repo` | Check if path is a valid repository |
  542. | `get_index_status` | Show index stats and enabled features |
  543. ### Symbol Search & Navigation
  544. | Tool | Description |
  545. |------|-------------|
  546. | `find_symbols` | Find structs, classes, functions by type/pattern |
  547. | `get_symbol_definition` | Get symbol source with surrounding context |
  548. | `find_references` | Find all references to a symbol |
  549. | `get_dependencies` | Analyze imports and dependents |
  550. | `workspace_symbol_search` | Fuzzy search symbols across workspace |
  551. | `find_symbol_usages` | Cross-file symbol usage with imports |
  552. | `get_export_map` | Get exported symbols from a file/module |
  553. ### Code Search
  554. | Tool | Description |
  555. |------|-------------|
  556. | `search_code` | Keyword search with relevance ranking |
  557. | `semantic_search` | BM25-ranked semantic search |
  558. | `hybrid_search` | Combined BM25 + TF-IDF with rank fusion |
  559. | `search_chunks` | Search over AST-aware code chunks |
  560. | `find_similar_code` | Find code similar to a snippet (TF-IDF) |
  561. | `find_similar_to_symbol` | Find code similar to a symbol |
  562. ### AST-Aware Chunking
  563. | Tool | Description |
  564. |------|-------------|
  565. | `get_chunks` | Get AST-aware chunks for a file |
  566. | `get_chunk_stats` | Statistics about code chunks |
  567. | `get_embedding_stats` | Embedding index statistics |
  568. ### Neural Semantic Search (requires `--neural`)
  569. | Tool | Description |
  570. |------|-------------|
  571. | `neural_search` | Semantic search using neural embeddings (finds similar code even with different names) |
  572. | `find_semantic_clones` | Find Type-3/4 semantic clones of a function |
  573. | `get_neural_stats` | Neural embedding index statistics |
  574. ### Call Graph Analysis (requires `--call-graph`)
  575. | Tool | Description |
  576. |------|-------------|
  577. | `get_call_graph` | Get call graph for repository/function |
  578. | `get_callers` | Find functions that call a function |
  579. | `get_callees` | Find functions called by a function |
  580. | `find_call_path` | Find path between two functions |
  581. | `get_complexity` | Get cyclomatic/cognitive complexity |
  582. | `get_function_hotspots` | Find highly connected functions |
  583. ### Control Flow Analysis
  584. | Tool | Description |
  585. |------|-------------|
  586. | `get_control_flow` | Get CFG showing basic blocks and branches |
  587. | `find_dead_code` | Find unreachable code blocks |
  588. ### Data Flow Analysis
  589. | Tool | Description |
  590. |------|-------------|
  591. | `get_data_flow` | Variable definitions and uses |
  592. | `get_reaching_definitions` | Which assignments reach each point |
  593. | `find_uninitialized` | Variables used before initialization |
  594. | `find_dead_stores` | Assignments that are never read |
  595. ### Type Inference (Python/JavaScript/TypeScript)
  596. | Tool | Description |
  597. |------|-------------|
  598. | `infer_types` | Infer types for variables in a function without external type checkers |
  599. | `check_type_errors` | Find potential type errors without running mypy/tsc |
  600. | `get_typed_taint_flow` | Enhanced taint analysis combining data flow with type inference |
  601. ### Import/Dependency Graph
  602. | Tool | Description |
  603. |------|-------------|
  604. | `get_import_graph` | Build and analyze import graph |
  605. | `find_circular_imports` | Detect circular dependencies |
  606. | `get_incremental_status` | Merkle tree and change statistics |
  607. ### Security Analysis - Taint Tracking
  608. | Tool | Description |
  609. |------|-------------|
  610. | `find_injection_vulnerabilities` | Find SQL injection, XSS, command injection, path traversal |
  611. | `trace_taint` | Trace tainted data flow from a source |
  612. | `get_taint_sources` | List taint sources (user input, files, network) |
  613. | `get_security_summary` | Comprehensive security risk assessment |
  614. ### Security Analysis - Rules Engine
  615. | Tool | Description |
  616. |------|-------------|
  617. | `scan_security` | Scan with security rules (OWASP, CWE, crypto, secrets) |
  618. | `check_owasp_top10` | Scan for OWASP Top 10 2021 vulnerabilities |
  619. | `check_cwe_top25` | Scan for CWE Top 25 weaknesses |
  620. | `explain_vulnerability` | Get detailed vulnerability explanation |
  621. | `suggest_fix` | Get remediation suggestions for findings |
  622. ### Supply Chain Security
  623. | Tool | Description |
  624. |------|-------------|
  625. | `generate_sbom` | Generate SBOM (CycloneDX/SPDX/JSON) |
  626. | `check_dependencies` | Check for known vulnerabilities (OSV database) |
  627. | `check_licenses` | Analyze licenses for compliance issues |
  628. | `find_upgrade_path` | Find safe upgrade paths for vulnerable deps |
  629. ### Git Integration (requires `--git`)
  630. | Tool | Description |
  631. |------|-------------|
  632. | `get_blame` | Git blame for file |
  633. | `get_file_history` | Commit history for file |
  634. | `get_recent_changes` | Recent commits in repository |
  635. | `get_hotspots` | Files with high churn and complexity |
  636. | `get_contributors` | Repository/file contributors |
  637. | `get_commit_diff` | Diff for specific commit |
  638. | `get_symbol_history` | Commits that changed a symbol |
  639. | `get_branch_info` | Current branch and status |
  640. | `get_modified_files` | Working tree changes |
  641. ### LSP Integration (requires `--lsp`)
  642. | Tool | Description |
  643. |------|-------------|
  644. | `get_hover_info` | Type info and documentation |
  645. | `get_type_info` | Precise type information |
  646. | `go_to_definition` | Find definition location |
  647. ### Remote Repository Support (requires `--remote`)
  648. | Tool | Description |
  649. |------|-------------|
  650. | `add_remote_repo` | Clone and index GitHub repository |
  651. | `list_remote_files` | List files via GitHub API |
  652. | `get_remote_file` | Fetch file via GitHub API |
  653. ### Metrics
  654. | Tool | Description |
  655. |------|-------------|
  656. | `get_metrics` | Performance stats and timing |
  657. ### SPARQL / Knowledge Graph (requires `--graph`)
  658. | Tool | Description |
  659. |------|-------------|
  660. | `sparql_query` | Execute SPARQL query against RDF knowledge graph |
  661. | `list_sparql_templates` | List available SPARQL query templates |
  662. | `run_sparql_template` | Execute predefined SPARQL template with parameters |
  663. ### Code Context Graph (CCG) (requires `--graph`)
  664. CCG provides standardized, AI-consumable representations of codebases in tiered layers.
  665. | Tool | Description |
  666. |------|-------------|
  667. | `get_ccg_manifest` | Layer 0 manifest (~1-2KB JSON-LD) - repo identity, counts |
  668. | `export_ccg_manifest` | Export Layer 0 manifest to file |
  669. | `export_ccg_architecture` | Layer 1 architecture (~10-50KB JSON-LD) - modules, API |
  670. | `export_ccg_index` | Layer 2 symbol index (~100-500KB N-Quads gzipped) |
  671. | `export_ccg_full` | Layer 3 full detail (~1-20MB N-Quads gzipped) |
  672. | `export_ccg` | Export all CCG layers as a bundle |
  673. | `query_ccg` | Query CCG using SPARQL |
  674. | `get_ccg_acl` | Generate WebACL access control for CCG layers |
  675. | `get_ccg_access_info` | Get CCG access tier information |
  676. | `import_ccg` | Import CCG layer from URL or file |
  677. | `import_ccg_from_registry` | Import CCG from codecontextgraph.com registry |
  678. ## Security Rules
  679. narsil-mcp includes built-in security rules in `rules/`:
  680. **Core Rulesets:**
  681. - **`owasp-top10.yaml`** - OWASP Top 10 2021 vulnerability patterns
  682. - **`cwe-top25.yaml`** - CWE Top 25 Most Dangerous Weaknesses
  683. - **`crypto.yaml`** - Cryptographic issues (weak algorithms, hardcoded keys)
  684. - **`secrets.yaml`** - Secret detection (API keys, passwords, tokens)
  685. **Language-Specific Rules:**
  686. - **`rust.yaml`** - Rust security patterns (unsafe transmute, FFI boundaries, command injection, TOCTOU)
  687. - **`elixir.yaml`** - Elixir/BEAM patterns (atom exhaustion, binary_to_term, Code.eval, Ecto SQL injection)
  688. - **`go.yaml`** - Go security patterns (SQL injection, TLS, command injection)
  689. - **`java.yaml`** - Java vulnerabilities (XXE, deserialization, LDAP injection)
  690. - **`csharp.yaml`** - C# security issues (deserialization, XSS, path traversal)
  691. - **`kotlin.yaml`** - Kotlin/Android patterns (WebView, intents, secrets)
  692. - **`bash.yaml`** - Shell script vulnerabilities (command injection, eval)
  693. **Infrastructure & Configuration:**
  694. - **`iac.yaml`** - Infrastructure as Code (Terraform, CloudFormation, Kubernetes)
  695. - **`config.yaml`** - Configuration file security (hardcoded credentials, insecure settings)
  696. Custom rules can be loaded with `scan_security --ruleset /path/to/rules.yaml`.
  697. ## Architecture
  698. ```
  699. +-----------------------------------------------------------------+
  700. | MCP Server |
  701. | +-----------------------------------------------------------+ |
  702. | | JSON-RPC over stdio | |
  703. | +-----------------------------------------------------------+ |
  704. | | |
  705. | +---------------------------v-------------------------------+ |
  706. | | Code Intel Engine | |
  707. | | +------------+ +------------+ +------------------------+ | |
  708. | | | Symbol | | File | | Search Engine | | |
  709. | | | Index | | Cache | | (Tantivy + TF-IDF) | | |
  710. | | | (DashMap) | | (DashMap) | +------------------------+ | |
  711. | | +------------+ +------------+ | |
  712. | | +------------+ +------------+ +------------------------+ | |
  713. | | | Call Graph | | Taint | | Security Rules | | |
  714. | | | Analysis | | Tracker | | Engine | | |
  715. | | +------------+ +------------+ +------------------------+ | |
  716. | +-----------------------------------------------------------+ |
  717. | | |
  718. | +---------------------------v-------------------------------+ |
  719. | | Tree-sitter Parser | |
  720. | | +------+ +------+ +------+ +------+ +------+ | |
  721. | | | Rust | |Python| | JS | | TS | | Go | ... | |
  722. | | +------+ +------+ +------+ +------+ +------+ | |
  723. | +-----------------------------------------------------------+ |
  724. | | |
  725. | +---------------------------v-------------------------------+ |
  726. | | Repository Walker | |
  727. | | (ignore crate - respects .gitignore) | |
  728. | +-----------------------------------------------------------+ |
  729. +-----------------------------------------------------------------+
  730. ```
  731. ## Performance
  732. Benchmarked on Apple M1 (criterion.rs):
  733. ### Parsing Throughput
  734. | Language | Input Size | Time | Throughput |
  735. |----------|------------|------|------------|
  736. | Rust (large file) | 278 KB | 131 µs | **1.98 GiB/s** |
  737. | Rust (medium file) | 27 KB | 13.5 µs | 1.89 GiB/s |
  738. | Python | ~4 KB | 16.7 µs | - |
  739. | TypeScript | ~5 KB | 13.9 µs | - |
  740. | Mixed (5 files) | ~15 KB | 57 µs | - |
  741. ### Search Latency
  742. | Operation | Corpus Size | Time |
  743. |-----------|-------------|------|
  744. | Symbol exact match | 1,000 symbols | **483 ns** |
  745. | Symbol prefix match | 1,000 symbols | 2.7 µs |
  746. | Symbol fuzzy match | 1,000 symbols | 16.5 µs |
  747. | BM25 full-text | 1,000 docs | 80 µs |
  748. | TF-IDF similarity | 1,000 docs | 130 µs |
  749. | Hybrid (BM25+TF-IDF) | 1,000 docs | 151 µs |
  750. ### End-to-End Indexing
  751. | Repository | Files | Symbols | Time | Memory |
  752. |------------|-------|---------|------|--------|
  753. | narsil-mcp (this repo) | 53 | 1,733 | 220 ms | ~50 MB |
  754. | rust-analyzer | 2,847 | ~50K | 2.1s | 89 MB |
  755. | linux kernel | 78,000+ | ~500K | 45s | 2.1 GB |
  756. **Key metrics:**
  757. - Tree-sitter parsing: **~2 GiB/s** sustained throughput
  758. - Symbol lookup: **<1µs** for exact match
  759. - Full-text search: **<1ms** for most queries
  760. - Hybrid search runs BM25 + TF-IDF in parallel via rayon
  761. ## Development
  762. ```bash
  763. # Run the full test suite
  764. cargo test
  765. # Run benchmarks (criterion.rs)
  766. cargo bench
  767. # Run with debug logging
  768. RUST_LOG=debug cargo run -- --repos ./test-fixtures
  769. # Format code
  770. cargo fmt
  771. # Lint
  772. cargo clippy
  773. # Test with MCP Inspector
  774. npx @modelcontextprotocol/inspector ./target/release/narsil-mcp --repos ./path/to/repo
  775. ```
  776. ## Troubleshooting
  777. ### Tree-sitter Build Errors
  778. If you see errors about missing C compilers or tree-sitter during build:
  779. ```bash
  780. # macOS
  781. xcode-select --install
  782. # Ubuntu/Debian
  783. sudo apt install build-essential
  784. # For WASM builds
  785. brew install emscripten # macOS
  786. ```
  787. ### Neural Search API Errors
  788. ```bash
  789. # Check your API key is set
  790. echo $VOYAGE_API_KEY # or $OPENAI_API_KEY
  791. # Common issue: wrong key format
  792. export VOYAGE_API_KEY="pa-..." # Voyage keys start with "pa-"
  793. export OPENAI_API_KEY="sk-..." # OpenAI keys start with "sk-"
  794. ```
  795. ### Index Not Finding Files
  796. ```bash
  797. # Check .gitignore isn't excluding files
  798. narsil-mcp --repos /path --verbose # Shows skipped files
  799. # Force reindex
  800. narsil-mcp --repos /path --reindex
  801. ```
  802. ### Memory Issues with Large Repos
  803. ```bash
  804. # For very large repos (>50K files), increase stack size
  805. RUST_MIN_STACK=8388608 narsil-mcp --repos /path/to/huge-repo
  806. # Or index specific subdirectories
  807. narsil-mcp --repos /path/to/repo/src --repos /path/to/repo/lib
  808. ```
  809. ### Graph Feature Not Working
  810. If you pass `--graph` and see a warning like:
  811. ```
  812. WARN: --graph flag was passed but the binary was built without the 'graph' feature.
  813. SPARQL and CCG tools will not be available.
  814. ```
  815. This means you're using a binary that wasn't compiled with the `graph` feature. To fix:
  816. ```bash
  817. # Build from source with the graph feature
  818. cargo build --release --features graph
  819. # Or with multiple features
  820. cargo build --release --features graph,frontend
  821. # Then run with --graph
  822. ./target/release/narsil-mcp --repos ~/project --graph
  823. ```
  824. **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.
  825. **How to check if graph is enabled:** Look at the startup logs:
  826. - `graph=true` means the feature is compiled in AND enabled
  827. - `graph=false` means either the feature isn't compiled, OR `--graph` wasn't passed
  828. ## Roadmap
  829. ### Completed
  830. - [x] Multi-language symbol extraction (32 languages)
  831. - [x] Full-text search with Tantivy (BM25 ranking)
  832. - [x] Hybrid search (BM25 + TF-IDF with RRF)
  833. - [x] AST-aware code chunking
  834. - [x] Git blame/history integration
  835. - [x] Call graph analysis with complexity metrics
  836. - [x] Control flow graph (CFG) analysis
  837. - [x] Data flow analysis (DFG) with reaching definitions
  838. - [x] Dead code and dead store detection
  839. - [x] Taint analysis for injection vulnerabilities
  840. - [x] Security rules engine (OWASP, CWE, crypto, secrets)
  841. - [x] SBOM generation (CycloneDX, SPDX)
  842. - [x] Dependency vulnerability checking (OSV)
  843. - [x] License compliance analysis
  844. - [x] Import graph with circular dependency detection
  845. - [x] Cross-language symbol resolution
  846. - [x] Incremental indexing with Merkle trees
  847. - [x] Index persistence
  848. - [x] Watch mode for file changes
  849. - [x] LSP integration
  850. - [x] Remote repository support
  851. - [x] Streaming responses
  852. ## What's New
  853. ### v1.6.x (Current)
  854. - **Crash-proof chunking** - Fixed unsafe byte-level string slicing in `chunk_file()` and `extract_signature()` that caused `hybrid_search`, `search_chunks`, and `get_chunk_stats` to crash when processing files with multi-byte UTF-8 characters (emoji, CJK, accented chars). All byte slicing now uses safe `content.get()` with fallback.
  855. - **NaN-safe sort operations** - Fixed 5 locations across search, embeddings, git, index, and extract modules where `partial_cmp().unwrap()` would panic on NaN float values. All sorts now use `unwrap_or(Ordering::Equal)`.
  856. - **Defense-in-depth chunking** - Added `catch_unwind` wrappers around all repo-wide `chunk_file()` loops so a panic in one file skips it instead of crashing the entire MCP server.
  857. - **Visualization frontend overhaul** - Full SPA with HashRouter routing, file tree sidebar, syntax-highlighted code viewer, dashboard, and per-repo overview pages
  858. - **Graph view performance** - Import graph now uses cached index data instead of filesystem walks; symbol graph iterates file cache directly instead of markdown round-trips; all views respect `max_nodes` for early termination
  859. - **Real control flow graphs** - Flow view now uses the real CFG builder (`cfg::analyze_function`) with proper basic blocks, branch conditions, and loop back-edges instead of the single-block stub
  860. - **Hybrid graph budget splitting** - Hybrid view allocates 60/40 node budget between call and import graphs for balanced results
  861. - **Fix [#14](https://github.com/postrv/narsil-mcp/issues/14): configurable embedding dimensions** - Added `--neural-dimension` CLI arg and `default_dimension_for_model()` lookup so models like `text-embedding-3-large` use correct dimensions (3072) instead of hardcoded 1536
  862. - **Fix [#13](https://github.com/postrv/narsil-mcp/issues/13): Nix frontend build** - Added `frontendDist` derivation in `flake.nix` using `buildNpmPackage` so `nix profile install github:postrv/narsil-mcp#with-frontend` works
  863. - **Rust security rules** - 18 new rules (RUST-004 to RUST-021) covering command injection, transmute, FFI boundaries, TOCTOU, ReDoS, static mut, SSRF, and more
  864. - **Elixir security rules** - 18 new rules (EX-001 to EX-018) covering atom exhaustion, binary_to_term deserialization, Code.eval injection, Ecto SQL injection, Phoenix XSS, Erlang distribution security
  865. - **Migrated from `serde_yaml` to `serde-saphyr`** - Deprecated `serde_yaml` replaced with actively maintained, panic-free YAML library
  866. - **Custom favicon** - Frontend now uses narsil-mcp branding icon instead of default Vite logo
  867. - **Dependency security** - Updated `time` to 0.3.47 (RUSTSEC-2026-0009), `bytes` to 1.11.1 (RUSTSEC-2026-0007)
  868. - **Test count** increased from 1,611 to 1,763 (+152 tests)
  869. ### v1.5.x
  870. - **Deterministic call graph resolution** - Scope-hint propagation disambiguates callee resolution (e.g., `App::run()` correctly resolves to `src/app/mod.rs::run`)
  871. - **8 graph analysis fixes** - Qualified node keys, hotspot filtering, CFG expression handling, import path parsing
  872. - **Nix flake improvements** - DRY `mkPkg` helper, removed unnecessary macOS frameworks, `--lib` test strategy for sandbox builds
  873. ### v1.4.x
  874. - **SPARQL / RDF Knowledge Graph** - Query code intelligence data with SPARQL via Oxigraph
  875. - **Code Context Graph (CCG)** - 12 tools for standardized, AI-consumable codebase representations with tiered layers (L0-L3)
  876. - **Type-aware security analysis** - Enhanced taint tracking with type inference and trait implementations
  877. - **Multi-language CFG/DFG** - Control flow and data flow analysis extended to Go, Java, C#, Kotlin
  878. - **Infrastructure as Code scanning** - New `iac.yaml` rules for Terraform, CloudFormation, Kubernetes
  879. - **Language-specific security rules** - New rules for Go, Java, C#, Kotlin, Bash
  880. - **6 new languages** - Erlang, Elm, Fortran, PowerShell, Nix, Groovy
  881. - **90 tools total** - Up from 79 with new SPARQL, CCG, and analysis capabilities
  882. ### v1.2.x
  883. - **`exclude_tests` parameter** - 22 tools support filtering out test files
  884. - **npm package** - Install via `npm install -g narsil-mcp`
  885. ### v1.1.x
  886. - **Multi-platform distribution** - Install via Homebrew, Scoop, npm, Cargo, or direct download
  887. - **Configurable tool presets** - Minimal, balanced, full, and security-focused presets
  888. - **Automatic editor detection** - Optimal defaults for Zed, VS Code, Claude Desktop
  889. - **Interactive setup wizard** - `narsil-mcp config init` for easy configuration
  890. - **32 language support** - Added Dart, Julia, R, Perl, Zig, and more
  891. - **Improved performance** - Faster startup with background indexing
  892. ### v1.0.x
  893. - **Neural semantic search** - Find similar code using Voyage AI or OpenAI embeddings
  894. - **Type inference** - Infer types in Python/JavaScript/TypeScript without external tools
  895. - **Multi-language taint analysis** - Security scanning for PHP, Java, C#, Ruby, Kotlin
  896. - **WASM build** - Run in browser for code playgrounds and educational tools
  897. - **147 bundled security rules** - OWASP, CWE, crypto, secrets, Rust, Elixir detection
  898. - **IDE configs included** - Claude Desktop, Cursor, VS Code, Zed templates
  899. ## License
  900. Licensed under either of:
  901. - Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
  902. - MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
  903. at your option.
  904. ## Credits
  905. Built with:
  906. - [tree-sitter](https://tree-sitter.github.io/) - Incremental parsing
  907. - [tantivy](https://github.com/quickwit-oss/tantivy) - Full-text search
  908. - [tokio](https://tokio.rs/) - Async runtime
  909. - [rayon](https://github.com/rayon-rs/rayon) - Data parallelism
  910. - [serde](https://serde.rs/) - Serialization

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.