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.

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

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

AI Tool	Transport	Config
Claude Code	stdio	mcpServers in .mcp.json
Continue	stdio	mcpServers in config.json
Cline	stdio	mcpServers in settings
Cursor	stdio	mcpServers in settings
Any MCP client	HTTP+SSE	--http --port 8080 with Bearer token auth

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

Skill	Purpose
/lsp-impact	Blast-radius analysis before touching a symbol or file
/lsp-implement	Find all concrete implementations of an interface
/lsp-dead-code	Detect zero-reference exports before cleanup

Editing safely

Skill	Purpose
/lsp-safe-edit	Speculative preview before disk write; before/after diagnostic diff; surfaces code actions on errors
/lsp-simulate	Test changes in-memory without touching the file
/lsp-edit-symbol	Edit a named symbol without knowing its file or position
/lsp-edit-export	Safe editing of exported symbols, finds all callers first
/lsp-rename	prepare_rename safety gate, preview all sites, confirm, apply atomically

Understanding unfamiliar code

Skill	Purpose
/lsp-explore	"Tell me about this symbol": hover + implementations + call hierarchy + references in one pass
/lsp-understand	Deep-dive Code Map for a symbol or file: type info, call hierarchy, references, source
/lsp-docs	Three-tier documentation: hover → offline toolchain → source
/lsp-cross-repo	Find all usages of a library symbol across consumer repos
/lsp-local-symbols	File-scoped symbol list, usage search, and type info

After editing

Skill	Purpose
/lsp-verify	Diagnostics + build + tests after every edit
/lsp-fix-all	Apply quick-fix code actions for all diagnostics in a file
/lsp-test-correlation	Find and run only tests that cover an edited file
/lsp-format-code	Format a file or selection via the language server formatter

Generating code

Skill	Purpose
/lsp-generate	Trigger server-side code generation (interface stubs, test skeletons, mocks)
/lsp-extract-function	Extract a code block into a named function via code actions

Full workflow

Skill	Purpose
/lsp-refactor	End-to-end refactor: blast-radius → preview → apply → verify → test

cd skills && ./install.sh

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.

Installation

macOS / Linux

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

# Homebrew
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@latest

Quick start

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.

Setup

Step 1: Install language servers

Install the servers for your stack. Common ones:

Language	Server	Install
TypeScript / JavaScript	typescript-language-server	npm i -g typescript-language-server typescript
Python	pyright-langserver	npm i -g pyright
Go	gopls	go install golang.org/x/tools/gopls@latest
Rust	rust-analyzer	rustup component add rust-analyzer
C / C++	clangd	apt install clangd / brew install llvm
Ruby	solargraph	gem install solargraph

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

Step 2: Add to your AI config

{
  "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 3: Start working

start_lsp(root_dir="/your/project")

Then use any of the 50 tools. The session stays warm; no restart needed when switching files.

Why agent-lsp

	agent-lsp	next best competitor
Tools	50	39
Languages (CI-verified)	30 (end-to-end integration tests)	0 (config-listed, untested)
Agent workflows (skills)	20	0 (in MCP space)
Speculative execution	8 tools (simulate before writing)	none
Connection model	persistent (warm index)	per-request or cold-start
Call hierarchy	✓ (single tool, direction param)	split across 3 tools or absent
Type hierarchy	✓ (CI-verified)	untested or absent
Cross-repo references	✓ (multi-root workspace)	single-workspace only
Auto-watch	✓ (always-on, debounced)	manual notify required
HTTP+SSE transport	✓ (bearer token auth, non-root Docker)	experimental or absent
Distribution	single Go binary (8 channels)	Node.js/Bun runtime required

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

• docs/skills.md - skill reference: workflows, use cases, and composition
• docs/tools.md - full tool reference
• docs/language-support.md - language coverage matrix
• docs/speculative-execution.md - simulate-before-apply workflows
• docs/lsp-conformance.md - LSP 3.17 spec coverage
• docs/architecture.md - Go package structure and internals
• docs/ci-notes.md - CI quirks and test harness details
• docs/distribution.md - install channels and release pipeline
• DOCKER.md - Docker tags, compose, and volume caching

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