项目简介

Laravel Loop 是一个专为 Laravel 应用设计的 Model Context Protocol (MCP) 服务器。它使得你的 Laravel 应用能够通过标准的 MCP 协议与各种支持该协议的 AI 助手（如 Claude Code, Cursor 等）进行交互。通过 Laravel Loop，你可以将 Laravel 应用的数据和功能作为工具 (Tools) 提供给 AI 助手，让 AI 助手能够理解和操作你的应用上下文。

主要功能点

工具托管与执行: 轻松定义和注册与你的 Laravel 应用深度集成的工具。AI 助手可以通过 MCP 调用这些工具来执行特定操作或获取应用数据。
支持多种传输协议: 支持 STDIO（命令行方式）和 HTTP+SSE/Streamable HTTP 等 MCP 传输方式，方便在不同环境（本地开发、生产服务器）下连接 AI 客户端。
提供预置工具包: 内置了一些常用的工具包，例如用于与 Laravel 模型数据交互（读取、查找、列表）、使用 Laravel Factories 创建测试数据等，加速开发。
会话管理: 对于 HTTP+SSE 等需要持久连接的传输方式，服务器负责管理客户端会话。
安全配置: 支持配置认证中间件，确保 MCP 端点仅授权访问。

安装步骤

通过 Composer 安装包：

composer require kirschbaum-development/laravel-loop

发布配置文件（可选，用于自定义设置）：

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

服务器配置 (供 MCP 客户端使用)

MCP 客户端需要知道如何启动或连接到你的 Laravel Loop 服务器。根据你选择的传输方式，配置信息会有所不同。通常，这些配置会添加到客户端的设置文件（如 JSON 文件）中。

1. STDIO 传输 (推荐用于本地开发)

通过运行 Laravel Artisan 命令来启动服务器。客户端配置需要指定 PHP 命令和 Artisan 脚本路径。

JSON 配置示例描述:

{
  "mcpServers": {
    "laravel-loop-mcp": { // 服务器名称，客户端显示
      "command": "php", // 启动命令，这里是 PHP 可执行文件
      "args": [
        "/your/full/path/to/laravel/artisan", // Artisan 脚本的完整路径
        "loop:mcp:start", // Laravel Loop 的启动命令
        // 可选参数：
        // "--user-id=1", // (可选) 指定用于认证的 Laravel 用户 ID
        // "--user-model=App\\Models\\User" // (可选) 指定用户模型类，默认为 App\Models\User
        // "--debug" // (可选) 开启调试模式，在终端显示更多信息
      ]
    }
    // ... 其他 MCP 服务器配置
  }
}

说明：将 '/your/full/path/to/laravel' 替换为你 Laravel 项目的实际完整路径。

2. HTTP+SSE / Streamable HTTP 传输 (推荐用于生产环境)

通过 HTTP 端点连接到正在运行的 Laravel 应用。首先需要在 '.env' 文件中启用相应的传输方式（'LOOP_SSE_ENABLED=true' 或 'LOOP_STREAMABLE_HTTP_ENABLED=true'）并配置认证中间件（在 'config/loop.php' 中）。

JSON 配置示例描述:

{
  "mcpServers": {
    "laravel-loop-mcp": { // 服务器名称，客户端显示
      // 使用 Streamable HTTP 传输 (较新)
      // "url": "http://your-url.test/mcp", // 服务器 HTTP 端点 URL
      // "transport": "streamable-http" // 指定传输协议

      // 或使用 HTTP+SSE 传输 (兼容性更好，但已废弃)
      "url": "http://your-url.test/mcp/sse", // 服务器 SSE 端点 URL
      "transport": "sse" // 指定传输协议

      // 注意：确保你的 Laravel 应用正在运行并通过该 URL 可访问
      // 确保配置了认证中间件，保障端点安全
    }
    // ... 其他 MCP 服务器配置
  }
}

说明：将 'http://your-url.test' 替换为你 Laravel 应用的实际基础 URL。路径 '/mcp' 和 '/mcp/sse' 可以在 'config/loop.php' 中配置。请根据你的客户端支持和偏好选择 Streamable HTTP 或 SSE。

某些客户端可能不支持直接连接 SSE，可能需要通过 'mcp-remote' 等 Node.js 工具进行代理。

基本使用方法

在你的 Laravel 应用中，通常在 'AppServiceProvider' 或其他服务提供者中注册你的工具或工具包：

use Illuminate\Support\ServiceProvider;
use Kirschbaum\Loop\Facades\Loop;
use Kirschbaum\Loop\Toolkits;
use Kirschbaum\Loop\Tools; // 如果定义了自定义工具类

class AppServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        // 注册预置的 Laravel 模型工具包 (只读模式)
        Loop::toolkit(Toolkits\LaravelModelToolkit::make(
            models: [\App\Models\User::class, \App\Models\Product::class] // 指定要暴露的模型
        ));

        // 注册预置的 Laravel Factories 工具包 (用于创建测试数据)
        Loop::toolkit(Toolkits\LaravelFactoriesToolkit::make());

        // 注册一个自定义工具
        // Loop::tool(
        //     Tools\CustomTool::make(
        //         name: 'get_current_time',
        //         description: '获取服务器当前时间'
        //     )->using(function () {
        //         return now()->toDateTimeString();
        //     })
        // );
    }

    public function boot(): void
    {
        //
    }
}

注册工具后，启动你的 Laravel 应用（对于 HTTP 传输）或运行 'php artisan loop:mcp:start' 命令（对于 STDIO 传输），然后连接你的 MCP 客户端。AI 助手就能够发现并调用你注册的工具了。

关键词