agent-lsp

agent-lsp makes code operations reliable for AI agents.

It is a stateful runtime over real language servers, not a bridge. It keeps the language server's semantic index warm and adds a skill layer that turns multi-step code operations into single, correct workflows.

Most MCP-LSP tools fail in practice:

• Stateless bridges — no session, no context, no cross-file awareness
• Raw tools — agents skip steps or use them incorrectly

The tools exist. The workflow doesn't reliably happen.

agent-lsp fixes both. The persistent session indexes your workspace once and keeps it warm. The skill layer encodes correct tool sequences so workflows actually happen.

Example: call /lsp-rename and it will validate the rename, preview all affected files, show diagnostic impact, and apply atomically. One command. No missed steps.

50 tools. 49 CI-verified end-to-end. 30 languages. Built to LSP 3.17 spec.

Work across all your projects in one AI session. Point your AI assistant at your ~/code/ directory. One agent-lsp process automatically routes .go files to gopls, .ts files to typescript-language-server, .py to pyright; no reconfiguration when you switch projects.

Persistent session, warm index. Unlike per-request bridges, agent-lsp maintains a live language server session. start_lsp indexes the workspace once; every subsequent call hits the warm index. get_references returns all 12 call sites without loading files into context. get_diagnostics returns only the errors. get_info_on_location returns the type signature at one position without loading the module. The language server's index stays fresh automatically: agent-lsp watches the workspace using kernel-level filesystem events (inotify/kqueue/FSEvents) and forwards changes to keep the session synchronized. High-churn directories (.git/, node_modules/, etc.) are excluded; rapid edits are debounced at 150ms. No did_change_watched_files calls required.

Fuzzy position fallback. When an AI assistant gets a line/column slightly wrong, go_to_definition, get_references, and rename_symbol fall back to workspace symbol search by hover name and retry, returning results instead of silently returning empty.

Semantic token classification. get_semantic_tokens classifies every token in a range as function, parameter, variable, type, keyword, etc.; the same data an IDE uses to colorize code. No other MCP-LSP server exposes this.

Skills

The skill layer is the behavioral reliability layer. Raw tools get ignored; skills get used. Each skill encodes the correct tool sequence for a workflow; the agent reads the skill, follows the steps, and uses the tools in the right order without per-prompt orchestration instructions. This is the difference between tools that are available and workflows that actually happen.

Fourteen skills ship with agent-lsp:

Skills work with any MCP client that supports tool use, not just Claude Code.

cd skills && ./install.sh

See docs/tools.md for full parameter details.

Docker

Pre-built images on GitHub Container Registry for all major languages:

# 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

# Multi-language (runtime install)
docker run --rm -i -v /your/project:/workspace \
  -e LSP_SERVERS=gopls,typescript-language-server \
  ghcr.io/blackwell-systems/agent-lsp:latest \
  go:gopls typescript:typescript-language-server,--stdio

See DOCKER.md for full tier documentation, per-language tags, docker-compose setup, and volume caching.

Installation

Linux / macOS — no Go required:

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

Homebrew:

brew install blackwell-systems/tap/agent-lsp

Go install:

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

To use agent-lsp as a library in your Go program (without running the MCP server), import the pkg/ packages directly — see Library Usage below.

If agent-lsp isn't found after install, add Go's bin directory to your PATH:

export PATH="$PATH:$(go env GOPATH)/bin"   # add to ~/.zshrc or ~/.bashrc to persist

Quick setup with agent-lsp init

After installing, run the setup wizard to auto-detect installed language servers and write the correct MCP config for your AI tool:

agent-lsp init

The wizard:

1. Detects language servers installed on your PATH
2. Asks which servers to include
3. Asks which AI tool to configure (Claude Code, Claude Desktop, Cursor, Cline/VS Code, Windsurf, Gemini CLI, or custom path)
4. Writes the MCP server config to the correct location and shows you what was written

For CI or scripted use (no prompts):

agent-lsp init --non-interactive

Detects all available servers and writes .mcp.json in the current directory targeting Claude Code. Edit the file afterward if needed.

Setup

Step 1: Install language servers for your stack

agent-lsp runs on top of real language servers. Install the servers for your stack and agent-lsp handles the rest.

Step 2: Add to your AI config

