laravel-mcp

Laravel MCP スキル

Laravel MCP（Model Context Protocol）開発を幅広く支援します。Laravel MCP は、Model Context Protocol を通じて AI クライアントが Laravel アプリケーションとやり取りするための、シンプルで洗練された方法を提供します。これにより、AI を活用したインタラクション向けにサーバー、ツール、リソース、プロンプトを定義できます。

このスキルを使用する場面

次のような場合に、このスキルを使用してください。

• Laravel アプリケーション向けに MCP サーバーを構築する
• Laravel でアクションを実行する AI ツールを作成する
• AI とのインタラクションに使える再利用可能なプロンプトを定義する
• Laravel のリソース（データ／コンテンツ）を AI クライアントに公開する
• MCP 向けに OAuth 2.1 または Sanctum 認証を実装する
• MCP ルート（web または local）を登録して設定する
• MCP サーバーとツールをテストする
• ツール入力向けに Laravel JSON Schema ビルダーを使用する
• ストリーミング応答や進捗通知を実装する
• MCP を使用して AI を活用した Laravel 機能を構築する

主な概念

コアコンポーネント

MCP サーバー：MCP の機能を公開する中心的な通信ポイントです。各サーバーには次の項目があります。

• name：サーバー識別子
• version：サーバーのバージョン
• instructions：サーバーの目的の説明
• tools：ツールクラスの配列
• resources：リソースクラスの配列
• prompts：プロンプトクラスの配列

ツール：AI クライアントがアクションを実行できるようにします。ツールでは次のことができます。

• Laravel の JSON Schema ビルダーを使用して入力スキーマを定義する
• Laravel のバリデーションルールで引数を検証する
• 依存性注入をサポートする
• 単一または複数の応答を返す
• ジェネレーターを使用して応答をストリーミングする
• #[IsReadOnly] や #[IsIdempotent] などのアノテーションを使用する

プロンプト：共通のクエリを構造化する標準的な方法を提供する、再利用可能なプロンプトテンプレートです。引数の定義と検証にも対応します。

リソース：AI クライアントが読み取れるデータやコンテンツをサーバーから公開できます。カスタマイズ可能な MIME タイプと URI を使用したテキストおよび blob 応答に対応します。

クイックリファレンス

1. 基本的な MCP サーバーの定義

<?php
namespace App\Mcp\Servers;

use Laravel\Mcp\Server;

class WeatherServer extends Server
{
    protected string $name = 'Weather Server';
    protected string $version = '1.0.0';
    protected string $instructions = 'This server provides weather information and forecasts.';

    protected array $tools = [
        // CurrentWeatherTool::class,
    ];

    protected array $resources = [
        // WeatherGuidelinesResource::class,
    ];

    protected array $prompts = [
        // DescribeWeatherPrompt::class,
    ];
}

2. 入力スキーマを持つツール

<?php
namespace App\Mcp\Tools;

use Illuminate\JsonSchema\JsonSchema;
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Tool;

class CurrentWeatherTool extends Tool
{
    protected string $description = 'Fetches the current weather forecast for a specified location.';

    public function handle(Request $request): Response
    {
        $location = $request->get('location');
        // Get weather...
        return Response::text('The weather is...');
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'location' => $schema->string()
                ->description('The location to get the weather for.')
                ->required(),
        ];
    }
}

3. バリデーション付きのツール

public function handle(Request $request): Response
{
    $validated = $request->validate([
        'location' => 'required|string|max:100',
        'units' => 'in:celsius,fahrenheit',
    ], [
        'location.required' => 'You must specify a location.',
        'units.in' => 'You must specify either "celsius" or "fahrenheit".',
    ]);
    // Fetch weather data...
}

4. 依存性注入を使用するツール

<?php
namespace App\Mcp\Tools;

use App\Repositories\WeatherRepository;
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Tool;

class CurrentWeatherTool extends Tool
{
    public function __construct(
        protected WeatherRepository $weather,
    ) {}

    public function handle(Request $request, WeatherRepository $weather): Response
    {
        $location = $request->get('location');
        $forecast = $weather->getForecastFor($location);
        // ...
    }
}

5. アノテーション付きのツール

<?php
namespace App\Mcp\Tools;

