agent-lsp

Infraestrutura de inteligência de código para agentes de IA. 65 ferramentas, 31 linguagens verificadas por CI, 24 fluxos de trabalho para agentes. Um único binário Go.

curl -fsSL https://raw.githubusercontent.com/blackwell-systems/agent-lsp/main/install.sh | sh && agent-lsp init

O que é?

agent-lsp é um servidor MCP que orquestra servidores LSP existentes (gopls, rust-analyzer, jdtls, etc.) em fluxos de trabalho nativos para agentes.

Não é um servidor LSP — é uma camada de orquestração que gerencia servidores de linguagem e expõe operações em lote, edição especulativa e fluxos de trabalho em múltiplas etapas por meio de ferramentas MCP.

Arquitetura:

• Servidores de linguagem (gopls, rust-analyzer, etc.) → fornecem inteligência de código
• agent-lsp (servidor MCP) → orquestra fluxos de trabalho, mantém runtime aquecido
• Agentes de IA → consomem via protocolo MCP

Por que agent-lsp?

Runtime aquecido e persistente
Os servidores de linguagem permanecem indexados entre sessões de agentes. Primeira sessão: indexa o workspace (~10s para projetos típicos). Sessões subsequentes: instantâneo. Sem penalidade de cold-start a cada requisição.

Operações em lote
blast_radius → uma chamada retorna todas as exportações + todos os chamadores (particionados entre teste e não-teste). Sem orquestração: 20+ chamadas LSP sequenciais.

Edição especulativa
simulate_edit → pré-visualize alterações em memória, verifique o delta de diagnósticos, aplique ou descarte. Teste edições antes de tocar no disco.

Orquestração de fluxos de trabalho
24 habilidades que encadeiam operações LSP em pipelines completos:

• /lsp-refactor → análise de impacto → pré-visualização → aplicação → verificação de build → execução de testes
• /lsp-safe-edit → pré-visualização → diff de diagnósticos → aplicar se seguro
• /lsp-verify → diagnósticos LSP → build → suíte de testes

Multi-linguagem, sessão única
Um único processo agent-lsp roteia .go para gopls, .ts para tsserver, .py para pyright. Sem reconfiguração entre projetos. A sessão persiste entre arquivos e repositórios.

[!TIP] Saída otimizada em tokens: Respostas de ferramentas codificadas em GCF em vez de JSON. 30-84% menos tokens dependendo da ferramenta (até 92,7% com deduplicação de sessão). 100% de compreensão por LLMs em todos os modelos de fronteira, 91,2% em grafos de código complexos onde JSON tem média de 54,1%. Veja abaixo para economias medidas por ferramenta.

Como as peças se encaixam: LSP (Language Server Protocol) é como editores obtêm inteligência de código: autocompletes, diagnósticos, ir para definição. MCP (Model Context Protocol) é o padrão pelo qual ferramentas de IA como Claude Code descobrem e chamam ferramentas externas. agent-lsp faz a ponte entre os dois: inteligência de servidor de linguagem, acessível a agentes de IA.

Use quando

• Construindo sistemas agenticos de geração de código
• Automatizando refatorações em grandes bases de código
• Ferramentas de CI que precisam de inteligência de código programática
• Qualquer fluxo de trabalho onde chamadas LSP sequenciais são lentas ou complexas demais

O que os agentes dizem

Pedimos a agentes de IA que avaliassem agent-lsp em 10 tarefas de codificação (encontrar chamadores, renomear com segurança, pré-visualizar edições, detectar código morto) e escrevessem uma avaliação honesta. Quatro modelos diferentes, quatro avaliações independentes, mesma conclusão:

Claude (Opus 4.6): "Eu recomendaria agent-lsp para qualquer fluxo de trabalho envolvendo refatoração, análise de impacto ou edição segura. As ferramentas de destaque são blast_radius (raio de impacto em uma chamada, com particionamento teste/não-teste que exigiria 5-10 comandos grep para replicar), go_to_implementation (satisfação de interface verificada por tipo que grep simplesmente não consegue fazer), e o fluxo de trabalho de sessão de simulação (verificação de tipos especulativa sem tocar no disco, que não tem equivalente em grep/leitura)."

