agent-lsp

英語 · 简体中文 · Русский · हिन्दी · العربية

AI エージェント向けのコードインテリジェンス基盤です。 65 個のツール、CI で検証済みの 32 言語、24 個のエージェントワークフローを備えています。単一の Go バイナリです。

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

これは何ですか？

agent-lsp は、既存の LSP サーバー（gopls、rust-analyzer、jdtls など）をエージェント向けのワークフローに統合する MCP サーバー です。

LSP サーバーではありません。言語サーバーを管理し、バッチ操作、投機的編集、複数ステップのワークフローを MCP ツール経由で提供するオーケストレーション層です。

アーキテクチャ：

• 言語サーバー（gopls、rust-analyzer など）→ コードインテリジェンスを提供
• agent-lsp（MCP サーバー）→ ワークフローを統合し、ウォームランタイムを維持
• AI エージェント → MCP プロトコル経由で利用

なぜ agent-lsp なのか？

ウォーム状態を維持するランタイム
言語サーバーは、エージェントのセッションをまたいでインデックスを保持します。初回のセッションでは、ワークスペースのインデックスを作成します（一般的なプロジェクトで約10秒）。2回目以降のセッションは即座に開始できます。リクエストごとのコールドスタートによる遅延はありません。

バッチ操作
blast_radius → 1回の呼び出しで、すべてのエクスポートと呼び出し元を返します（テスト用と非テスト用に分類）。オーケストレーションなしでは、LSP を20回以上、順番に呼び出す必要があります。

編集の事前シミュレーション
simulate_edit → メモリ上で変更をプレビューし、診断の差分を確認してから、適用または破棄します。ディスクに触れる前に編集をテストできます。

ワークフローのオーケストレーション
LSP 操作を一連の完全なパイプラインにつなぐ24個のスキルがあります。

• /lsp-refactor → 影響分析 → プレビュー → 適用 → ビルドを検証 → テストを実行
• /lsp-safe-edit → プレビュー → 診断の差分 → 安全な場合に適用
• /lsp-verify → LSP 診断 → ビルド → テストスイート

1つのセッションで複数言語に対応
1つの agent-lsp プロセスが、.go を gopls に、.ts を tsserver に、.py を pyright に振り分けます。プロジェクトを切り替えても再設定は不要です。セッションはファイルやリポジトリをまたいで維持されます。

ヒント

トークンを最適化した出力： ツールの応答は JSON ではなく GCF でエンコードされます。ツールに応じてトークンを30～84％削減できます（セッションの重複排除を使うと最大92.7％）。最先端のすべてのモデルでLLMの理解率100％、JSON の平均が54.1％となる複雑なコードグラフでは91.2％です。ツールごとの実測値については、以下をご覧ください。

各要素の連携方法： LSP（Language Server Protocol）は、エディターがコード補完、診断、定義への移動などのコードインテリジェンスを得るための仕組みです。MCP（Model Context Protocol）は、Claude Code などの AI ツールが外部ツールを検出し、呼び出すための標準です。agent-lsp はこの2つを橋渡しし、言語サーバーのインテリジェンスを AI エージェントから利用できるようにします。

次のような用途でお使いください

• エージェント型コード生成システムの構築
• 大規模なコードベース全体にわたるリファクタリングの自動化
• プログラムからコードインテリジェンスを利用する CI ツール
• LSP の逐次呼び出しが遅すぎる、または複雑すぎるワークフロー

エージェントの評価

AI エージェントに、10種類のコーディングタスク（呼び出し元の検索、安全な名前変更、編集のプレビュー、デッドコードの検出）を通じて agent-lsp を評価し、率直な評価を書くよう依頼しました。異なる4つのモデルによる独立した評価は、いずれも同じ結論でした。

