VoDmAl Composer Scripts MCP Server

VoDmAl Composer Scripts MCP サーバー

プロジェクトの Composer スクリプトを MCP（Model Context Protocol）ツールとして公開する PHP ライブラリです。インストールすると、AI アシスタント（または任意の MCP クライアント）が Composer スクリプトを自動的に検出して実行できるため、コマンドをその都度説明する必要がありません。

あらゆる PHP プロジェクトで利用でき、複数のプロジェクトを無制限に接続できます。各プロジェクトの MCP ツール名は、composer.json（たとえば "name" フィールド）から自動的に決定されます。

Composer スクリプトを使う理由

Composer スクリプトを使うと、追加の依存関係を導入せずに、一般的なタスク（テスト、リンティング、コード生成など）を標準化して自動化できます。主なメリットは次のとおりです。

• 追加の依存関係が不要：composer install の後、すぐにスクリプトを利用できます。
• 一貫したインターフェース：OS やローカル環境の設定にかかわらず、チームメンバー全員が同じコマンドを使えます。
• ワークフローを自己文書化：composer.json が、利用可能なコマンドのドキュメントも兼ねます。
• クロスプラットフォーム：スクリプトは macOS、Linux、Windows で一貫して実行されます。

この方法には多くの利点がありますが、いくつか制約もあります。

• プロジェクトごとのスクリプト名を覚えておく必要があります
• 複雑なスクリプトチェーンは、単独のツールよりデバッグが難しい場合があります
• ネイティブバイナリより、パフォーマンスがやや遅い場合があります

こうした小さな欠点はあるものの、外部の依存関係を追加せずに composer install の直後からコマンドを利用できる利便性は、大きなメリットです。このツールを使えば、コマンドをその都度説明しなくても、AI アシスタントが Composer スクリプトを検出して実行できます。

実際の使用例

実際のプロジェクトで Composer スクリプトを活用する例を紹介します。

"scripts": {
    "check:before:commit": [
        "@test",
        "@check:code:style",
        "@check:code:static",
        "@check:code:dependency"
    ],
    "check:before:push": [
        "@check:config",
        "@check:before:commit",
        "@check:code:security"
    ],
    "check:code:static": [
        "@check:code:lint",
        "@rector",
        "@psalm",
        "@phpstan",
        "@classleak",
        "@check:code:comments"
    ],
    "test": [
        "@test:unit:phpunit"
    ],
    "test:unit:phpunit": [
        "@phpunit --testsuite Unit"
    ],
    "phpunit": "./vendor/bin/phpunit"
}

これらのスクリプトを使うと、開発者は composer check:before:commit のような簡単なコマンドで、コミットやコードのプッシュ前に包括的なチェックを実行できます。MCP サーバーはこれらのスクリプトを AI アシスタントに公開するため、プロジェクト固有のテストや検証手順をその都度説明しなくても、適切なコマンドを理解して実行できます。

この方法の最大のメリットの一つは、テストの実行方法やコードスタイルの確認方法、その他の一般的な開発タスクの実行方法を、LLM に何度も説明する必要がないことです。代わりに、LLM は MCP サーバーを通じて利用可能なコマンドを検出し、実行するタスクに適したコマンドを提案できます。これにより、PHP プロジェクトで AI アシスタントを活用する際の時間を節約し、手間を軽減できます。

機能

VoDmAl Composer Scripts MCP Server をインストールすると、次の2つの大きなメリットがあります。

1. プロジェクト内のすべての Composer スクリプトを MCP ツールとして自動検出できます。
2. AI アシスタント（例：Claude Desktop）とワンステップで連携でき、手動で設定しなくても、あらゆるスクリプトの一覧表示と実行が可能になります。

• composer.json から Composer スクリプトを自動的に読み込みます
• 検出して実行できる MCP ツールとしてスクリプトを公開します
• stdio と HTTP の両トランスポートに対応しています
• あらゆる PHP プロジェクトと簡単に連携できます
• インストール時に、プロジェクトの composer.json へスクリプトを自動的に追加します

要件

• PHP 8.1 以上
• Composer
• php-mcp/server ^2.1

簡単なインストールと自動セットアップ

開始するには、次を実行します。

composer require vodmal/composer-scripts-mcp-server
composer install

Composer の処理が完了すると、プロジェクトの composer.json に新しいスクリプトが 2 つ追加されます。

"scripts": {
    "mcp:server:start": "vendor/bin/mcp-server-start",
    "mcp:server:install": "vendor/bin/mcp-server-install"
}

これで必要なものはすべて揃いました。composer mcp:server:start をすぐに実行する必要はありません。代わりに、Claude Desktop（または MCP 互換の LLM）と連携する場合は、次を実行します。

composer mcp:server:install

Claude Desktop がインストールされていて、その設定ファイルが検出されると、このコマンドによって MCP の設定が自動的にマージされます。

Claude の設定が見つからない場合は、JSON のスニペットが出力されます。そのスニペットを claude_config.json の "tools" の下に貼り付け、Claude を再起動してください。

