agent-lsp

Infraestructura de inteligencia de código para agentes de IA. 65 herramientas, 31 lenguajes verificados por CI, 24 flujos de trabajo para agentes. Un único binario Go.

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

¿Qué es?

agent-lsp es un servidor MCP que orquesta servidores LSP existentes (gopls, rust-analyzer, jdtls, etc.) en flujos de trabajo nativos para agentes.

No es un servidor LSP — es una capa de orquestación que gestiona servidores de lenguaje y expone operaciones por lotes, edición especulativa y flujos de trabajo de múltiples pasos a través de herramientas MCP.

Arquitectura:

• Servidores de lenguaje (gopls, rust-analyzer, etc.) → proporcionan inteligencia de código
• agent-lsp (servidor MCP) → orquesta flujos de trabajo, mantiene un runtime cálido
• Agentes de IA → consumen a través del protocolo MCP

¿Por qué agent-lsp?

Runtime cálido persistente
Los servidores de lenguaje permanecen indexados entre sesiones de agentes. Primera sesión: indexa el workspace (~10s para proyectos típicos). Sesiones posteriores: instantáneo. Sin penalización de arranque en frío en cada solicitud.

Operaciones por lotes
blast_radius → una llamada devuelve todas las exportaciones y todos los llamadores (particionados entre test y no-test). Sin orquestación: más de 20 llamadas LSP secuenciales.

Edición especulativa
simulate_edit → previsualiza cambios en memoria, comprueba el delta de diagnósticos, aplica o descarta. Prueba ediciones antes de tocar el disco.

Orquestación de flujos de trabajo
24 habilidades que encadenan operaciones LSP en pipelines completos:

• /lsp-refactor → análisis de impacto → previsualización → aplicación → verificación de compilación → ejecución de pruebas
• /lsp-safe-edit → previsualización → diff de diagnósticos → aplicar si es seguro
• /lsp-verify → diagnósticos LSP → compilación → suite de pruebas

Multi-lenguaje, sesión única
Un solo proceso agent-lsp enruta .go a gopls, .ts a tsserver, .py a pyright. Sin reconfiguración entre proyectos. La sesión persiste entre archivos y repositorios.

[!TIP] Salida optimizada en tokens: Las respuestas de las herramientas se codifican en GCF en lugar de JSON. 30-84% menos tokens dependiendo de la herramienta (hasta 92.7% con deduplicación de sesión). 100% de comprensión LLM en cada modelo frontera, 91.2% en grafos de código complejos donde JSON promedia 54.1%. Ver abajo para ahorros medidos por herramienta.

Cómo encajan las piezas: LSP (Protocolo de Servidor de Lenguaje) es cómo los editores obtienen inteligencia de código: autocompletados, diagnósticos, ir a definición. MCP (Protocolo de Contexto de Modelo) es el estándar por el cual herramientas de IA como Claude Code descubren y llaman herramientas externas. agent-lsp une ambos: inteligencia de servidor de lenguaje, accesible para agentes de IA.

Úsalo cuando

• Construyas sistemas de generación de código agénticos
• Automatices refactorizaciones en bases de código grandes
• Herramientas de CI que necesiten inteligencia de código programática
• Cualquier flujo de trabajo donde las llamadas LSP secuenciales sean demasiado lentas o complejas

Lo que dicen los agentes

Pedimos a agentes de IA que evaluaran agent-lsp en 10 tareas de codificación (encontrar llamadores, renombrar de forma segura, previsualizar ediciones, detectar código muerto) y escribieran una evaluación honesta. Cuatro modelos diferentes, cuatro evaluaciones independientes, misma conclusión:

Claude (Opus 4.6): "Recomendaría agent-lsp para cualquier flujo de trabajo que implique refactorización, análisis de impacto o edición segura. Las herramientas destacadas son blast_radius (radio de explosión en una sola llamada, con partición test/no-test que requeriría 5-10 comandos grep para replicar), go_to_implementation (satisfacción de interfaz verificada por tipos que grep simplemente no puede hacer), y el flujo de trabajo de sesión de simulación (verificación especulativa de tipos sin tocar el disco, que no tiene equivalente con grep/lectura)."

