Laravel Loop

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

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

[!IMPORTANT] Laravel Loop 及其预构建工具仍在开发中，这是测试版。

它的功能

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: '这是一个自定义工具',
    )
        ->withStringParameter(name: 'name', description: '用户的姓名', required: true)
        ->withNumberParameter(name: 'age', description: '用户的年龄')
        ->using(function (string $name, ?int $age = null) {
            return sprintf('你好，%s！你%d岁了。', $name, $age ?? '未知');
        }),
    );
);

可用参数类型可以在 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('向用户打招呼')
            ->withStringParameter('name', '要打招呼的用户的姓名。', required: true)
            ->using(fn (string $name) => "你好，$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

# 带有认证用户
claude mcp add laravel-loop-mcp php /your/full/path/to/laravel/artisan loop:mcp:start --user-id=1 --user-model=App\Models\User

# 带有调试模式
claude mcp add laravel-loop-mcp php /your/full/path/to/laravel/artisan loop:mcp:start --debug

要在 Cursor、Claude 或任何 MCP 客户端中使用 JSON 配置文件配置 Laravel Loop：

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

Streamable HTTP & SSE

运行 PHP 或 Node 来运行 MCP 服务器可能会很麻烦。为了避免这种情况，您可以使用 Streamable HTTP 或 SSE 传输，它们通过 HTTP 直接将 MCP 客户端连接到您的应用。

Laravel Loop 还支持 Streamable HTTP 传输 和已弃用的 HTTP+SSE 传输。

[!IMPORTANT] 注意：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 客户端的情况下在应用内使用工具。
• 完善现有工具
• 为现有工具添加写入功能

安全性

如果您发现任何与安全相关的问题，请发送电子邮件至 security@kirschbaumdevelopment.com 而不是使用问题跟踪器。

赞助

该包的开发由 Kirschbaum Development Group 赞助，这是一家专注于解决问题、团队建设和社区发展的开发者驱动公司。了解更多 关于我们 或 加入我们！

许可证

MIT 许可证 (MIT)。请参阅 许可证文件 获取更多信息。