Laravel Loop

Laravel Loop

Laravel Loop は、Laravel アプリケーション専用に設計された、強力な Model Context Protocol（MCP）サーバーです。MCP プロトコルを使用して、Laravel アプリケーションを AI アシスタントに接続します。

Laravel Loop は、内部で Prism を使用してツールを構築します。

重要

Laravel Loop と付属のツールは現在も開発中であり、これはベータ版です。

できること

Laravel Loop を使用すると、次のことができます。

• Laravel アプリケーションに直接統合された独自のツールを作成して公開する
• Claude Code、Cursor、Windsurf などの MCP クライアントに接続する

付属のツール：

• Filament MCP Server。
• Laravel Model Tools（モデルデータを操作）：Kirschbaum\Loop\Toolkits\LaravelModelToolkit（書き込み操作は今後追加予定）
• Laravel Factories Tools（MCP クライアントからテストデータを作成）：Kirschbaum\Loop\Toolkits\LaravelFactoriesToolkit
• Stripe Tool（Stripe API を操作）：Kirschbaum\Loop\Tools\StripeTool

インストール

Composer を使用してパッケージをインストールできます。

composer require kirschbaum-development/laravel-loop

設定ファイルを公開します。

php artisan vendor:publish --tag="loop-config"

使用方法

まず、ツールを登録する必要があります（登録場所がわからない場合は、app/Providers/AppServiceProvider に登録してください）。

use Illuminate\Support\ServiceProvider;
use Kirschbaum\Loop\Facades\Loop;
use Kirschbaum\Loop\Toolkits;
use Kirschbaum\Loop\Tools;

Loop::toolkit(Kirschbaum\Loop\Filament\FilamentToolkit::make());

カスタムツール

独自のツールを作成するには、Loop::tool メソッドを使用します。

use Kirschbaum\Loop\Facades\Loop;
use Kirschbaum\Loop\Tools\CustomTool;

Loop::tool(
    CustomTool::make(
        name: 'custom_tool',
        description: 'This is a custom tool',
    )
        ->withStringParameter(name: 'name', description: 'The name of the user', required: true)
        ->withNumberParameter(name: 'age', description: 'The age of the user')
        ->using(function (string $name, ?int $age = null) {
            return sprintf('Hello, %s! You are %d years old.', $name, $age ?? 'unknown');
        }),
    );
);

使用可能なパラメーターの型については、Prism Tool Documentation を参照してください。

カスタムツールオブジェクト

独自のツールクラスを作成することもできます。各ツールは Tool コントラクトを実装し、build メソッドで Prism\Prism\Tool インスタンスを返す必要があります。

use Kirschbaum\Loop\Contracts\Tool;

class HelloTool implements Tool
{
    use \Kirschbaum\Loop\Concerns\Makeable;

    public function build(): \Prism\Prism\Tool
    {
        return app(\Prism\Prism\Tool::class)
            ->as($this->getName())
            ->for('Says hello to the user')
            ->withStringParameter('name', 'The name of the user to say hello to.', required: true)
            ->using(fn (string $name) => "Hello, $name!");
    }

    public function getName(): string
    {
        return 'hello';
    }
}

似たようなツールを複数提供する場合は、ツールのコレクションを返すツールキットを作成できます。

use Kirschbaum\Loop\Collections\ToolCollection;
use Kirschbaum\Loop\Contracts\Toolkit;

class LaravelFactoriesToolkit implements Toolkit
{
    use \Kirschbaum\Loop\Concerns\Makeable;

    public function getTools(): ToolCollection
    {
        return new ToolCollection([
            HelloTool::make(),
            GoodbyeTool::make(),
        ]);
    }
}

---

MCP サーバーへの接続

MCP サーバーを実際に活用するには、MCP クライアント（Claude Code、Claude Desktop、Cursor、Windsurf など）を Laravel Loop MCP サーバーに接続する必要があります。

MCP プロトコルには、接続に使用する主なトランスポートとして STDIO と Streamable HTTP があり、非推奨の HTTP+SSE トランスポートもあります。Laravel Loop はすべてに対応しています。

MCP クライアントを設定する最も簡単な方法は、php artisan loop:mcp:config コマンドを使用することです。このコマンドの案内に従って、MCP クライアントを設定できます。

php artisan loop:mcp:generate-config

STDIO

STDIO を使用して MCP サーバーを実行するために、次の Artisan コマンドを用意しています。

