Laravel MCP Server by OP.GG

OP.GG による Laravel MCP サーバー

Laravel と Lumen でルートファーストの MCP サーバーを構築

公式ウェブサイト

英語 | ブラジルポルトガル語 | 韓国語 | ロシア語 | 簡体字中国語 | 繁体字中国語 | ポーランド語 | スペイン語

重大な変更 2.0.0

• エンドポイントの設定方法が、設定ファイルによる登録からルートによる登録に変更されました。
• サポートされるトランスポートは Streamable HTTP のみです。
• サーバーメタデータのミューテーターは setServerInfo(...) に統合されました。
• 従来のツールトランスポートメソッド（messageType()、ProcessMessageType::SSE）はランタイムから削除されました。

完全な移行ガイド：docs/migrations/v2.0.0-migration.md

概要

Laravel MCP Server は、Laravel と Lumen 向けにルートベースの MCP エンドポイント登録機能を提供します。

主なポイント：

• Streamable HTTP トランスポート
• ルートファーストの設定（Route::mcp(...) / McpRoute::register(...)）
• エンドポイントごとのツール、リソース、リソーステンプレート、プロンプトの登録
• ルートキャッシュに対応したエンドポイントメタデータ

要件

• PHP >= 8.2
• Laravel (Illuminate) >= 9.x
• Lumen >= 9.x（任意）

クイックスタート

1) インストール

composer require opgginc/laravel-mcp-server

2) エンドポイントを登録（Laravel）

use Illuminate\Support\Facades\Route;
use OPGG\LaravelMcpServer\Enums\ProtocolVersion;
use OPGG\LaravelMcpServer\Services\ToolService\Examples\HelloWorldTool;
use OPGG\LaravelMcpServer\Services\ToolService\Examples\VersionCheckTool;

Route::mcp('/mcp')
    ->setServerInfo(
        name: 'OP.GG MCP Server',
        version: '2.0.0',
    )
    ->setConfig(
        compactEnumExampleCount: 3,
    )
    ->setProtocolVersion(ProtocolVersion::V2025_11_25)
    ->enabledApi()
    ->tools([
        HelloWorldTool::class,
        VersionCheckTool::class,
    ]);

2025-11-25 に対応していないクライアントとの互換性が必要な場合は、次のように設定します。

->setProtocolVersion(ProtocolVersion::V2025_06_18)

3) 動作確認

php artisan route:list | grep mcp
php artisan mcp:test-tool --list --endpoint=/mcp

簡単な JSON-RPC チェック：

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

クエリ文字列によるツールの動的フィルタリング

受信 URL に応じて異なるツールセットを公開する必要がある場合は、動的ツールリゾルバーをルートに追加します。 リゾルバーは、エンドポイントで宣言されたツールカタログと、リクエストごとに表示するサブセットの両方を管理します。

use OPGG\LaravelMcpServer\Data\ToolResolutionContext;
use OPGG\LaravelMcpServer\Routing\McpEndpointDefinition;
use OPGG\LaravelMcpServer\Services\ToolService\DynamicToolResolverInterface;

final class LolPhaseToolResolver implements DynamicToolResolverInterface
{
    public function declaredTools(McpEndpointDefinition $endpoint): array
    {
        return [
            \App\MCP\Tools\LolSearchChampionMetaTool::class,
            \App\MCP\Tools\LolGetChampionAnalysisTool::class,
            \App\MCP\Tools\LolGetLiveItemRecommendationsTool::class,
        ];
    }

    public function resolve(
        McpEndpointDefinition $endpoint,
        ToolResolutionContext $context,
    ): array {
        return match ($context->queryParameters['phase'] ?? null) {
            'lobby' => [
                \App\MCP\Tools\LolSearchChampionMetaTool::class,
                \App\MCP\Tools\LolGetChampionAnalysisTool::class,
            ],
            'inprogress' => [
                \App\MCP\Tools\LolGetLiveItemRecommendationsTool::class,
            ],
            default => $this->declaredTools($endpoint),
        };
    }

    public function consumedQueryParameters(): array
    {
        return ['phase'];
    }
}

Route::mcp('/mcp/voice/lol/live')
    ->setServerInfo(
        name: 'OP.GG MCP Server - Voice lol Live',
        version: '1.0.0',
    )
    ->dynamicTools(LolPhaseToolResolver::class);