Cursor (auto): "Recomendaría agent-lsp para refactorizaciones pesadas y navegación de código porque las herramientas de renombrado, referencias, implementaciones, jerarquía de llamadas y simulación eliminan mucho trabajo frágil de grep/edición manual y hacen los cambios más seguros."

GPT-5.5 (vía Codex): "Recomendaría agent-lsp para trabajo consciente de símbolos: referencias, implementaciones, previsualizaciones de renombrado, diagnósticos y estructura de archivos grandes son materialmente más rápidos y menos propensos a errores que los bucles de grep/lectura."

Gemini 2.5 Pro (vía Gemini CLI): "Recomendaría encarecidamente agent-lsp porque proporciona un nivel de conciencia semántica que las herramientas estándar de búsqueda de texto simplemente no pueden igualar. La capacidad de realizar renombrados de alta confianza, encontrar implementaciones de interfaces y previsualizar el impacto diagnóstico de ediciones sin escribir en disco reduce significativamente el riesgo de introducir regresiones."

Probado, no asumido

Cada otra implementación MCP-LSP lista lenguajes soportados en un archivo de configuración. Ninguna ejecuta el servidor de lenguaje real en CI para verificar que funciona.

El CI de agent-lsp ejecuta 31 servidores de lenguaje reales contra codebases de fixture reales en 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, y más. Cuando decimos "funciona con gopls," eso es una afirmación verificada y automatizada, no una esperanza.

Ejecución especulativa

Simula cambios en memoria antes de escribir en disco. Ninguna otra implementación MCP-LSP tiene esto.

preview_edit previsualiza el impacto diagnóstico de cualquier edición. Ves exactamente qué se rompe antes de tocar el archivo. simulate_chain evalúa una secuencia de ediciones dependientes (renombrar una función, actualizar todos los llamadores, cambiar el tipo de retorno) e informa qué paso introduce primero un error.

8 herramientas de ejecución especulativa. Ver docs/guide/speculative-execution.md para el flujo de trabajo completo.

Ahorro de tokens

Las respuestas LSP estructuradas usan 5-34x menos tokens que grep/lectura en las mismas tareas. En HashiCorp Consul (319K líneas), un análisis de radio de explosión usa 17.7MB vía grep vs 841KB vía LSP, reduciendo 5,534 llamadas de herramientas a 119. El ahorro escala con el tamaño de la base de código. Ver docs/guide/token-savings.md para el experimento completo en cinco bases de código.

Salida optimizada en tokens (GCF)

Las respuestas de las herramientas se codifican en GCF (Formato Compacto de Grafo) en lugar de JSON. GCF elimina la repetición de nombres de campos, la repetición de identificadores y la sobrecarga estructural por registro.

Las respuestas agrupadas/anidadas (llamadores bajo un símbolo, diagnósticos con información relacionada) también se tabularizan, con ~14% sobre JSON en esa forma (detalles).

GCF está habilitado por defecto. Para revertir a JSON:

export AGENT_LSP_OUTPUT_FORMAT=json

Benchmark: go run scripts/gcf-benchmark.go. Ver docs/guide/gcf-integration.md para detalles de arquitectura.

GCF: gcformat.com · Especificación · Go · Python · TypeScript · Playground

Por qué la orquestación importa

Los agentes de IA hacen cambios incorrectos en el código porque no pueden ver el panorama completo: quién llama a esta función, qué se rompe si la renombro, si la compilación sigue pasando. Los servidores de lenguaje tienen las respuestas, pero las herramientas LSP crudas requieren más de 20 llamadas secuenciales y lógica de orquestación compleja.

agent-lsp resuelve esto codificando operaciones correctas de múltiples pasos en llamadas y habilidades únicas. blast_radius hace lo que tomaría a un agente más de 20 llamadas en una sola. /lsp-refactor encadena impacto → previsualización → aplicación → verificación → prueba sin orquestación por prompt.

Modo daemon persistente

Los proyectos Python y TypeScript necesitan minutos de indexación en segundo plano antes de que find_references funcione. agent-lsp genera automáticamente un broker daemon persistente que sobrevive entre sesiones, por lo que el workspace permanece indexado. Primera sesión: el daemon se inicia e indexa (~10s para FastAPI). Sesiones posteriores: conexión instantánea al daemon cálido. Se auto-cierra después de 30 minutos de inactividad. Go, Rust y otros lenguajes de indexación rápida omiten esto por completo (cero sobrecarga).

