Narsil MCP

narsil-mcp

El servidor MCP ultrarrápido y centrado en la privacidad para inteligencia de código profunda

Un servidor MCP (Model Context Protocol) desarrollado en Rust que proporciona a los asistentes de IA una comprensión profunda del código a través de 90 herramientas especializadas.

¿Por qué narsil-mcp?

Característica	narsil-mcp	XRAY	Serena	GitHub MCP
Lenguajes	32	4	30+ (LSP)	N/D
Búsqueda neuronal	Sí	No	No	No
Análisis de contaminación	Sí	No	No	No
SBOM/Licencias	Sí	No	No	Parcial
Offline/Local	Sí	Sí	Sí	No
WASM/Navegador	Sí	No	No	No
Grafos de llamadas	Sí	Parcial	No	No
Inferencia de tipos	Sí	No	No	No

Características principales

• Inteligencia de código - Extracción de símbolos, búsqueda semántica, análisis de grafos de llamadas
• Búsqueda semántica neuronal - Encuentra código similar usando embeddings (Voyage AI, OpenAI)
• Análisis de seguridad - Análisis de contaminación, escaneo de vulnerabilidades, cobertura OWASP/CWE
• Seguridad de la cadena de suministro - Generación de SBOM, auditoría de dependencias, cumplimiento de licencias
• Análisis avanzado - Grafos de flujo de control, análisis de flujo de datos, detección de código muerto

¿Por qué elegir narsil-mcp?

• Escrito en Rust - Ultrarrápido, seguro en memoria, binario único (~30MB)
• Impulsado por Tree-sitter - Análisis preciso e incremental para 32 lenguajes
• Configuración cero - Apunta a los repositorios y listo
• Compatible con MCP - Funciona con Claude, Cursor, VS Code Copilot, Zed y cualquier cliente MCP
• Privacidad primero - Totalmente local, ningún dato sale de tu máquina
• Indexación paralela - Utiliza todos los núcleos mediante Rayon
• Extractos inteligentes - Se expande a ámbitos sintácticos completos
• Seguridad primero - Detección de vulnerabilidades y análisis de contaminación integrados
• Embeddings neuronales - Búsqueda semántica opcional con Voyage AI u OpenAI
• Soporte WASM - Ejecución en navegador con compilación WebAssembly
• Transmisión en tiempo real - Resultados a medida que avanza la indexación para repositorios grandes

Lenguajes soportados

Lenguaje	Extensiones	Símbolos extraídos
Rust	.rs	funciones, estructuras, enumeraciones, traits, implementaciones, módulos
Python	.py, .pyi	funciones, clases
JavaScript	.js, .jsx, .mjs	funciones, clases, métodos, variables
TypeScript	.ts, .tsx	funciones, clases, interfaces, tipos, enumeraciones
Go	.go	funciones, métodos, tipos
C	.c, .h	funciones, estructuras, enumeraciones, typedefs
C++	.cpp, .cc, .hpp	funciones, clases, estructuras, espacios de nombres
Java	.java	métodos, clases, interfaces, enumeraciones
C#	.cs	métodos, clases, interfaces, estructuras, enumeraciones, delegados, espacios de nombres
Bash	.sh, .bash, .zsh	funciones, variables
Ruby	.rb, .rake, .gemspec	métodos, clases, módulos
Kotlin	.kt, .kts	funciones, clases, objetos, interfaces
PHP	.php, .phtml	funciones, métodos, clases, interfaces, traits
Swift	.swift	clases, estructuras, enumeraciones, protocolos, funciones
Verilog/SystemVerilog	.v, .vh, .sv, .svh	módulos, tareas, funciones, interfaces, clases
Scala	.scala, .sc	clases, objetos, traits, funciones, valores
Lua	.lua	funciones, métodos
Haskell	.hs, .lhs	funciones, tipos de datos, clases de tipos
Elixir	.ex, .exs	módulos, funciones
Clojure	.clj, .cljs, .cljc, .edn	listas (AST básico)
Dart	.dart	funciones, clases, métodos
Julia	.jl	funciones, módulos, estructuras
R	.R, .r, .Rmd	funciones
Perl	.pl, .pm, .t	funciones, paquetes
Zig	.zig	funciones, variables
Erlang	.erl, .hrl	funciones, módulos, registros
Elm	.elm	funciones, tipos
Fortran	.f90, .f95, .f03, .f08, .f, .for, .fpp	programas, subrutinas, funciones, módulos
PowerShell	.ps1, .psm1, .psd1	funciones, clases, enumeraciones
Nix	.nix	vinculaciones
Groovy	.groovy, .gradle	métodos, clases, interfaces, enumeraciones, funciones