リクエストの例：

/mcp/voice/lol/live?phase=lobby
/mcp/voice/lol/live?phase=inprogress

同じフィルタリング済みツールセットが、次の項目に一貫して適用されます。

• tools/list
• tools/call
• tools/execute
• ->enabledApi() が有効な場合の POST /tools/{tool_name}

同じエンドポイントで POST /tools/{tool_name} も使用する場合、フィルタリング専用とし、ツール引数には渡さないクエリキーについて、リゾルバーにパブリックな consumedQueryParameters(): array フックを任意で公開できます。このフックはドキュメント化された規約であり、 DynamicToolResolverInterface の一部ではありません。フックを省略したリゾルバーでは、これらのクエリキーはツール引数として渡されます。

Lumen のセットアップ

// bootstrap/app.php
$app->withFacades();
$app->withEloquent();
$app->register(OPGG\LaravelMcpServer\LaravelMcpServerServiceProvider::class);

use OPGG\LaravelMcpServer\Routing\McpRoute;
use OPGG\LaravelMcpServer\Services\ToolService\Examples\HelloWorldTool;

McpRoute::register('/mcp')
    ->setServerInfo(
        name: 'OP.GG MCP Server',
        version: '2.0.0',
    )
    ->tools([
        HelloWorldTool::class,
    ]);

最小限のセキュリティ（本番環境）

MCP ルートグループに Laravel ミドルウェアを使用します。

use Illuminate\Support\Facades\Route;

Route::middleware([
    'auth:sanctum',
    'throttle:100,1',
])->group(function (): void {
    Route::mcp('/mcp')
        ->setServerInfo(
            name: 'Secure MCP',
            version: '2.0.0',
        )
        ->tools([
            \App\MCP\Tools\MyCustomTool::class,
        ]);
});

v2.0.0 移行に関する注意事項（v1.0.0 から）

• MCP エンドポイントの設定方法が、設定ファイルからルート登録に変更されました。
• サポートされるトランスポートは Streamable HTTP のみです。
• サーバーメタデータのミューテーターは setServerInfo(...) に統合されました。
• 従来のシグネチャ向けに、ツール移行コマンドを利用できます。

php artisan mcp:migrate-tools

完全なガイド：docs/migrations/v2.0.0-migration.md

高度な機能（クイックリンク）

• ツールを作成する：php artisan make:mcp-tool ToolName
• リソースを作成する：php artisan make:mcp-resource ResourceName
• リソーステンプレートを作成する：php artisan make:mcp-resource-template TemplateName
• プロンプトを作成する：php artisan make:mcp-prompt PromptName
• 通知を作成する：php artisan make:mcp-notification HandlerName --method=notifications/method
• OpenAPI から生成する：php artisan make:swagger-mcp-tool <spec-url-or-file>
• ツールを OpenAPI にエクスポートする：php artisan mcp:export-openapi --output=storage/api-docs-mcp/api-docs.json

コードの参照先：

• ツールの例：src/Services/ToolService/Examples/
• リソースの例：src/Services/ResourceService/Examples/
• プロンプトサービス：src/Services/PromptService/
• 通知ハンドラー：src/Server/Notification/
• ルートビルダー：src/Routing/McpRouteBuilder.php

Swagger/OpenAPI から MCP ツールへ

Swagger/OpenAPI 仕様から MCP ツールを生成します：

# From URL
php artisan make:swagger-mcp-tool https://api.example.com/openapi.json

# From local file
php artisan make:swagger-mcp-tool ./specs/openapi.json

便利なオプション：

php artisan make:swagger-mcp-tool ./specs/openapi.json \
  --group-by=tag \
  --prefix=Billing \
  --test-api

• --group-by：tag、path、または none
• --prefix：生成するツール／リソースのクラス名に付けるプレフィックス
• --test-api：生成前にエンドポイントへの接続をテストする

生成時の動作：

• 対話モードでは、エンドポイントごとにツールまたはリソースを選択できます。
• 非対話モードでは、GET エンドポイントはリソースとして、その他のメソッドはツールとして生成されます。

強化された対話型プレビュー

--group-by を指定せずにコマンドを実行すると、生成前にフォルダー構造とファイル数の対話型プレビューが表示されます。