php artisan loop:mcp:start [--user-id=1 [--user-model=] [--auth-guard=] [--debug]

たとえば、Laravel Loop MCP サーバーを Claude Code に接続するには、次のコマンドを使用できます。

claude mcp add laravel-loop-mcp php /your/full/path/to/laravel/artisan loop:mcp:start

# with an authenticated user
claude mcp add laravel-loop-mcp php /your/full/path/to/laravel/artisan loop:mcp:start --user-id=1 --user-model=App\Models\User

# with debug mode
claude mcp add laravel-loop-mcp php /your/full/path/to/laravel/artisan loop:mcp:start --debug

JSON 設定ファイルを使用して Cursor、Claude、または任意の MCP クライアントで Laravel Loop を設定するには、次のようにします。

{
  "mcpServers": {
    "laravel-loop-mcp": {
      "command": "php",
      "args": [
        "/your/full/path/to/laravel/artisan",
        "loop:mcp:start",
        "--user-id=1"
      ]
    }
  }
}

Streamable HTTP と SSE

MCP サーバーを実行するために PHP や Node を起動するのは煩わしい場合があります。これを避けるには、Streamable HTTP または SSE トランスポートを使用すると、MCP クライアントを HTTP 経由でアプリケーションに直接接続できます。

Laravel Loop は、streamable HTTP transport と、非推奨の HTTP+SSE transport にも対応しています。

重要

注意：Streamable HTTP トランスポートは新しく、まだすべての MCP クライアントでサポートされているわけではありません。一方、SSE は（ほとんどの MCP クライアントでサポートされていますが）非推奨です。

以下のドキュメントは、両方のトランスポートを対象としています。有効にする必要があるのは、どちらか一方だけです。

1. トランスポートを有効にして設定する

Streamable HTTP トランスポートを有効にするには、.env ファイルを更新します。

# streamable http
LOOP_STREAMABLE_HTTP_ENABLED=true

# sse
LOOP_SSE_ENABLED=true

注： SSE を使用する場合、デフォルトのドライバーは file です。ローカル開発では、これが最もシンプルで便利です。ただし、本番環境では、ファイルロックの問題を避けるため、redis の使用をおすすめします。ドライバーと追加オプションは、config/loop.php ファイルで変更できます。

これにより、2 つの MCP エンドポイントが公開されます。

• 新しい Streamable HTTP トランスポートをサポートする /mcp。
• 非推奨の HTTP+SSE トランスポートをサポートする /mcp/sse。

注： アプリケーションをローカルで https を使用して実行している場合、自己署名証明書が原因で多くのクライアントが接続に失敗します。これを避けるには、STDIO トランスポートを使用するか、ローカルでは http プロトコルを使用してください。

2. 認証を設定する（任意）

エンドポイントを一般公開すると、データも世界中に公開されることにご注意ください。MCP エンドポイントを安全に保つには、streamable_http.middleware または sse.middleware の設定オプションを設定してください。エンドポイントを保護するため、Sanctum（デフォルトで設定済み）のような仕組みの使用をおすすめします。

[
    'streamable_http' => [
        'middleware' => ['auth:sanctum'],
    ],
    
    'sse' => [
        'middleware' => ['auth:sanctum'],
    ],
]

3. MCP サーバーをクライアントに追加する

あとは、クライアントで MCP サーバーのエンドポイントを設定するだけです。

Claude Code

claude mcp add laravel-loop-mcp http://your-url.test/mcp/sse -t sse

JSON 設定ファイルから

{
  "mcpServers": {
    "laravel-loop-mcp": {
      "url": "http://your-url.test/mcp/sse",
    }
  }
}

すべてのクライアントが SSE への直接接続をサポートしているわけではありません。そのような場合は、mcp-remote パッケージ経由でプロキシできます。Node.js（> 20）がインストールされている必要があります。以下は、mcp-remote パッケージを使用する例です。

{
  "mcpServers": {
    "laravel-loop-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-remote-url.com/mcp",
        "--header",
        "Authorization: Bearer ${AUTH_TOKEN}"
      ]
    }
  }
}

---

トラブルシューティング

接続に失敗しました：MCP error -32000: Connection closed

このエラーが発生した場合、アプリケーションで何らかのエラーが起きている可能性があります。詳しくは、アプリケーションのログを確認してください。

Error: spawn php ENOENT

このエラーは、php バイナリが PATH にない場合に発生することがあります。次のいずれかの方法で解決できます。

• .bashrc または .zshrc ファイルにパスを追加します。.zshrc のみに設定されている場合がありますが、Claude などのアプリケーションは .bashrc を使用します。
• PHP バイナリのフルパスを使用します。ターミナルで which php を実行すると確認できます。
  • プロジェクトに適したバージョンの PHP を常に使用するための方法として有効です。たとえば Herd を使用している場合、選択したバージョンに応じて php が変わります。

ツールを手動で呼び出して出力を確認する

ツールの作成中に予期しない結果が発生することがあり、MCP クライアントからのデバッグが難しい場合があります。次のコマンドを実行すると、ツールを手動で呼び出して出力を確認できます。

php artisan loop:mcp:call

アプリケーションのログを必ず確認してください

不明なエラーが発生した場合は、詳しく調べるためにアプリケーションのログを確認してください。

---

ロードマップ

• パッケージにチャットコンポーネントを追加し、MCP クライアントなしでアプリケーション内からツールを使用できるようにする。
• 既存のツールを改善する
• 既存のツールに書き込み機能を追加する

セキュリティ

セキュリティ関連の問題を発見した場合は、イシュートラッカーではなく [email protected] にメールでご連絡ください。

スポンサー

このパッケージの開発は、問題解決、チーム構築、コミュニティに注力する、開発者主導の企業である Kirschbaum Development Group の支援を受けています。当社について詳しくご覧いただくか、ぜひご参加ください！

ライセンス

MIT License（MIT）。詳細については、ライセンスファイルをご覧ください。