Narsil MCP

narsil-mcp

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

Un servidor MCP (Model Context Protocol) impulsado por 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
Idiomas	32	4	30+ (LSP)	N/A
Búsqueda neuronal	Sí	No	No	No
Análisis de flujo de datos	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 flujo de datos, 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 - Extremadamente rápido, seguro en memoria, binario único (~30MB)
• Impulsado por Tree-sitter - Análisis preciso e incremental para 32 idiomas
• Cero configuración - Apunta a los repositorios y listo
• Compatible con MCP - Funciona con Claude, Cursor, VS Code Copilot, Zed y cualquier cliente MCP
• Prioridad a la privacidad - Totalmente local, ningún dato sale de tu máquina
• Indexación paralela - Usa 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 flujo de datos integrados
• Embeddings neuronales - Búsqueda semántica opcional con Voyage AI u OpenAI
• Soporte WASM - Ejecuta en el navegador con la compilación WebAssembly
• Transmisión en tiempo real - Resultados mientras avanza la indexación para repositorios grandes

Idiomas compatibles

Idioma	Extensiones	Símbolos extraídos
Rust	.rs	funciones, structs, enums, traits, impls, mods
Python	.py, .pyi	funciones, clases
JavaScript	.js, .jsx, .mjs	funciones, clases, métodos, variables
TypeScript	.ts, .tsx	funciones, clases, interfaces, tipos, enums
Go	.go	funciones, métodos, tipos
C	.c, .h	funciones, structs, enums, typedefs
C++	.cpp, .cc, .hpp	funciones, clases, structs, namespaces
Java	.java	métodos, clases, interfaces, enums
C#	.cs	métodos, clases, interfaces, structs, enums, delegados, namespaces
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, structs, enums, protocolos, funciones
Verilog/SystemVerilog	.v, .vh, .sv, .svh	módulos, tareas, funciones, interfaces, clases
Scala	.scala, .sc	clases, objetos, traits, funciones, vals
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, structs
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, enums
Nix	.nix	bindings
Groovy	.groovy, .gradle	métodos, clases, interfaces, enums, funciones

Instalación

Mediante 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 con 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 comprobará las herramientas de compilación necesarias si se compila desde el código fuente.

Desde el código fuente

Requisitos previos:

• Rust estable actual (esta versión se verificó con Rust 1.98 y 1.99)
• En Windows: Visual Studio Build Tools con "Desarrollo de escritorio con 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

Compilaciones por características

narsil-mcp admite diferentes conjuntos de características para diferentes 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

# Experimental browser/WASM source build (not release-qualified)
cargo build --release --target wasm32-unknown-unknown --no-default-features --features wasm

Característica	Descripción	Tamaño
native (predeterminado)	Servidor MCP completo con todas las herramientas	~30MB
graph	+ Grafo de conocimiento RDF, SPARQL, herramientas CCG	~35MB
frontend	+ Interfaz web de visualización integrada	~31MB
neural	+ Búsqueda vectorial TF-IDF, embeddings de API	~32MB
neural-onnx	+ Inferencia de modelos ONNX local	~50MB
wasm	Compilación experimental de fuente para navegador (sin sistema de archivos, git)	No calificada para publicación

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

Para instrucciones de instalación detalladas, 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 características

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: Este indicador habilita consultas SPARQL y herramientas de Grafo de Contexto de Código (CCG), pero solo si el binario se compiló con --features graph. El binario predeterminado no incluye esta característica. 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 característica, verás una advertencia al inicio y el servidor continuará sin las herramientas SPARQL/CCG.

Nota: Los embeddings neuronales requieren una clave de API (o endpoint personalizado). La forma más fácil 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)
• Solicitará tu proveedor de API (Voyage AI, OpenAI o personalizado)
• Validará tu clave de 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 de API genérica para cualquier proveedor
• VOYAGE_API_KEY - Clave de API específica de Voyage AI
• OPENAI_API_KEY - Clave de API específica de OpenAI
• EMBEDDING_SERVER_ENDPOINT - URL del endpoint de API de embeddings personalizado (opcional, permite usar modelos autoalojados)

Configuración

v1.1.0+ introduce configuración opcional para control detallado de herramientas y 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 de editor

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

Editor	Preset	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 características
Claude Desktop	Completo	90	~12,001	Capacidades máximas

Ahorro de tokens:

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

Presets

Elige un preset 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: Indicadores de CLI > Variables de entorno > Configuración de proyecto > Configuración de usuario > Valores predeterminados

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 de 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

Aprende más:

• 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 de 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 grafos:

Vista	Descripción
Grafo de llamadas	Relaciones de llamadas de 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 de archivos
Híbrido	Grafo combinado de llamadas + importaciones con presupuesto dividido
Flujo de control	CFG real con bloques básicos, ramas y bordes de retroceso de bucles

Características:

