lsp-setup

LSP 自動設定スキル

Language Server Protocol（LSP）設定を手動で制御し、トラブルシューティングを行います。

重要：LSP は自動的に設定されます

このスキルは必要ない場合がほとんどです！ amplihack claude を実行すると、LSP は自動的に設定されます。

amplihack が Claude Code を起動すると、次の処理が自動的に行われます。

• プロジェクト内のプログラミング言語を検出します
• ENABLE_LSP_TOOL=1 環境変数を設定します
• Claude Code のプラグインマーケットプレイスを通じて、必要な LSP プラグインをインストールします
• .env にプロジェクト固有の設定を行います

amplihack が Claude Code を起動すると、次のように表示されます。 📡 LSP: Detected 3 language(s): python, javascript...

このスキルを使う場合

次のような場合にのみ /lsp-setup を使ってください。

• ステータスの確認：LSP 設定が機能しているか確認します（/lsp-setup --status-only）
• 問題のトラブルシューティング：コードインテリジェンスが機能しない原因を診断します
• 再設定の強制：手動で変更した後に LSP 設定を再構築します（/lsp-setup --force）
• 言語の追加：新たに追加した言語向けに LSP を設定します

次の場合はこのスキルを使わないでください。 LSP がすでに機能している場合です！自動設定でほとんどのケースに対応できます。

概要

LSP セットアップスキルを使うと、起動時に自動で行われる LSP 自動設定を手動で制御できます。一般的なプログラミング言語 16 種に標準で対応しており、設定、ステータス確認、トラブルシューティングを直接行えます。

LSP が提供する機能

LSP が正しく設定されると、Claude Code は強力なコードインテリジェンス機能を利用できるようになり、AI によるコードベースの理解が向上します。

リアルタイムのコードインテリジェンス

型情報 — Claude は変数、関数、クラスの正確な型を確認できます。

# Claude can hover over 'user' and see: Type: User (class from models.py)
user = get_current_user()

定義へ移動 — Claude はシンボルの定義箇所に移動できます。

# Claude can navigate from 'authenticate()' call to its definition in auth.py
result = authenticate(credentials)

コード診断 — Claude は LSP サーバーからリアルタイムでエラー検出結果を受け取ります。

# Pyright reports: "Set" is not accessed
from typing import List, Set  # Claude sees this warning

Claude による LSP の活用方法

コードのより深い理解 — 型や動作を推測する代わりに、Claude は LSP サーバーから次のような正確な情報を得ます。

• 関数のシグネチャと戻り値の型
• クラス階層と継承関係
• インポートパスとモジュール構造
• 実行前のエラーと警告

より賢い提案 — LSP のデータを利用して、Claude は次のような提案を行います。

• 正確なリファクタリングの推奨
• 型安全なコード補完
• 的確なエラー修正
• コンテキストに応じたコード生成

ワークフローの例：

You: "Fix the type error in user_service.py"

Without LSP: Claude reads the file, guesses at types, may miss subtle issues

With LSP: Claude receives diagnostic:
  Line 42: Expected type 'User | None', got 'str'
  → Claude provides exact fix based on actual type information

気づくこと

/lsp-setup でプロジェクトを設定すると、次のような効果があります。

1. より正確な応答 — Claude のコード提案が、実際の型や API に合致します
2. より迅速なデバッグ — Claude が IDE に表示されるのと同じエラーを確認できます
3. より優れたリファクタリング — LSP の参照情報を使って、ファイルをまたいで安全に変数名を変更できます
4. よりスムーズなナビゲーション — Claude が定義、使用箇所、実装箇所を正確に見つけられます

重要な注意事項

LSP は_裏側で_ Claude の機能を強化します。LSP を直接操作する必要はありません。LSP が自動的にコードに関する Claude の理解を深めます。

このスキルを使う場合

次のような場合に /lsp-setup を使ってください。

• Claude Code で新しいプロジェクトに取り組み始める
• 既存のプロジェクトにプログラミング言語を追加する
• コードインテリジェンス機能が表示されない、または正しく動作しない
• LSP 設定が正しいか確認したい
• LSP サーバーの接続問題をトラブルシューティングする必要がある

仕組み

LSP アーキテクチャ — 3 つのレイヤー

Claude Code の LSP システムは 3 層アーキテクチャを採用しており、LSP 機能を使用するにはすべてのレイヤーを設定する必要があります。

レイヤー 1：システム LSP バイナリ（ユーザーがインストール）

