agent-lsp

The most complete MCP server for language intelligence. 50 tools, 30 CI-verified languages, 20 agent workflows. Single Go binary.

AI agents make incorrect code changes because they can't see the full picture: who calls this function, what breaks if I rename it, does the build still pass. Language servers have the answers, but existing MCP bridges either cold-start on every request or expose raw tools that agents use incorrectly.

agent-lsp is a stateful runtime over real language servers. It indexes your workspace once, keeps the index warm, and adds a skill layer that encodes correct multi-step operations so they actually complete.

How the pieces fit together: LSP (Language Server Protocol) is how editors get code intelligence — completions, diagnostics, go-to-definition. MCP (Model Context Protocol) is the standard way AI tools like Claude Code discover and call external tools. agent-lsp bridges the two: language server intelligence, accessible to AI agents.

How it works

One agent-lsp process manages your language servers. Point your AI at ~/code/. It routes .go to gopls, .ts to typescript-language-server, .py to pyright. No reconfiguration when you switch projects. The session stays warm across files, packages, and repositories.

Tested, not assumed

Every other MCP-LSP implementation lists supported languages in a config file. None of them run the actual language server in CI to verify it works.

agent-lsp CI runs 30 real language servers against real fixture codebases on every 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, and more. When we say "works with gopls," that's a verified, automated claim, not a hope.

Speculative execution

Simulate changes in memory before writing to disk. No other MCP-LSP implementation has this.

simulate_edit_atomic previews the diagnostic impact of any edit. You see exactly what breaks before the file is touched. simulate_chain evaluates a sequence of dependent edits (rename a function, update all callers, change the return type) and reports which step first introduces an error.

8 speculative execution tools: create_simulation_session, simulate_edit, simulate_chain, evaluate_session, commit_session, discard_session, destroy_session, simulate_edit_atomic.

See docs/speculative-execution.md for the full workflow.

Works with

Skills

Raw tools get ignored. Skills get used. Each skill encodes the correct tool sequence so workflows actually happen without per-prompt orchestration instructions.

See docs/skills.md for full descriptions and usage guidance.

Before you change anything

Editing safely

Understanding unfamiliar code

After editing

Generating code

Full workflow

Docker

Stdio mode (MCP client spawns the container directly):

# 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

HTTP mode (persistent service, remote clients connect over 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

Images run as a non-root user (uid 65532) by default. Set AGENT_LSP_TOKEN via environment variable, never --token on the command line. Images are also mirrored to Docker Hub (blackwellsystems/agent-lsp). See DOCKER.md for the full tag list, HTTP mode setup, and security hardening options.

Setup

Step 1: Install agent-lsp

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

macOS / Linux

brew install blackwell-systems/tap/agent-lsp

Windows

# 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

All platforms

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

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

Step 2: Install language servers

Install the servers for your stack. Common ones:

Full list of 30 supported languages in docs/language-support.md.

Step 3: Verify setup

agent-lsp doctor

Probes each configured language server and reports capabilities. Fix any failures before proceeding. See language support for install commands and server-specific notes.

Step 4: Configure your AI tool

agent-lsp init

Detects language servers on your PATH, asks which AI tool you use, and writes the correct MCP config. For CI or scripted use: agent-lsp init --non-interactive.

The generated config looks like:

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

Each arg is language:server-binary (comma-separate server args).

Step 5: Install 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 are prompt files copied into your AI tool's configuration — --copy means the clone can be safely deleted afterward.

Skills are multi-tool workflows that encode reliable procedures — blast-radius check before edit, speculative preview before write, test run after change. See docs/skills.md for the full list.

Step 6: Start working

Your AI agent calls tools automatically. The first call initializes the workspace:

start_lsp(root_dir="/your/project")

This is what the agent does, not something you type. Then use any of the 50 tools. The session stays warm; no restart needed when switching files.

What's unique about agent-lsp

Use Cases

• Multi-project sessions: point your AI at ~/code/, work across any project without reconfiguring
• Polyglot development: Go backend + TypeScript frontend + Python scripts in one session
• Large monorepos: one server handles all languages, routes by file extension
• Code migration: refactor across repos with full cross-repo reference tracking
• CI pipelines: validate against real language server behavior
• Niche language stacks: Gleam, Elixir, Prisma, Zig, Clojure, Nix, Dart, Scala, MongoDB, all CI-verified

Multi-Language Support

30 languages, CI-verified end-to-end against real language servers on every CI run. No other MCP-LSP implementation tests a single language in 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.

See docs/language-support.md for the full coverage matrix.

Tools

50 tools covering navigation, analysis, refactoring, speculative execution, and session lifecycle. All CI-verified.

See docs/tools.md for the full reference with parameters and examples.

Further reading

Documentation

• Tools reference — full tool reference with parameters and examples
• Skills reference — skill reference: workflows, use cases, and composition
• Language support — language coverage matrix
• Architecture — system design and internals
• Speculative execution — simulate-before-apply workflows
• LSP conformance — LSP 3.17 spec coverage
• Docker — Docker tags, compose, and volume caching

Contributing

• CI notes — CI quirks and test harness details
• Distribution — install channels and release pipeline

Development

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)

Library Usage

The pkg/lsp, pkg/session, and pkg/types packages expose a stable Go API for using agent-lsp's LSP client directly without running the MCP server.

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

See docs/architecture.md for the full package API.

License

MIT