• Grafos interactivos de Cytoscape.js con arrastre, zoom y exploración con doble clic
• Superposición de métricas de complejidad con codificación de colores (verde/amarillo/naranja/rojo)
• Superposición de vulnerabilidades de seguridad que resalta fuentes y sumideros de flujo de datos
• Seis algoritmos de diseño (dagre, dirigido por fuerza, breadthfirst, concéntrico, círculo, cuadrícula)
• Barra lateral de árbol de archivos con visor de código resaltado con sintaxis
• Estado impulsado por URL (enlaces compartibles, botones atrás/adelante del navegador)
• Soporte de modo oscuro
• Panel de detalles de nodo con extractos de código y navegación a la 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

Admite 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 ni tsc.

Herramienta	Descripción
infer_types	Obtén 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, una puerta de enlace MCP de Code Mode que reduce las 90 herramientas a 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 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 se comunica a través de objetos proxy tipados dentro de un isolate V8 en sandbox — las credenciales, rutas de archivos y el estado interno nunca salen del host. Este enfoque es particularmente útil cuando se trabaja con múltiples servidores MCP simultáneamente, ya que mantiene el contexto total de herramientas pequeño y predecible.

Configuración de MCP

Agrega narsil-mcp a tu asistente de IA creando un archivo de configuración. Aquí están las configuraciones recomendadas:

---

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

Crea .mcp.json en el directorio de tu proyecto para configuración por proyecto:

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

Luego inicia Claude Code en tu 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: Agrega --persist --index-path .claude/cache para un inicio más rápido en ejecuciones posteriores.

Para configuración global, edita ~/.claude/settings.json en su lugar. Consulta 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 de MCP requiere VS Code 1.102+ y debe ser habilitado por el administrador de tu 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 el uso efectivo de 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 exhaustivas
/narsil:explore	Explorar bases de código desconocidas
/narsil:analyze-function	Análisis profundo de funciones específicas
/narsil:find-feature	Encontrar dónde están implementadas las funcionalidades
/narsil:supply-chain	Analizar seguridad de la cadena de suministro
Habilidad	Guía a Claude en el uso efectivo de 90 herramientas
Config MCP	Inicia automáticamente narsil-mcp con valores predeterminados sensatos

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

Integración con Ralph Automation

Ralph es un conjunto de automatización para Claude Code destinado al 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	Basado 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 elegantemente cuando narsil-mcp no está disponible — todas las funciones principales de automatización funcionan sin él.

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

Playbooks y Tutoriales

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

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

Cada playbook muestra las cadenas de herramientas exactas que Claude usa para responder tus preguntas.

Uso en WebAssembly (Navegador)

El repositorio contiene código fuente experimental de WebAssembly y un script de compilación local. @narsil-mcp/wasm no está publicado en npm y no es un canal de distribución para el lanzamiento CLI 1.7.1. La compilación WASM y los ejemplos no están cubiertos por su calificación de lanzamiento. Consulta docs/wasm.md para el flujo de trabajo experimental de código fuente.

Herramientas Disponibles (93)

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 y tamaños de archivos
get_file	Obtener contenido de archivos con rango de líneas opcional
get_excerpt	Extraer código alrededor de líneas específicas con contexto
reindex	Activar re-indexación de repositorios
discover_repos	Auto-descubrir repositorios en un directorio
validate_repo	Verificar si una ruta es un repositorio válido
get_index_status	Mostrar estadísticas de índice y funciones habilitadas

Búsqueda y Navegación de Símbolos

Herramienta	Descripción
find_symbols	Encontrar structs, clases, funciones por tipo/patrón
get_symbol_definition	Obtener código 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 todo 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 palabras clave con ranking de relevancia
semantic_search	Búsqueda semántica clasificada por BM25
hybrid_search	Combinación BM25 + TF-IDF con fusión de rankings
search_chunks	Búsqueda sobre fragmentos de código conscientes de 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 de AST

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

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

Herramienta	Descripción
neural_search	Búsqueda semántica usando incrustaciones 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 incrustaciones 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 llegan a 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 tipos sin ejecutar mypy/tsc
get_typed_taint_flow	Análisis de flujo de datos mejorado combinando flujo de datos con inferencia de tipos

Grafo de Importación/Dependencias

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

Análisis de Seguridad - Seguimiento de Flujo de Datos

Herramienta	Descripción
find_injection_vulnerabilities	Encontrar inyección SQL, XSS, inyección de comandos, traversal de rutas
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, criptografía, 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 vulnerabilidades
suggest_fix	Obtener sugerencias de remediación para hallazgos

Seguridad de 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	Contribuyentes 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 tipos y documentación
get_type_info	Información precisa de tipos
go_to_definition	Encontrar ubicación de definición

Soporte de 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 jerárquicas.

Herramienta	Descripción
get_ccg_manifest	Manifiesto Capa 0 (~1-2KB JSON-LD) - identidad del repositorio, conteos
export_ccg_manifest	Exportar manifiesto Capa 0 a archivo
export_ccg_architecture	Arquitectura Capa 1 (~10-50KB JSON-LD) - módulos, API
export_ccg_index	Índice de símbolos Capa 2 (~100-500KB N-Quads comprimidos)
export_ccg_full	Detalle completo Capa 3 (~1-20MB N-Quads comprimidos)
export_ccg	Exportar todas las capas CCG como 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 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 - CWE Top 25 Debilidades Más Peligrosas
• crypto.yaml - Problemas criptográficos (algoritmos débiles, claves codificadas)
• 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, ajustes inseguros)