• npm、brew、rustup などを使ってシステムにインストールする LSP サーバーの実行ファイルです。
• 例：npm install -g pyright を実行すると、Pyright LSP サーバーのバイナリがインストールされます。
• これらは実際に言語を解析するエンジンです。

レイヤー 2：Claude Code LSP プラグイン（cclsp 経由でインストール）

• レイヤー 1 のバイナリに接続する Claude Code プラグインです。
• npx cclsp install <server-name> を使ってインストールします。
• cclsp ツールは claude-code-lsps プラグインマーケットプレイスを使用します。
• これらは Claude Code と LSP サーバーをつなぐブリッジとして機能します。

レイヤー 3：プロジェクト設定（.env ファイル）

• 仮想環境やプロジェクトのルートなど、プロジェクト固有の設定です。
• LSP 機能を有効にするには、ENABLE_LSP_TOOL=1 を含める必要があります。
• プロジェクトルートの .env に保存します。

重要：cclsp と claude-code-lsps は連携して動作します。cclsp はインストールツールで、claude-code-lsps はそれが使用するプラグインマーケットプレイスです。両者は相互に補完するものであり、代替関係ではありません。

スキルの 4 段階のプロセス

/lsp-setup スキルは、npx cclsp@latest setup から始まるワークフローを自動化します。

フェーズ 1：言語の検出

ファイル拡張子やフレームワークの識別子をもとに、プロジェクトディレクトリをスキャンしてプログラミング言語を特定します。Python、TypeScript、JavaScript、Rust、Go、Java など、16 の言語を検出します。

フェーズ 2：LSP の設定

検出した各言語に適した LSP サーバー設定を生成します。次の項目を確認します。

1. システム LSP バイナリがインストールされているか（レイヤー 1）
2. Claude Code プラグインがインストールされているか（レイヤー 2）

いずれかが不足している場合は、インストール方法を案内します。自動インストールは行いません。すべてユーザーが制御できます。

フェーズ 3：プロジェクトの設定

プロジェクト固有の LSP 設定（レイヤー 3）を含む .env ファイルを作成または更新します。

• ワークスペース固有のオプション（Python の仮想環境、Node.js のプロジェクトルートなど）
• ENABLE_LSP_TOOL=1（LSP 機能を有効にするために必要）

フェーズ 4：検証

各 LSP サーバーへの接続をテストし、ステータスを報告します。設定に問題がある場合は、対処方法を案内します。

使い方

基本的な使い方

/lsp-setup

プロジェクト内のすべての言語を検出し、LSP サーバーを自動的に設定します。

ステータスのみを確認

/lsp-setup --status-only

変更を加えずに、現在の LSP 設定とサーバーの利用可否を報告します。

強制的に再設定

/lsp-setup --force

有効な設定がすでに存在する場合も、LSP 設定を再生成します。

特定の言語

/lsp-setup --languages python,typescript

指定した言語のみを対象に LSP サーバーを設定します。

プラグインを手動で管理

Claude Code LSP プラグインを直接管理する必要がある場合は、cclsp コマンドを使用します。

# Install a plugin (Layer 2)
npx cclsp install pyright

# List installed plugins
npx cclsp list

# Remove a plugin
npx cclsp remove pyright

# Full setup workflow (what /lsp-setup automates)
npx cclsp@latest setup

/lsp-setup スキルは、npx cclsp@latest setup のワークフローを自動化し、言語のインテリジェントな検出とプロジェクト固有の設定を追加します。

対応言語

言語	LSP サーバー	システムバイナリのインストール（レイヤー 1）	Claude Code プラグイン（レイヤー 2）
Python	pyright	npm install -g pyright	npx cclsp install pyright
TypeScript	vtsls	npm install -g @vtsls/language-server	npx cclsp install vtsls
JavaScript	vtsls	npm install -g @vtsls/language-server	npx cclsp install vtsls
Rust	rust-analyzer	rustup component add rust-analyzer	npx cclsp install rust-analyzer
Go	gopls	go install golang.org/x/tools/gopls@latest	npx cclsp install gopls
Java	jdtls	eclipse.org/jdtls からダウンロード	npx cclsp install jdtls
C/C++	clangd	brew install llvm（macOS） / apt install clangd（Linux）	npx cclsp install clangd
C#	omnisharp	omnisharp.net からダウンロード	npx cclsp install omnisharp
Ruby	ruby-lsp	gem install ruby-lsp	npx cclsp install ruby-lsp
PHP	phpactor	composer global require phpactor/phpactor	npx cclsp install phpactor
Bash	bash-language-server	npm install -g bash-language-server	npx cclsp install bash-language-server
YAML	yaml-language-server	npm install -g yaml-language-server	npx cclsp install yaml-language-server
JSON	vscode-json-languageserver	npm install -g vscode-json-languageserver	npx cclsp install vscode-json-languageserver
HTML	vscode-html-languageserver	npm install -g vscode-html-languageserver	npx cclsp install vscode-html-languageserver
CSS	vscode-css-languageserver	npm install -g vscode-css-languageserver	npx cclsp install vscode-css-languageserver
Markdown	marksman	brew install marksman（macOS） / GitHub からダウンロード	npx cclsp install marksman