Claude（Opus 4.6）：「リファクタリング、影響分析、安全な編集を伴うワークフローには、どのようなものでも agent-lsp を推奨します。特に優れているツールは、blast_radius（テスト用と非テスト用に分類して、1回の呼び出しで影響範囲を把握できます。これを再現するには grep を5～10回実行する必要があります）、go_to_implementation（型チェック済みのインターフェース実装判定は、grep では実現できません）、そしてシミュレーションセッションのワークフロー（ディスクに触れずに変更を仮の型チェックにかけられます。これに相当する grep や read の手段はありません）です。」

Cursor（自動）：「大規模なリファクタリングやコードのナビゲーションには agent-lsp を推奨します。名前変更、参照、実装、呼び出し階層、シミュレーションの各ツールによって、壊れやすい grep や手動編集の手間が大幅に減り、変更をより安全に行えるためです。」

GPT-5.5（Codex 経由）：「シンボルを考慮する作業には agent-lsp を推奨します。参照、実装、名前変更のプレビュー、診断、大きなファイルの構造の把握は、grep と read を繰り返す方法より大幅に速く、エラーも起こりにくくなります。」

Gemini 2.5 Pro（Gemini CLI 経由）：「agent-lsp を強く推奨します。一般的なテキスト検索ツールでは到底かなわないレベルの意味理解を実現するためです。高い信頼性での名前変更、インターフェースの実装の検索、ディスクに書き込まずに編集が診断に与える影響をプレビューできる機能により、リグレッションを引き起こすリスクを大幅に減らせます。」

テストで確認済み

他のすべての MCP-LSP 実装では、設定ファイルに対応言語を列挙しています。しかし、CI で実際の言語サーバーを実行して動作を確認しているものはありません。

agent-lsp の CI では、プッシュのたびに実際のフィクスチャコードベースを使って 32 個の実際の言語サーバー をテストしています。Go、Python、TypeScript、Rust、Java、C、C++、C#、Ruby、PHP、Kotlin、Swift、Scala、Zig、Lua、Elixir、Gleam、Clojure、Dart、Terraform、Nix、Prisma、SQL、MongoDB、MQL などに対応しています。「gopls で動作する」と言う場合、それは希望的観測ではなく、検証済みの自動化された主張です。

投機的実行

ディスクに書き込む前に、メモリ上で変更をシミュレートします。この機能を備えた MCP-LSP 実装は他にありません。

preview_edit は、任意の編集による診断への影響をプレビューします。ファイルに手を加える前に、何が壊れるかを正確に確認できます。simulate_chain は、依存する一連の編集（関数の名前変更、すべての呼び出し元の更新、戻り値の型の変更など）を評価し、どのステップで初めてエラーが発生するかを報告します。

投機的実行ツールは 8 つあります。ワークフロー全体については、docs/guide/speculative-execution.md をご覧ください。

トークンの節約

構造化された LSP レスポンスは、同じタスクで grep/read を使う場合と比べて 5〜34 倍少ないトークン数で済みます。HashiCorp Consul（319K 行）での影響範囲分析では、grep 経由だと 17.7MB、LSP 経由だと 841KB となり、ツール呼び出し数を 5,534 回から 119 回に削減できます。コードベースが大きいほど節約効果も高まります。5 つのコードベースを使った実験全体については、docs/guide/token-savings.md をご覧ください。

トークン最適化出力（GCF）

ツールのレスポンスは JSON ではなく、GCF (Graph Compact Format) でエンコードされます。GCF は、フィールド名や識別子の繰り返し、およびレコードごとの構造上のオーバーヘッドをなくします。

グループ化された／ネストされたレスポンス（シンボル配下の呼び出し元、関連情報を含む診断など）も表形式に変換でき、その形式では JSON より約 14% 少ないトークン数で済みます（詳細）。

GCF はデフォルトで有効です。JSON に戻すには、以下を実行します。

export AGENT_LSP_OUTPUT_FORMAT=json

ベンチマーク：go run scripts/gcf-benchmark.go。アーキテクチャの詳細については、docs/guide/gcf-integration.md をご覧ください。

GCF： gcformat.com · 仕様 · Go · Python · TypeScript · プレイグラウンド