Cumplimiento de fases

Las habilidades dicen a los agentes el orden correcto de operaciones. El cumplimiento de fases hace que el runtime bloquee violaciones en lugar de confiar en que el agente siga instrucciones.

Cuando un agente activa una habilidad, cada llamada de herramienta se verifica contra los permisos de la fase actual. Llamar a apply_edit durante el análisis de radio de explosión no procede silenciosamente; devuelve un error con orientación de recuperación específica ("completa la fase blast_radius primero, herramientas permitidas: [blast_radius, find_references]"). Las fases avanzan automáticamente a medida que el agente llama herramientas de fases posteriores.

Ningún otro proveedor de herramientas MCP impone el orden de flujo de trabajo en runtime. Ver docs/guide/phase-enforcement.md.

Análisis de concurrencia

El inspector incluye 4 verificaciones de concurrencia que funcionan en 25 lenguajes en 4 familias de concurrencia (goroutine, thread, async, actor):

• Entrada concurrente no recuperada: goroutines/threads/tareas sin recuperación
• Estado compartido no verificado: aserciones de tipo desnudas en sync.Map, ConcurrentHashMap
• Canal nunca cerrado: canales/colas creados pero nunca cerrados (fugas de goroutines)
• Campo compartido sin sincronización: campos accedidos desde contextos concurrentes sin sincronización

blast_radius anota símbolos con sync_guarded: true cuando el tipo padre tiene un mutex. find_callers con cross_concurrent: true rastrea cadenas de llamadas a través de límites de goroutine/thread. La habilidad /lsp-concurrency-audit produce un informe de seguridad a nivel de campo para cualquier tipo.

Auto-diagnósticos

Las herramientas de edición de símbolos (replace_symbol_body, insert_after_symbol, insert_before_symbol, safe_delete_symbol) devuelven automáticamente conteos de errors_after y warnings_after. Los agentes saben inmediatamente si una edición rompió algo sin una llamada separada a get_diagnostics.

safe_apply_edit combina previsualización + aplicación en una sola llamada: previsualiza especulativamente, aplica al disco solo si net_delta == 0 (sin nuevos errores). Una llamada de herramienta en lugar de tres.

Funciona con

Ver docs/getting-started/mcp-clients.md para configuraciones de copiar y pegar.

Habilidades

Las herramientas crudas se ignoran. Las habilidades se usan. Cada habilidad codifica la secuencia correcta de herramientas para que los flujos de trabajo realmente ocurran sin instrucciones de orquestación por prompt. Las habilidades están disponibles como comandos de barra AgentSkills y como prompts MCP vía prompts/list / prompts/get para cualquier cliente MCP.

Ver docs/guide/skills.md para descripciones completas y guía de uso.

Antes de cambiar cualquier cosa

Editando de forma segura

Primeros pasos

Entendiendo código desconocido

Después de editar

Generando código

Flujo de trabajo completo

Docker

Modo Stdio (el cliente MCP inicia el contenedor directamente):

# 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 (servicio persistente, clientes remotos se conectan a través de 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

Las imágenes se ejecutan como un usuario no root (uid 65532) por defecto. Establezca AGENT_LSP_TOKEN mediante variable de entorno, nunca --token en la línea de comandos. Las imágenes también se reflejan en Docker Hub (blackwellsystems/agent-lsp). Consulte DOCKER.md para la lista completa de etiquetas, configuración del modo HTTP y opciones de endurecimiento de seguridad.

Configuración

Paso 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

Paso 2: Instalar servidores de lenguaje

Instale los servidores para su stack. Los comunes:

Lista completa de 31 lenguajes soportados en docs/reference/language-support.md.

Paso 3: Verificar la configuración

agent-lsp doctor

Prueba cada servidor de lenguaje configurado e informa capacidades. Corrija cualquier fallo antes de continuar. Consulte soporte de lenguajes para comandos de instalación y notas específicas del servidor.

Paso 4: Configurar su herramienta de IA

agent-lsp init