注：LSP 機能を使うには、レイヤー 1（システムバイナリ）とレイヤー 2（Claude Code プラグイン）の両方をインストールする必要があります。

例：Python プロジェクトのセットアップ

$ cd my-python-project
$ /lsp-setup

[LSP Setup] Detecting languages...
✓ Found: Python (23 files)
✓ Found: YAML (2 files)
✓ Found: Markdown (1 file)

[LSP Setup] Configuring LSP servers...
✓ pyright: Installed at /usr/local/bin/pyright
✓ yaml-language-server: Installed at /usr/local/bin/yaml-language-server
✓ marksman: Installed at /usr/local/bin/marksman

[LSP Setup] Configuring project...
✓ Created .env with LSP configuration
✓ Detected Python virtual environment: .venv
✓ Configured pyright to use .venv/bin/python

[LSP Setup] Verifying connections...
✓ pyright: Connected (Python 3.11.5)
✓ yaml-language-server: Connected
✓ marksman: Connected

Configuration complete! LSP servers ready.

例：マルチ言語プロジェクトのセットアップ

$ cd my-fullstack-app
$ /lsp-setup

[LSP Setup] Detecting languages...
✓ Found: TypeScript (45 files)
✓ Found: Python (12 files)
✓ Found: Rust (8 files)
✓ Found: JSON (6 files)

[LSP Setup] Configuring LSP servers...
✓ vtsls: Installed
✓ pyright: Installed
✗ rust-analyzer: Not found

[LSP Setup] Installation guidance:
To install rust-analyzer:
  $ rustup component add rust-analyzer

Would you like to continue with available servers? [Y/n] y

[LSP Setup] Configuring project...
✓ Created .env with LSP configuration
✓ Detected Node.js project root: ./frontend
✓ Detected Python project root: ./backend
✓ Detected Rust workspace: ./services

[LSP Setup] Verifying connections...
✓ vtsls: Connected (TypeScript 5.3.3)
✓ pyright: Connected (Python 3.11.5)
⚠ rust-analyzer: Skipped (not installed)

Configuration complete! 2/3 LSP servers ready.
Run `rustup component add rust-analyzer` to enable Rust support.

LSP が動作していることを確認する方法

/lsp-setup の実行後、LSP が Claude にコードインテリジェンスを提供していることを確認する方法は次のとおりです。

方法 1：診断を確認する

意図的にエラーを含めたファイルを分析するよう Claude に依頼します：

You: "What issues do you see in src/main.py?"

If LSP is working: Claude will report specific diagnostics from Pyright
  → "Line 15: 'name' is not accessed"
  → "Line 23: Expected type 'int', got 'str'"

If LSP is NOT working: Claude only sees what's in the file content
  → Generic observations about code style
  → No specific type errors or warnings

方法 2：型情報を尋ねる

コード内の型について Claude に尋ねます：

You: "What's the type of the 'user' variable in auth.py line 42?"

If LSP is working: Claude provides exact type from LSP
  → "Type: User | None (from models.User)"

If LSP is NOT working: Claude guesses based on context
  → "It appears to be a User object based on the code"

方法 3：ナビゲーションをテストする

定義を見つけるよう Claude に依頼します：

You: "Where is the authenticate() function defined?"

If LSP is working: Claude uses LSP goToDefinition
  → "Defined in src/auth/service.py:156"

If LSP is NOT working: Claude searches file contents
  → "I found it by searching for 'def authenticate'"

方法 4：ステータスコマンドを確認する

ステータスを確認します：

/lsp-setup --status-only

期待される出力（LSP が動作中）：

[LSP Setup] Configuration Status:

✓ Python (pyright): Connected
  - System Binary: /usr/local/bin/pyright-langserver
  - Plugin: Installed and active
  - Project Config: .env configured with ENABLE_LSP_TOOL=1

✓ TypeScript (vtsls): Connected
  - System Binary: /usr/local/bin/vtsls
  - Plugin: Installed and active
  - Project Config: .env configured with ENABLE_LSP_TOOL=1

Overall Status: ✓ All LSP servers ready (2/2)

問題がある場合の出力（LSP が動作していない）：

[LSP Setup] Configuration Status:

✗ Python (pyright): Not Connected
  - System Binary: Not found
  - Plugin: Not installed
  - Project Config: Missing ENABLE_LSP_TOOL=1

Issue: Run 'npm install -g pyright' and 'npx cclsp install pyright'

正常に動作している状態

LSP が正常に動作している場合、次のような状態になります。

1. エラーについて説明する際に、Claude が具体的な行番号を示します
2. Claude が推測ではなく、正確な型を提示します
3. Claude がコードの実行前に警告やエラーを認識します（IDE と同様です）
4. Claude が LSP の理解を活用して、コードの構造をたどれます

失敗した場合の状態

LSP が動作していない場合、次のような状態になります。

1. Claude がファイルの内容しか認識しない - 型情報や診断情報がありません
2. Claude が型や動作について推測する
3. コードを実行するまで、Claude がエラーに言及しない
4. 意味的な理解を使わず、テキストを検索する

トラブルシューティング

問題：LSP サーバーが見つからない

症状：設定中に「rust-analyzer: Not found」と表示される

解決策：提供されているインストールコマンドを使って LSP サーバーをインストールします

$ rustup component add rust-analyzer
$ /lsp-setup --force  # Reconfigure after installation

問題：LSP サーバーが起動時にクラッシュする

症状：検証中に「pyright: Connection failed」と表示される

解決策：LSP サーバーのログを確認し、インストールされていることを検証します

# Check if server is properly installed
$ which pyright
/usr/local/bin/pyright

# Test server manually
$ pyright --version
pyright 1.1.332

# Check Claude Code LSP logs
$ cat ~/.claude-code/lsp-logs/pyright.log

問題：誤った Python インタープリターが使用される

症状：仮想環境にパッケージがインストールされているにもかかわらず、インポートエラーが発生する

解決策：.env の設定で正しい Python インタープリターが指定されていることを確認します

# Check current configuration
$ cat .env | grep PYTHON

# Should show:
LSP_PYTHON_INTERPRETER=/path/to/.venv/bin/python

# If incorrect, update manually or run:
$ /lsp-setup --force

問題：TypeScript プロジェクトが検出されない

症状：.ts ファイルがあるにもかかわらず、TypeScript の LSP 設定がない

解決策：プロジェクトのルートに tsconfig.json があることを確認します

# Create minimal tsconfig.json
$ cat > tsconfig.json << EOF
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "strict": true
  }
}
EOF

$ /lsp-setup --force

問題：複数の Python バージョンが競合を引き起こす

症状：LSP サーバーが誤った Python バージョンを使用したときに「Module not found」エラーが発生する

解決策：.env で Python インタープリターを明示的に設定します

# Edit .env manually
LSP_PYTHON_INTERPRETER=/usr/bin/python3.11

# Or activate the correct virtual environment before running
$ source .venv/bin/activate
$ /lsp-setup --force

設定ファイル

.env（プロジェクトルート）

このスキルは、LSP 固有の設定を含む .env を作成または更新します。

# LSP Configuration - Auto-generated by /lsp-setup
ENABLE_LSP_TOOL=1  # REQUIRED: Activates LSP features in Claude Code

# Project-specific settings (Layer 3)
LSP_PYTHON_INTERPRETER=/path/to/.venv/bin/python
LSP_NODE_PROJECT_ROOT=/path/to/frontend
LSP_RUST_WORKSPACE=/path/to/services
LSP_GO_MODULE=/path/to/go.mod

# Language Server Paths (auto-detected)
LSP_PYRIGHT_PATH=/usr/local/bin/pyright
LSP_VTSLS_PATH=/usr/local/bin/vtsls
LSP_RUST_ANALYZER_PATH=/usr/local/bin/rust-analyzer

重要：LSP 機能を動作させるには、ENABLE_LSP_TOOL=1 が必ず必要です。これがないと、LSP サーバーは有効になりません。

Claude Code の LSP 設定