Las reglas personalizadas se pueden cargar 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

Evaluado en Apple M1 (criterion.rs):

Rendimiento de análisis sintáctico

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 documentos	80 µs
Similitud TF-IDF	1,000 documentos	130 µs
Híbrido (BM25+TF-IDF)	1,000 documentos	151 µs

Indexación de extremo a extremo

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

Métricas clave:

• Análisis sintáctico con tree-sitter: ~2 GiB/s de rendimiento sostenido
• Búsqueda de símbolos: <1µs para coincidencia exacta
• Búsqueda de texto completo: <1ms para la mayoría de las 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 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 función de grafo 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 (~5MB de tamaño adicional del binario) que no es necesaria para la mayoría de los casos de uso. Se mantiene opcional para mantener el binario predeterminado más pequeño.

Cómo verificar si el grafo está habilitado: Observa 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 que --graph no fue pasado

Hoja de ruta

Completado

• Extracción de símbolos multilingüe (32 lenguajes)
• Búsqueda de texto completo con Tantivy (clasificación 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, criptografía, secretos)
• Generación de SBOM (CycloneDX, SPDX)
• Verificación de vulnerabilidades de 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 Merkle
• Persistencia del índice
• Modo de vigilancia para cambios de archivos
• Integración LSP
• Soporte de 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 ordenamiento seguras con NaN - Se corrigieron 5 ubicaciones en los módulos de búsqueda, embeddings, git, índice y extracción donde partial_cmp().unwrap() entraba en pánico con valores flotantes NaN. Todos los ordenamientos ahora usan unwrap_or(Ordering::Equal).
• Fragmentación de defensa en profundidad - Se añadieron envoltorios catch_unwind alrededor de todos los bucles chunk_file() en todo el repositorio para que un pánico en un archivo lo omita en lugar de bloquear todo el servidor MCP.
• Reforma del frontend de visualización - SPA completo con enrutamiento HashRouter, barra lateral de árbol de archivos, visor de código con resaltado de sintaxis, panel de control y páginas de descripción general por repositorio
• Rendimiento de la vista de grafo - El grafo de importaciones ahora usa datos de índice en caché en lugar de recorridos del sistema de archivos; el grafo de símbolos itera la caché de archivos directamente en lugar de idas y vueltas de markdown; todas las vistas respetan max_nodes para terminación anticipada
• Grafos de flujo de control reales - La vista de flujo ahora usa el constructor CFG real (cfg::analyze_function) con bloques básicos adecuados, condiciones de rama y bordes de retroceso de bucles en lugar del stub de bloque único
• División de presupuesto de grafo híbrido - La vista híbrida asigna un presupuesto de nodos 60/40 entre grafos de llamadas e importaciones para resultados equilibrados
• Corrección #14: dimensiones de embeddings 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 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 de Rust - 18 reglas nuevas (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 de Elixir - 18 reglas nuevas (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
• Migrado de serde_yaml a serde-saphyr - serde_yaml obsoleto reemplazado por una biblioteca YAML mantenida activamente y a prueba de pánicos
• Favicon personalizado - El frontend ahora usa el icono de marca narsil-mcp en lugar del logotipo predeterminado de Vite
• Seguridad de dependencias - Se actualizó time a 0.3.47 (RUSTSEC-2026-0009), bytes a 1.11.1 (RUSTSEC-2026-0007)
• Número 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 pistas de alcance desambigua la resolución del destinatario (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, marcos de macOS innecesarios eliminados, 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 mediante Oxigraph
• Grafo de contexto de código (CCG) - 12 herramientas para representaciones estandarizadas de bases de código 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 multilingüe - 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 lenguajes nuevos - Erlang, Elm, Fortran, PowerShell, Nix, Groovy
• 90 herramientas en total - Frente a 79 con nuevas capacidades SPARQL, CCG y de análisis

v1.2.x

• Parámetro exclude_tests - 22 herramientas admiten filtrar archivos de prueba
• Paquete npm - Instalar mediante npm install -g narsil-mcp

v1.1.x

• Distribución multiplataforma - Instalar mediante Homebrew, Scoop, npm, Cargo o descarga directa
• Ajustes de herramientas configurables - Ajustes mínimos, equilibrados, completos y centrados 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 fácil
• Soporte de 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 o OpenAI
• Inferencia de tipos - Infiere tipos en Python/JavaScript/TypeScript sin herramientas externas
• Análisis de contaminación multilingüe - Escaneo de seguridad para PHP, Java, C#, Ruby, Kotlin
• Compilación WASM - Ejecutar en el navegador para entornos de práctica de código y herramientas educativas
• 147 reglas de seguridad incluidas - Detección de OWASP, CWE, criptografía, secretos, Rust, Elixir
• Configuraciones de IDE incluidas - Plantillas de Claude Desktop, Cursor, VS Code, Zed

Licencia

Licenciado bajo cualquiera de:

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

a tu elección.

Créditos

Construido con:

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