オーケストレーションが重要な理由

AI エージェントは全体像を把握できないため、誤ったコード変更を行います。この関数を呼び出すのは誰か、名前を変更したら何が壊れるか、ビルドは引き続き通るか、といった点を確認できません。言語サーバーは答えを持っていますが、生の LSP ツールでは 20 回以上の逐次呼び出しと、複雑なオーケストレーションロジックが必要です。

agent-lsp は、正しい複数ステップの操作を単一の呼び出しやスキルにまとめることで、この問題を解決します。blast_radius は、エージェントが 20 回以上呼び出す必要がある処理を 1 回で実行します。/lsp-refactor は、プロンプトごとのオーケストレーションなしで、影響分析 → プレビュー → 適用 → 検証 → テストを連結して実行します。

永続デーモンモード

Python および TypeScript のプロジェクトでは、find_references が使えるようになるまで、バックグラウンドでのインデックス作成に数分かかります。agent-lsp は、セッション間も動作し続ける永続デーモンブローカーを自動的に起動するため、ワークスペースのインデックスが維持されます。最初のセッションでは、デーモンが起動してインデックスを作成します（FastAPI で約 10 秒）。以降のセッションでは、ウォーム状態のデーモンに即座に接続できます。30 分間操作がないと自動終了します。Go、Rust などインデックス作成が速い言語では、この機能は完全にバイパスされます（オーバーヘッドはゼロです）。

フェーズの強制

スキルは、エージェントに正しい操作順序を伝えます。フェーズの強制により、エージェントが指示に従うことを信頼するのではなく、ランタイムが違反を ブロック します。

エージェントがスキルを有効にすると、すべてのツール呼び出しが現在のフェーズの権限に照らしてチェックされます。ブラスト範囲の分析中に apply_edit を呼び出しても、そのまま処理が進むことはありません。「blast_radius フェーズを先に完了してください。許可されているツール：[blast_radius, find_references]」という具体的な復旧手順を含むエラーが返されます。エージェントが後続フェーズのツールを呼び出すと、フェーズは自動的に進みます。

ランタイムでワークフローの順序を強制するMCPツールプロバイダーは、ほかにありません。docs/guide/phase-enforcement.mdをご覧ください。

並行処理の分析

インスペクターには、4つの並行処理ファミリー（goroutine、スレッド、async、アクター）に属する25言語で動作する、4つの並行処理チェックが含まれています。

• 復旧処理のない並行エントリーポイント：復旧処理のないgoroutine／スレッド／タスク
• チェックされていない共有状態：sync.Map、ConcurrentHashMapに対する、ガードのない型アサーション
• チャネルが閉じられない：作成されたものの閉じられないチャネル／キュー（goroutineリーク）
• 同期なしの共有フィールド：同期されていない状態で、並行コンテキストからアクセスされるフィールド

blast_radius は、親の型にミューテックスがある場合、シンボルに sync_guarded: true を付与します。cross_concurrent: true を指定した find_callers は、goroutine／スレッドの境界を越えて呼び出しチェーンをたどります。/lsp-concurrency-audit スキルは、任意の型についてフィールド単位の安全性レポートを生成します。

自動診断

シンボル編集ツール（replace_symbol_body、insert_after_symbol、insert_before_symbol、safe_delete_symbol）は、errors_after と warnings_after の件数を自動的に返します。エージェントは、別途 get_diagnostics を呼び出さなくても、編集によって問題が発生したかどうかをすぐに把握できます。

safe_apply_edit は、プレビューと適用を1回の呼び出しにまとめます。試験的にプレビューし、net_delta == 0（新たなエラーなし）の場合にのみディスクに適用します。ツール呼び出しは3回ではなく1回です。

対応ツール

コピーして貼り付けられる設定については、docs/getting-started/mcp-clients.mdをご覧ください。

スキル

