platform-lsp-integrate

Salesforce LSP の使用方法

salesforce-development プラグインは、Salesforce Language Server の子プロセスを遅延起動し、そのセマンティック機能を MCP ツールとして公開する、salesforce-lsp というローカル MCP サーバーを提供します。このスキルは、それらのツールを呼び出す他のスキルが従う契約であり、「Salesforce LSP の使い方」への回答です。各ツールの機能、結果の読み方、すべてのエラーコードの意味、ホストが存在しない場合のフォールバックについて説明します。

これはドキュメント／リファレンススキルです。コードの作成やデプロイは行わず、LSP ツールの正しい使い方をユーザー（および他のスキル）に説明します。

このプラグインのビルドに含まれるのは Apex と SOQL のみです。 salesforce-lsp ホストには、Apex 言語サーバー（@salesforce/apex-ls）と SOQL 言語サーバーが含まれています。LWC 言語サーバーはこのプラグインには意図的に含まれていません。ホストに lwc.* ツールは登録されていますが、ここでは常に unavailable クラスのエンベロープを返します。lwc.* の呼び出しは利用不可として扱い、フォールバック（コンポーネントのソースを読む／デプロイ時にコンパイルする）を使用してください。

このスキルを使用するタイミング

• ユーザーが Salesforce LSP の使い方、または利用可能な LSP／MCP ツールについて質問している場合。
• ユーザーが特定のツール（apex.diagnostics、validate_soql、complete_soql など）の機能や、出力の読み方について質問している場合。
• LSP ツールがエラーエンベロープ（lsp_disabled、spawn_timeout、circuit_open、no_apex_workspace、no_org_connected）を返し、その意味や復旧方法を確認する必要がある場合。
• LSP ツールを呼び出す別のスキルを作成またはレビューしており、標準的な呼び出し／フォールバックパターンを確認する必要がある場合。
• LSP が壊れているようで、デバッグが必要な場合（lsp.health、${CLAUDE_PLUGIN_ROOT}/bin/lsp-doctor、キルスイッチ）。

ツール

すべてのツールは MCP サーバー salesforce-lsp によって提供されます（呼び出し名はプラグイン接頭辞付きのパターンに従います： mcp__plugin_salesforce-development_salesforce-lsp__<tool_name>。ツール名のドットはアンダースコアになります。例：apex.diagnostics は mcp__plugin_salesforce-development_salesforce-lsp__apex_diagnostics になります）。起動は遅延方式です。言語サーバーが必要なツールは、最初の呼び出し時に子プロセスを起動し（Apex の場合、初回起動に数秒かかります）、以降はそれを再利用します。純粋な静的解析ツールは何も起動しません。

Apex（Apex LSP を起動）

ツール	目的	主な入力	主な出力
apex.diagnostics	.cls／.trigger をコンパイルチェックし、エラー／警告を提示します	{ filePath }	{ ok, diagnostics: [{ line, column, severity, message }] }
apex.hover	指定位置の型／シグネチャ	{ filePath, line, character }	ホバー用 Markdown
apex.documentSymbol	ファイルのシンボル一覧	{ filePath }	シンボルツリー
apex.completion	指定位置でのコード補完	{ filePath, line, character }	補完候補

SOQL

ツール	目的	起動するか	主な出力
validate_soql	SOQL 文字列を解析して構文エラーを検出します	SOQL LSP	{ ok, diagnostics: [{ line, column, severity, message }] }
complete_soql	カーソル位置で、スキーマに基づく補完を行います（組織に対して解決された SObject、項目、選択リスト値）	SOQL LSP	{ ok, items, expanded, unresolved, hint? }
extract_soql_from_apex	Apex 内のインライン [SELECT …] をすべて静的に抽出します	いいえ（純粋な静的処理）	{ ok, totalQueries, totalDynamic, files }
check_soql_selectivity	選択性ヒューリスティック（任意で組織に対して LIMIT-0 プローブを実行）	デフォルトではいいえ	選択性レポート
refresh_org_schema	キャッシュされた組織の describe を無効にし、補完時に再取得させます	いいえ	{ ok, removed }

デプロイしたばかりの項目／オブジェクトが解決されませんか？ デプロイ直後に、SOQL または Apex の参照先としてデプロイしたばかりの項目を指定するとエラーになる（例：No such column 'Foo__c' が表示される、または complete_soql に項目が表示されない）場合、キャッシュされた組織の describe が古くなっています。refresh_org_schema を呼び出してキャッシュを無効にし、コードのエラーを疑ったり名前を変更したりする前に、チェックを再実行してください。デプロイ後のスキーマ反映の遅れには、この方法を使います。クエリ／クラスのバグと判断する前に試してください。（ローカルキャッシュをクリアするだけなので、サーバー側の反映を早めることはできません。組織側で項目の公開がまだ完了していない場合は、少し待ってから再実行してください。）

