Laravel Loop

Laravel Loop

Laravel Loop 是专为 Laravel 应用设计的强大模型上下文协议（MCP）服务。它使用 MCP 协议将 Laravel 应用与 AI 助手连接起来。

Laravel Loop 在幕后使用 Prism 来构建工具。

重要

Laravel Loop 及其预构建工具仍在开发中，目前为 beta 版本。

功能介绍

Laravel Loop 支持：

• 创建并公开与你的 Laravel 应用直接集成的自定义工具
• 连接 Claude Code、Cursor、Windsurf 等 MCP 客户端

预构建工具：

• Filament MCP 服务。
• Laravel 模型工具（与模型数据交互）：Kirschbaum\Loop\Toolkits\LaravelModelToolkit（即将支持写入操作）
• Laravel 工厂工具（通过 MCP 客户端创建测试数据）：Kirschbaum\Loop\Toolkits\LaravelFactoriesToolkit
• Stripe 工具（与 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 契约，并在 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 客户端（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

要在 Cursor、Claude 或任何支持 JSON 配置文件的 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 传输方式和已弃用的 HTTP+SSE 传输方式。

重要

注意：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 文件中更改驱动和其他选项。

这将公开两个 MCP 端点：

• /mcp，支持新的 Streamable HTTP 传输方式。
• /mcp/sse，支持已弃用的 HTTP+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 错误 -32000：连接已关闭

如果出现此错误，可能是应用中发生了错误。请查看应用日志以了解详情。

错误：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 许可证（MIT）。更多信息请参阅许可证文件。