Laravel循环
 ](https://packagist.org/packages/kirschbaum-development/laravel-loop)
Laravel Loop是一个功能强大的模型上下文协议（MCP）服务器，专为Laravel应用程序设计。它使用MCP协议将Laravel应用程序与AI助手连接起来。
Laravel循环使用 棱镜 在幕后构建工具。
\[！重要\] Laravel Loop及其预构建工具仍在开发中，这是一个测试版。
它做什么
Laravel循环允许您：
- 创建并公开与Laravel应用程序直接集成的自己的工具
- 与Claude Code、Cursor、Windsurf等MCP客户端连接
预构建工具：
- Filament MCP服务器.
- Laravel模型工具（与模型数据交互）：
Kirschbaum\Loop\Toolkits\LaravelModelToolkit（即将进行的写入操作） - Laravel工厂工具（从MCP客户端创建测试数据）：
Kirschbaum\Loop\Toolkits\LaravelFactoriesToolkit - 条纹工具（与条纹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 合同，并返回a Prism\Prism\Tool 实例中 build 方法。
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 LoopMCP服务器。
MCP协议有两种主要的传输方式可供连接：STDIO和Streamable HTTP，以及已弃用的HTTP+SSE传输。Laravel循环支持所有这些。
配置MCP客户端的最简单方法是使用 php artisan loop:mcp:config 命令。这将指导您完成配置MCP客户端的过程。
php artisan loop:mcp:generate-config标准输入输出
要使用STDIO运行MCP服务器，我们提供以下技工命令：
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循环：
{
"mcpServers": {
"laravel-loop-mcp": {
"command": "php",
"args": [
"/your/full/path/to/laravel/artisan",
"loop:mcp:start",
"--user-id=1"
]
}
}
}流式HTTP和SSE
必须运行PHP或Node来运行MCP服务器可能会很烦人。为了避免这种情况，您可以使用Streamable HTTP或SSE传输，它通过HTTP将MCP客户端直接连接到您的应用程序。
Laravel循环也支持 流式HTTP传输 以及已弃用的 HTTP+SSE传输.
\[！重要\] 注意：流式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传输。
注： 如果您在本地运行应用程序 超文本传输安全协议，大多数客户端将由于自签名证书而失败。为了避免这种情况，请使用STDIO传输或使用 超文本传输协议 本地协议。
2.配置身份验证（可选）
请注意，如果你公开你的端点，你就是在向世界公开你的数据。为确保您的MCP端点安全，请确保配置 streamable_http.middleware 或 sse.middleware 配置选项。我们建议使用类似Sanctum（默认配置）的东西来保护端点。
[
'streamable_http' => [
'middleware' => ['auth:sanctum'],
],
'sse' => [
'middleware' => ['auth:sanctum'],
],
]3.将MCP服务器添加到您的客户端
然后，您只需在客户端中配置MCP服务器端点：
克劳德代码
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遥控器 包裹。
{
"mcpServers": {
"laravel-loop-mcp": {
"command": "npx",
"args": [
"mcp-remote",
"https://your-remote-url.com/mcp",
"--header",
"Authorization: Bearer ${AUTH_TOKEN}"
]
}
}
}______________________________________________________________________
故障排除
连接失败：MCP错误-32000:连接已关闭
如果您遇到此错误，则可能意味着您的应用程序中发生了一些错误。有关更多详细信息，请查看您的应用程序日志。
错误：生成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而不是使用问题跟踪器。
赞助
许可证
MIT许可证（MIT）。请看 许可证文件 了解更多信息。