LWC — このビルドでは利用できません

lwc.diagnostics、lwc.hover、lwc.definition、lwc.completion、lwc.workspace_symbols などの lwc.* ツールはホストに登録されていますが、このプラグインには LWC 言語サーバーが同梱されていません。すべての lwc.* 呼び出しは利用不可を示すエンベロープを返します。LWC の作業では、コンポーネントのソース／テンプレートを直接読むか、デプロイ時のコンパイルを行って CLI のエラーを確認してください。

診断／ヘルス

ツール	目的	起動するか
lsp.health	キルスイッチのモード、ワークスペース、サーバーごとの状態、サーキットブレーカーの状態、コールド起動の所要時間、apex-ls のバージョンを読み取り専用で確認します	いいえ — 起動することはありません

座標はすべて1 始まり（line／column）です。validate_soql の診断座標はファイルではなくクエリ文字列を基準とします。クエリが extract_soql_from_apex から取得された場合は、そのクエリの範囲を使って元の位置に換算してください。

呼び出し／フォールバックの契約

LSP ツールを呼び出すすべてのスキルは、次の 3 つのルールに従います。

1. 推測するより LSP ツールを優先します。 その手順に使えるツール（クエリの検証、クラスのコンパイルチェック、組織スキーマに基づく補完など）がある場合は、手作業で分析する方法にフォールバックする前に呼び出してください。
2. エラーエンベロープは「利用不可」として扱い、「合格」として扱わないでください。 ツールは結果の代わりに { error: <code> } を返すことがあります（エラーコードを参照）。そのようなコードが返された場合は、レポートに <tool>=unavailable: <code> と記録し、フォールバック手順に進んでください。チェックを実行できなかったというだけで、入力が有効／問題なしと報告することは決してしないでください。
3. 失敗させるのではなく、機能を縮退させてください。 LSP は処理を高速化するものであり、必須の依存先ではありません。ホストがまったく利用できない場合、salesforce-lsp ツール自体が存在しません。その手順では CLI／手動の方法にフォールバックし、その旨を伝えてください。

LSP ホストが存在しない場合

プラグイン／ホストが利用できない場合、上記の MCP ツールは登録されないため、 validate_soql などを呼び出しても解決されません。エラーエンベロープを検出するのと 同じ方法で、ツールが利用できないことを検出し、次に示す文書化されたフォールバックを 使用してください。

LSP ツールが利用できない場合	フォールバック
apex.diagnostics	sf project deploy でデプロイ／コンパイルし、CLI エラーを確認します
validate_soql	sf data query --json でクエリを読み取り専用で実行して簡易チェックします（解析エラーは CLI エラーに表示されます）
complete_soql	フィールドについては sf sobject describe --sobject <O> --json を使用し、ユーザーが指定した名前に基づいて作成します
extract_soql_from_apex	ファイルを読み込み、[SELECT … ] を手作業で探します
apex.completion / apex.hover	ソースを直接読み込みます
lwc.*（ここでは常に利用不可）	コンポーネントのソース／テンプレートを直接読むか、デプロイ時にコンパイルして CLI エラーを確認します

エラーコード

ツールは結果の代わりに { error: <code> }（または complete_soql の場合は hint）を 返します。それぞれのエラーからの復旧方法は次のとおりです。