Cursor (auto): "Eu recomendaria agent-lsp para refatorações pesadas e navegação de código porque as ferramentas de renomear, referências, implementações, hierarquia de chamadas e simulação eliminam muito trabalho frágil de grep/edição manual e tornam as alterações mais seguras."

GPT-5.5 (via Codex): "Eu recomendaria agent-lsp para trabalho ciente de símbolos: referências, implementações, pré-visualizações de renomeação, diagnósticos e estrutura de arquivos grandes são materialmente mais rápidos e menos propensos a erros do que loops de grep/leitura."

Gemini 2.5 Pro (via Gemini CLI): "Eu recomendaria fortemente agent-lsp porque ele fornece um nível de consciência semântica que ferramentas padrão de busca de texto simplesmente não conseguem igualar. A capacidade de realizar renomeações de alta confiança, encontrar implementações de interfaces e pré-visualizar o impacto de diagnósticos de edições sem escrever no disco reduz significativamente o risco de introduzir regressões."

Testado, não presumido

Toda outra implementação MCP-LSP lista linguagens suportadas em um arquivo de configuração. Nenhuma delas executa o servidor de linguagem real em CI para verificar se funciona.

O CI do agent-lsp executa 31 servidores de linguagem reais contra bases de código fixture reais a cada push: Go, Python, TypeScript, Rust, Java, C, C++, C#, Ruby, PHP, Kotlin, Swift, Scala, Zig, Lua, Elixir, Gleam, Clojure, Dart, Terraform, Nix, Prisma, SQL, MongoDB, e mais. Quando dizemos "funciona com gopls," isso é uma afirmação verificada e automatizada, não uma esperança.

Execução especulativa

Simule alterações em memória antes de escrever no disco. Nenhuma outra implementação MCP-LSP tem isso.

preview_edit pré-visualiza o impacto de diagnósticos de qualquer edição. Você vê exatamente o que quebra antes de o arquivo ser tocado. simulate_chain avalia uma sequência de edições dependentes (renomear uma função, atualizar todos os chamadores, mudar o tipo de retorno) e relata qual etapa primeiro introduz um erro.

8 ferramentas de execução especulativa. Veja docs/guide/speculative-execution.md para o fluxo de trabalho completo.

Economia de tokens

Respostas LSP estruturadas usam 5-34x menos tokens do que grep/leitura nas mesmas tarefas. No HashiCorp Consul (319K linhas), uma análise de raio de impacto usa 17,7MB via grep vs 841KB via LSP, reduzindo 5.534 chamadas de ferramentas para 119. A economia escala com o tamanho da base de código. Veja docs/guide/token-savings.md para o experimento completo em cinco bases de código.

Saída otimizada em tokens (GCF)

Respostas de ferramentas são codificadas em GCF (Graph Compact Format) em vez de JSON. GCF elimina repetição de nomes de campos, repetição de identificadores e sobrecarga estrutural por registro.

Respostas agrupadas/ aninhadas (chamadores sob um símbolo, diagnósticos com informações relacionadas) também são tabularizadas, com ~14% sobre JSON nesse formato (detalhes).

GCF está habilitado por padrão. Para reverter para JSON:

export AGENT_LSP_OUTPUT_FORMAT=json

Benchmark: go run scripts/gcf-benchmark.go. Veja docs/guide/gcf-integration.md para detalhes de arquitetura.

GCF: gcformat.com · Spec · Go · Python · TypeScript · Playground

Por que a orquestração importa

Agentes de IA fazem alterações incorretas de código porque não conseguem ver o quadro completo: quem chama esta função, o que quebra se eu renomeá-la, o build ainda passa. Servidores de linguagem têm as respostas, mas ferramentas LSP brutas exigem 20+ chamadas sequenciais e lógica de orquestração complexa.

