Narsil MCP

narsil-mcp

O servidor MCP ultrarrápido e focado em privacidade para inteligência profunda de código

Um servidor MCP (Model Context Protocol) desenvolvido em Rust que fornece a assistentes de IA compreensão profunda de código por meio de 90 ferramentas especializadas.

Por que narsil-mcp?

Funcionalidade	narsil-mcp	XRAY	Serena	GitHub MCP
Linguagens	32	4	30+ (LSP)	N/A
Busca Neural	Sim	Não	Não	Não
Análise de Taint	Sim	Não	Não	Não
SBOM/Licenças	Sim	Não	Não	Parcial
Offline/Local	Sim	Sim	Sim	Não
WASM/Navegador	Sim	Não	Não	Não
Grafos de Chamada	Sim	Parcial	Não	Não
Inferência de Tipos	Sim	Não	Não	Não

Principais Funcionalidades

• Inteligência de Código - Extração de símbolos, busca semântica, análise de grafo de chamadas
• Busca Semântica Neural - Encontre código similar usando embeddings (Voyage AI, OpenAI)
• Análise de Segurança - Análise de taint, varredura de vulnerabilidades, cobertura OWASP/CWE
• Segurança da Cadeia de Suprimentos - Geração de SBOM, auditoria de dependências, conformidade de licenças
• Análise Avançada - Grafos de fluxo de controle, análise de fluxo de dados, detecção de código morto

Por que Escolher narsil-mcp?

• Escrito em Rust - Extremamente rápido, seguro em memória, binário único (~30MB)
• Baseado em Tree-sitter - Análise precisa e incremental para 32 linguagens
• Configuração zero - Aponte para repositórios e pronto
• Compatível com MCP - Funciona com Claude, Cursor, VS Code Copilot, Zed e qualquer cliente MCP
• Privacidade em primeiro lugar - Totalmente local, nenhum dado sai da sua máquina
• Indexação paralela - Usa todos os núcleos via Rayon
• Trechos inteligentes - Expande para escopos sintáticos completos
• Segurança em primeiro lugar - Detecção de vulnerabilidades e análise de taint integradas
• Embeddings neurais - Busca semântica opcional com Voyage AI ou OpenAI
• Suporte a WASM - Execute no navegador com build WebAssembly
• Streaming em tempo real - Resultados conforme a indexação progride para repositórios grandes

Linguagens Suportadas

Linguagem	Extensões	Símbolos Extraídos
Rust	.rs	funções, structs, enums, traits, impls, mods
Python	.py, .pyi	funções, classes
JavaScript	.js, .jsx, .mjs	funções, classes, métodos, variáveis
TypeScript	.ts, .tsx	funções, classes, interfaces, tipos, enums
Go	.go	funções, métodos, tipos
C	.c, .h	funções, structs, enums, typedefs
C++	.cpp, .cc, .hpp	funções, classes, structs, namespaces
Java	.java	métodos, classes, interfaces, enums
C#	.cs	métodos, classes, interfaces, structs, enums, delegates, namespaces
Bash	.sh, .bash, .zsh	funções, variáveis
Ruby	.rb, .rake, .gemspec	métodos, classes, módulos
Kotlin	.kt, .kts	funções, classes, objetos, interfaces
PHP	.php, .phtml	funções, métodos, classes, interfaces, traits
Swift	.swift	classes, structs, enums, protocolos, funções
Verilog/SystemVerilog	.v, .vh, .sv, .svh	módulos, tarefas, funções, interfaces, classes
Scala	.scala, .sc	classes, objetos, traits, funções, vals
Lua	.lua	funções, métodos
Haskell	.hs, .lhs	funções, tipos de dados, classes de tipo
Elixir	.ex, .exs	módulos, funções
Clojure	.clj, .cljs, .cljc, .edn	listas (AST básico)
Dart	.dart	funções, classes, métodos
Julia	.jl	funções, módulos, structs
R	.R, .r, .Rmd	funções
Perl	.pl, .pm, .t	funções, pacotes
Zig	.zig	funções, variáveis
Erlang	.erl, .hrl	funções, módulos, registros
Elm	.elm	funções, tipos
Fortran	.f90, .f95, .f03, .f08, .f, .for, .fpp	programas, sub-rotinas, funções, módulos
PowerShell	.ps1, .psm1, .psd1	funções, classes, enums
Nix	.nix	vinculações
Groovy	.groovy, .gradle	métodos, classes, interfaces, enums, funções