生のツールは無視されます。スキルは活用されます。各スキルには適切なツールの実行手順が組み込まれており、プロンプトごとにオーケストレーションの指示を追加しなくても、ワークフローが実際に実行されます。スキルはAgentSkillsのスラッシュコマンドとして、また、あらゆるMCPクライアント向けにprompts/list / prompts/getを介したMCPプロンプトとして利用できます。

詳しい説明と使い方については、docs/guide/skills.mdをご覧ください。

変更を加える前に

安全に編集する

使い始める

不慣れなコードを理解する

編集後

コードを生成する

一連のワークフロー

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）にもミラーされています。タグの全一覧、HTTPモードのセットアップ、セキュリティ強化オプションについては、DOCKER.mdをご覧ください。

セットアップ

ステップ1：agent-lspをインストールする

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

brew install blackwell-systems/tap/agent-lsp

# 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

# 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

お使いのスタックに対応するサーバーをインストールします。一般的なものは次のとおりです。

サポートされている 32 言語の完全な一覧は、docs/reference/language-support.md をご覧ください。

ステップ 3：セットアップを確認する

agent-lsp doctor

設定されている各言語サーバーをテストし、機能を報告します。続行する前に、失敗をすべて修正してください。インストールコマンドと言語サーバー固有の注意事項については、言語サポートをご覧ください。

ステップ 4：AI ツールを設定する

agent-lsp init

PATH 上の言語サーバーを検出し、使用している AI ツールを確認して、適切な MCP 設定を書き込みます。また、AI プロバイダー向けのスキル認識ルールをインストールします（Claude Code の場合は CLAUDE.md、Cursor の場合は .cursor/rules/、Cline の場合は .clinerules、Windsurf の場合は .windsurfrules、Gemini CLI の場合は GEMINI.md、Pi の場合は AGENTS.md）。CI やスクリプトから使用する場合は、agent-lsp init --non-interactive を実行してください。

Pi の場合は、プロジェクト（9）またはグローバル（10）の対象を選択してください。Pi には MCP の組み込みサポートがありません。init は、pi-mcp-adapter パッケージが読み込む共通の標準 MCP ファイルを書き込みます。プロジェクトの場合は .mcp.json（Claude Code と同じファイルなので、1 つの設定を両方で使用できます）、グローバルの場合は ~/.config/mcp/mcp.json です。スキル認識ルールは、プロジェクトの場合は AGENTS.md、グローバルの場合は ~/.pi/agent/AGENTS.md に書き込まれます。アダプターは pi install npm:pi-mcp-adapter で一度インストールしてください。

1 つのコマンドでセットアップを完了する

埋め込みスキルファイルもインストールするには、--with-skills を追加します（リポジトリのクローンは不要です）。

agent-lsp init --with-skills

スキルは、選択した対象に対応する場所に書き込まれます。Pi のプロジェクト対象（9）のみ、ツールに依存しない .agents/skills/ ディレクトリを使用します（リポジトリでバージョン管理できます）。Pi のグローバル対象（10）は ~/.pi/agent/skills/、Claude Code の対象（1／2）は ~/.claude/skills/、Cursor（4）は ~/.cursor/skills/、Gemini CLI（7）は ~/.config/gemini-cli/skills/ を使用します。スキルディレクトリが確認されていないプロバイダーはスキップされ、skills/install.sh --dest の使用を案内します。再実行すると、管理対象のスキルファイルが上書きされ、インストール済みのバイナリと同期されます。agent-lsp uninstall で削除できます。

生成される設定は次のようになります。