agent-lsp resolve isso codificando operações corretas de múltiplas etapas em chamadas únicas e habilidades. blast_radius faz o que exigiria 20+ chamadas de um agente em uma só. /lsp-refactor encadeia impacto → pré-visualização → aplicação → verificação → teste sem orquestração por prompt.

Modo daemon persistente

Projetos Python e TypeScript precisam de minutos de indexação em segundo plano antes de find_references funcionar. agent-lsp automaticamente inicia um broker daemon persistente que sobrevive entre sessões, então o workspace permanece indexado. Primeira sessão: daemon inicia e indexa (~10s para FastAPI). Sessões subsequentes: conexão instantânea ao daemon aquecido. Sai automaticamente após 30 minutos de inatividade. Go, Rust e outras linguagens de indexação rápida ignoram isso completamente (zero sobrecarga).

Aplicação de fases

Habilidades dizem aos agentes a ordem correta de operações. A aplicação de fases faz o runtime bloquear violações em vez de confiar que o agente seguirá instruções.

Quando um agente ativa uma habilidade, cada chamada de ferramenta é verificada contra as permissões da fase atual. Chamar apply_edit durante análise de raio de impacto não prossegue silenciosamente; retorna um erro com orientação específica de recuperação ("complete a fase blast_radius primeiro, ferramentas permitidas: [blast_radius, find_references]"). As fases avançam automaticamente conforme o agente chama ferramentas de fases posteriores.

Nenhum outro provedor de ferramentas MCP aplica ordenação de fluxo de trabalho em runtime. Veja docs/guide/phase-enforcement.md.

Análise de concorrência

O inspetor inclui 4 verificações de concorrência que funcionam em 25 linguagens em 4 famílias de concorrência (goroutine, thread, async, actor):

• Entrada concorrente não recuperada: goroutines/threads/tarefas sem recuperação
• Estado compartilhado não verificado: asserções de tipo nuas em sync.Map, ConcurrentHashMap
• Canal nunca fechado: canais/filas criados mas nunca fechados (vazamentos de goroutine)
• Campo compartilhado sem sincronização: campos acessados de contextos concorrentes sem sincronização

blast_radius anota símbolos com sync_guarded: true quando o tipo pai tem um mutex. find_callers com cross_concurrent: true rastreia cadeias de chamadas através de limites de goroutine/thread. A habilidade /lsp-concurrency-audit produz um relatório de segurança em nível de campo para qualquer tipo.

Auto-diagnósticos

Ferramentas de edição de símbolos (replace_symbol_body, insert_after_symbol, insert_before_symbol, safe_delete_symbol) retornam automaticamente contagens de errors_after e warnings_after. Agentes sabem imediatamente se uma edição quebrou algo sem uma chamada separada de get_diagnostics.

safe_apply_edit combina pré-visualização + aplicação em uma chamada: pré-visualiza especulativamente, aplica no disco apenas se net_delta == 0 (sem novos erros). Uma chamada de ferramenta em vez de três.

Funciona com

Veja docs/getting-started/mcp-clients.md para configurações de copiar e colar.

Habilidades

Ferramentas brutas são ignoradas. Habilidades são usadas. Cada habilidade codifica a sequência correta de ferramentas para que fluxos de trabalho realmente aconteçam sem instruções de orquestração por prompt. Habilidades estão disponíveis como comandos de barra AgentSkills e como prompts MCP via prompts/list / prompts/get para qualquer cliente MCP.

Veja docs/guide/skills.md para descrições completas e orientação de uso.

Antes de mudar qualquer coisa

Editando com segurança

Primeiros passos

Entendendo código desconhecido

Após editar

Gerando código

Fluxo de trabalho completo

Docker

Modo Stdio (cliente MCP inicia o contêiner diretamente):

# Go
docker run --rm -i -v /your/project:/workspace ghcr.io/blackwell-systems/agent-lsp:go go:gopls

# TypeScript
docker run --rm -i -v /your/project:/workspace ghcr.io/blackwell-systems/agent-lsp:typescript typescript:typescript-language-server,--stdio