use Laravel\Mcp\Server\Tools\Annotations\IsIdempotent;
use Laravel\Mcp\Server\Tools\Annotations\IsReadOnly;
use Laravel\Mcp\Server\Tool;

#[IsIdempotent]
#[IsReadOnly]
class CurrentWeatherTool extends Tool
{
    // ...
}

6. 応答をストリーミングするツール

<?php
namespace App\Mcp\Tools;

use Generator;
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Tool;

class CurrentWeatherTool extends Tool
{
    public function handle(Request $request): Generator
    {
        $locations = $request->array('locations');

        foreach ($locations as $index => $location) {
            yield Response::notification('processing/progress', [
                'current' => $index + 1,
                'total' => count($locations),
                'location' => $location,
            ]);
            yield Response::text($this->forecastFor($location));
        }
    }
}

7. プロンプトの定義

<?php
namespace App\Mcp\Prompts;

use Laravel\Mcp\Server\Prompt;
use Laravel\Mcp\Server\Prompts\Argument;

class DescribeWeatherPrompt extends Prompt
{
    protected string $description = 'Generates a natural-language explanation of the weather.';

    public function arguments(): array
    {
        return [
            new Argument(
                name: 'tone',
                description: 'The tone to use in the weather description.',
                required: true,
            ),
        ];
    }

    public function handle(Request $request): array
    {
        $tone = $request->string('tone');
        return [
            Response::text("You are a weather assistant. Provide a {$tone} tone.")->asAssistant(),
            Response::text("What is the current weather like in New York City?"),
        ];
    }
}

8. リソースの定義

<?php
namespace App\Mcp\Resources;

use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Resource;

class WeatherGuidelinesResource extends Resource
{
    protected string $description = 'Comprehensive guidelines for using the Weather API.';
    protected string $uri = 'weather://resources/guidelines';
    protected string $mimeType = 'application/pdf';

    public function handle(Request $request): Response
    {
        return Response::text($weatherData);
    }
}

9. サーバーの登録（Web）

use App\Mcp\Servers\WeatherServer;
use Laravel\Mcp\Facades\Mcp;

Mcp::web('/mcp/weather', WeatherServer::class);

// With middleware
Mcp::web('/mcp/weather', WeatherServer::class)
    ->middleware(['throttle:mcp']);

10. サーバーの登録（Local）

use App\Mcp\Servers\WeatherServer;
use Laravel\Mcp\Facades\Mcp;

Mcp::local('weather', WeatherServer::class);

11. OAuth 2.1 認証の設定

use App\Mcp\Servers\WeatherExample;
use Laravel\Mcp\Facades\Mcp;

Mcp::oauthRoutes();

Mcp::web('/mcp/weather', WeatherExample::class)
    ->middleware('auth:api');

12. Sanctum 認証

use App\Mcp\Servers\WeatherExample;
use Laravel\Mcp\Facades\Mcp;

Mcp::web('/mcp/demo', WeatherExample::class)
    ->middleware('auth:sanctum');

リファレンスファイル

このスキルには、references/ に充実したドキュメントが含まれています。

• other.md - Laravel 12.x の公式ドキュメントに基づく、Laravel MCP の完全なドキュメントです。次の内容を含みます。
  • インストールとセットアップの手順
  • サーバー、ツール、リソース、プロンプトの作成
  • JSON Schema ビルダーを使用した入力スキーマの定義
  • バリデーションと依存性注入
  • ストリーミング応答と進捗通知
  • 認証（OAuth 2.1 と Sanctum）
  • 登録（web および local ルート）
  • テストと検査

詳細が必要な場合は、view を使用して該当するリファレンスファイルを読んでください。

このスキルの活用

初心者向け

まず、コアコンセプトを理解しましょう。

1. インストール：composer require laravel/mcp で Laravel MCP をインストールします
2. セットアップ：php artisan vendor:publish --tag=ai-routes を実行して routes/ai.php を作成します
3. 最初のサーバー：php artisan make:mcp-server で最初のサーバーを生成します
4. 登録：Mcp::web() または Mcp::local() を使って、routes/ai.php にサーバーを追加します