{
  "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

クローンを完全に省略することもできます。agent-lsp init --with-skills を実行すると、選択した対象に対応する場所に同じ埋め込みスキルがインストールされます。

スキルは AI ツールの設定にコピーされるプロンプトファイルです。--copy を指定すると、コピー後にクローンを安全に削除できます。スクリプトのデフォルトは ~/.claude/skills/ です。他のエージェントの場合は、たとえば Pi なら --dest ~/.pi/agent/skills のように --dest を指定してください。また、既存の指示ファイル（~/.claude/CLAUDE.md、プロジェクトの AGENTS.md、~/.pi/agent/AGENTS.md、GEMINI.md）に、管理対象のスキル一覧表を追記します。

スキルは MCP プロンプトとしても利用できます。任意の MCP クライアントが prompts/list でスキルを検出し、prompts/get でワークフローの全指示を取得できるため、手動でインストールする必要はありません。install.sh を使う方法は、AgentSkills 対応クライアント（Claude Code のスラッシュコマンド、Pi の /skill:name コマンド）向けです。

ステップ 6：ツールの権限を許可する（Claude Code）

Claude Code では、権限の許可リストに mcp__lsp__* を追加すると、ツールごとの承認プロンプトなしで 65 個すべてのツールを利用できます。

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

追加しない場合、Claude Code はツールを呼び出すたびに権限を求めます。他の MCP クライアントでは権限の扱いが異なります。お使いのクライアントのドキュメントを確認してください。

スキルは、信頼性の高い手順を組み込んだ複数のツールにまたがるワークフローです。編集前の影響範囲の確認、書き込み前の試行プレビュー、変更後のテスト実行などがあります。すべてのスキルについては、docs/guide/skills.md を参照してください。

ステップ 7：作業を開始する

AI エージェントがツールを自動的に呼び出します。最初の呼び出しでワークスペースが初期化されます。

start_lsp(root_dir="/your/project")

これはエージェントが実行するものであり、入力するものではありません。その後、65 個のツールのうちどれでも使用できます。セッションはウォーム状態に保たれるため、ファイルを切り替えるときに再起動する必要はありません。

agent-lsp の独自機能

ユースケース

• 複数プロジェクトでのセッション：AI の対象に ~/code/ を指定すれば、再設定せずに任意のプロジェクトで作業できます
• 複数言語での開発：1 つのセッションで Go のバックエンド、TypeScript のフロントエンド、Python スクリプトを扱えます
• 大規模なモノレポ：1 つのサーバーですべての言語を処理し、ファイル拡張子に応じて振り分けます
• コードの移行：リポジトリをまたいだ参照をすべて追跡しながら、複数のリポジトリを横断してリファクタリングできます
• CI パイプライン：実際の言語サーバーの動作に照らして検証できます
• ニッチな言語スタック：Gleam、Elixir、Prisma、Zig、Clojure、Nix、Dart、Scala、MongoDB。すべて CI で検証済みです

複数言語のサポート

32 言語に対応し、すべての CI 実行で実際の言語サーバーに対するエンドツーエンドの検証を実施しています。単一の言語すら CI でテストしていない MCP-LSP 実装もあります。

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、MQL。

対応範囲の全一覧は、docs/reference/language-support.md を参照してください。

ツール

ナビゲーション、分析、リファクタリング、シンボル編集、複合的な探索、安全な編集、投機的実行、セッションのライフサイクルを網羅する 65 個のツールを用意しています。すべて CI で検証済みです。

パラメーターと例を含む完全なリファレンスは、docs/reference/tools.md を参照してください。

関連情報

ドキュメント

• ツールリファレンス：パラメーターと例を含むツールの完全なリファレンス
• スキルリファレンス：スキルのリファレンス、ワークフロー、ユースケース、組み合わせ方
• 言語サポート：言語の対応範囲一覧
• アーキテクチャ：システム設計と内部構造
• 投機的実行：適用前にシミュレートするワークフロー
• LSP 準拠状況：LSP 3.17 仕様への対応範囲
• Docker：Docker タグ、compose、ボリュームキャッシュ

貢献

• CI に関する注意事項：CI 特有の注意点とテストハーネスの詳細
• 配布：インストール方法とリリースパイプライン

開発

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 パッケージは、MCP サーバーを実行せずに agent-lsp の LSP クライアントを直接使用できる、安定した Go API を提供します。

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

パッケージ API の詳細については、docs/architecture/architecture.md をご覧ください。

ライセンス

MIT