Laravel MCP Server (bramatolaravel MCP Server)

🚀 Laravel MCP サーバー

Laravel MCP サーバーは、モデルコンテキストプロトコル（Model Context Protocol、略称 MCP）に基づく拡張パッケージです。Laravel アプリケーションに、モデルリソースの管理とツール実行のための統一インターフェースを提供します。このプロトコルは、クライアントとサーバー間のやり取り方法を定義し、クライアントが標準的な方法でモデルデータを要求したり、特定の操作を実行したりできるようにします。

🚀 クイックスタート

📦 インストール

依存関係のインストール

Laravel プロジェクトで Laravel MCP サーバーを使用するには、まず以下の依存関係をインストールしてください。

composer require bramato/laravel-mcp-server

設定ファイルの公開

パッケージの設定ファイルをプロジェクトの設定ディレクトリに公開します。

php artisan vendor:publish --provider="Bramato\LaravelMcpServer\ServiceProvider"

インストール完了後

インストールが完了したら、config/mcp.php ファイルを必要に応じて設定してください。

💻 使用例

MCP サーバーの起動

標準入出力（Stdio）

標準入出力に基づく MCP サーバーを起動するには、コンソールで以下のコマンドを実行します。

php artisan mcp:server --transport=stdio

これにより、標準入力でリクエストを送信し、標準出力でレスポンスを受け取ることができる対話型の MCP サーバーが起動します。

HTTP ランタイム

HTTP ランタイムを有効にするには、MCP の HTTP パスを設定してください。デフォルトでは、MCP は /mcp-rpc パスで HTTP リクエストを処理します。Laravel 開発サーバーを起動するか、リバースプロキシを設定した後、このパスに POST リクエストを送信することで MCP サービスとやり取りできます。

WebSocket（Reverb 経由）

WebSocket サポートを有効にするには、まず Laravel の Reverb 拡張パッケージをインストールして設定してください。

php artisan reverb:install

次に、config/mcp.php ファイルの enabled_transports 配列に websocket を追加し、Reverb サーバーを起動します。

php artisan reverb:start

🔧 セキュリティに関する注意事項

MCP プロトコル自体は、クライアントとサーバー間の認証や承認メカニズムを定義していません。そのため、以下のセキュリティ機能を提供して、MCP サービスを保護します。

• ツールホワイトリスト：config/mcp.php ファイルで明示的にリストされたツールのみが実行できます。
• 基本的なトークン認証：設定により、トークンベースの認証を有効にできます。

⚠️ 重要提示

クライアントのリクエストがアプリケーションの権限ポリシーに沿っていることを確認するために、細かい承認ロジックを独自に実装する必要があります。Laravel の Gates と Policies を使用してこれらの権限を管理することをお勧めします。

🧪 テスト

テストスイートの実行

組み込みの PHPUnit テストスイートを実行するには、以下の手順に従ってください。

パッケージディレクトリで実行

../../vendor/bin/phpunit

プロジェクトのルートディレクトリで実行

./vendor/bin/phpunit packages/bramato/laravel-mcp-server/tests

カスタムテストの作成

MCP サービスの機能が正常に動作することを確認するために、カスタムの統合テストを作成することをお勧めします。tests/_factory.php ファイルの例を参考に、MCP クライアントインスタンスを作成して構成し、さまざまなリクエストを送信して、予期される動作を検証できます。

⚙️ 設定オプション

以下は、MCP サーバーの主な設定オプションです。

return [
    // 有効なトランスポート方式
    'enabled_transports' => ['http', 'stdio', 'websocket'],

    // HTTP 関連の設定
    'http' => [
        'path' => '/mcp-rpc',
        'middleware' => [
            \Bramato\LaravelMcpServer\Http\Middleware\McpAuthentication::class,
        ],
    ],

    // WebSocket 関連の設定（Reverb を使用する場合のみ有効）
    'websocket' => [
        'driver' => 'reverb',
        'prefix' => 'mcp-ws',
    ],

    // リソースとツールの定義
    'resources' => [
        // サンプルリソースの定義
        'example.resource' => [
            'description' => 'これはサンプルリソースです',
            'schema' => [
                // リソースの入力と出力のスキーマを定義
            ],
        ],
    ],

    'tools' => [
        // サンプルツールの定義
        'example.tool' => [
            'description' => 'これは特定の操作を実行するためのサンプルツールです',
            'parameters' => [
                // ツールに必要なパラメータを定義
            ],
        ],
    ],
];

📝 リソースの作成

基本構造

各リソースは、以下の属性を含む必要があります。

public function __construct() {
}

/**
 * リソースのメタデータを取得します。
 *
 * @return array
 */
public function meta(): array {
    return [];
}

/**
 * 指定されたモデルインスタンスのデータを取得します。
 *
 * @param Model $model
 * @return mixed
 */
public function get(Model $model) {
    // モデルデータを返します
}

/**
 * クライアントからのリソースリクエストを処理します。
 *
 * @param Request $request
 * @return Response
 */
public function handle(Request $request): Response {
    // リクエストタイプに応じた処理ロジック
}

⚒️ ツールの作成

基本構造

各ツールは、以下の属性を含む必要があります。

public function __construct() {
}

/**
 * ツールのメタデータを取得します。
 *
 * @return array
 */
public function meta(): array {
    return [];
}

/**
 * ツールの操作を実行します。
 *
 * @param array $parameters
 * @return mixed
 */
public function execute(array $parameters) {
    // 実行結果を返します
}

💻 使用例

クライアントコードの例

use Bramato\LaravelMcpServer\Client\McpClient;

$client = new McpClient('http://localhost:8000/mcp-rpc');

// リソースデータを取得する
$response = $client->get('example.resource', $modelId);
echo json_encode($response);

// ツール操作を実行する
$response = $client->execute('example.tool', [
    'parameter1' => 'value1',
]);
echo json_encode($response);

サーバーサイドコードの例

use Bramato\LaravelMcpServer\Resource\McpResource;
use Bramato\LaravelMcpServer\Tool\McpTool;

class ExampleResource extends McpResource {
    public function get(Model $model) {
        // モデルデータを返す
        return [
            'id' => $model->id,
            'name' => $model->name,
        ];
    }
}

class ExampleTool extends McpTool {
    public function execute(array $parameters) {
        // ツール操作を実行する
        return 'Operation completed successfully';
    }
}

📚 その他のリソース

• 公式ドキュメント：Laravel MCP サーバードキュメント
• GitHub リポジトリ：Bramato/LaravelMcpServer