Instalación

Vía gestores de paquetes (Recomendado)

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 (todas las plataformas):

cargo install narsil-mcp

Node.js/npm (todas las plataformas):

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

Script de instalación en un clic

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

Nota para usuarios de Windows: El instalador de PowerShell proporciona mejores mensajes de error e integración nativa con Windows. Configurará automáticamente tu PATH y verificará las herramientas de compilación necesarias si se compila desde el código fuente.

Desde el código fuente

Requisitos previos:

• Rust 1.70 o posterior
• En Windows: Visual Studio Build Tools con "Desarrollo para escritorio con C++"

# Clone and build
git clone [email protected]: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

Compilaciones con funcionalidades específicas

narsil-mcp soporta diferentes conjuntos de funcionalidades para distintos casos de uso:

# 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

Funcionalidad	Descripción	Tamaño
native (por defecto)	Servidor MCP completo con todas las herramientas	~30MB
graph	+ Grafo de conocimiento RDF, herramientas SPARQL, CCG	~35MB
frontend	+ Interfaz web de visualización integrada	~31MB
neural	+ Búsqueda vectorial TF-IDF, embeddings de API	~32MB
neural-onnx	+ Inferencia con modelo ONNX local	~50MB
wasm	Compilación para navegador (sin sistema de archivos, git)	~3MB

Importante: La bandera CLI --graph requiere que el binario se compile con --features graph. Si pasas --graph a un binario compilado sin esta funcionalidad, verás una advertencia y las herramientas SPARQL/CCG no estarán disponibles. Consulta Solución de problemas a continuación.

Para instrucciones detalladas de instalación, solución de problemas y guías específicas por plataforma, consulta docs/INSTALL.md.

Uso

Uso básico

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

Conjunto completo de funcionalidades

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)

Nota sobre --graph: Esta bandera habilita las consultas SPARQL y las herramientas de Code Context Graph (CCG), pero solo si el binario se compiló con --features graph. El binario por defecto no incluye esta funcionalidad. Si necesitas capacidades SPARQL/CCG, compila desde el código fuente con:

cargo build --release --features graph

Si pasas --graph a un binario sin la funcionalidad, verás una advertencia al inicio y el servidor continuará sin las herramientas SPARQL/CCG.

Nota: Los embeddings neuronales requieren una clave API (o un endpoint personalizado). La forma más sencilla de configurarlo es con el asistente interactivo:

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

El asistente:

• Detectará tu editor (Claude Desktop, Claude Code, Zed, VS Code, JetBrains)
• Te pedirá tu proveedor de API (Voyage AI, OpenAI o personalizado)
• Validará tu clave API
• La añadirá automáticamente a la configuración MCP de tu editor

Alternativamente, puedes configurar manualmente una de estas variables de entorno:

• EMBEDDING_API_KEY - Clave API genérica para cualquier proveedor
• VOYAGE_API_KEY - Clave API específica de Voyage AI
• OPENAI_API_KEY - Clave API específica de OpenAI
• EMBEDDING_SERVER_ENDPOINT - URL de endpoint de API de embedding personalizado (opcional, permite usar modelos autoalojados)

Configuración

¡v1.1.0+ introduce configuración opcional para un control detallado sobre las herramientas y el rendimiento. ¡Todo el uso existente sigue funcionando - la configuración es completamente opcional!

Inicio rápido

# 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

Detección automática del editor

narsil-mcp detecta tu editor y aplica un preajuste óptimo automáticamente:

Editor	Preajuste	Herramientas	Tokens de contexto	Por qué
Zed	Mínimo	26	~4,686	Inicio rápido, contexto mínimo
VS Code	Equilibrado	51	~8,948	Buen equilibrio de funcionalidades
Claude Desktop	Completo	90	~12,001	Máximas capacidades

Ahorro de tokens:

• Preajuste mínimo: 61% menos tokens vs Completo
• Preajuste equilibrado: 25% menos tokens vs Completo

Preajustes

Elige un preajuste según tu caso de uso:

# 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

Archivos de configuración