php artisan make:swagger-mcp-tool ./specs/openapi.json

プレビュー出力の例：

Choose how to organize your generated tools and resources:

Tag-based grouping (organize by OpenAPI tags)
  Total: 25 endpoints -> 15 tools + 10 resources
  Examples: Tools/Pet, Tools/Store, Tools/User

Path-based grouping (organize by API path)
  Total: 25 endpoints -> 15 tools + 10 resources
  Examples: Tools/Api, Tools/Users, Tools/Orders

No grouping (everything in root folder)
  Total: 25 endpoints -> 15 tools + 10 resources
  Examples: Tools/, Resources/

生成後、生成されたツールクラスを MCP エンドポイントに登録します：

use Illuminate\Support\Facades\Route;

Route::mcp('/mcp')
    ->setServerInfo(
        name: 'Generated MCP Server',
        version: '2.0.0',
    )
    ->tools([
        \App\MCP\Tools\Billing\CreateInvoiceTool::class,
        \App\MCP\Tools\Billing\UpdateInvoiceTool::class,
    ]);

MCP ツールから OpenAPI へエクスポート

登録済みのすべての ToolInterface クラス（Route::mcp(...)->tools([...]) または ->dynamicTools(...) 経由）を、各ツールの inputSchema() を使用して OpenAPI JSON ドキュメントにエクスポートします。 このエクスポートに含まれ、POST /tools/{tool_name} 経由で公開されるのは、->enabledApi() が設定されたエンドポイントのみです。 オペレーションは OpenAPI の tags を使って、エンドポイントの name ごとにグループ化されます。 複数のエンドポイントで同じツール名が登録されている場合、オペレーションには最初に登録されたものが適用され、一致するすべてのエンドポイント名が tags に統合されます。 ルート登録がない場合、コマンドはデフォルトのパス app/MCP/Tools と app/Tools 内のツールを自動検出します。

# Default output: storage/api-docs-mcp/api-docs.json
php artisan mcp:export-openapi

# Custom output + metadata
php artisan mcp:export-openapi \
  --output=storage/app/mcp.openapi.json \
  --title="MCP Tools API" \
  --api-version=2.1.0

# Limit to one endpoint (id or path)
php artisan mcp:export-openapi --endpoint=/mcp

# Discover tools from additional directory paths
php artisan mcp:export-openapi --discover-path=app/MCP/Tools

# Existing output is overwritten by default
php artisan mcp:export-openapi

ツール API ルートの生成を有効にします：

use Illuminate\Support\Facades\Route;

Route::mcp('/mcp')
    ->setServerInfo(name: 'OP.GG MCP Server', version: '2.0.0')
    ->enabledApi()
    ->tools([
        \App\MCP\Tools\GreetingTool::class,
    ]);

Swagger UI でのテストに関するヒント：

• エクスポートされたオペレーションでは、手動テストを簡単にするため、requestBody は使用せず、query parameters のみを使用します。
• 各ツールの inputSchema().required に含まれる必須フィールドは、Swagger のパラメーター検証に反映されます。
• Enum フィールドは schema.enum としてエクスポートされ、Swagger ではドロップダウン選択として表示されます。
• 配列フィールドは style=form と explode=true でエクスポートされます（キーを繰り返す形式。例：desired_output_fields=items&desired_output_fields=runes）。
• /tools/{tool_name} の引数解析では、Swagger との競合を避けるため、body/form ペイロードよりクエリパラメーターを優先します。
• 明示的な default／example がない Enum フィールドには、最初の Enum 値（または最初の null 以外の Enum 値）が自動設定されます。
• e.g., en_US, ko_KR, ja_JP のような説明がある String フィールドでは、最初のサンプル値が default と example として自動推定されます。

ツールクラスの例

<?php

namespace App\MCP\Tools;

use App\Enums\Platform;
use OPGG\LaravelMcpServer\JsonSchema\JsonSchema;
use OPGG\LaravelMcpServer\Services\ToolService\ToolInterface;

class GreetingTool implements ToolInterface
{
    public function name(): string
    {
        return 'greeting-tool';
    }

    public function description(): string
    {
        return 'Return a greeting message.';
    }

