一个将语言服务器协议（LSP）能力桥接到 MCP 的有状态运行时，让 AI 编程 Agent 获得类型感知导航、推测执行和安全编辑能力，支持 30 种语言和 61 个工具。
**最完整的语言智能 MCP 服务器。** 61 个工具，30 种经 CI 验证的语言，23 个 Agent 工作流。单个 Go 二进制文件。
AI Agent 经常做出错误的代码更改，因为它们无法看清全貌：谁调用了这个函数，如果重命名会导致什么破坏，构建是否仍能通过。语言服务器有这些答案，但现有的 MCP 桥接器要么在每次请求时都冷启动，要么暴露出被 Agent 错误使用的原始工具。
agent-lsp 是一个构建在真实语言服务器之上的**有状态运行时**。它只对你的工作区进行一次索引，保持索引热度，并增加了一个**技能层**，该层编码了正确的多步操作，从而确保任务能真正完成。
### Agent 们的评价
我们让 AI Agent 在 10 个编码任务（查找调用者、安全重命名、预览编辑、检测死代码）中对 agent-lsp 进行评估，并写下诚实的评价。四个不同的模型，四份独立的评估，同一个结论：
**各部分如何协同工作：** [LSP](https://microsoft.github.io/language-server-protocol/)（Language Server Protocol，语言服务器协议）是编辑器获取代码智能（补全、诊断、转到定义）的方式。[MCP](https://modelcontextprotocol.io/)（Model Context Protocol，模型上下文协议）是像 Claude Code 这样的 AI 工具发现和调用外部工具的标准方式。agent-lsp 将两者桥接起来：将语言服务器的智能提供给 AI Agent 使用。
### 工作原理
一个 agent-lsp 进程管理着你的语言服务器。将你的 AI 指向 `~/code/`。它会将 `.go` 路由到 gopls，将 `.ts` 路由到 typescript-language-server，将 `.py` 路由到 pyright。切换项目时无需重新配置。会话在跨文件、跨包和跨代码库的过程中始终保持活跃状态。
### 经过测试，而非想当然
所有其他的 MCP-LSP 实现都只在配置文件中列出支持的语言。它们都没有在 CI 中运行真正的语言服务器来验证其是否有效。
agent-lsp 的 CI 在每次推送时都会针对真实的固件代码库运行 **30 个真实的语言服务器**：Go, Python, TypeScript, Rust, Java, C, C++, C#, Ruby, PHP, Kotlin, Swift, Scala, Zig, Lua, Elixir, Gleam, Clojure, Dart, Terraform, Nix, Prisma, SQL, MongoDB 等等。当我们在谈论“支持 gopls”时，那是一个经过验证的、自动化的断言，而不是一种期望。
### 推测执行
在写入磁盘之前，先在内存中模拟更改。没有其他的 MCP-LSP 实现具备此功能。
`preview_edit` 可预览任何编辑带来的诊断影响。你可以确切地看到在文件被触碰之前哪里会出错。`simulate_chain` 会评估一系列相互依赖的编辑（重命名函数、更新所有调用者、更改返回类型），并报告哪一步最先引入错误。
8 个推测执行工具。请参阅 [docs/speculative-execution.md](./docs/speculative-execution.md) 了解完整的工作流。
### 节省 Token
在执行相同任务时，结构化的 LSP 响应比 grep/read 使用的 Token **少 5-34 倍**。在 HashiCorp Consul 项目（31.9 万行代码）中，一次爆炸半径分析使用 grep 需要 17.7MB，而使用 LSP 仅需 841KB，将 5,534 次工具调用减少到了 119 次。节省的规模随代码库的大小而增加。请参阅 [docs/token-savings.md](./docs/token-savings.md) 查看横跨五个代码库的完整实验。
### 持久化守护进程模式
Python 和 TypeScript 项目需要几分钟的后台索引，然后 `find_references` 才能工作。agent-lsp 会自动生成一个在会话之间存活的持久化守护进程代理，从而使工作区保持索引状态。首次会话：守护进程启动并建立索引（FastAPI 约需 10 秒）。后续会话：即时连接到热载的守护进程。在闲置 30 分钟后自动退出。Go、Rust 和其他索引速度快的语言则完全绕过此过程（零开销）。
### 阶段强制执行
技能告诉 Agent 正确的操作顺序。阶段强制执行使得运行时能够*阻止*违规行为，而不是寄望于 Agent 遵守指令。
当 Agent 激活一个技能时，每一次工具调用都会根据当前阶段的权限进行检查。在爆炸半径分析期间调用 `apply_edit` 不会被静默放行；它会返回一个带有具体恢复指导的错误（“请先完成 blast_radius 阶段，允许使用的工具：[get_change_impact, find_references]”）。随着 Agent 调用后续阶段的工具，阶段会自动推进。
没有其他 MCP 工具提供者会在运行时强制执行工作流顺序。请参阅 [docs/phase-enforcement.md](./docs/phase-enforcement.md)。
### 兼容工具
| AI 工具 | 传输方式 | 配置 |
|---------|-----------|--------|
| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | stdio | `.mcp.json` 中的 `mcpServers` |
| [Continue](https://continue.dev) | stdio | `config.json` 中的 `mcpServers` |
| [Cline](https://github.com/cline/cline) | stdio | 设置中的 `mcpServers` |
| [Cursor](https://cursor.com) | stdio | 设置中的 `mcpServers` |
| 任何 MCP 客户端 | HTTP+SSE | 使用 Bearer token 认证的 `--http --port 8080` |
## 技能
原始工具往往被忽视。技能才会被使用。每个技能都编码了正确的工具序列，因此工作流无需每次都在提示词中编排指令即可实际发生。技能可以通过 [AgentSkills](https://github.com/anthropics/agent-skills) 斜杠命令使用，也可以通过任何 MCP 客户端的 `prompts/list` / `prompts/get` 作为 MCP 提示词使用。
请参阅 [docs/skills.md](./docs/skills.md) 获取完整的描述和使用指南。
**在你更改任何内容之前**
| 技能 | 目的 |
|-------|---------|
| `/lsp-impact` | 在触碰某个符号或文件之前进行爆炸半径分析 |
| `/lsp-implement` | 查找接口的所有具体实现 |
| `/lsp-dead-code` | 在清理前检测零引用的导出 |
**安全编辑**
| 技能 | 目的 |
|-------|---------|
| `/lsp-safe-edit` | 磁盘写入前的推测预览；修改前后的诊断差异；出错时浮现代码操作 |
| `/lsp-simulate` | 在内存中测试更改而不触碰文件 |
| `/lsp-edit-symbol` | 在不知道文件或位置的情况下编辑命名符号 |
| `/lsp-edit-export` | 安全编辑导出的符号，首先查找所有调用者 |
| `/lsp-rename` | `prepare_rename` 安全门，预览所有位置，确认，并自动应用 |
**开始上手**
| 技能 | 目的 |
|-------|---------|
| `/lsp-onboard` | 首次会话的项目引导：检测语言，映射包，查找入口点和热点，检查诊断信息 |
**理解陌生代码**
| 技能 | 目的 |
|-------|---------|
| `/lsp-explore` | “告诉我关于这个符号的信息”：一次性获取悬停信息 + 实现 + 调用层次结构 + 引用 |
| `/lsp-understand` | 针对符号或文件的深度代码地图：类型信息、调用层次结构、引用、源码 |
| `/lsp-docs` | 三层文档：悬停 → 离线工具链 → 源码 |
| `/lsp-cross-repo` | 在消费者代码库中查找库符号的所有用法 |
| `/lsp-local-symbols` | 文件作用域内的符号列表、用法搜索和类型信息 |
**编辑之后**
| 技能 | 目的 |
|-------|---------|
| `/lsp-verify` | 每次编辑后执行诊断 + 构建 + 测试 |
| `/lsp-fix-all` | 为文件中的所有诊断应用快速修复代码操作 |
| `/lsp-test-correlation` | 仅查找并运行覆盖已编辑文件的测试 |
| `/lsp-format-code` | 通过语言服务器格式化程序格式化文件或选定内容 |
**生成代码**
| 技能 | 目的 |
|-------|---------|
| `/lsp-generate` | 触发服务器端的代码生成（接口存根、测试骨架、模拟对象） |
| `/lsp-extract-function` | 通过代码操作将代码块提取为命名函数 |
**完整工作流**
| 技能 | 目的 |
|-------|---------|
| `/lsp-refactor` | 端到端重构：爆炸半径 → 预览 → 应用 → 验证 → 测试 |
| `/lsp-inspect` | 完整的代码质量审计：死符号、测试覆盖率、错误处理、文档偏差 |
## Docker
**Stdio 模式**（MCP 客户端直接生成容器）：
```
# 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 模式**（持久化服务，远程客户端通过 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
```
镜像默认以非 root 用户 (uid 65532) 运行。请通过环境变量设置 `AGENT_LSP_TOKEN`，切勿在命令行上使用 `--token`。镜像也同步到了 Docker Hub (`blackwellsystems/agent-lsp`)。请参阅 [DOCKER.md](./DOCKER.md) 了解完整的标签列表、HTTP 模式设置和安全加固选项。
## 安装设置
### 步骤 1：安装 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 (无需管理员权限)
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
```
### 步骤 2：安装语言服务器
为你技术栈安装相应的服务器。以下是常见的几种：
| 语言 | 服务器 | 安装命令 |
|----------|--------|---------|
| 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` |
在 [docs/language-support.md](./docs/language-support.md) 中查看完整的 30 种支持语言列表。
### 步骤 3：验证安装
```
agent-lsp doctor
```
探测每个已配置的语言服务器并报告其能力。在继续之前请修复所有故障。请参阅[语言支持](./docs/language-support.md)获取安装命令和特定服务器的注意事项。
### 步骤 4：配置你的 AI 工具
```
agent-lsp init
```
检测你 PATH 上的语言服务器，询问你使用的 AI 工具，写入正确的 MCP 配置，并为你使用的 AI 提供商安装技能感知规则（Claude Code 的 CLAUDE.md，Cursor 的 `.cursor/rules/`，Cline 的 `.clinerules`，Windsurf 的 `.windsurfrules`，Gemini CLI 的 `GEMINI.md`）。对于 CI 或脚本化使用：`agent-lsp init --non-interactive`。
生成的配置如下所示：
```
{
"mcpServers": {
"lsp": {
"type": "stdio",
"command": "agent-lsp",
"args": [
"go:gopls",
"typescript:typescript-language-server,--stdio",
"python:pyright-langserver,--stdio"
]
}
}
}
```
每个参数均为 `language:server-binary`（用逗号分隔服务器参数）。
### 步骤 5：安装技能
```
git clone https://github.com/blackwell-systems/agent-lsp.git /tmp/agent-lsp-skills
cd /tmp/agent-lsp-skills/skills && ./install.sh --copy
```
技能是复制到你的 AI 工具配置中的提示文件。`--copy` 意味着之后可以安全地删除克隆的仓库。
技能也可以作为 **MCP 提示词**使用：任何 MCP 客户端都可以通过 `prompts/list` 发现它们，并通过 `prompts/get` 检索完整的工作流指令，无需手动安装。`install.sh` 路径适用于兼容 AgentSkills 的客户端（如 Claude Code 斜杠命令）。
### 步骤 6：允许工具权限 (Claude Code)
对于 Claude Code，请将 `mcp__lsp__*` 添加到你的权限允许列表中，以便所有 61 个工具都可以直接使用，而无需每次弹出工具批准提示：
```
// ~/.claude/settings.json
{
"permissions": {
"allow": ["mcp__lsp__*"]
}
}
```
如果不进行此设置，Claude Code 将在每次工具调用时提示请求权限。其他 MCP 客户端处理权限的方式有所不同；请查阅你所使用客户端的文档。
技能是编码了可靠流程的多工具工作流：编辑前的爆炸半径检查，写入前的推测预览，更改后的测试运行。请参阅 [docs/skills.md](./docs/skills.md) 获取完整列表。
### 步骤 7：开始工作
你的 AI Agent 会自动调用工具。第一次调用将初始化工作区：
```
start_lsp(root_dir="/your/project")
```
这是 Agent 自动执行的操作，而不是你需要的内容。然后即可使用 61 个工具中的任何一个。会话将保持活跃；切换文件时无需重启。
## agent-lsp 的独特之处
| 能力 | 详情 |
|------------|---------|
| 工具 | **61** 个 |
| 语言 (经 CI 验证) | **30** 种，每次推送都会进行端到端集成测试 |
| Agent 工作流 (技能) | **23** 种，命名的多步过程，可通过 MCP `prompts/list` 发现 |
| 推测执行 | **8** 个工具，在写入磁盘前模拟更改 |
| 阶段强制执行 | **4** 个技能，运行时阻止乱序的工具调用并提供恢复指导 |
| 连接模型 | **持久化**，跨文件和项目的热索引 |
| 调用层次结构 | **✓**，单一工具，方向参数 |
| 类型层次结构 | **✓**，经 CI 验证 |
| 跨代码库引用 | **✓**，多根工作区 |
| 自动监视 | **✓**，始终开启，防抖动的文件监视 |
| HTTP+SSE 传输 | **✓**，Bearer token 认证，非 root Docker |
| 分发方式 | **单个 Go 二进制文件**，10 个安装渠道 |
## 使用场景
- **多项目会话**：将你的 AI 指向 `~/code/`，无需重新配置即可跨任何项目工作
- **多语言开发**：在一个会话中处理 Go 后端 + TypeScript 前端 + Python 脚本
- **大型单体仓库**：一个服务器处理所有语言，按文件扩展名进行路由
- **代码迁移**：通过完整的跨代码库引用跟踪在仓库之间进行重构
- **CI 流水线**：根据真实的语言服务器行为进行验证
- **小众语言技术栈**：Gleam, Elixir, Prisma, Zig, Clojure, Nix, Dart, Scala, MongoDB，全部经过 CI 验证
## 多语言支持
30 种语言，在每次 CI 运行时都会针对真实的语言服务器进行端到端验证。没有其他任何 MCP-LSP 实现会在 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。
请参阅 [docs/language-support.md](./docs/language-support.md) 获取完整的覆盖范围矩阵。
## 工具
61 个工具，涵盖导航、分析、重构、符号编辑、推测执行和会话生命周期。全部经过 CI 验证。
请参阅 [docs/tools.md](./docs/tools.md) 获取包含参数和示例的完整参考。
## 延伸阅读
### 文档
- [工具参考](./docs/tools.md)：包含参数和示例的完整工具参考
- [技能参考](./docs/skills.md)：技能参考、工作流、用例和组合
- [语言支持](./docs/language-support.md)：语言覆盖矩阵
- [架构](./docs/architecture.md)：系统设计和内部原理
- [推测执行](./docs/speculative-execution.md)：先模拟后应用的工作流
- [LSP 一致性](./docs/lsp-conformance.md)：LSP 3.17 规范覆盖范围
- [Docker](./DOCKER.md)：Docker 标签、Compose 和卷缓存
### 贡献
- [CI 说明](./docs/ci-notes.md)：CI 注意事项和测试工具详情
- [分发](./docs/distribution.md)：安装渠道和发布流程
## 开发
```
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)
```
## 库使用
`pkg/lsp`、`pkg/session` 和 `pkg/types` 包暴露了稳定的 Go API，用于直接使用 agent-lsp 的 LSP 客户端而无需运行 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})
```
请参阅 [docs/architecture.md](./docs/architecture.md) 获取完整的包 API。
## 许可证
MIT