agent-lsp

by blackwell-systems

2.1k downloads Not rated yet

GitHub Website

Developer Tools

About

A stateful LSP runtime for AI agents: warm language server sessions with 50+ tools for go-to-definition, find-references, diagnostics, rename, and more across 30+ languages.

Explore

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name agent-lsp

Command (node, npx, python, etc.)

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "agent-lsp": {
            "server": {
                "command": "npx",
                "args": [
                    "-y",
                    "@blackwell-systems/agent-lsp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "agent-lsp": {
            "server": {
                "command": "npx",
                "args": [
                    "-y",
                    "@blackwell-systems/agent-lsp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "agent-lsp": {
            "server": {
                "command": "npx",
                "args": [
                    "-y",
                    "@blackwell-systems/agent-lsp"
                ]
            }
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "agent-lsp": {
            "server": {
                "command": "npx",
                "args": [
                    "-y",
                    "@blackwell-systems/agent-lsp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "agent-lsp": {
            "server": {
                "command": "npx",
                "args": [
                    "-y",
                    "@blackwell-systems/agent-lsp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "agent-lsp": {
            "server": {
                "command": "npx",
                "args": [
                    "-y",
                    "@blackwell-systems/agent-lsp"
                ]
            }
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "agent-lsp": {
            "server": {
                "command": "npx",
                "args": [
                    "-y",
                    "@blackwell-systems/agent-lsp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "agent-lsp": {
            "server": {
                "command": "npx",
                "args": [
                    "-y",
                    "@blackwell-systems/agent-lsp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "agent-lsp": {
            "server": {
                "command": "npx",
                "args": [
                    "-y",
                    "@blackwell-systems/agent-lsp"
                ]
            }
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "agent-lsp": {
            "server": {
                "command": "npx",
                "args": [
                    "-y",
                    "@blackwell-systems/agent-lsp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "agent-lsp": {
            "server": {
                "command": "npx",
                "args": [
                    "-y",
                    "@blackwell-systems/agent-lsp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "agent-lsp": {
            "server": {
                "command": "npx",
                "args": [
                    "-y",
                    "@blackwell-systems/agent-lsp"
                ]
            }
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "agent-lsp": {
            "server": {
                "command": "npx",
                "args": [
                    "-y",
                    "@blackwell-systems/agent-lsp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "agent-lsp": {
            "server": {
                "command": "npx",
                "args": [
                    "-y",
                    "@blackwell-systems/agent-lsp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "agent-lsp": {
            "server": {
                "command": "npx",
                "args": [
                    "-y",
                    "@blackwell-systems/agent-lsp"
                ]
            }
        }
    }
}

For Claude Code, addmcp__lsp__to your permissions allow list so all 65 tools are available without per-tool approval prompts:

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

Without this, Claude Code will prompt for permission on each tool call. Other MCP clients handle permissions differently; check your client's documentation.

Skills are multi-tool workflows that encode reliable procedures: blast-radius check before edit, speculative preview before write, test run after change. Seedocs/guide/skills.mdfor the full list.

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 65 tools. The session stays warm; no restart needed when switching files.

- 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

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/reference/language-support.mdfor the full coverage matrix.

65 tools covering navigation, analysis, refactoring, symbol editing, composite exploration, safe editing, speculative execution, and session lifecycle. All CI-verified.

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

- 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

- CI notes: CI quirks and test harness details
- Distribution: install channels and release pipeline

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)

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "agent-lsp": {
            "server": {
                "command": "npx",
                "args": [
                    "-y",
                    "@blackwell-systems/agent-lsp"
                ]
            }
        }
    }
}

McpServers

{
    "server": {
        "command": "npx",
        "args": [
            "-y",
            "@blackwell-systems/agent-lsp"
        ]
    }
}

Transport

"stdio"

Package

"@blackwell-systems/agent-lsp"

Registry

"npm"

Code intelligence infrastructure for AI agents.65 tools, 30 CI-verified languages, 24 agent workflows. Single Go binary.

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

agent-lsp is anMCP serverthat orchestrates existing LSP servers (gopls, rust-analyzer, jdtls, etc.) into agent-native workflows.

Not an LSP server— it's an orchestration layer that manages language servers and exposes batch operations, speculative editing, and multi-step workflows via MCP tools.

- Language servers(gopls, rust-analyzer, etc.) → provide code intelligence
- agent-lsp(MCP server) → orchestrates workflows, maintains warm runtime
- AI agents→ consume via MCP protocol

Persistent warm runtime
Language servers stay indexed across agent sessions. First session: indexes workspace (~10s for typical projects). Subsequent sessions: instant. No cold-start penalty on each request.

Batch operations
blast_radius→ one call returns all exports + all callers (test vs non-test partitioned). Without orchestration: 20+ sequential LSP calls.

Speculative editing
simulate_edit→ preview changes in memory, check diagnostic delta, apply or discard. Test edits before touching disk.

Workflow orchestration
24 skills that chain LSP operations into complete pipelines:

- /lsp-refactor→ impact analysis → preview → apply → verify build → run tests
- /lsp-safe-edit→ preview → diagnostic diff → apply if safe
- /lsp-verify→ LSP diagnostics → build → test suite

Multi-language, single session
One agent-lsp process routes.goto gopls,.tsto tsserver,.pyto pyright. No reconfiguration between projects. Session persists across files and repositories.

[!TIP]Token-optimized output:Tool responses encoded inGCFinstead of JSON. 30-84% fewer tokens depending on tool (up to 92.7% with session dedup).100% LLM comprehension on every frontier model, 91.2% on complex code graphs where JSON averages 54.1%. See belowfor measured savings per tool.

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.

- Building agentic code generation systems
- Automating refactors across large codebases
- CI tooling that needs programmatic code intelligence
- Any workflow where sequential LSP calls are too slow or complex

We asked AI agents to evaluate agent-lsp across 10 coding tasks (find callers, rename safely, preview edits, detect dead code) and write an honest assessment. Four different models, four independent evaluations, same conclusion:

Claude (Opus 4.6):"I would recommend agent-lsp for any workflow involving refactoring, impact analysis, or safe editing. The standout tools areblast_radius(blast radius in one call, with test/non-test partitioning that would take 5-10 grep commands to replicate),go_to_implementation(type-checked interface satisfaction that grep simply cannot do), and the simulation session workflow (speculative type-checking without touching disk, which has no grep/read equivalent at all)."

Cursor (auto):"I would recommend agent-lsp for heavy refactors and code navigation because the rename, references, implementations, call hierarchy, and simulation tools remove a lot of brittle grep/manual-edit work and make changes safer."

GPT-5.5 (via Codex):"I would recommend agent-lsp for symbol-aware work: references, implementations, rename previews, diagnostics, and large-file structure are materially faster and less error-prone than grep/read loops."

Gemini 2.5 Pro (via Gemini CLI):"I would highly recommend agent-lsp because it provides a level of semantic awareness that standard text-searching tools simply cannot match. The ability to perform high-confidence renames, find interface implementations, and preview the diagnostic impact of edits without writing to disk significantly reduces the risk of introducing regressions."

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 runs30 real language serversagainst 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.

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

preview_editpreviews the diagnostic impact of any edit. You see exactly what breaks before the file is touched.simulate_chainevaluates 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. See docs/guide/speculative-execution.mdfor the full workflow.

Structured LSP responses use5-34x fewer tokensthan grep/read on the same tasks. On HashiCorp Consul (319K lines), a blast-radius analysis uses 17.7MB via grep vs 841KB via LSP, reducing 5,534 tool calls to 119. Savings scale with codebase size. See docs/guide/token-savings.mdfor the full experiment across five codebases.

Tool responses are encoded in GCF (Graph Compact Format)instead of JSON. GCF eliminates field-name repetition, identifier repetition, and per-record structural overhead.

Grouped/nested responses (callers under a symbol, diagnostics with related info) tabularize too, for ~14% over JSON on that shape (details).

GCF is enabled by default. To revert to JSON:

Benchmark:go run scripts/gcf-benchmark.go. See docs/guide/gcf-integration.mdfor architecture details.

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

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 raw LSP tools require 20+ sequential calls and complex orchestration logic.

agent-lsp solves this by encoding correct multi-step operations into single calls and skills.blast_radiusdoes what would take an agent 20+ calls in one./lsp-refactorchains impact → preview → apply → verify → test without per-prompt orchestration.

Python and TypeScript projects need minutes of background indexing beforefind_referencesworks. agent-lsp automatically spawns a persistent daemon broker that survives between sessions, so the workspace stays indexed. First session: daemon starts and indexes (~10s for FastAPI). Subsequent sessions: instant connection to the warm daemon. Auto-exits after 30 minutes of inactivity. Go, Rust, and other fast-indexing languages bypass this entirely (zero overhead).

Skills tell agents the correct order of operations. Phase enforcement makes the runtimeblockviolations instead of trusting the agent to follow instructions.

…

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Explore

Setting up with Highlight

Claude Desktop / Cursor

McpServers

Transport

Package

Registry

More like this

Sentry

Github

Git

GitLab