Laravel MCP Server (bramato/laravel-mcp-server)

Laravel MCP Server (bramato/laravel-mcp-server)

Model Context Protocol (MCP) サーバーを構築するための、Laravel の基本パッケージです。

このパッケージは、さまざまなトランスポート（Stdio、HTTP、Reverb 経由の WebSocket）で MCP リクエストを処理するための基本的なインフラストラクチャを提供します。堅牢な JSON-RPC 2.0 リクエストの解析とレスポンスのフォーマットには、優れたライブラリである sajya/server を内部で使用しています。

MCP の仕様に従ってアプリケーションのデータや機能を公開するには、独自の ResourceInterface クラスと ToolInterface クラス（Bramato\\LaravelMcpServer\\Mcp\\Interfaces 名前空間を使用）を実装し、設定ファイルに登録する必要があります。

インストール

composer を使ってパッケージをインストールできます。

composer require bramato/laravel-mcp-server

次に、vendor:publish Artisan コマンドを使って設定ファイルを公開します。

php artisan vendor:publish --provider="Bramato\LaravelMcpServer\Providers\McpServiceProvider" --tag="config"

これにより、アプリケーションの設定ディレクトリに config/mcp.php ファイルが作成され、サーバーの動作をカスタマイズできるようになります。

設定

config/mcp.php ファイルでは、次の項目を設定できます。

• enabled_transports：有効にするトランスポート（stdio、http、websocket）を選択します。
• transports：各トランスポートの詳細を設定します（例：transports.http.path の HTTP パス）。
• authentication：基本認証を設定します（authentication.driver で none または token を指定できます）。トークン認証の場合は、authentication.options.header でヘッダー名を指定します。
• resources：MCP リソースを登録します。 Bramato\\LaravelMcpServer\\Mcp\\Interfaces\\ResourceInterface を実装する完全修飾クラス名の配列を指定します。
• tools：MCP ツールを登録します。 Bramato\\LaravelMcpServer\\Mcp\\Interfaces\\ToolInterface を実装する完全修飾クラス名の配列を指定します。これは実行可能なツールの許可リストとして機能します。
• logging：パッケージ固有のログに使用するロギングチャンネルとレベルを設定します。

リソースとツールの作成

このパッケージではインターフェースを提供しますが、実際のロジックは実装する必要があります。

例：リソースの作成

1. リソースクラスを作成します（例：app/Mcp/Resources/UserProfileResource.php）。

   namespace App\Mcp\Resources;
   
   use Bramato\LaravelMcpServer\Mcp\Interfaces\ResourceInterface;
   use Illuminate\Support\Facades\Auth;
   
   class UserProfileResource implements ResourceInterface
   {
       public function getUri(): string { return 'user://profile'; } // このリソース固有の URI
       public function getName(): string { return 'User Profile'; }
       public function getDescription(): string { return 'Provides information about the authenticated user.'; }
       public function getMimeType(): string { return 'application/json'; }
   
       public function getContents(): mixed
       {
           $user = Auth::user(); // 例：認証済みユーザーを取得
           if (!$user) {
               return null; // または、エラーに対応付けられた例外をスロー
           }
           return [
               'id' => $user->id,
               'name' => $user->name,
               'email' => $user->email,
           ];
       }
   }
   

2. config/mcp.php に登録します。

   // config/mcp.php
   return [
       // ... other config
       'resources' => [
           \App\Mcp\Resources\UserProfileResource::class,
       ],
       // ...
   ];
   

例：ツールの作成

1. ツールクラスを作成します（例：app/Mcp/Tools/SendNotificationTool.php）。

   namespace App\Mcp\Tools;
   
   use Bramato\LaravelMcpServer\Mcp\Interfaces\ToolInterface;
   // use App\Jobs\ProcessNotificationJob; // 例：ジョブ
   use Illuminate\Support\Facades\Log;
   
   class SendNotificationTool implements ToolInterface
   {
       public function getName(): string { return 'sendNotification'; }
       public function getDescription(): string { return 'Sends a notification to a user.'; }
   
       public function getInputSchema(): array
       {
           // JSON Schema 形式で想定されるパラメーターを定義
           return [
               'type' => 'object',
               'properties' => [
                   'user_id' => ['type' => 'integer', 'description' => 'ID of the target user'],
                   'message' => ['type' => 'string', 'description' => 'The notification message content'],
               ],
               'required' => ['user_id', 'message'],
           ];
       }
   
       public function execute(array $arguments): mixed
       {
           Log::info('Executing sendNotification tool', $arguments);
           // ** ここにロジックを追加 **
           // 例：入力を検証し、ユーザーを検索して、ジョブをディスパッチ
           // ProcessNotificationJob::dispatch($arguments['user_id'], $arguments['message']);
           return ['status' => 'queued', 'user_id' => $arguments['user_id']];
       }
   }
   

2. config/mcp.php に登録します。

   // config/mcp.php
   return [
       // ... other config
       'tools' => [
           \App\Mcp\Tools\SendNotificationTool::class,
       ],
   ];
   

使用方法

サーバーの実行方法は、有効になっているトランスポートによって異なります。

• Stdio：Artisan コマンドを実行します：php artisan mcp:server --transport=stdio。
• HTTP：ウェブサーバー（例：php artisan serve または Nginx/Apache）が実行中であることを確認します。mcp.transports.http.path で設定されたパス（デフォルト：/mcp-rpc）に JSON-RPC POST リクエストを送信します。
• WebSocket（Reverb）：
  1. メインアプリケーションに Laravel Reverb をインストールして設定します：php artisan reverb:install。
  2. config/mcp.php の enabled_transports に websocket トランスポートが指定されていることを確認します。
  3. Reverb サーバーを起動します：php artisan reverb:start。
  4. MCP WebSocket クライアントを Reverb サーバーのエンドポイントに接続します（Reverb の設定を確認してください）。

テスト

このパッケージには、PHPUnit と Orchestra Testbench を使用した基本的なテストスイートが含まれています。

# From the package directory (packages/bramato/laravel-mcp-server)
../../vendor/bin/phpunit

# Or from the project root
./vendor/bin/phpunit packages/bramato/laravel-mcp-server/tests

セキュリティに関する考慮事項

MCP 仕様では、クライアントとサーバー間の認証または認可の仕組みは定義されていません。このパッケージでは、次の機能を提供しています。

• ツールのホワイトリスト登録：config/mcp.php の tools 配列に明示的に記載されたツールのみ実行できます。
• 基本的なトークン認証：authentication 設定セクションで、トークンベースの認証を有効にできます。

重要：ToolInterface::execute メソッドと ResourceInterface::getContents メソッド内で、きめ細かな認可ロジックを実装する責任はお客様にあります。Laravel の Gate と Policy、またはその他の認可の仕組みを使用して、リクエスト元のクライアントが特定のリソースへのアクセスや特定のツールの実行に必要な権限を持っていることを確認してください。

貢献

詳細については、CONTRIBUTING.md をご覧ください（利用可能な場合）。

ライセンス

MIT ライセンス（MIT）。詳しくは、LICENSE.md ファイルをご覧ください。