Detecta servidores de lenguaje en su PATH, pregunta qué herramienta de IA usa, escribe la configuración MCP correcta e instala reglas de conciencia de habilidades para su proveedor de IA (CLAUDE.md para Claude Code, .cursor/rules/ para Cursor, .clinerules para Cline, .windsurfrules para Windsurf, GEMINI.md para Gemini CLI). Para CI o uso con scripts: agent-lsp init --non-interactive.

La configuración generada se ve así:

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

Cada argumento es language:server-binary (argumentos del servidor separados por comas).

Paso 5: Instalar habilidades

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

Las habilidades son archivos de prompt copiados en la configuración de su herramienta de IA. --copy significa que el clon se puede eliminar de forma segura después.

Las habilidades también están disponibles como prompts MCP: cualquier cliente MCP puede descubrirlas a través de prompts/list y recuperar instrucciones completas de flujo de trabajo a través de prompts/get, sin necesidad de instalación manual. La ruta install.sh es para clientes compatibles con AgentSkills (comandos de barra de Claude Code).

Paso 6: Permitir permisos de herramientas (Claude Code)

Para Claude Code, agregue mcp__lsp__* a su lista de permisos permitidos para que las 65 herramientas estén disponibles sin prompts de aprobación por herramienta:

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

Sin esto, Claude Code solicitará permiso en cada llamada de herramienta. Otros clientes MCP manejan los permisos de manera diferente; consulte la documentación de su cliente.

Las habilidades son flujos de trabajo de múltiples herramientas que codifican procedimientos confiables: verificación de radio de explosión antes de editar, vista previa especulativa antes de escribir, ejecución de pruebas después del cambio. Consulte docs/guide/skills.md para la lista completa.

Paso 7: Comenzar a trabajar

Su agente de IA llama a las herramientas automáticamente. La primera llamada inicializa el espacio de trabajo:

start_lsp(root_dir="/your/project")

Esto es lo que hace el agente, no algo que usted escriba. Luego use cualquiera de las 65 herramientas. La sesión permanece activa; no se necesita reinicio al cambiar de archivos.

Qué hace único a agent-lsp

Casos de uso

• Sesiones multi-proyecto: apunte su IA a ~/code/, trabaje en cualquier proyecto sin reconfigurar
• Desarrollo políglota: backend Go + frontend TypeScript + scripts Python en una sola sesión
• Monorepos grandes: un servidor maneja todos los lenguajes, enruta por extensión de archivo
• Migración de código: refactorice entre repositorios con seguimiento completo de referencias entre repositorios
• Pipelines de CI: valide contra el comportamiento real del servidor de lenguaje
• Stacks de lenguajes de nicho: Gleam, Elixir, Prisma, Zig, Clojure, Nix, Dart, Scala, MongoDB, todos verificados en CI

Soporte Multi-Lenguaje

31 lenguajes, verificados de extremo a extremo en CI contra servidores de lenguaje reales en cada ejecución de CI. Ninguna otra implementación MCP-LSP prueba un solo lenguaje en 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 la matriz de cobertura completa.

Herramientas

65 herramientas que cubren navegación, análisis, refactorización, edición de símbolos, exploración compuesta, edición segura, ejecución especulativa y ciclo de vida de sesión. Todas verificadas en CI.

Consulte docs/reference/tools.md para la referencia completa con parámetros y ejemplos.

Lectura adicional

Documentación

• Referencia de herramientas: referencia completa de herramientas con parámetros y ejemplos
• Referencia de habilidades: referencia de habilidades, flujos de trabajo, casos de uso y composición
• Soporte de lenguajes: matriz de cobertura de lenguajes
• Arquitectura: diseño del sistema e internals
• Ejecución especulativa: flujos de trabajo de simular-antes-de-aplicar
• Conformidad LSP: cobertura de especificación LSP 3.17
• Docker: etiquetas de Docker, compose y caché de volúmenes

Contribuyendo

• Notas de CI: peculiaridades de CI y detalles del arnés de pruebas
• Distribución: canales de instalación y pipeline de lanzamiento

Desarrollo

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

Los paquetes pkg/lsp, pkg/session y pkg/types exponen una API Go estable para usar el cliente LSP de agent-lsp directamente sin ejecutar el 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 la API completa de paquetes.

Licencia

MIT