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?

Recurso	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 Recursos

• Inteligência de Código - Extração de símbolos, busca semântica, análise de grafos de chamada
• Busca Semântica Neural - Encontre código semelhante 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 - Parsing incremental e preciso para 32 linguagens
• Zero configuração - Aponte para os repositórios e pronto
• Compatível com MCP - Funciona com Claude, Cursor, VS Code Copilot, Zed e qualquer cliente MCP
• Foco em privacidade - 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 integrada de vulnerabilidades e análise de taint
• 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 avança em 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, protocols, funções
Verilog/SystemVerilog	.v, .vh, .sv, .svh	módulos, tasks, 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, type classes
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, records
Elm	.elm	funções, tipos
Fortran	.f90, .f95, .f03, .f08, .f, .for, .fpp	programas, subrotinas, funções, módulos
PowerShell	.ps1, .psm1, .psd1	funções, classes, enums
Nix	.nix	bindings
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 Windows: O instalador PowerShell fornece melhores mensagens de erro e integração nativa com 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 estável atual (esta versão foi verificada com Rust 1.98 e 1.99)
• No Windows: Visual Studio Build Tools com "Desenvolvimento para desktop com 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

Builds de Recursos

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

Recurso	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 experimental para navegador (sem sistema de arquivos, git)	Não qualificado para release

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

Para instruções detalhadas de instalação, solução de problemas e guias específicos por plataforma, consulte 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 Recursos

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 sinalizador habilita consultas SPARQL e ferramentas de Code Context Graph (CCG), mas somente se o binário foi compilado com --features graph. O binário padrão não inclui esse recurso. Se você precisar 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 o recurso, 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 para Voyage AI
• OPENAI_API_KEY - Chave de API específica para OpenAI
• EMBEDDING_SERVER_ENDPOINT - URL do endpoint de API de embedding personalizado (opcional, permite usar modelos auto-hospedados)

Configuração

A 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

O narsil-mcp detecta seu editor e aplica um preset ideal automaticamente:

Editor	Preset	Ferramentas	Tokens de Contexto	Por quê
Zed	Mínimo	26	~4.686	Inicialização rápida, contexto mínimo
VS Code	Equilibrado	51	~8.948	Bom equilíbrio de recursos
Claude Desktop	Completo	90	~12.001	Máximas capacidades

Economia de Tokens:

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

Presets

Escolha um preset 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 workspaces 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: Sinalizadores de 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 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

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	Relações 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 todo o 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

Recursos:

• Grafos interativos Cytoscape.js com arrastar, zoom e detalhamento com duplo clique
• Sobreposição de métricas de complexidade com codificação por cores (verde/amarelo/laranja/vermelho)
• Sobreposição de vulnerabilidades de segurança destacando fontes e sumidouros de taint
• Seis algoritmos de layout (dagre, force-directed, breadthfirst, concentric, circle, grid)
• Barra lateral de árvore de arquivos com visualizador de código com realce de sintaxe
• Estado orientado por URL (links compartilháveis, botões voltar/avançar do navegador)
• Suporte a modo escuro
• Painel de detalhes do nó com trechos de código e navegação para a fonte

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

Busca Semântica Neural

Encontre código semelhante 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: Consulte 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	Obtenha tipos inferidos para todas as variáveis em uma função
check_type_errors	Encontre possíveis incompatibilidades de tipos
get_typed_taint_flow	Análise de segurança aprimorada com informações de tipos

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

Integração com Forgemax (Experimental)

Para fluxos de trabalho agênticos em larga escala, o narsil-mcp pode ser usado através do Forgemax — um gateway MCP Code Mode 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 o 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 faz chamadas por meio de objetos proxy tipados dentro de um isolate V8 em sandbox — credenciais, caminhos de arquivos e estado interno nunca saem do host. Essa abordagem é particularmente útil ao trabalhar com vários servidores MCP simultaneamente, pois mantém o contexto total das ferramentas pequeno e previsível.

Configuração do 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"]
    }
  }
}

Em seguida, inicie o Claude Code no seu projeto:

cd /path/to/project
claude

Usar . para --repos indexa automaticamente o diretório atual. O 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. Consulte Integração com 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 a 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: o narsil-mcp inicia imediatamente e indexa em segundo plano, evitando timeouts de inicialização.