Add to .mcp.json (project) or your AI tool's global MCP config. List only the languages you use:

{
  "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). Single language? Use "args": ["go", "gopls"]. Complex setup with many servers or per-server options? Use "args": ["--config", "/path/to/agent-lsp.json"].

Step 3: Start working

Once your AI session opens, call start_lsp with your project root to initialize:

start_lsp(root_dir="/your/project")

Then use any of the 50 tools. The session persists; no need to restart when switching files.

Why agent-lsp

Use Cases

• Multi-project AI sessions: point your AI assistant 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 (e.g., extracting a Go library used by 3 services)
• CI pipelines: validate against real language server behavior

Multi-Language Support

Every language below is integration-tested on every CI run with a real language server binary and a real fixture codebase. The test harness verifies Tier 1 (start_lsp, open_document, get_diagnostics, get_info_on_location) and Tier 2 (27 tools including navigation, analysis, refactoring, workspace, and session lifecycle) for each language. No other MCP-LSP implementation has an equivalent test matrix; competitors list supported languages in config examples but do not run integration tests against them.

Tier 2 results per language from the latest CI run:

Java Tier 2 is skipped when jdtls does not finish indexing within the CI timeout (a known jdtls cold-start characteristic, not a tool bug). Scala (metals) runs in a separate CI job with continue-on-error: true and a 30-minute timeout; metals requires sbt compilation on first start and results are informational. Swift (sourcekit-lsp) runs on a macos-latest runner since sourcekit-lsp ships with Xcode. Prisma runs with continue-on-error: true; the language server works standalone after prisma generate initializes the client. Completions and workspace symbol search are not supported by this server. SQL (sqls) requires a live PostgreSQL service container; the CI job provisions postgres:16 automatically. type_hierarchy is tested on Java (jdtls) and TypeScript (typescript-language-server); TypeScript skips when the server does not return a hierarchy item at the configured position. Clojure (clojure-lsp), Nix (nil), Dart (dart language-server), and MongoDB (mongodb-language-server) CI-verified as of the ci-coverage-expansion IMPL. Nix runs with continue-on-error: true (Nix installer is slow in CI; nil installs via nix profile). MongoDB language server is extracted from the mongodb-js/vscode VS Code extension VSIX at dist/languageServer.js; the CI job has continue-on-error: true since the extracted server may behave differently outside VS Code extension host context. MongoDB requires a live mongo:7 service container; the CI job provisions it automatically.

Tools

All tools require start_lsp to be called first.

CI coverage: The following tools are end-to-end integration-tested against real language servers on every CI run across all 30 languages (34 tools in the multi-language harness; 50/50 total across all test suites):

• Tier 1 (4 tools, all 30 languages): start_lsp, open_document, get_diagnostics, get_info_on_location
• Tier 2 (34 tools): get_document_symbols, go_to_definition, get_references, get_completions, get_workspace_symbols, format_document, go_to_declaration, type_hierarchy, get_info_on_location, call_hierarchy, get_semantic_tokens, get_signature_help, get_document_highlights, get_inlay_hints, get_code_actions, prepare_rename, rename_symbol, get_server_capabilities, add_workspace_folder, go_to_type_definition, go_to_implementation, format_range, apply_edit, detect_lsp_servers, close_document, did_change_watched_files, run_build, run_tests, get_tests_for_file, get_symbol_source, go_to_symbol, restart_lsp_server, set_log_level, execute_command

Speculative session tools (create_simulation_session, simulate_edit, simulate_edit_atomic, simulate_chain, evaluate_session, commit_session, discard_session, destroy_session) are covered by TestSpeculativeSessions in test/speculative_test.go. All 50 tools are covered across the three test suites. get_change_impact and get_cross_repo_references are covered by TestGetChangeImpact and TestGetCrossRepoReferences in test/multi_lang_test.go. get_symbol_documentation is covered by TestGetSymbolDocumentation in test/documentation_test.go.

Session

Analysis

Navigation

Refactoring

Utilities

Workspace

Speculative Execution

Safe what-if analysis: simulate edits in-memory, evaluate diagnostic changes (errors introduced/resolved), then commit or discard atomically. No disk writes until you call commit_session.

See docs/speculative-execution.md for session lifecycle examples and refactor/rename preview workflows.

Recommended agent workflow:

start_lsp(root_dir="/your/project")
open_document(file_path=..., language_id=...)
get_diagnostics()                          # whole project, no file_path
get_info_on_location(...) / get_references(...)
close_document(...)

Keeping the index fresh:

agent-lsp watches the workspace root for file changes and automatically notifies the language server; no did_change_watched_files calls required after edits. The watcher skips high-churn directories (.git/, node_modules/, target/, etc.) and debounces rapid edits at 150ms.

did_change_watched_files is still available for cases where files are changed by an external process that the watcher may not see immediately, or for explicit control over change notifications.

Rename workflow (prepare_rename → rename_symbol → apply_edit):

prepare_rename(file_path=..., line=..., column=...)        # confirm rename is valid at this position
rename_symbol(file_path=..., line=..., column=..., new_name="newName")  # returns WorkspaceEdit
apply_edit(edit=<WorkspaceEdit>)                           # writes all changed files to disk
# auto-watch notifies the server automatically — no did_change_watched_files needed

Language IDs: typescript, typescriptreact, javascript, javascriptreact, python, go, rust, java, kotlin, scala, swift, lua, zig, terraform, c, cpp, csharp, php, ruby, css, html, yaml, json, dockerfile, gleam, elixir, prisma

Resources

Diagnostic resources support real-time subscriptions; the server sends notifications/resources/updated when diagnostics change for a subscribed file.

Subscribing to real-time diagnostics:

{ "method": "resources/subscribe", "params": { "uri": "lsp-diagnostics:///path/to/file.go" } }

The server sends notifications/resources/updated each time the language server publishes new diagnostics for that file. Read the resource after each notification to get the current diagnostic list:

{ "method": "resources/read", "params": { "uri": "lsp-diagnostics:///path/to/file.go" } }

LSP 3.17 Conformance

agent-lsp is implemented directly against the LSP 3.17 specification and validated through integration testing against real language servers. Coverage includes:

• Full lifecycle (initialize → initialized → shutdown) with graceful SIGINT/SIGTERM handling
• Progress protocol: workspace-ready detection waits for all $/progress tokens to complete before sending references
• Server-initiated requests (workspace/configuration, window/workDoneProgress/create, dynamic registration): all correctly responded to, unblocking servers that gate workspace loading on these responses
• Correct JSON-RPC framing, error code handling, and response shape normalization across hover, completion, code actions, and diagnostics

See docs/lsp-conformance.md for the full method coverage matrix and spec section references.

See docs/tools.md for the full tool reference with example inputs and outputs.

See docs/architecture.md for the Go package structure, WithDocument pattern, URI handling, and resource subscription internals.

Extensions

The 50 core tools cover everything LSP exposes. Extensions add a second layer — language-specific tools that go beyond what the protocol provides.

Where the core tools stop at what the language server can answer, an extension can run arbitrary logic for that language. Examples of what extensions enable that core tools cannot:

Extensions are registered at compile time — an extension for go only activates when go:gopls is in the server config. All extension tools are namespaced by language ID (e.g. go.mod_graph) so they never conflict with core tools.

No extensions ship with agent-lsp today. The infrastructure exists and is ready to use. To build one, create extensions/<language-id>/ implementing any subset of the extension interface and call extensions.RegisterFactory in an init() function. See docs/architecture.md for the interface definition.

Development

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

Library Usage

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

Import the LSP client

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

client := lsp.NewLSPClient("gopls", []string{})
if err := client.Initialize(ctx, "/path/to/workspace"); err != nil {
    log.Fatal(err)
}
defer client.Shutdown(ctx)

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

Import types

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

var pos types.Position = types.Position{Line: 0, Character: 0}

Speculative editing (simulate-before-apply)

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

mgr := session.NewSessionManager(client) // client is a *lsp.LSPClient
id, _ := mgr.CreateSession(ctx, "/workspace", "go")
mgr.ApplyEdit(ctx, id, fileURI, editRange, newText)
result, _ := mgr.Evaluate(ctx, id, "file", 3000)
if result.NetDelta == 0 {
    mgr.Commit(ctx, id, "", true)
} else {
    mgr.Discard(ctx, id)
}

All pkg/ types are aliases of the internal implementation types and are fully interchangeable with them.

License

MIT