データを変更するツールに進む前に、#[IsReadOnly] アノテーションを使ったシンプルな読み取り専用ツールから始めましょう。

中級者向け

堅牢なツールの構築に重点を置きましょう。

• JSON Schema ビルダーを使って、入力を正確に検証する
• Laravel のバリデーションルールを活用して、複雑な制約に対応する
• 依存性注入を実装し、コードをすっきりとテストしやすくする
• プロンプトを使って、再利用可能な AI インタラクションパターンを作成する
• リソースを公開して、AI クライアントにコンテキストを提供する

上級ユーザー向け

本番環境で使用できる機能を実装します。

• OAuth 2.1 または Sanctum 認証を追加して、MCP サーバーを保護します
• 進捗通知を伴う長時間実行操作には、ストリーミングレスポンスを使用します
• ミドルウェアを適用して、レート制限とカスタム認証を行います
• #[IsIdempotent] アノテーションを使用して、冪等性のあるツールを作成します
• 複雑な複数ツールのワークフローを構築します
• デバッグとテストには MCP Inspector を使用します

ナビゲーションのヒント

• すぐに実装する：よく使うパターンについては、上記のクイックリファレンスセクションを使用します
• 詳しく学ぶ：包括的なドキュメントについては、references/other.md を読んでください
• 例：すべてのコード例には、適切な名前空間とインポートが含まれています
• テスト：MCP Inspector の使用方法と単体テストについては、ドキュメントを参照してください

よく使うパターン

新しい MCP サーバーの作成

# Generate server class
php artisan make:mcp-server WeatherServer

# Edit app/Mcp/Servers/WeatherServer.php
# Add tools, resources, and prompts

# Register in routes/ai.php
Mcp::web('/mcp/weather', WeatherServer::class);

入力スキーマのパターン

// Simple required string
'location' => $schema->string()->required()

// Optional with default
'units' => $schema->string()->default('celsius')

// Number with constraints
'temperature' => $schema->number()->minimum(0)->maximum(100)

// Array of items
'cities' => $schema->array()->items($schema->string())

// Object with properties
'forecast' => $schema->object()->properties([
    'temperature' => $schema->number(),
    'humidity' => $schema->number(),
])

レスポンスのパターン

// Text response
return Response::text('The weather is sunny');

// Multiple responses
return [
    Response::text('First message'),
    Response::text('Second message'),
];

// Notification (streaming)
yield Response::notification('processing/progress', ['status' => 'processing']);

リソース

インストール

composer require laravel/mcp
php artisan vendor:publish --tag=ai-routes

公式ドキュメント

• Laravel MCP Docs：https://laravel.com/docs/12.x/mcp
• Model Context Protocol Spec：https://modelcontextprotocol.io/

関連する Laravel の機能

• JSON Schema Builder：ツールの入力スキーマを定義します
• 検証：ツールの引数を検証します
• サービスコンテナ：ツールとリソースへの依存性注入に使用します
• OAuth/Sanctum：認証に使用します

注意事項

• このスキルは、Laravel 12.x の公式 MCP ドキュメントから生成されています
• すべてのコード例では、型付きプロパティを使った適切な PHP 8+ 構文を使用しています
• 例では、Laravel の洗練された API 設計を紹介しています
• ツールは同期レスポンスとストリーミングレスポンスの両方に対応しています
• 認証は任意ですが、本番環境での使用には推奨されます
• Web（HTTP）とローカル（CLI）の両方のサーバー登録に対応しています

ヒントとベストプラクティス

1. シンプルに始める：まずは #[IsReadOnly] を付けた読み取り専用ツールから始めます
2. 入力を検証する：常にスキーマを定義し、ユーザー入力の検証を行います
3. DI を使用する：依存性注入を活用して、リポジトリやサービスを利用します
4. 進捗をストリーミングする：時間のかかる操作では、ジェネレーターを使用して進捗をストリーミングします
5. サーバーを保護する：本番環境では認証ミドルウェアを追加します
6. 徹底的にテストする：MCP Inspector と単体テストを使用して、機能を検証します
7. 適切にドキュメントを作成する：サーバー、ツール、プロンプト、リソースの説明を明確に記述します
8. 規約に従う：Laravel のサービスコンテナのパターンと命名規則を使用します