Instalação

O Silex é um servidor MCP local distribuído como pacote Python. Ele escaneia o código na sua máquina; nada sai dela. Requer Python 3.10+.

# Requer Python 3.10+
pip install silex-archaeology

Sem cartão. Sem conta. Sem telemetria. Os comandos abaixo instalam em um ambiente virtual isolado — do jeito que rodamos em campo.

Prefira o venv acima, ou pipx (pipx install silex-archaeology). Um pip install global pode trocar silenciosamente dependências compartilhadas com outras ferramentas da sua máquina — uma instalação em campo viu starlette e idna serem atualizados de um jeito que quebrou um setup existente de aider-chat/fastapi. A instalação isolada abaixo nunca toca nelas.

Windows — PowerShell

O PowerShell usa $env:USERPROFILE, nunca %USERPROFILE%. A sintaxe %VAR% é exclusiva do cmd.exe — no PowerShell ela não é expandida e cria silenciosamente uma pasta literal %USERPROFILE% (um venv de 400 MB parou dentro de uma dessas em campo). Use $env:USERPROFILE no PowerShell; mantenha %USERPROFILE% apenas no cmd.exe clássico.

Crie um venv isolado e instale o pacote nele:

# PowerShell — crie o venv e instale
python -m venv $env:USERPROFILE\silex-mcp\venv
& $env:USERPROFILE\silex-mcp\venv\Scripts\pip install silex-archaeology

# Teste rápido — o servidor responde fora do seu cliente
& $env:USERPROFILE\silex-mcp\venv\Scripts\silex-mcp-server.exe --help

Linux / macOS

A mesma receita com o layout de venv POSIX:

# bash / zsh — crie o venv e instale
python3 -m venv ~/silex-mcp/venv
~/silex-mcp/venv/bin/pip install silex-archaeology

# Teste rápido
~/silex-mcp/venv/bin/silex-mcp-server --help

Conecte seu agente

O Silex fala MCP via stdio. Adicione-o a qualquer cliente compatível com MCP — Cursor, Claude Desktop, Claude Code, Windsurf, Cline, Continue, Zed. A extensão do VS Code está a caminho; hoje o caminho é o MCP. Há duas superfícies de configuração:

Claude Desktop — claude_desktop_config.json

No Windows, esse arquivo fica em %APPDATA%\Claude\claude_desktop_config.json (abra $env:APPDATA\Claude pelo PowerShell). Cinco linhas bastam — o comando mais SILEX_TIER=free:

{
  "mcpServers": {
    "silex": {
      "command": "silex-mcp-server",
      "args": ["--transport", "stdio"],
      "env": { "SILEX_TIER": "free" }
    }
  }
}

Aponte command para o binário do venv acima se ele não estiver no seu PATH. Depois feche completamente e reabra o Claude Desktop — o ícone de ferramentas lista as ferramentas silex.

Claude Code / VS Code — .mcp.json (primário)

Bug de caixa do drive no Windows. claude mcp add grava o caminho em ~/.claude.json como C:/… enquanto a extensão do VS Code lê c:/… — a divergência de caixa quebra a descoberta do servidor (travou uma execução em campo). O caminho robusto no Windows é um .mcp.json na raiz do projeto como forma primária; mantenha claude mcp add para Linux/macOS.

Crie .mcp.json na raiz do projeto que você quer que o Silex enxergue:

// .mcp.json — raiz do projeto (Claude Code e VS Code)
{
  "mcpServers": {
    "silex": {
      "command": "silex-mcp-server",
      "args": ["--transport", "stdio"],
      "env": { "SILEX_TIER": "free" }
    }
  }
}

No Linux / macOS você pode, em vez disso, rodar claude mcp add silex -- silex-mcp-server --transport stdio.

Primeiro scan

No primeiro uso, o Silex escaneia o workspace e constrói uma base de conhecimento local: arquitetura, dependências, workflows e regras de negócio — cada afirmação ancorada em file:line. Seu agente então consulta esse conhecimento pelas ferramentas MCP abaixo.

O índice acompanha os seus commits sozinho: cada chamada de tool compara o commit que o índice cobre com o HEAD atual (mais o working tree) e re-ingere só os arquivos que mudaram — a âncora file:line segue o código que você acabou de escrever. Toda resposta carrega um bloco index_age: qual commit foi indexado, quantos commits o repo andou desde então e se aquela chamada refrescou. Instalar o hook git (silex-fresh-hook-install) é otimização, nunca requisito; rescan_workspace é o caminho manual de volta.

Ferramentas MCP

Todas as ferramentas vivem sob o namespace silex-archaeology. A lista completa e sempre atual — nomes, parâmetros e exemplos — é gerada a partir do registro real na página de referência de ferramentas MCP.

Evidências e confiança

Toda afirmação carrega um veredito, um percentual de confiança e uma âncora de proveniência. Vereditos:

A confiança é exibida como percentual arredondado em monospace (96%). Âncoras são links file:line para o seu código, ex.: Order.cs:99-131.

Território desconhecido

O Silex nunca chuta. O que o scan não consegue provar é reportado como território desconhecido, então seu agente sabe onde o mapa termina.

Relatório compartilhável

Cada scan produz um relatório que você pode compartilhar com o time — a mesma evidência que seu agente vê, legível por humanos. Veja um exemplo real gerado a partir do eShop, app de referência da Microsoft, com cada regra ancorada a um link fixo no commit do código-fonte.