---

Plugin do Claude Code

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

Instalação via Marketplace (Recomendado):

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

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

Ou instale diretamente do GitHub:

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

O que está incluído:

Componente	Descrição
/narsil:security-scan	Executa auditorias de segurança abrangentes
/narsil:explore	Explore bases de código desconhecidas
/narsil:analyze-function	Mergulho profundo em funções específicas
/narsil:find-feature	Encontre onde os recursos são implementados
/narsil:supply-chain	Analise a segurança da cadeia de suprimentos
Skill	Orienta o Claude no uso eficaz de 90 ferramentas
Config MCP	Inicia automaticamente o narsil-mcp com padrões sensatos

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

Integração com Ralph Automation

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

Recurso	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 arquivos	Grafos de chamadas, 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 de ciclos

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>

O Ralph degrada graciosamente quando o narsil-mcp está indisponível — todos os recursos principais de automação funcionam sem ele.

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

Playbooks e Tutoriais

Consulte docs/playbooks para guias de uso prático:

Guia	Descrição
Começando	Configuração rápida e primeiras chamadas de ferramenta
Entenda uma Base de Código	Explore projetos desconhecidos
Corrija um Bug	Depure com grafos de chamadas e análise de taint
Auditoria de Segurança	Encontre vulnerabilidades com varredura OWASP/CWE
Revisão de Código	Revise alterações de forma eficaz

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

Uso em WebAssembly (Navegador)

O repositório contém código-fonte WebAssembly experimental e um script de build local. @narsil-mcp/wasm não é publicado no npm e não é um canal de distribuição para o lançamento da CLI 1.7.1. O build WASM e os exemplos não são cobertos pela qualificação desse lançamento. Consulte docs/wasm.md para o fluxo de trabalho do código-fonte experimental.

Ferramentas Disponíveis (93)

Gerenciamento de Repositório e Arquivos

Ferramenta	Descrição
list_repos	Lista todos os repositórios indexados com metadados
get_project_structure	Obtém árvore de diretórios com ícones e tamanhos de arquivos
get_file	Obtém conteúdo de arquivo com intervalo de linhas opcional
get_excerpt	Extrai código ao redor de linhas específicas com contexto
reindex	Aciona reindexação de repositórios
discover_repos	Descobre automaticamente repositórios em um diretório
validate_repo	Verifica se o caminho é um repositório válido
get_index_status	Mostra estatísticas do índice e recursos habilitados

Busca e Navegação de Símbolos

Ferramenta	Descrição
find_symbols	Encontra structs, classes, funções por tipo/padrão
get_symbol_definition	Obtém código-fonte do símbolo com contexto ao redor
find_references	Encontra todas as referências a um símbolo
get_dependencies	Analisa imports e dependentes
workspace_symbol_search	Busca difusa de símbolos no workspace
find_symbol_usages	Uso de símbolos entre arquivos com imports
get_export_map	Obtém símbolos exportados de um arquivo/módulo

Busca de Código

Ferramenta	Descrição
search_code	Busca por palavras-chave com classificação por relevância
semantic_search	Busca semântica classificada por BM25
hybrid_search	Combinação BM25 + TF-IDF com fusão de rankings
search_chunks	Busca em blocos de código cientes de AST
find_similar_code	Encontra código semelhante a um trecho (TF-IDF)
find_similar_to_symbol	Encontra código semelhante a um símbolo

Fragmentação Ciente de AST

Ferramenta	Descrição
get_chunks	Obtém blocos cientes de AST para um arquivo
get_chunk_stats	Estatísticas sobre blocos de código
get_embedding_stats	Estatísticas do índice de embeddings

Busca Semântica Neural (requer --neural)

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

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

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

Análise de Fluxo de Controle

Ferramenta	Descrição
get_control_flow	Obtém CFG mostrando blocos básicos e ramificações
find_dead_code	Encontra 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	Infere tipos para variáveis em uma função sem verificadores de tipo externos
check_type_errors	Encontra 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ências

Ferramenta	Descrição
get_import_graph	Constrói e analisa grafo de importação
find_circular_imports	Detecta dependências circulares
get_incremental_status	Árvore Merkle e estatísticas de alterações

Análise de Segurança - Rastreamento de Taint