# Python
docker run --rm -i -v /your/project:/workspace ghcr.io/blackwell-systems/agent-lsp:python python:pyright-langserver,--stdio

Modo HTTP (serviço persistente, clientes remotos conectam via HTTP+SSE):

docker run --rm \
  -p 8080:8080 \
  -v /your/project:/workspace \
  -e AGENT_LSP_TOKEN=your-secret-token \
  ghcr.io/blackwell-systems/agent-lsp:go \
  --http --port 8080 go:gopls

As imagens são executadas como um usuário não root (uid 65532) por padrão. Defina AGENT_LSP_TOKEN via variável de ambiente, nunca --token na linha de comando. As imagens também são espelhadas no Docker Hub (blackwellsystems/agent-lsp). Consulte DOCKER.md para a lista completa de tags, configuração do modo HTTP e opções de endurecimento de segurança.

Configuração

Etapa 1: Instalar agent-lsp

curl -fsSL https://raw.githubusercontent.com/blackwell-systems/agent-lsp/main/install.sh | sh

brew install blackwell-systems/tap/agent-lsp

# PowerShell (no admin required)
iwr -useb https://raw.githubusercontent.com/blackwell-systems/agent-lsp/main/install.ps1 | iex

# Scoop
scoop bucket add blackwell-systems https://github.com/blackwell-systems/agent-lsp
scoop install blackwell-systems/agent-lsp

# Winget
winget install BlackwellSystems.agent-lsp

# pip
pip install agent-lsp

# npm
npm install -g @blackwell-systems/agent-lsp

# Go install
go install github.com/blackwell-systems/agent-lsp/cmd/agent-lsp@latest

Etapa 2: Instalar servidores de linguagem

Instale os servidores para sua stack. Os comuns:

Lista completa das 31 linguagens suportadas em docs/reference/language-support.md.

Etapa 3: Verificar a configuração

agent-lsp doctor

Testa cada servidor de linguagem configurado e relata capacidades. Corrija quaisquer falhas antes de prosseguir. Consulte suporte a linguagens para comandos de instalação e notas específicas do servidor.

Etapa 4: Configurar sua ferramenta de IA

agent-lsp init

Detecta servidores de linguagem no seu PATH, pergunta qual ferramenta de IA você usa, escreve a configuração MCP correta e instala regras de conscientização de skills para seu provedor de IA (CLAUDE.md para Claude Code, .cursor/rules/ para Cursor, .clinerules para Cline, .windsurfrules para Windsurf, GEMINI.md para Gemini CLI). Para uso em CI ou script: agent-lsp init --non-interactive.

A configuração gerada se parece com:

{
  "mcpServers": {
    "lsp": {
      "type": "stdio",
      "command": "agent-lsp",
      "args": [
        "go:gopls",
        "typescript:typescript-language-server,--stdio",
        "python:pyright-langserver,--stdio"
      ]
    }
  }
}

Cada argumento é language:server-binary (argumentos do servidor separados por vírgula).

Etapa 5: Instalar skills

git clone https://github.com/blackwell-systems/agent-lsp.git /tmp/agent-lsp-skills
cd /tmp/agent-lsp-skills/skills && ./install.sh --copy

Skills são arquivos de prompt copiados para a configuração da sua ferramenta de IA. --copy significa que o clone pode ser excluído com segurança depois.

Skills também estão disponíveis como prompts MCP: qualquer cliente MCP pode descobri-los via prompts/list e recuperar instruções completas de fluxo de trabalho via prompts/get, sem necessidade de instalação manual. O caminho install.sh é para clientes compatíveis com AgentSkills (comandos de barra do Claude Code).

Etapa 6: Permitir permissões de ferramentas (Claude Code)

Para Claude Code, adicione mcp__lsp__* à sua lista de permissões para que todas as 65 ferramentas estejam disponíveis sem prompts de aprovação por ferramenta:

// ~/.claude/settings.json
{
  "permissions": {
    "allow": ["mcp__lsp__*"]
  }
}