Instalação

Via Gerenciadores de Pacotes (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 as plataformas):

cargo install narsil-mcp

Node.js/npm (todas as 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 Instalação com Um Clique

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 usuários do Windows: O instalador PowerShell fornece mensagens de erro melhores e integração nativa com o Windows. Ele configurará automaticamente seu PATH e verificará as ferramentas de build necessárias se estiver compilando a partir do código fonte.

A Partir do Código Fonte

Pré-requisitos:

• Rust 1.70 ou posterior
• No Windows: Visual Studio Build Tools com "Desenvolvimento para desktop com 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

Builds com Funcionalidades Específicas

narsil-mcp suporta diferentes conjuntos de funcionalidades 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

# For browser/WASM usage
cargo build --release --target wasm32-unknown-unknown --features wasm

Funcionalidade	Descrição	Tamanho
native (padrão)	Servidor MCP completo com todas as ferramentas	~30MB
graph	+ Grafo de conhecimento RDF, SPARQL, ferramentas CCG	~35MB
frontend	+ Interface web de visualização embutida	~31MB
neural	+ Busca vetorial TF-IDF, embeddings de API	~32MB
neural-onnx	+ Inferência de modelo ONNX local	~50MB
wasm	Build para navegador (sem sistema de arquivos, git)	~3MB

Importante: A flag CLI --graph requer que o binário seja compilado com --features graph. Se você passar --graph para um binário compilado sem essa funcionalidade, verá um aviso e as ferramentas SPARQL/CCG não estarão disponíveis. Veja Solução de Problemas abaixo.

Para instruções detalhadas de instalação, solução de problemas e guias específicos de plataforma, veja 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 flag habilita consultas SPARQL e ferramentas de Grafo de Contexto de Código (CCG), mas apenas se o binário foi compilado com --features graph. O binário padrão não inclui essa funcionalidade. Se você precisa de capacidades SPARQL/CCG, compile a partir do código fonte com:

cargo build --release --features graph

Se você passar --graph para um binário sem a funcionalidade, verá um aviso na inicialização e o servidor continuará sem as ferramentas SPARQL/CCG.

Nota: Embeddings neurais requerem uma chave de API (ou endpoint personalizado). A maneira mais fácil de configurar isso é com o assistente interativo:

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

O assistente irá:

• Detectar seu editor (Claude Desktop, Claude Code, Zed, VS Code, JetBrains)
• Solicitar seu provedor de API (Voyage AI, OpenAI ou personalizado)
• Validar sua chave de API
• Adicioná-la automaticamente à configuração MCP do seu editor

Alternativamente, você pode definir manualmente uma destas variáveis de ambiente:

• EMBEDDING_API_KEY - Chave de API genérica para qualquer provedor
• VOYAGE_API_KEY - Chave de API específica do Voyage AI
• OPENAI_API_KEY - Chave de API específica da OpenAI
• EMBEDDING_SERVER_ENDPOINT - URL de endpoint de API de embedding personalizado (opcional, permite usar modelos auto-hospedados)

Configuração

v1.1.0+ introduz configuração opcional para controle refinado sobre ferramentas e desempenho. Todo o uso existente continua funcionando - a configuração é completamente opcional!

Início 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

Detecção Automática de Editor

narsil-mcp detecta seu editor e aplica uma predefinição ideal automaticamente:

Editor	Predefinição	Ferramentas	Tokens de Contexto	Por quê
Zed	Mínima	26	~4.686	Inicialização rápida, contexto mínimo
VS Code	Balanceada	51	~8.948	Bom equilíbrio de funcionalidades
Claude Desktop	Completa	90	~12.001	Capacidades máximas

Economia de Tokens:

• Predefinição mínima: 61% menos tokens vs Completa
• Predefinição balanceada: 25% menos tokens vs Completa

Predefinições

Escolha uma predefinição com base no seu 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

Arquivos de Configuração

Configuração do usuário (~/.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

Configuração do projeto (.narsil.yaml na raiz do repositório):

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

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

Perfis de repositório nomeados são úteis para espaços de trabalho com múltiplos repositórios:

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

Prioridade: Flags CLI > Variáveis de ambiente > Configuração do projeto > Configuração do usuário > Padrões

Variáveis de Ambiente

# 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

Saiba Mais:

• Guia de Configuração - Referência completa de configuração
• Guia de Instalação - Instalação específica por plataforma

Frontend de Visualização

Explore grafos de chamada, importações, referências de símbolos e fluxo de controle interativamente no seu 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 visualizações de grafo:

Visualização	Descrição
Grafo de Chamada	Relacionamentos de chamada de função com controle de profundidade e filtragem de direção
Grafo de Importação	Dependências de importação em nível de arquivo em toda a base de código
Grafo de Símbolos	Todas as referências a um símbolo, com agrupamento por arquivo
Híbrido	Grafo combinado de chamada + importação com orçamento dividido
Fluxo de Controle	CFG real com blocos básicos, ramificações e arestas de retorno de loop

Funcionalidades:

• Grafos interativos Cytoscape.js com arrastar, zoom e drill-down com duplo clique
• Sobreposição de métricas de complexidade com codificação de cores (verde/amarelo/laranja/vermelho)
• Sobreposição de vulnerabilidade de segurança destacando fontes e sumidouros de taint
• Seis algoritmos de layout (dagre, força-direcionada, largura-primeiro, concêntrico, círculo, grade)
• Barra lateral de árvore de arquivos com visualizador de código com destaque de sintaxe
• Estado orientado por URL (links compartilháveis, voltar/avançar do navegador)
• Suporte a modo escuro
• Painel de detalhes do nó com trechos de código e navegação para o código fonte

Documentação completa: Veja docs/frontend.md para configuração, endpoints de API e modo de desenvolvimento.

Busca Semântica Neural

Encontre código similar usando embeddings neurais - mesmo quando nomes de variáveis e estrutura diferem.

# 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

Suporta Voyage AI, OpenAI, endpoints personalizados e modelos ONNX locais.

Documentação completa: Veja docs/neural-search.md para configuração, backends e casos de uso.

Inferência de Tipos

Inferência de tipos integrada para Python, JavaScript e TypeScript - sem necessidade de mypy ou tsc.

Ferramenta	Descrição
infer_types	Obter tipos inferidos para todas as variáveis em uma função
check_type_errors	Encontrar possíveis incompatibilidades de tipo
get_typed_taint_flow	Análise de segurança aprimorada com informações de tipo

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

Integração Forgemax (Experimental)

Para fluxos de trabalho agênticos em larga escala, narsil-mcp pode ser usado através do Forgemax — um gateway MCP Modo Código que colapsa todas as 90 ferramentas em apenas 2 (search + execute), reduzindo a sobrecarga do esquema de ferramentas de ~12.000 tokens para ~1.000.

# Install Forgemax
cargo install forgemax

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

O forge.toml incluído configura narsil-mcp com padrões 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

O LLM escreve JavaScript que chama através de objetos proxy tipados dentro de um isolado V8 em sandbox — credenciais, caminhos de arquivo e estado interno nunca saem do host. Esta abordagem é particularmente útil ao trabalhar com vários servidores MCP simultaneamente, pois mantém o contexto total de ferramentas pequeno e previsível.

Configuração MCP

Adicione narsil-mcp ao seu assistente de IA criando um arquivo de configuração. Aqui estão as configurações recomendadas:

---

Claude Code (.mcp.json na raiz do projeto - Recomendado):

Crie .mcp.json no diretório do seu projeto para configuração por projeto:

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

Então inicie o Claude Code no seu projeto:

cd /path/to/project
claude

Usar . para --repos indexa automaticamente o diretório atual. Claude agora tem acesso a 90 ferramentas de inteligência de código.

Dica: Adicione --persist --index-path .claude/cache para inicialização mais rápida em execuções subsequentes.

Para configuração global, edite ~/.claude/settings.json em vez disso. Veja Integração Claude Code para configurações avançadas.

---

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: O suporte MCP requer VS Code 1.102+ e deve ser habilitado pelo administrador da sua organização.

---

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 inicia imediatamente e indexa em segundo plano, prevenindo timeouts de inicialização.

---

Plugin Claude Code

Para usuários do Claude Code, fornecemos um plugin com comandos de barra e uma habilidade para uso eficaz das ferramentas.

Instalar via Marketplace (Recomendado):

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

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

Ou instalar diretamente do GitHub:

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

O que está incluído:

Componente	Descrição
/narsil:security-scan	Executar auditorias de segurança abrangentes
/narsil:explore	Explorar bases de código desconhecidas
/narsil:analyze-function	Mergulho profundo em funções específicas
/narsil:find-feature	Encontrar onde funcionalidades são implementadas
/narsil:supply-chain	Analisar segurança da cadeia de suprimentos
Habilidade	Guia Claude sobre como usar 90 ferramentas eficazmente
Configuração MCP	Inicia automaticamente narsil-mcp com padrões sensatos

Veja narsil-plugin/README.md para documentação completa.

Integração Ralph Automation

Ralph é um conjunto de automação Claude Code para desenvolvimento autônomo de código. Quando narsil-mcp está disponível, Ralph ganha capacidades aprimoradas de inteligência de código:

Funcionalidade	Sem narsil-mcp	Com narsil-mcp
Varredura de segurança	Básica (clippy)	Detecção de vulnerabilidades OWASP/CWE
Compreensão de código	Baseada em arquivo	Grafos de chamada, referências de símbolos
Análise de arquitetura	Manual	Camadas automáticas CCG L0/L1/L2
Análise de dependências	cargo tree	Grafos de importação, detecção circular

Configuração:

# 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 graciosamente quando narsil-mcp está indisponível - todas as funcionalidades principais de automação funcionam sem ele.

Documentação: Veja Ralph README para detalhes completos de integração.

Playbooks e Tutoriais

Veja docs/playbooks para guias práticos de uso:

Guia	Descrição
Primeiros Passos	Configuração rápida e primeiras chamadas de ferramenta
Entender uma Base de Código	Explorar projetos desconhecidos
Corrigir um Bug	Depurar com grafos de chamada e análise de taint
Auditoria de Segurança	Encontrar vulnerabilidades com varredura OWASP/CWE
Revisão de Código	Revisar mudanças eficazmente

Cada playbook mostra as cadeias exatas de ferramentas que Claude usa para responder suas perguntas.

Uso WebAssembly (Navegador)

narsil-mcp pode ser executado inteiramente no navegador via WebAssembly - perfeito para IDEs baseadas em navegador, ferramentas de revisão de código ou plataformas educacionais.

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

Documentação completa: Veja docs/wasm.md para instruções de build, exemplos React e referência de API.

Ferramentas Disponíveis (90)

Gerenciamento de Repositório e Arquivos

Ferramenta	Descrição
list_repos	Listar todos os repositórios indexados com metadados
get_project_structure	Obter árvore de diretórios com ícones de arquivo e tamanhos
get_file	Obter conteúdo de arquivo com intervalo de linhas opcional
get_excerpt	Extrair código ao redor de linhas específicas com contexto
reindex	Acionar re-indexação de repositórios
discover_repos	Auto-descobrir repositórios em um diretório
validate_repo	Verificar se o caminho é um repositório válido
get_index_status	Mostrar estatísticas do índice e funcionalidades habilitadas

Busca e Navegação de Símbolos

Ferramenta	Descrição
find_symbols	Encontrar structs, classes, funções por tipo/padrão
get_symbol_definition	Obter código fonte do símbolo com contexto ao redor
find_references	Encontrar todas as referências a um símbolo
get_dependencies	Analisar importações e dependentes
workspace_symbol_search	Busca difusa de símbolos em todo o espaço de trabalho
find_symbol_usages	Uso de símbolo entre arquivos com importações
get_export_map	Obter símbolos exportados de um arquivo/módulo

Busca de Código

Ferramenta	Descrição
search_code	Busca por palavra-chave com classificação por relevância
semantic_search	Busca semântica classificada por BM25
hybrid_search	BM25 + TF-IDF combinados com fusão de classificação
search_chunks	Busca sobre pedaços de código cientes de AST
find_similar_code	Encontrar código similar a um trecho (TF-IDF)
find_similar_to_symbol	Encontrar código similar a um símbolo

Fragmentação Ciente de AST

Ferramenta	Descrição
get_chunks	Obter pedaços cientes de AST para um arquivo
get_chunk_stats	Estatísticas sobre pedaços de código
get_embedding_stats	Estatísticas do índice de embedding

Busca Semântica Neural (requer --neural)

Ferramenta	Descrição
neural_search	Busca semântica usando embeddings neurais (encontra código similar mesmo com nomes diferentes)
find_semantic_clones	Encontrar clones semânticos Tipo-3/4 de uma função
get_neural_stats	Estatísticas do índice de embedding neural

Análise de Grafo de Chamada (requer --call-graph)

Ferramenta	Descrição
get_call_graph	Obter grafo de chamada para repositório/função
get_callers	Encontrar funções que chamam uma função
get_callees	Encontrar funções chamadas por uma função
find_call_path	Encontrar caminho entre duas funções
get_complexity	Obter complexidade ciclomática/cognitiva
get_function_hotspots	Encontrar funções altamente conectadas

Análise de Fluxo de Controle

Ferramenta	Descrição
get_control_flow	Obter CFG mostrando blocos básicos e ramificações
find_dead_code	Encontrar blocos de código inalcançáveis

Análise de Fluxo de Dados

Ferramenta	Descrição
get_data_flow	Definições e usos de variáveis
get_reaching_definitions	Quais atribuições alcançam cada ponto
find_uninitialized	Variáveis usadas antes da inicialização
find_dead_stores	Atribuições que nunca são lidas

Inferência de Tipos (Python/JavaScript/TypeScript)

Ferramenta	Descrição
infer_types	Inferir tipos para variáveis em uma função sem verificadores de tipo externos
check_type_errors	Encontrar possíveis erros de tipo sem executar mypy/tsc
get_typed_taint_flow	Análise de taint aprimorada combinando fluxo de dados com inferência de tipos

Grafo de Importação/Dependência

Ferramenta	Descrição
get_import_graph	Construir e analisar grafo de importação
find_circular_imports	Detectar dependências circulares
get_incremental_status	Árvore de Merkle e estatísticas de mudança

Análise de Segurança - Rastreamento de Taint

Ferramenta	Descrição
find_injection_vulnerabilities	Encontrar injeção SQL, XSS, injeção de comando, path traversal
trace_taint	Rastrear fluxo de dados contaminados a partir de uma fonte
get_taint_sources	Listar fontes de taint (entrada do usuário, arquivos, rede)
get_security_summary	Avaliação abrangente de risco de segurança

Análise de Segurança - Motor de Regras

Ferramenta	Descrição
scan_security	Escanear com regras de segurança (OWASP, CWE, criptografia, segredos)
check_owasp_top10	Escanear vulnerabilidades OWASP Top 10 2021
check_cwe_top25	Escanear fraquezas CWE Top 25
explain_vulnerability	Obter explicação detalhada da vulnerabilidade
suggest_fix	Obter sugestões de remediação para achados

Segurança da Cadeia de Suprimentos

Ferramenta	Descrição
generate_sbom	Gerar SBOM (CycloneDX/SPDX/JSON)
check_dependencies	Verificar vulnerabilidades conhecidas (base de dados OSV)
check_licenses	Analisar licenças para problemas de conformidade
find_upgrade_path	Encontrar caminhos seguros de atualização para dependências vulneráveis

Integração Git (requer --git)

Ferramenta	Descrição
get_blame	Git blame para arquivo
get_file_history	Histórico de commits para arquivo
get_recent_changes	Commits recentes no repositório
get_hotspots	Arquivos com alta rotatividade e complexidade
get_contributors	Contribuidores do repositório/arquivo
get_commit_diff	Diff para commit específico
get_symbol_history	Commits que mudaram um símbolo
get_branch_info	Branch atual e status
get_modified_files	Mudanças na árvore de trabalho

Integração LSP (requer --lsp)

Ferramenta	Descrição
get_hover_info	Informação de tipo e documentação
get_type_info	Informação precisa de tipo
go_to_definition	Encontrar localização da definição

Suporte a Repositório Remoto (requer --remote)

Ferramenta	Descrição
add_remote_repo	Clonar e indexar repositório GitHub
list_remote_files	Listar arquivos via API GitHub
get_remote_file	Buscar arquivo via API GitHub

Métricas

Ferramenta	Descrição
get_metrics	Estatísticas de desempenho e temporização

SPARQL / Grafo de Conhecimento (requer --graph)

Ferramenta	Descrição
sparql_query	Executar consulta SPARQL no grafo de conhecimento RDF
list_sparql_templates	Listar modelos de consulta SPARQL disponíveis
run_sparql_template	Executar modelo SPARQL predefinido com parâmetros

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

CCG fornece representações padronizadas e consumíveis por IA de bases de código em camadas hierárquicas.

Ferramenta	Descrição
get_ccg_manifest	Manifesto da Camada 0 (~1-2KB JSON-LD) - identidade do repositório, contagens
export_ccg_manifest	Exportar manifesto da Camada 0 para arquivo
export_ccg_architecture	Arquitetura da Camada 1 (~10-50KB JSON-LD) - módulos, API
export_ccg_index	Índice de símbolos da Camada 2 (~100-500KB N-Quads gzipado)
export_ccg_full	Detalhe completo da Camada 3 (~1-20MB N-Quads gzipado)
export_ccg	Exportar todas as camadas CCG como um pacote
query_ccg	Consultar CCG usando SPARQL
get_ccg_acl	Gerar controle de acesso WebACL para camadas CCG
get_ccg_access_info	Obter informações de nível de acesso CCG
import_ccg	Importar camada CCG de URL ou arquivo
import_ccg_from_registry	Importar CCG do registro codecontextgraph.com

Regras de Segurança

narsil-mcp inclui regras de segurança integradas em rules/:

Conjuntos de Regras Principais:

• owasp-top10.yaml - Padrões de vulnerabilidade OWASP Top 10 2021
• cwe-top25.yaml - Fraquezas Mais Perigosas CWE Top 25
• crypto.yaml - Problemas criptográficos (algoritmos fracos, chaves hardcoded)
• secrets.yaml - Detecção de segredos (chaves de API, senhas, tokens)

Regras Específicas por Linguagem:

• rust.yaml - Padrões de segurança Rust (transmute inseguro, fronteiras FFI, injeção de comando, TOCTOU)
• elixir.yaml - Padrões Elixir/BEAM (exaustão de átomos, binary_to_term, Code.eval, injeção SQL Ecto)
• go.yaml - Padrões de segurança Go (injeção SQL, TLS, injeção de comando)
• java.yaml - Vulnerabilidades Java (XXE, desserialização, injeção LDAP)
• csharp.yaml - Problemas de segurança C# (desserialização, XSS, path traversal)
• kotlin.yaml - Padrões Kotlin/Android (WebView, intents, segredos)
• bash.yaml - Vulnerabilidades de script shell (injeção de comando, eval)

Infraestrutura e Configuração:

• iac.yaml - Infraestrutura como Código (Terraform, CloudFormation, Kubernetes)
• config.yaml - Segurança de arquivo de configuração (credenciais hardcoded, configurações inseguras)

Regras personalizadas podem ser carregadas com scan_security --ruleset /path/to/rules.yaml.

Arquitetura

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

Desempenho

Avaliado em Apple M1 (criterion.rs):

Taxa de Análise (Parsing)

Linguagem	Tamanho da Entrada	Tempo	Taxa
Rust (arquivo grande)	278 KB	131 µs	1,98 GiB/s
Rust (arquivo médio)	27 KB	13,5 µs	1,89 GiB/s
Python	~4 KB	16,7 µs	-
TypeScript	~5 KB	13,9 µs	-
Misto (5 arquivos)	~15 KB	57 µs	-

Latência de Busca

Operação	Tamanho do Corpus	Tempo
Correspondência exata de símbolo	1.000 símbolos	483 ns
Correspondência de prefixo de símbolo	1.000 símbolos	2,7 µs
Correspondência difusa de símbolo	1.000 símbolos	16,5 µs
Texto completo BM25	1.000 docs	80 µs
Similaridade TF-IDF	1.000 docs	130 µs
Híbrido (BM25+TF-IDF)	1.000 docs	151 µs

Indexação de Ponta a Ponta

Repositório	Arquivos	Símbolos	Tempo	Memória
narsil-mcp (este repositório)	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 principais:

• Análise Tree-sitter: taxa sustentada de ~2 GiB/s
• Busca de símbolo: <1µs para correspondência exata
• Busca de texto completo: <1ms para a maioria das consultas
• Busca híbrida executa BM25 + TF-IDF em paralelo via rayon

Desenvolvimento

# 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

Solução de Problemas

Erros de Build do Tree-sitter

Se você vir erros sobre compiladores C ausentes ou tree-sitter durante o build:

# macOS
xcode-select --install

# Ubuntu/Debian
sudo apt install build-essential

# For WASM builds
brew install emscripten  # macOS

Erros de API de Busca Neural

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

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

Índice Não Encontra Arquivos

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

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

Problemas de Memória com Repositórios 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

Funcionalidade de Grafo Não Funciona

Se você passar --graph e vir um aviso como:

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

Isso significa que você está usando um binário que não foi compilado com a funcionalidade graph. Para corrigir:

# 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 que isso é uma funcionalidade separada? A funcionalidade graph adiciona o banco de dados RDF Oxigraph (~5MB adicionais no tamanho do binário) que não é necessário para a maioria dos casos de uso. É mantida opcional para manter o binário padrão menor.

Como verificar se o grafo está habilitado: Veja os logs de inicialização:

• graph=true significa que a funcionalidade está compilada E habilitada
• graph=false significa que a funcionalidade não está compilada, OU --graph não foi passado

Roadmap

Concluído

• Extração de símbolos multi-linguagem (32 linguagens)
• Busca de texto completo com Tantivy (classificação BM25)
• Busca híbrida (BM25 + TF-IDF com RRF)
• Fragmentação de código ciente de AST
• Integração Git blame/histórico
• Análise de grafo de chamada com métricas de complexidade
• Análise de grafo de fluxo de controle (CFG)
• Análise de fluxo de dados (DFG) com definições alcançantes
• Detecção de código morto e armazenamento morto
• Análise de taint para vulnerabilidades de injeção
• Motor de regras de segurança (OWASP, CWE, criptografia, segredos)
• Geração de SBOM (CycloneDX, SPDX)
• Verificação de vulnerabilidade de dependências (OSV)
• Análise de conformidade de licenças
• Grafo de importação com detecção de dependência circular
• Resolução de símbolos entre linguagens
• Indexação incremental com árvores de Merkle
• Persistência de índice
• Modo de observação para mudanças de arquivo
• Integração LSP
• Suporte a repositório remoto
• Respostas em streaming

Novidades

v1.6.x (Atual)

• Fragmentação à prova de falhas - Corrigido fatiamento inseguro de strings em nível de byte em chunk_file() e extract_signature() que causava falhas em hybrid_search, search_chunks e get_chunk_stats ao processar arquivos com caracteres UTF-8 multi-byte (emoji, CJK, caracteres acentuados). Todo fatiamento de byte agora usa content.get() seguro com fallback.
• Operações de ordenação seguras contra NaN - Corrigidos 5 locais nos módulos de busca, embeddings, git, índice e extração onde partial_cmp().unwrap() entraria em pânico com valores float NaN. Todas as ordenações agora usam unwrap_or(Ordering::Equal).
• Fragmentação com defesa em profundidade - Adicionados wrappers catch_unwind em torno de todos os loops chunk_file() em todo o repositório para que um pânico em um arquivo o pule em vez de derrubar todo o servidor MCP.
• Revisão do frontend de visualização - SPA completo com roteamento HashRouter, barra lateral de árvore de arquivos, visualizador de código com destaque de sintaxe, painel e páginas de visão geral por repositório
• Desempenho da visualização de grafo - Grafo de importação agora usa dados de índice em cache em vez de caminhadas no sistema de arquivos; grafo de símbolos itera cache de arquivo diretamente em vez de round-trips markdown; todas as visualizações respeitam max_nodes para término antecipado
• Grafos de fluxo de controle reais - Visualização de fluxo agora usa o construtor CFG real (cfg::analyze_function) com blocos básicos adequados, condições de ramificação e arestas de retorno de loop em vez do stub de bloco único
• Divisão de orçamento de grafo híbrido - Visualização híbrida aloca orçamento de nós 60/40 entre grafos de chamada e importação para resultados balanceados
• Correção #14: dimensões de embedding configuráveis - Adicionado argumento CLI --neural-dimension e busca default_dimension_for_model() para que modelos como text-embedding-3-large usem dimensões corretas (3072) em vez de 1536 hardcoded
• Correção #13: build do frontend Nix - Adicionada derivação frontendDist em flake.nix usando buildNpmPackage para que nix profile install github:postrv/narsil-mcp#with-frontend funcione
• Regras de segurança Rust - 18 novas regras (RUST-004 a RUST-021) cobrindo injeção de comando, transmute, fronteiras FFI, TOCTOU, ReDoS, static mut, SSRF e mais
• Regras de segurança Elixir - 18 novas regras (EX-001 a EX-018) cobrindo exaustão de átomos, desserialização binary_to_term, injeção Code.eval, injeção SQL Ecto, XSS Phoenix, segurança de distribuição Erlang
• Migrado de serde_yaml para serde-saphyr - serde_yaml obsoleto substituído por biblioteca YAML mantida ativamente e livre de pânico
• Favicon personalizado - Frontend agora usa ícone de marca narsil-mcp em vez do logo Vite padrão
• Segurança de dependências - Atualizado time para 0.3.47 (RUSTSEC-2026-0009), bytes para 1.11.1 (RUSTSEC-2026-0007)
• Contagem de testes aumentou de 1.611 para 1.763 (+152 testes)

v1.5.x

• Resolução determinística de grafo de chamada - Propagação de dica de escopo desambigua a resolução do chamado (ex., App::run() resolve corretamente para src/app/mod.rs::run)
• 8 correções de análise de grafo - Chaves de nó qualificadas, filtragem de hotspot, manipulação de expressão CFG, análise de caminho de importação
• Melhorias no flake Nix - Auxiliar DRY mkPkg, removidos frameworks macOS desnecessários, estratégia de teste --lib para builds em sandbox

v1.4.x

• SPARQL / Grafo de Conhecimento RDF - Consultar dados de inteligência de código com SPARQL via Oxigraph
• Grafo de Contexto de Código (CCG) - 12 ferramentas para representações de base de código padronizadas e consumíveis por IA com camadas hierárquicas (L0-L3)
• Análise de segurança ciente de tipos - Rastreamento de taint aprimorado com inferência de tipos e implementações de trait
• CFG/DFG multi-linguagem - Análise de fluxo de controle e fluxo de dados estendida para Go, Java, C#, Kotlin
• Varredura de Infraestrutura como Código - Novas regras iac.yaml para Terraform, CloudFormation, Kubernetes
• Regras de segurança específicas por linguagem - Novas regras para Go, Java, C#, Kotlin, Bash
• 6 novas linguagens - Erlang, Elm, Fortran, PowerShell, Nix, Groovy
• 90 ferramentas no total - Acima de 79 com novas capacidades SPARQL, CCG e análise

v1.2.x

• Parâmetro exclude_tests - 22 ferramentas suportam filtragem de arquivos de teste
• Pacote npm - Instale via npm install -g narsil-mcp

v1.1.x

• Distribuição multi-plataforma - Instale via Homebrew, Scoop, npm, Cargo ou download direto
• Predefinições de ferramentas configuráveis - Predefinições mínima, balanceada, completa e focada em segurança
• Detecção automática de editor - Padrões ideais para Zed, VS Code, Claude Desktop
• Assistente de configuração interativo - narsil-mcp config init para configuração fácil
• Suporte a 32 linguagens - Adicionado Dart, Julia, R, Perl, Zig e mais
• Desempenho aprimorado - Inicialização mais rápida com indexação em segundo plano

v1.0.x

• Busca semântica neural - Encontre código similar usando embeddings Voyage AI ou OpenAI
• Inferência de tipos - Infira tipos em Python/JavaScript/TypeScript sem ferramentas externas
• Análise de taint multi-linguagem - Varredura de segurança para PHP, Java, C#, Ruby, Kotlin
• Build WASM - Execute no navegador para playgrounds de código e ferramentas educacionais
• 147 regras de segurança empacotadas - Detecção OWASP, CWE, criptografia, segredos, Rust, Elixir
• Configurações de IDE incluídas - Templates Claude Desktop, Cursor, VS Code, Zed

Licença

Licenciado sob uma das seguintes:

• Apache License, Versão 2.0 (LICENSE-APACHE ou http://www.apache.org/licenses/LICENSE-2.0)
• Licença MIT (LICENSE-MIT ou http://opensource.org/licenses/MIT)

à sua escolha.

Créditos

Construído com:

• tree-sitter - Análise incremental
• tantivy - Busca de texto completo
• tokio - Runtime assíncrono
• rayon - Paralelismo de dados
• serde - Serialização