Ferramenta	Descrição
find_injection_vulnerabilities	Encontra injeção de SQL, XSS, injeção de comandos, path traversal
trace_taint	Rastreia fluxo de dados contaminados a partir de uma origem
get_taint_sources	Lista 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 - Mecanismo de Regras

Ferramenta	Descrição
scan_security	Varredura com regras de segurança (OWASP, CWE, cripto, segredos)
check_owasp_top10	Varredura para vulnerabilidades OWASP Top 10 2021
check_cwe_top25	Varredura para fraquezas CWE Top 25
explain_vulnerability	Obtém explicação detalhada da vulnerabilidade
suggest_fix	Obtém sugestões de remediação para descobertas

Segurança da Cadeia de Suprimentos

Ferramenta	Descrição
generate_sbom	Gera SBOM (CycloneDX/SPDX/JSON)
check_dependencies	Verifica vulnerabilidades conhecidas (banco de dados OSV)
check_licenses	Analisa licenças para problemas de conformidade
find_upgrade_path	Encontra caminhos seguros de atualização para dependências vulneráveis

Integração com 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 alto churn e complexidade
get_contributors	Contribuidores do repositório/arquivo
get_commit_diff	Diff para commit específico
get_symbol_history	Commits que alteraram um símbolo
get_branch_info	Branch atual e status
get_modified_files	Alterações na árvore de trabalho

Integração com LSP (requer --lsp)

Ferramenta	Descrição
get_hover_info	Informações de tipo e documentação
get_type_info	Informações precisas de tipo
go_to_definition	Encontra localização da definição

Suporte a Repositórios Remotos (requer --remote)

Ferramenta	Descrição
add_remote_repo	Clona e indexa repositório do GitHub
list_remote_files	Lista arquivos via API do GitHub
get_remote_file	Busca arquivo via API do GitHub

Métricas

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

SPARQL / Grafo de Conhecimento (requer --graph)

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

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

O 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	Exporta 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	Exporta todas as camadas CCG como um pacote
query_ccg	Consulta CCG usando SPARQL
get_ccg_acl	Gera controle de acesso WebACL para camadas CCG
get_ccg_access_info	Obtém informações de nível de acesso CCG
import_ccg	Importa camada CCG de URL ou arquivo
import_ccg_from_registry	Importa CCG do registro codecontextgraph.com

Regras de Segurança

O 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 - CWE Top 25 Fraquezas Mais Perigosas
• crypto.yaml - Problemas criptográficos (algoritmos fracos, chaves codificadas)
• secrets.yaml - Detecção de segredos (chaves de API, senhas, tokens) Regras Específicas por Linguagem:
• rust.yaml - Padrões de segurança em Rust (transmute inseguro, fronteiras FFI, injeção de comandos, TOCTOU)
• elixir.yaml - Padrões Elixir/BEAM (exaustão de átomos, binary_to_term, Code.eval, injeção SQL no Ecto)
• go.yaml - Padrões de segurança em Go (injeção SQL, TLS, injeção de comandos)
• java.yaml - Vulnerabilidades em Java (XXE, desserialização, injeção LDAP)
• csharp.yaml - Problemas de segurança em C# (desserialização, XSS, path traversal)
• kotlin.yaml - Padrões Kotlin/Android (WebView, intents, segredos)
• bash.yaml - Vulnerabilidades em shell script (injeção de comandos, eval)

Infraestrutura e Configuração:

• iac.yaml - Infraestrutura como Código (Terraform, CloudFormation, Kubernetes)
• config.yaml - Segurança em arquivos 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)             |  |
|  +-----------------------------------------------------------+  |
+-----------------------------------------------------------------+

Performance

Benchmark realizado em Apple M1 (criterion.rs):

Throughput de Parsing

Linguagem	Tamanho da Entrada	Tempo	Throughput
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 documentos	80 µs
Similaridade TF-IDF	1.000 documentos	130 µs
Híbrido (BM25+TF-IDF)	1.000 documentos	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
linux kernel	78.000+	~500K	45s	2,1 GB

Métricas-chave:

• Parsing Tree-sitter: ~2 GiB/s de throughput sustentado
• Busca de símbolos: <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 da 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 Encontrando 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

Recurso de Grafo Não Funcionando

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 o recurso 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 é um recurso separado? O recurso 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. Ele é mantido opcional para manter o binário padrão menor.

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