    public function inputSchema(): array
    {
        return [
            'name' => JsonSchema::string()
                ->description('Developer Name')
                ->required(),
            'platform' => JsonSchema::string()
                ->enum(Platform::class)
                ->description('Client platform')
                ->compact(),
        ];
    }

    public function annotations(): array
    {
        return [
            'readOnlyHint' => true,
            'destructiveHint' => false,
        ];
    }

    public function execute(array $arguments): mixed
    {
        return [
            'message' => 'Hello '.$arguments['name'],
        ];
    }
}

JsonSchema ビルダー（Laravel スタイル）

このパッケージは、OPGG\LaravelMcpServer 名前空間で独自の JsonSchema ビルダーを提供します。 inputSchema(): array を維持しながら、Laravel 12 スタイルの流暢な形式でツールのスキーマを定義できます。

<?php

namespace App\MCP\Tools;

use App\Enums\Platform;
use OPGG\LaravelMcpServer\JsonSchema\JsonSchema;
use OPGG\LaravelMcpServer\Services\ToolService\ToolInterface;

class WeatherTool implements ToolInterface
{
    public function name(): string
    {
        return 'weather-tool';
    }

    public function description(): string
    {
        return 'Get weather by location.';
    }

    public function inputSchema(): array
    {
        return [
            'location' => JsonSchema::string()
                ->description('Location to query')
                ->required(),
            'platform' => JsonSchema::string()
                ->enum(Platform::class)
                ->description('Client platform'),
            'days' => JsonSchema::integer()
                ->min(1)
                ->max(7)
                ->default(1),
        ];
    }

    public function annotations(): array
    {
        return [];
    }

    public function execute(array $arguments): mixed
    {
        return ['ok' => true];
    }
}

注：

• 既存の完全な JSON Schema 配列も引き続きサポートされます。
• enum() は、配列または BackedEnum::class のいずれかを受け取ります。
• enum() の後に compact() をチェーンすると、出力されるスキーマから enum が削除され、description にコンパクトなヒントが追加されます（compact()、compact(null)、compact(3)、または compact('custom hint')）。
• コンパクトな例の既定の件数は 3 です。エンドポイントごとに Route::mcp(...)->setConfig(compactEnumExampleCount: N) で変更できます。
• エクスポート時（tools/list、OpenAPI）には、プロパティマップが JSON Schema のオブジェクト形式に自動的に正規化されます。

プロンプトクラスの例

<?php

namespace App\MCP\Prompts;

use OPGG\LaravelMcpServer\Services\PromptService\Prompt;

class WelcomePrompt extends Prompt
{
    public string $name = 'welcome-user';

    public ?string $description = 'Generate a welcome message.';

    public array $arguments = [
        [
            'name' => 'username',
            'description' => 'User name',
            'required' => true,
        ],
    ];

    public string $text = 'Welcome, {username}!';
}

リソースクラスの例

<?php

namespace App\MCP\Resources;

use OPGG\LaravelMcpServer\Services\ResourceService\Resource;

class BuildInfoResource extends Resource
{
    public string $uri = 'app://build-info';

    public string $name = 'Build Info';

    public ?string $mimeType = 'application/json';

    public function read(): array
    {
        return [
            'uri' => $this->uri,
            'mimeType' => $this->mimeType,
            'text' => json_encode([
                'version' => '2.0.0',
                'environment' => app()->environment(),
            ], JSON_THROW_ON_ERROR),
        ];
    }
}

ルートに例を登録する

use App\MCP\Prompts\WelcomePrompt;
use App\MCP\Resources\BuildInfoResource;
use App\MCP\Tools\GreetingTool;
use Illuminate\Support\Facades\Route;

Route::mcp('/mcp')
    ->setServerInfo(
        name: 'Example MCP Server',
        version: '2.0.0',
    )
    ->tools([GreetingTool::class])
    ->resources([BuildInfoResource::class])
    ->prompts([WelcomePrompt::class]);

テストおよび品質確認コマンド

vendor/bin/pest
vendor/bin/phpstan analyse
vendor/bin/pint

翻訳

pip install -r scripts/requirements.txt
export ANTHROPIC_API_KEY='your-api-key'
python scripts/translate_readme.py

選択した言語を翻訳します：

python scripts/translate_readme.py es ko

ライセンス

このプロジェクトは MIT ライセンスの下で配布されています。