このスキルは Claude Code の LSP 設定を自動的に更新します。手動で編集する必要はありません。

Claude Code との統合

設定が完了すると、Claude Code は次のことを自動的に行います。

• プロジェクトのコンテキストに基づくコード補完を提供する
• リアルタイムの診断情報（エラー、警告）を表示する
• 「定義へ移動」のナビゲーションを有効にする
• ホバー時にインラインドキュメントを表示する
• インテリジェントなリファクタリングを提案する

ベストプラクティス

1. プロジェクト開始時に実行する：プロジェクトを最初に開いたときに LSP サーバーを設定します
2. 言語を追加したら更新する：新しい言語のファイルを追加したときは /lsp-setup を再実行します
3. .env をコミットする：チーム内で設定を統一するため、LSP 設定をバージョン管理に含めます
4. インストール後に検証する：--status-only を使ってサーバーが利用可能か確認します
5. サーバーを最新の状態に保つ：LSP サーバーを定期的に最新バージョンへ更新します

技術的な詳細

スキルの種類：対話型のコマンド駆動ワークフロー

依存関係：なし（外部パッケージを必要としない純粋なスキル）

実行時間：プロジェクトの規模に応じて 2～10 秒

永続性：設定は .env と Claude Code の設定に保存されます

対応プラットフォーム：macOS、Linux、WSL

関連スキル

• environment-setup - 一般的な開発環境の設定
• dependency-manager - パッケージと依存関係の管理
• project-init - 新しいプロジェクトの初期化

メンテナンス

LSP Setup スキルには手動でのメンテナンスは必要ありません。プロジェクトの構造に自動的に適応し、実行するたびに言語の変更を検出します。

LSP サーバーの定義を更新したり、新しい言語を追加したりするには、README.md の開発者向けドキュメントを参照してください。

---

実行手順（Claude Code 向け）

このスキルが /lsp-setup または起動キーワードによって有効になったら、次のワークフローを実行します。

フェーズ 1：言語の検出

from pathlib import Path
from lsp_setup import LanguageDetector

# Detect languages in current project
detector = LanguageDetector()
project_root = Path.cwd()
languages = detector.detect_languages(project_root)

# Report findings
print(f"Detected {len(languages)} language(s):")
for lang in languages:
    print(f"  - {lang.language}: {lang.file_count} files")

フェーズ 2：現在のステータスを確認

from lsp_setup import StatusTracker

# Get current LSP setup status
language_names = [lang.language for lang in languages]
tracker = StatusTracker(project_root, language_names)
status = tracker.get_full_status()

# Show status
print(tracker.generate_user_guidance())

フェーズ 3：LSP を設定（必要な場合）

from lsp_setup import LSPConfigurator

# Configure .env file
configurator = LSPConfigurator(project_root)

# Enable LSP
if not configurator.is_lsp_enabled():
    configurator.enable_lsp()
    print("✓ Enabled LSP in .env")

フェーズ 4：プラグインをインストール（必要な場合）

from lsp_setup import PluginManager

# Install Claude Code plugins for detected languages
manager = PluginManager()

# Check prerequisites
if not manager.check_npx_available():
    print("⚠ npx not found. Install Node.js first:")
    print("  macOS: brew install node")
    print("  Linux: sudo apt install nodejs")
    exit(1)

# Install plugins for languages with missing Layer 2
for lang_name in language_names:
    layer_2_status = status["layer_2"][lang_name]
    if not layer_2_status["installed"]:
        print(f"Installing {lang_name} plugin...")
        success = manager.install_plugin(lang_name)
        if success:
            print(f"✓ {lang_name} plugin installed")
        else:
            print(f"✗ Failed to install {lang_name} plugin")
            print(f"  {layer_2_status.get('install_guide', 'See docs')}")

フェーズ 5：最終ステータスレポート

# Recheck status after installation
final_status = tracker.get_full_status()

if final_status["overall_ready"]:
    print("\n✅ LSP setup complete! All layers configured.")
else:
    print("\n⚠ LSP partially configured. Next steps:")
    print(tracker.generate_user_guidance())

コマンドライン引数（任意）

ユーザーから指定された場合は、次の引数に対応します。

• --status-only：インストールをスキップし、現在のステータスのみを報告します
• --force：すでにインストール済みであっても、すべてのプラグインを再インストールします
• --languages <lang1,lang2>：指定された言語のみを設定します
• --dry-run：変更を行わず、実行される内容を表示します