Configuración de usuario (~/.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

Configuración de proyecto (.narsil.yaml en la raíz del repositorio):

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

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

Los perfiles de repositorio con nombre son útiles para espacios de trabajo con múltiples repositorios:

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

Prioridad: Banderas CLI > Variables de entorno > Configuración de proyecto > Configuración de usuario > Valores por defecto

Variables de entorno

# 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

Comandos 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

Más información:

• Guía de configuración - Referencia completa de configuración
• Guía de instalación - Instalación específica por plataforma

Interfaz de visualización

Explora grafos de llamadas, importaciones, referencias a símbolos y flujo de control de forma interactiva en tu navegador.

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

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

Cinco vistas de grafo:

Vista	Descripción
Grafo de llamadas	Relaciones de llamadas a funciones con control de profundidad y filtrado de dirección
Grafo de importaciones	Dependencias de importación a nivel de archivo en todo el código base
Grafo de símbolos	Todas las referencias a un símbolo, con agrupación por archivos
Híbrido	Grafo combinado de llamadas + importaciones con presupuesto dividido
Flujo de control	CFG real con bloques básicos, ramas y aristas de retroceso de bucles

Características:

• Grafos interactivos con Cytoscape.js: arrastrar, zoom y doble clic para profundizar
• Superposición de métricas de complejidad con código de colores (verde/amarillo/naranja/rojo)
• Superposición de vulnerabilidades de seguridad resaltando fuentes y sumideros de contaminación
• Seis algoritmos de disposición (dagre, dirigido por fuerza, primero en anchura, concéntrico, circular, cuadrícula)
• Barra lateral de árbol de archivos con visor de código con resaltado de sintaxis
• Estado basado en URL (enlaces compartibles, navegación adelante/atrás del navegador)
• Soporte para modo oscuro
• Panel de detalles del nodo con extractos de código y navegación al código fuente

Documentación completa: Consulta docs/frontend.md para configuración, endpoints de API y modo de desarrollo.

Búsqueda semántica neuronal

Encuentra código similar usando embeddings neuronales, incluso cuando los nombres de variables y la estructura difieren.

# 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

Soporta Voyage AI, OpenAI, endpoints personalizados y modelos ONNX locales.

Documentación completa: Consulta docs/neural-search.md para configuración, backends y casos de uso.

Inferencia de tipos

Inferencia de tipos integrada para Python, JavaScript y TypeScript, sin necesidad de mypy o tsc.

Herramienta	Descripción
infer_types	Obtiene los tipos inferidos para todas las variables en una función
check_type_errors	Encuentra posibles discrepancias de tipos
get_typed_taint_flow	Análisis de seguridad mejorado con información de tipos

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

Integración con Forgemax (Experimental)

Para flujos de trabajo agénticos a gran escala, narsil-mcp se puede usar a través de Forgemax — un gateway MCP en Modo Código que colapsa las 90 herramientas en solo 2 (search + execute), reduciendo la sobrecarga del esquema de herramientas de ~12,000 tokens a ~1,000.

# Install Forgemax
cargo install forgemax

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

El archivo forge.toml incluido configura narsil-mcp con valores predeterminados sensatos:

[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

El LLM escribe JavaScript que llama a través de objetos proxy tipados dentro de un aislado V8 en sandbox: las credenciales, rutas de archivo y estado interno nunca salen del host. Este enfoque es particularmente útil al trabajar con múltiples servidores MCP simultáneamente, ya que mantiene el contexto total de herramientas pequeño y predecible.

Configuración MCP

Agregue narsil-mcp a su asistente de IA creando un archivo de configuración. Estas son las configuraciones recomendadas:

---

Claude Code (.mcp.json en la raíz del proyecto - Recomendado):

Cree .mcp.json en el directorio de su proyecto para configuración por proyecto:

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

Luego inicie Claude Code en su proyecto:

cd /path/to/project
claude

Usar . para --repos indexa automáticamente el directorio actual. Claude ahora tiene acceso a 90 herramientas de inteligencia de código.

Consejo: Agregue --persist --index-path .claude/cache para un inicio más rápido en ejecuciones posteriores.

Para configuración global, edite ~/.claude/settings.json en su lugar. Consulte Integración con Claude Code para configuraciones avanzadas.

---

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

Nota para Copilot Enterprise: El soporte MCP requiere VS Code 1.102+ y debe ser habilitado por el administrador de su organización.

---

Claude Desktop (claude_desktop_config.json):

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

---

Zed (settings.json → Servidores de Contexto):

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

Nota para Zed: narsil-mcp se inicia inmediatamente e indexa en segundo plano, evitando tiempos de espera de inicialización.

---

Plugin de Claude Code

Para usuarios de Claude Code, proporcionamos un plugin con comandos de barra y una habilidad para un uso efectivo de las herramientas.

Instalar vía Marketplace (Recomendado):

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

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

O instalar directamente desde GitHub:

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

Qué incluye:

Componente	Descripción
/narsil:security-scan	Ejecutar auditorías de seguridad integrales
/narsil:explore	Explorar bases de código desconocidas
/narsil:analyze-function	Análisis profundo de funciones específicas
/narsil:find-feature	Encontrar dónde se implementan características
/narsil:supply-chain	Analizar seguridad de la cadena de suministro
Habilidad	Guía a Claude sobre el uso efectivo de 90 herramientas
Configuración MCP	Inicia automáticamente narsil-mcp con valores predeterminados sensatos

Consulte narsil-plugin/README.md para documentación completa.

Integración con Ralph Automation

Ralph es un conjunto de automatización de Claude Code para desarrollo autónomo de código. Cuando narsil-mcp está disponible, Ralph obtiene capacidades mejoradas de inteligencia de código:

Característica	Sin narsil-mcp	Con narsil-mcp
Escaneo de seguridad	Básico (clippy)	Detección de vulnerabilidades OWASP/CWE
Comprensión de código	Basada en archivos	Grafos de llamadas, referencias de símbolos
Análisis de arquitectura	Manual	Capas automáticas CCG L0/L1/L2
Análisis de dependencias	cargo tree	Grafos de importación, detección circular

Configuración:

# 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 se degrada con gracia cuando narsil-mcp no está disponible: todas las características principales de automatización funcionan sin él.

Documentación: Consulte Ralph README para detalles completos de integración.

Guías y Tutoriales

Consulte docs/playbooks para guías de uso práctico:

Guía	Descripción
Primeros pasos	Configuración rápida y primeras llamadas a herramientas
Comprender una base de código	Explorar proyectos desconocidos
Corregir un error	Depurar con grafos de llamadas y análisis de contaminación
Auditoría de seguridad	Encontrar vulnerabilidades con escaneo OWASP/CWE
Revisión de código	Revisar cambios de manera efectiva

Cada guía muestra las cadenas de herramientas exactas que Claude usa para responder sus preguntas.

Uso en WebAssembly (Navegador)

narsil-mcp puede ejecutarse completamente en el navegador a través de WebAssembly, perfecto para IDEs basados en navegador, herramientas de revisión de código o plataformas educativas.

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

Documentación completa: Consulte docs/wasm.md para instrucciones de compilación, ejemplos de React y referencia de API.

Herramientas Disponibles (90)

Gestión de Repositorios y Archivos

Herramienta	Descripción
list_repos	Listar todos los repositorios indexados con metadatos
get_project_structure	Obtener árbol de directorios con iconos de archivo y tamaños
get_file	Obtener contenido de archivo con rango de líneas opcional
get_excerpt	Extraer código alrededor de líneas específicas con contexto
reindex	Activar reindexación de repositorios
discover_repos	Auto-descubrir repositorios en un directorio
validate_repo	Verificar si la ruta es un repositorio válido
get_index_status	Mostrar estadísticas de índice y características habilitadas

Búsqueda y Navegación de Símbolos

Herramienta	Descripción
find_symbols	Encontrar estructuras, clases, funciones por tipo/patrón
get_symbol_definition	Obtener fuente de símbolo con contexto circundante
find_references	Encontrar todas las referencias a un símbolo
get_dependencies	Analizar importaciones y dependientes
workspace_symbol_search	Búsqueda difusa de símbolos en el espacio de trabajo
find_symbol_usages	Uso de símbolos entre archivos con importaciones
get_export_map	Obtener símbolos exportados de un archivo/módulo

Búsqueda de Código

Herramienta	Descripción
search_code	Búsqueda por palabra clave con clasificación de relevancia
semantic_search	Búsqueda semántica clasificada BM25
hybrid_search	BM25 + TF-IDF combinado con fusión de clasificación
search_chunks	Búsqueda sobre fragmentos de código conscientes del AST
find_similar_code	Encontrar código similar a un fragmento (TF-IDF)
find_similar_to_symbol	Encontrar código similar a un símbolo

Fragmentación Consciente del AST

Herramienta	Descripción
get_chunks	Obtener fragmentos conscientes del AST para un archivo
get_chunk_stats	Estadísticas sobre fragmentos de código
get_embedding_stats	Estadísticas del índice de embeddings

Búsqueda Semántica Neural (requiere --neural)

Herramienta	Descripción
neural_search	Búsqueda semántica usando embeddings neuronales (encuentra código similar incluso con nombres diferentes)
find_semantic_clones	Encontrar clones semánticos Tipo-3/4 de una función
get_neural_stats	Estadísticas del índice de embeddings neuronales

Análisis de Grafo de Llamadas (requiere --call-graph)

Herramienta	Descripción
get_call_graph	Obtener grafo de llamadas para repositorio/función
get_callers	Encontrar funciones que llaman a una función
get_callees	Encontrar funciones llamadas por una función
find_call_path	Encontrar ruta entre dos funciones
get_complexity	Obtener complejidad ciclomática/cognitiva
get_function_hotspots	Encontrar funciones altamente conectadas

Análisis de Flujo de Control

Herramienta	Descripción
get_control_flow	Obtener CFG mostrando bloques básicos y ramas
find_dead_code	Encontrar bloques de código inalcanzables

Análisis de Flujo de Datos

Herramienta	Descripción
get_data_flow	Definiciones y usos de variables
get_reaching_definitions	Qué asignaciones alcanzan cada punto
find_uninitialized	Variables usadas antes de inicialización
find_dead_stores	Asignaciones que nunca se leen

Inferencia de Tipos (Python/JavaScript/TypeScript)

Herramienta	Descripción
infer_types	Inferir tipos para variables en una función sin verificadores de tipos externos
check_type_errors	Encontrar posibles errores de tipo sin ejecutar mypy/tsc
get_typed_taint_flow	Análisis de contaminación mejorado combinando flujo de datos con inferencia de tipos

Grafo de Importación/Dependencia

Herramienta	Descripción
get_import_graph	Construir y analizar grafo de importación
find_circular_imports	Detectar dependencias circulares
get_incremental_status	Árbol de Merkle y estadísticas de cambios

Análisis de Seguridad - Seguimiento de Contaminación

Herramienta	Descripción
find_injection_vulnerabilities	Encontrar inyección SQL, XSS, inyección de comandos, path traversal
trace_taint	Rastrear flujo de datos contaminados desde una fuente
get_taint_sources	Listar fuentes de contaminación (entrada de usuario, archivos, red)
get_security_summary	Evaluación integral de riesgos de seguridad

Análisis de Seguridad - Motor de Reglas

Herramienta	Descripción
scan_security	Escanear con reglas de seguridad (OWASP, CWE, cripto, secretos)
check_owasp_top10	Escanear vulnerabilidades OWASP Top 10 2021
check_cwe_top25	Escanear debilidades CWE Top 25
explain_vulnerability	Obtener explicación detallada de vulnerabilidad
suggest_fix	Obtener sugerencias de remediación para hallazgos

Seguridad de la Cadena de Suministro

Herramienta	Descripción
generate_sbom	Generar SBOM (CycloneDX/SPDX/JSON)
check_dependencies	Verificar vulnerabilidades conocidas (base de datos OSV)
check_licenses	Analizar licencias para problemas de cumplimiento
find_upgrade_path	Encontrar rutas de actualización seguras para dependencias vulnerables

Integración Git (requiere --git)

Herramienta	Descripción
get_blame	Git blame para archivo
get_file_history	Historial de commits para archivo
get_recent_changes	Commits recientes en repositorio
get_hotspots	Archivos con alta rotación y complejidad
get_contributors	Contribuidores de repositorio/archivo
get_commit_diff	Diff para commit específico
get_symbol_history	Commits que cambiaron un símbolo
get_branch_info	Rama actual y estado
get_modified_files	Cambios en el árbol de trabajo

Integración LSP (requiere --lsp)

Herramienta	Descripción
get_hover_info	Información de tipo y documentación
get_type_info	Información precisa de tipo
go_to_definition	Encontrar ubicación de definición

Soporte para Repositorios Remotos (requiere --remote)

Herramienta	Descripción
add_remote_repo	Clonar e indexar repositorio de GitHub
list_remote_files	Listar archivos vía API de GitHub
get_remote_file	Obtener archivo vía API de GitHub

Métricas

Herramienta	Descripción
get_metrics	Estadísticas de rendimiento y tiempos

SPARQL / Grafo de Conocimiento (requiere --graph)

Herramienta	Descripción
sparql_query	Ejecutar consulta SPARQL contra grafo de conocimiento RDF
list_sparql_templates	Listar plantillas de consulta SPARQL disponibles
run_sparql_template	Ejecutar plantilla SPARQL predefinida con parámetros

Grafo de Contexto de Código (CCG) (requiere --graph)

CCG proporciona representaciones estandarizadas y consumibles por IA de bases de código en capas escalonadas.

Herramienta	Descripción
get_ccg_manifest	Manifiesto de Capa 0 (~1-2KB JSON-LD) - identidad del repo, conteos
export_ccg_manifest	Exportar manifiesto de Capa 0 a archivo
export_ccg_architecture	Arquitectura de Capa 1 (~10-50KB JSON-LD) - módulos, API
export_ccg_index	Índice de símbolos de Capa 2 (~100-500KB N-Quads comprimido)
export_ccg_full	Detalle completo de Capa 3 (~1-20MB N-Quads comprimido)
export_ccg	Exportar todas las capas CCG como un paquete
query_ccg	Consultar CCG usando SPARQL
get_ccg_acl	Generar control de acceso WebACL para capas CCG
get_ccg_access_info	Obtener información de nivel de acceso CCG
import_ccg	Importar capa CCG desde URL o archivo
import_ccg_from_registry	Importar CCG desde el registro codecontextgraph.com

Reglas de Seguridad

narsil-mcp incluye reglas de seguridad integradas en rules/:

Conjuntos de Reglas Principales:

• owasp-top10.yaml - Patrones de vulnerabilidad OWASP Top 10 2021
• cwe-top25.yaml - Debilidades Más Peligrosas CWE Top 25
• crypto.yaml - Problemas criptográficos (algoritmos débiles, claves hardcodeadas)
• secrets.yaml - Detección de secretos (claves API, contraseñas, tokens) Reglas específicas por lenguaje:
• rust.yaml - Patrones de seguridad en Rust (transmute inseguro, límites FFI, inyección de comandos, TOCTOU)
• elixir.yaml - Patrones de Elixir/BEAM (agotamiento de átomos, binary_to_term, Code.eval, inyección SQL en Ecto)
• go.yaml - Patrones de seguridad en Go (inyección SQL, TLS, inyección de comandos)
• java.yaml - Vulnerabilidades en Java (XXE, deserialización, inyección LDAP)
• csharp.yaml - Problemas de seguridad en C# (deserialización, XSS, path traversal)
• kotlin.yaml - Patrones de Kotlin/Android (WebView, intents, secretos)
• bash.yaml - Vulnerabilidades en scripts de shell (inyección de comandos, eval)

Infraestructura y configuración:

• iac.yaml - Infraestructura como código (Terraform, CloudFormation, Kubernetes)
• config.yaml - Seguridad en archivos de configuración (credenciales hardcodeadas, configuraciones inseguras)

Se pueden cargar reglas personalizadas con scan_security --ruleset /path/to/rules.yaml.

Arquitectura

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

Rendimiento

Benchmark realizado en Apple M1 (criterion.rs):

Rendimiento de análisis

Lenguaje	Tamaño de entrada	Tiempo	Rendimiento
Rust (archivo grande)	278 KB	131 µs	1.98 GiB/s
Rust (archivo mediano)	27 KB	13.5 µs	1.89 GiB/s
Python	~4 KB	16.7 µs	-
TypeScript	~5 KB	13.9 µs	-
Mixto (5 archivos)	~15 KB	57 µs	-

Latencia de búsqueda

Operación	Tamaño del corpus	Tiempo
Coincidencia exacta de símbolo	1,000 símbolos	483 ns
Coincidencia por prefijo de símbolo	1,000 símbolos	2.7 µs
Coincidencia difusa de símbolo	1,000 símbolos	16.5 µs
Texto completo BM25	1,000 docs	80 µs
Similitud TF-IDF	1,000 docs	130 µs
Híbrida (BM25+TF-IDF)	1,000 docs	151 µs

Indexación de extremo a extremo

Repositorio	Archivos	Símbolos	Tiempo	Memoria
narsil-mcp (este repo)	53	1,733	220 ms	~50 MB
rust-analyzer	2,847	~50K	2.1s	89 MB
kernel linux	78,000+	~500K	45s	2.1 GB

Métricas clave:

• Análisis Tree-sitter: rendimiento sostenido de ~2 GiB/s
• Búsqueda de símbolos: <1µs para coincidencia exacta
• Búsqueda de texto completo: <1ms para la mayoría de consultas
• La búsqueda híbrida ejecuta BM25 + TF-IDF en paralelo mediante rayon

Desarrollo

# 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

Solución de problemas

Errores de compilación de Tree-sitter

Si ves errores sobre compiladores de C faltantes o tree-sitter durante la compilación:

# macOS
xcode-select --install

# Ubuntu/Debian
sudo apt install build-essential

# For WASM builds
brew install emscripten  # macOS

Errores de la API de búsqueda neuronal

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

El índice no encuentra archivos

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

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

Problemas de memoria con repositorios grandes

# 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

La funcionalidad de grafos no funciona

Si pasas --graph y ves una advertencia como:

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

Esto significa que estás usando un binario que no fue compilado con la característica graph. Para solucionarlo:

# 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

¿Por qué es una característica separada? La característica graph añade la base de datos RDF Oxigraph (~5 MB adicionales de tamaño de binario) que no es necesaria para la mayoría de los casos de uso. Se mantiene opcional para que el binario por defecto sea más pequeño.

Cómo verificar si el grafo está habilitado: Revisa los registros de inicio:

• graph=true significa que la característica está compilada Y habilitada
• graph=false significa que la característica no está compilada, O no se pasó --graph

Hoja de ruta

Completado

• Extracción de símbolos multi-lenguaje (32 lenguajes)
• Búsqueda de texto completo con Tantivy (ranking BM25)
• Búsqueda híbrida (BM25 + TF-IDF con RRF)
• Fragmentación de código consciente del AST
• Integración de Git blame/historial
• Análisis de grafo de llamadas con métricas de complejidad
• Análisis de grafo de flujo de control (CFG)
• Análisis de flujo de datos (DFG) con definiciones alcanzables
• Detección de código muerto y almacenamiento muerto
• Análisis de contaminación para vulnerabilidades de inyección
• Motor de reglas de seguridad (OWASP, CWE, cripto, secretos)
• Generación de SBOM (CycloneDX, SPDX)
• Verificación de vulnerabilidades en dependencias (OSV)
• Análisis de cumplimiento de licencias
• Grafo de importaciones con detección de dependencias circulares
• Resolución de símbolos entre lenguajes
• Indexación incremental con árboles de Merkle
• Persistencia del índice
• Modo vigilancia para cambios en archivos
• Integración con LSP
• Soporte para repositorios remotos
• Respuestas en streaming

Novedades

v1.6.x (Actual)

• Fragmentación a prueba de fallos - Se corrigió el corte inseguro de cadenas a nivel de bytes en chunk_file() y extract_signature() que causaba que hybrid_search, search_chunks y get_chunk_stats fallaran al procesar archivos con caracteres UTF-8 multibyte (emoji, CJK, caracteres acentuados). Todo el corte de bytes ahora usa content.get() seguro con respaldo.
• Operaciones de ordenación seguras ante NaN - Se corrigieron 5 ubicaciones en los módulos de búsqueda, embeddings, git, índice y extracción donde partial_cmp().unwrap() entraría en pánico con valores float NaN. Todas las ordenaciones ahora usan unwrap_or(Ordering::Equal).
• Fragmentación con defensa en profundidad - Se añadieron envoltorios catch_unwind alrededor de todos los bucles chunk_file() de todo el repositorio para que un pánico en un archivo lo omita en lugar de bloquear todo el servidor MCP.
• Revisión del frontend de visualización - SPA completa con enrutamiento HashRouter, barra lateral de árbol de archivos, visor de código con resaltado de sintaxis, panel de control y páginas de resumen por repositorio.
• Rendimiento de la vista de grafos - El grafo de importaciones ahora usa datos del índice en caché en lugar de recorridos del sistema de archivos; el grafo de símbolos itera directamente sobre la caché de archivos en lugar de viajes de ida y vuelta a markdown; todas las vistas respetan max_nodes para terminación temprana.
• Grafos de flujo de control reales - La vista de flujo ahora usa el constructor CFG real (cfg::analyze_function) con bloques básicos, condiciones de rama y bordes de retroceso de bucle adecuados en lugar del stub de bloque único.
• División del presupuesto del grafo híbrido - La vista híbrida asigna un presupuesto de nodos 60/40 entre los grafos de llamadas e importaciones para obtener resultados equilibrados.
• Corrección #14: dimensiones de embedding configurables - Se añadió el argumento CLI --neural-dimension y la búsqueda default_dimension_for_model() para que modelos como text-embedding-3-large usen las dimensiones correctas (3072) en lugar de las 1536 hardcodeadas.
• Corrección #13: compilación del frontend Nix - Se añadió la derivación frontendDist en flake.nix usando buildNpmPackage para que nix profile install github:postrv/narsil-mcp#with-frontend funcione.
• Reglas de seguridad para Rust - 18 nuevas reglas (RUST-004 a RUST-021) que cubren inyección de comandos, transmute, límites FFI, TOCTOU, ReDoS, static mut, SSRF y más.
• Reglas de seguridad para Elixir - 18 nuevas reglas (EX-001 a EX-018) que cubren agotamiento de átomos, deserialización binary_to_term, inyección Code.eval, inyección SQL en Ecto, XSS en Phoenix, seguridad de distribución de Erlang.
• Migración de serde_yaml a serde-saphyr - serde_yaml obsoleto reemplazado por una biblioteca YAML mantenida activamente y libre de pánicos.
• Favicon personalizado - El frontend ahora usa el icono de marca narsil-mcp en lugar del logo por defecto de Vite.
• Seguridad de dependencias - Actualizado time a 0.3.47 (RUSTSEC-2026-0009), bytes a 1.11.1 (RUSTSEC-2026-0007).
• Conteo de pruebas aumentado de 1,611 a 1,763 (+152 pruebas).

v1.5.x

• Resolución determinista del grafo de llamadas - La propagación de sugerencias de ámbito desambigua la resolución del llamado (por ejemplo, App::run() se resuelve correctamente a src/app/mod.rs::run).
• 8 correcciones de análisis de grafos - Claves de nodo calificadas, filtrado de puntos calientes, manejo de expresiones CFG, análisis de rutas de importación.
• Mejoras en Nix flake - Helper mkPkg DRY, eliminación de frameworks macOS innecesarios, estrategia de prueba --lib para compilaciones en sandbox.

v1.4.x

• Grafo de conocimiento SPARQL / RDF - Consulta datos de inteligencia de código con SPARQL a través de Oxigraph.
• Grafo de contexto de código (CCG) - 12 herramientas para representaciones de base de código estandarizadas y consumibles por IA con capas escalonadas (L0-L3).
• Análisis de seguridad consciente de tipos - Seguimiento de contaminación mejorado con inferencia de tipos e implementaciones de traits.
• CFG/DFG multi-lenguaje - Análisis de flujo de control y flujo de datos extendido a Go, Java, C#, Kotlin.
• Escaneo de infraestructura como código - Nuevas reglas iac.yaml para Terraform, CloudFormation, Kubernetes.
• Reglas de seguridad específicas por lenguaje - Nuevas reglas para Go, Java, C#, Kotlin, Bash.
• 6 nuevos lenguajes - Erlang, Elm, Fortran, PowerShell, Nix, Groovy.
• 90 herramientas en total - Subiendo de 79 con nuevas capacidades SPARQL, CCG y de análisis.

v1.2.x

• Parámetro exclude_tests - 22 herramientas soportan el filtrado de archivos de prueba.
• Paquete npm - Instalación mediante npm install -g narsil-mcp.

v1.1.x

• Distribución multiplataforma - Instalación mediante Homebrew, Scoop, npm, Cargo o descarga directa.
• Preajustes de herramientas configurables - Preajustes mínimo, equilibrado, completo y enfocado en seguridad.
• Detección automática de editor - Valores predeterminados óptimos para Zed, VS Code, Claude Desktop.
• Asistente de configuración interactivo - narsil-mcp config init para una configuración sencilla.
• Soporte para 32 lenguajes - Se añadieron Dart, Julia, R, Perl, Zig y más.
• Rendimiento mejorado - Inicio más rápido con indexación en segundo plano.

v1.0.x

• Búsqueda semántica neuronal - Encuentra código similar usando embeddings de Voyage AI u OpenAI.
• Inferencia de tipos - Infiere tipos en Python/JavaScript/TypeScript sin herramientas externas.
• Análisis de contaminación multi-lenguaje - Escaneo de seguridad para PHP, Java, C#, Ruby, Kotlin.
• Compilación WASM - Ejecución en navegador para playgrounds de código y herramientas educativas.
• 147 reglas de seguridad incluidas - Detección OWASP, CWE, cripto, secretos, Rust, Elixir.
• Configuraciones de IDE incluidas - Plantillas para Claude Desktop, Cursor, VS Code, Zed.

Licencia

Licenciado bajo cualquiera de:

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

a su elección.

Créditos

Construido con:

• tree-sitter - Análisis incremental
• tantivy - Búsqueda de texto completo
• tokio - Tiempo de ejecución asíncrono
• rayon - Paralelismo de datos
• serde - Serialización