• graph=true significa que o recurso está compilado E habilitado
• graph=false significa que o recurso não está compilado, OU --graph não foi passado

Roadmap

Concluído

• Extração de símbolos multi-linguagem (32 linguagens)
• Busca de texto completo com Tantivy (ranqueamento BM25)
• Busca híbrida (BM25 + TF-IDF com RRF)
• Chunking de código ciente de AST
• Integração com Git blame/histórico
• Análise de grafo de chamadas 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çáveis
• 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, cripto, segredos)
• Geração de SBOM (CycloneDX, SPDX)
• Verificação de vulnerabilidades de dependências (OSV)
• Análise de conformidade de licenças
• Grafo de importação com detecção de dependências circulares
• Resolução de símbolos entre linguagens
• Indexação incremental com árvores Merkle
• Persistência de índice
• Modo de observação para mudanças em arquivos
• Integração LSP
• Suporte a repositórios remotos
• Respostas em streaming

O Que Há de Novo

v1.6.x (Atual)

• Chunking à prova de falhas - Corrigido o fatiamento inseguro de strings em nível de byte em chunk_file() e extract_signature() que causava hybrid_search, search_chunks e get_chunk_stats a falharem ao processar arquivos com caracteres UTF-8 multibyte (emoji, CJK, caracteres acentuados). Todo fatiamento de bytes agora usa content.get() seguro com fallback.
• Operações de ordenação seguras para NaN - Corrigidos 5 locais nos módulos de busca, embeddings, git, índice e extração onde partial_cmp().unwrap() causaria pânico em valores flutuantes NaN. Todas as ordenações agora usam unwrap_or(Ordering::Equal).
• Chunking 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 o servidor MCP inteiro.
• Reformulação do frontend de visualização - SPA completo com roteamento HashRouter, barra lateral de árvore de arquivos, visualizador de código com realce de sintaxe, dashboard e páginas de visão geral por repositório
• Performance da visualização de grafo - O grafo de importação agora usa dados de índice em cache em vez de varreduras no sistema de arquivos; o grafo de símbolos itera o cache de arquivos diretamente em vez de idas e voltas em markdown; todas as visualizações respeitam max_nodes para terminação antecipada
• Grafos de fluxo de controle reais - A 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 - A visualização híbrida aloca orçamento de nós 60/40 entre grafos de chamada e importação para resultados equilibrados
• Correção #14: dimensões de embedding configuráveis - Adicionado argumento CLI --neural-dimension e lookup 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 comandos, 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 no Ecto, XSS Phoenix, segurança de distribuição Erlang
• Migrado de serde_yaml para serde-saphyr - serde_yaml obsoleto substituído por biblioteca YAML ativamente mantida e à prova de pânico
• Favicon personalizado - O frontend agora usa o ícone de marca narsil-mcp em vez do logotipo padrão do Vite
• 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 aumentada de 1.611 para 1.763 (+152 testes)

v1.5.x

• Resolução determinística de grafo de chamadas - Propagação de dicas 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 hotspots, manipulação de expressões CFG, parsing de caminhos de importação
• Melhorias no flake Nix - Helper mkPkg DRY, frameworks macOS desnecessários removidos, estratégia de teste --lib para builds em sandbox

v1.4.x

• Grafo de Conhecimento SPARQL / RDF - Consulte dados de inteligência de código com SPARQL via Oxigraph
• Grafo de Contexto de Código (CCG) - 12 ferramentas para representações padronizadas de base de código consumíveis por IA com camadas em níveis (L0-L3)
• Análise de segurança ciente de tipos - Rastreamento de taint aprimorado com inferência de tipos e implementações de traits
• 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, equilibrada, 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 - Adicionadas Dart, Julia, R, Perl, Zig e mais
• Performance melhorada - Inicialização mais rápida com indexação em segundo plano

v1.0.x

• Busca semântica neural - Encontre código semelhante 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 incluídas - Detecção OWASP, CWE, cripto, segredos, Rust, Elixir
• Configurações de IDE incluídas - Modelos Claude Desktop, Cursor, VS Code, Zed

Licença

Licenciado sob qualquer 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 - Parsing incremental
• tantivy - Busca de texto completo
• tokio - Runtime assíncrono
• rayon - Paralelismo de dados
• serde - Serialização