Sem isso, o Claude Code solicitará permissão em cada chamada de ferramenta. Outros clientes MCP lidam com permissões de forma diferente; consulte a documentação do seu cliente.

Skills são fluxos de trabalho multi-ferramenta que codificam procedimentos confiáveis: verificação de raio de impacto antes da edição, pré-visualização especulativa antes da gravação, execução de testes após a alteração. Consulte docs/guide/skills.md para a lista completa.

Etapa 7: Começar a trabalhar

Seu agente de IA chama ferramentas automaticamente. A primeira chamada inicializa o espaço de trabalho:

start_lsp(root_dir="/your/project")

Isso é o que o agente faz, não algo que você digita. Em seguida, use qualquer uma das 65 ferramentas. A sessão permanece ativa; não é necessário reiniciar ao alternar arquivos.

O que torna agent-lsp único

Casos de Uso

• Sessões multi-projeto: aponte sua IA para ~/code/, trabalhe em qualquer projeto sem reconfigurar
• Desenvolvimento poliglota: backend Go + frontend TypeScript + scripts Python em uma única sessão
• Monorepos grandes: um servidor lida com todas as linguagens, roteia por extensão de arquivo
• Migração de código: refatore entre repositórios com rastreamento completo de referências entre repositórios
• Pipelines de CI: valide contra o comportamento real do servidor de linguagem
• Stacks de linguagens de nicho: Gleam, Elixir, Prisma, Zig, Clojure, Nix, Dart, Scala, MongoDB, todos verificados em CI

Suporte Multi-Linguagem

31 linguagens, verificadas de ponta a ponta em CI contra servidores de linguagem reais em cada execução de CI. Nenhuma outra implementação MCP-LSP testa uma única linguagem em CI.

Go, Python, TypeScript, Rust, Java, C, C++, C#, Ruby, PHP, Kotlin, Swift, Scala, Zig, Lua, Elixir, Gleam, Clojure, Dart, Terraform, Nix, Prisma, SQL, MongoDB, JavaScript, YAML, JSON, Dockerfile, CSS, HTML.

Consulte docs/reference/language-support.md para a matriz de cobertura completa.

Ferramentas

65 ferramentas cobrindo navegação, análise, refatoração, edição de símbolos, exploração composta, edição segura, execução especulativa e ciclo de vida de sessão. Todas verificadas em CI.

Consulte docs/reference/tools.md para a referência completa com parâmetros e exemplos.

Leitura adicional

Documentação

• Referência de ferramentas: referência completa de ferramentas com parâmetros e exemplos
• Referência de skills: referência de skills, fluxos de trabalho, casos de uso e composição
• Suporte a linguagens: matriz de cobertura de linguagens
• Arquitetura: design do sistema e detalhes internos
• Execução especulativa: fluxos de trabalho de simular-antes-de-aplicar
• Conformidade LSP: cobertura da especificação LSP 3.17
• Docker: tags Docker, compose e cache de volume

Contribuindo

• Notas de CI: peculiaridades de CI e detalhes do harness de teste
• Distribuição: canais de instalação e pipeline de lançamento

Desenvolvimento

git clone https://github.com/blackwell-systems/agent-lsp.git
cd agent-lsp && go build ./...
go test ./...                   # unit tests
go test ./... -tags integration # integration tests (requires language servers)

Uso como Biblioteca

Os pacotes pkg/lsp, pkg/session e pkg/types expõem uma API Go estável para usar o cliente LSP do agent-lsp diretamente sem executar o servidor MCP.

import "github.com/blackwell-systems/agent-lsp/pkg/lsp"

client := lsp.NewLSPClient("gopls", []string{})
client.Initialize(ctx, "/path/to/workspace")
defer client.Shutdown(ctx)

locs, err := client.GetDefinition(ctx, fileURI, lsp.Position{Line: 10, Character: 4})

Consulte docs/architecture/architecture.md para a API completa dos pacotes.

Licença

MIT