コード	意味	対応方法
lsp_disabled	キルスイッチ（SFDX_LSP）により、この言語での使用が禁止されています	LSP を使わないフォールバックを使用するか、LSP を再び有効にします（「デバッグ」を参照）
spawn_timeout	言語サーバーが時間内に起動しませんでした	1 回だけ再試行します。解決しない場合は、フォールバックを使用して ${CLAUDE_PLUGIN_ROOT}/bin/lsp-doctor を実行します
circuit_open	起動の失敗が繰り返されたため遮断器が作動し、呼び出しが短絡されています	すぐにフォールバックし、lsp.health / ${CLAUDE_PLUGIN_ROOT}/bin/lsp-doctor で調査します
no_apex_workspace	いずれのパッケージディレクトリにも classes/*.cls がありません — Apex ツールは起動しません	Apex を使用しないプロジェクトでは想定どおりです。確認は不要です
no_org_connected	（complete_soql のヒント）組織のスキーマを解決できませんでした	キーワード補完は引き続き利用できます。正確なフィールド名／オブジェクト名を尋ねるか、組織に接続してください。__…_PLACEHOLDER ラベルを実在するフィールドとして提示しないでください

最初の 3 つは、起動するすべてのツールに共通する一時的な状態／設定状態です。 残りは、特定のワークスペース／組織／ファイルのコンテキストで想定される正常な 状態であり、インストールの不具合を示すものではありません（no_lwc_bundles / unsupported_lwc_file は LWC 専用のコードです。このビルドでは LWC サーバーは 同梱されていないため、lwc.* は常に利用できません）。

LSP のデバッグ

コストの低いものから、次の 3 つのレイヤーがあります。

1. lsp.health（MCP ツール）。 最も手早く確認できます — 子プロセスは起動しません。 キルスイッチのモード、解決されたワークスペース、サーバーごとの状態、遮断器の状態、 直近の初回起動にかかった時間、同梱された apex-ls のバージョンを報告します。Claude に「lsp.health を実行」と依頼するか、lsp.health ツールを直接呼び出してください。

2. bin/lsp-doctor（CLI）。 サポートやオンボーディングに役立つ、インストールレベルの より詳細な診断ツールです。コミット済みバンドルの存在、同梱された apex-ls アーティファクトの解決可否、組織スキーマキャッシュの解析可否、各 LSP 子プロセスの 実際の起動可否を確認します。正常な場合は 0 で終了し、問題がある場合は チェックごとの構造化された出力とともに 1 で終了します。

   "${CLAUDE_PLUGIN_ROOT}"/bin/lsp-doctor            # human-readable report
   "${CLAUDE_PLUGIN_ROOT}"/bin/lsp-doctor --json     # machine-readable
   "${CLAUDE_PLUGIN_ROOT}"/bin/lsp-doctor --no-spawn # skip child-spawn probes (CI/restricted)
   

   （このビルドでは lsp-doctor が LWC サーバーの欠落を報告しますが、これは想定どおり です。ここに同梱されているのは Apex と SOQL のみです。）

3. SFDX_LSP_DEBUG=1。 1 行形式の JSON テレメトリ（起動時間、キャッシュヒット、 遮断器イベント、ツールごとのレイテンシ）を stderr に出力します。デフォルトでは 無効です（オーバーヘッドはゼロです）。

キルスイッチ — SFDX_LSP

LSP をすばやく制御または無効化する方法です。環境変数を設定します。

SFDX_LSP	効果
未設定 / all	同梱されたすべての LSP を起動できます（デフォルト）
apex-only	Apex LSP のみ起動できます。SOQL ツールは lsp_disabled を返します
disabled	LSP は起動しません。すべての LSP ツールが lsp_disabled を返します

LSP が問題の原因かどうかを切り分けるには、SFDX_LSP=disabled を設定して再実行します。 問題が続く場合、原因は LSP ではありません。また、スキルは自動的に LSP を使わない パスに切り替わります。不明な値を指定した場合は、警告とともに all がデフォルトとして 適用されるため、入力ミスによって機能が気付かないうちに無効化されることはありません。

デプロイ前の診断ゲート

PreToolUse フック（bin/lsp-precheck）は、sf project deploy start／validate がデプロイしようとしている .cls／.trigger ファイルに対して Apex 診断を実行し、判定を出力します。フェイルオープンであり、エラー（LSP が見つからない、または応答が遅い場合を含む）が発生すると、デプロイは許可されます。モードは SFDX_LSP_DEPLOY_GATE （off | warn | block、デフォルトは warn）で制御します。warn はデプロイをブロックせずに診断結果を表示し、block は Apex のコンパイルエラーがあるデプロイを拒否します。

検証

• 「Salesforce LSP ツールの使い方は？」と尋ねた場合、このスキルが一致し、ツールとその入力／出力、およびフォールバックの仕様が示されます。
• /skills の一覧に platform-lsp-integrate として表示されます。
• エラーコード（例：no_apex_workspace）が与えられた場合、未実行のチェックを合格として扱わず、その意味と適切な復旧方法を説明します。

スキル間の連携

必要なこと	委任先
直前に作成した Apex のコンパイルチェックと分析	platform-apex-generate
.cls／.trigger 内のインライン SOQL の検証	validate_soql（このスキル）。フォールバック：読み取り専用で sf data query --json を実行
組織に対する SOQL クエリの作成と実行	complete_soql + sf data query
デプロイ前の診断ゲートの動作	上記の「デプロイ前の診断ゲート」を参照