任意の数のプロジェクトに接続 PHP プロジェクトの各フォルダーで composer mcp:server:install を回数無制限に実行できます。各プロジェクトのツール名には、それぞれの composer.json の "name" フィールドが使われるため、複数のプロジェクトが Claude のツール一覧に別々に表示されます。

Claude を使用していない場合 次を実行すると、

composer mcp:server:install

MCP サーバーの起動方法を示す JSON ブロックが出力されます。必要な LLM または MCP クライアントの設定にコピーしてください。設定が完了すると、AI アシスタントは追加のセットアップなしで composer_list と composer_run の MCP メソッドを呼び出せます。

高度な手動設定と起動

stdio トランスポートを使用する場合

stdio トランスポートでサーバーを起動するには（AI アシスタントとの連携用）：

vendor/bin/mcp-server-start

HTTP トランスポートを使用する場合

HTTP トランスポートでサーバーを起動するには（クライアントでのテスト用）：

vendor/bin/mcp-server-start --http [--host=<host>] [--port=<port>]

デフォルトでは、サーバーは 127.0.0.1:8088 でリッスンします。

Claude Desktop との連携

この MCP サーバーを Claude Desktop と連携するには、提供されている mcp-server-install コマンドを使用できます。

vendor/bin/mcp-server-install

このコマンドはオペレーティングシステムを自動検出し、Claude Desktop の設定ファイルを検索します。見つかった場合は、MCP サーバーの設定が含まれるように更新します。見つからない場合は、Claude Desktop の設定ファイルに手動でマージする必要がある設定を出力します。サーバーは、プロジェクト内のすべての Composer スクリプトを MCP ツールとして自動的に公開します。

コマンドオプション

• --output=<file>：カスタム出力ファイルを指定します（デフォルトでは、コマンドはお使いの OS 用の Claude Desktop 設定ファイルを検索します）
• --name=<name>：サーバー名を指定します（デフォルト：composer.json のプロジェクト名）

複数のサーバー

このライブラリをインストールした PHP プロジェクトが複数ある場合は、それぞれを同じ設定ファイルに追加できます。

# In project1
vendor/bin/mcp-server-install --name=project1

# In project2
vendor/bin/mcp-server-install --name=project2 --output=/path/to/claude_desktop_config.json

設定の使用

1. Claude Desktop を完全に再起動します
2. 再起動後、入力ボックスの左下にスライダーアイコンが表示されます
3. スライダーアイコンをクリックすると、利用可能なツール（Composer スクリプト）が表示されます
4. Claude に Composer スクリプトを実行するよう依頼できるようになります

トラブルシューティング

Claude Desktop がサーバーを認識しない場合：

1. Claude Desktop が最新バージョンであることを確認します
2. 設定ファイルの構文が正しいことを確認します
3. 設定内のファイルパスが有効な絶対パス（相対パスではない）であることを確認します
4. ログを確認して、サーバーが接続できない理由を調べます：
   • macOS：~/Library/Logs/Claude
   • Windows：%APPDATA%\Claude\logs
5. 次を手動で実行し、エラーが発生するか確認します：

   vendor/bin/mcp-server-start
   

注： LLM アプリケーションで stdio トランスポートを使用する場合、すべてのログメッセージは stdout ではなく stderr に書き込まれます。これにより、ログメッセージがサーバーと LLM アプリケーション間の JSON 通信に干渉し、JSON の解析エラーが発生するのを防ぎます。

利用可能な MCP ツール

このライブラリでは、次の MCP ツールを利用できます。

composer_list

利用可能な Composer スクリプトをすべて一覧表示します。

パラメーター： なし

戻り値：

• scripts：スクリプト情報（名前とコマンド）の配列
• count：利用可能なスクリプトの数

composer_run

Composer スクリプトを実行します。

パラメーター：

• script（string、必須）：実行するスクリプトの名前
• arguments（array、任意）：スクリプトに渡す追加の引数

戻り値：

• script：実行したスクリプトの名前
• command：実行したコマンド
• output：コマンドの出力
• return_code：コマンドの戻りコード
• success：コマンドが成功したかどうか（戻りコードが 0）

ライセンス

このプロジェクトはデュアルライセンスです。

オープンソースライセンス

このプロジェクトは、オープンソースでの利用に限り、GNU General Public License v3.0（GPL-3.0）のもとでライセンスされています。詳細は LICENSE-GPL ファイルをご覧ください。

商用ライセンス

プロプライエタリソフトウェアでの商用利用には、別途商用ライセンスをご利用いただけます。商用ライセンスの条件については、[ваш email] までお問い合わせください。

ライセンスの概要

• GPL-3.0：GPL-3.0 のもとでライセンスされているオープンソースプロジェクトであれば無料で利用できます
• Commercial：GPL の制限を受けずにプロプライエタリ／商用利用するための有料ライセンス

どのライセンスがお客様の利用ケースに適用されるか不明な場合は、お問い合わせください。