星战科技xingzhan.cloud
返回市场
拉拉维尔

拉拉维尔

作者：php-mcp463 星标更新：2025-08-20
安装使用来源：spider==github.com

项目介绍

Laravel MCP Server SDK

Latest Version on Packagist Total Downloads License

一个全面的 Laravel SDK，用于构建具有企业级特性和 Laravel 原生集成的 模型上下文协议 (MCP) 服务器。

此 SDK 提供了对强大库 php-mcp/server 的 Laravel 优化封装，使您能够将 Laravel 应用程序的功能作为标准化的 MCP 工具、资源、提示和资源模板暴露给像 Anthropic 的 Claude、Cursor IDE、OpenAI 的 ChatGPT 等 AI 助手。

主要特性

  • Laravel 原生集成：与 Laravel 的服务容器、配置、缓存、日志记录、会话和 Artisan 控制台深度集成。
  • 流畅的元素定义：使用 Mcp 门面以优雅的 Laravel 风格 API 定义 MCP 元素。
  • 基于属性的发现：使用 PHP 8 属性（如 #[McpTool]、#[McpResource] 等）进行自动发现和缓存。
  • 高级会话管理：支持 Laravel 原生会话处理器（文件、数据库、缓存、Redis），并带有自动垃圾回收。
  • 灵活的传输选项：
    • 集成 HTTP：通过 Laravel 路由提供，支持中间件。
    • 专用 HTTP 服务器：高性能独立的 ReactPHP 服务器。
    • STDIO：命令行界面，直接客户端集成。
  • 可流式传输的传输：增强的 HTTP 传输，支持恢复和事件源。
  • Artisan 命令：用于服务、发现和元素管理的命令。
  • 完整的测试覆盖：确保可靠性的综合测试套件。

此包支持 2025-03-26 版本的模型上下文协议。

要求

  • PHP >= 8.1
  • Laravel >= 10.0
  • 扩展：json、mbstring、pcre（通常默认启用）

安装

通过 Composer 安装包：

composer require php-mcp/laravel:^3.0 -W

发布配置文件：

php artisan vendor:publish --provider="PhpMcp\Laravel\McpServiceProvider" --tag="mcp-config"

对于数据库会话存储，发布迁移：

php artisan vendor:publish --provider="PhpMcp\Laravel\McpServiceProvider" --tag="mcp-migrations"
php artisan migrate

配置

所有 MCP 服务器设置都通过 config/mcp.php 进行管理，该文件包含了每个选项的详细文档。配置涵盖了服务器标识、能力、发现设置、会话管理、传输选项、缓存和日志记录。所有设置都支持环境变量，便于部署管理。

主要配置区域包括：

  • 服务器信息：名称、版本和基本标识
  • 能力：控制哪些 MCP 功能被启用（工具、资源、提示等）
  • 发现：如何从代码库中找到和缓存元素
  • 会话管理：多种存储后端（文件、数据库、缓存、Redis），带有自动垃圾回收
  • 传输：STDIO、集成 HTTP 和专用 HTTP 服务器选项
  • 性能：缓存策略和分页限制

查看已发布的 config/mcp.php 文件，了解所有可用选项及其环境变量覆盖的详细文档。

定义 MCP 元素

Laravel MCP 提供了两种强大的方法来定义 MCP 元素：手动注册（使用流畅的 Mcp 门面）和基于属性的发现（使用 PHP 8 属性）。两者可以结合使用，手动注册优先。

元素类型

  • 工具：可执行函数/动作（例如，calculate、send_email、query_database）
  • 资源：可通过 URI 访问的静态内容/数据（例如，config://settings、file://readme.txt）
  • 资源模板：具有 URI 模式的动态资源（例如，user://{id}/profile）
  • 提示：对话启动器/模板（例如，summarize、translate）

1. 手动注册

在 routes/mcp.php 中使用优雅的 Mcp 门面定义您的 MCP 元素：

<?php

use PhpMcp\Laravel\Facades\Mcp;
use App\Services\{CalculatorService, UserService, EmailService, PromptService};

// 注册一个简单的工具
Mcp::tool([CalculatorService::class, 'add'])
    ->name('add_numbers')
    ->description('将两个数字相加');

// 注册一个可调用类作为工具
Mcp::tool(EmailService::class)
    ->description('向用户发送电子邮件');

// 注册一个闭包作为工具，并自定义输入模式
Mcp::tool(function(float $x, float $y): float {
    return $x * $y;
})
    ->name('multiply')
    ->description('将两个数字相乘')
    ->inputSchema([
        'type' => 'object',
        'properties' => [
            'x' => ['type' => 'number', 'description' => '第一个数字'],
            'y' => ['type' => 'number', 'description' => '第二个数字'],
        ],
        'required' => ['x', 'y'],
    ]);

// 注册一个带有元数据的资源
Mcp::resource('config://app/settings', [UserService::class, 'getAppSettings'])
    ->name('app_settings')
    ->description('应用程序配置设置')
    ->mimeType('application/json')
    ->size(1024);

// 注册一个闭包作为资源
Mcp::resource('system://time', function(): string {
    return now()->toISOString();
})
    ->name('current_time')
    ->description('获取当前服务器时间')
    ->mimeType('text/plain');

// 注册一个资源模板以生成动态内容
Mcp::resourceTemplate('user://{userId}/profile', [UserService::class, 'getUserProfile'])
    ->name('user_profile')
    ->description('根据ID获取用户资料')
    ->mimeType('application/json');

// 注册一个闭包作为资源模板
Mcp::resourceTemplate('file://{path}', function(string $path): string {
    if (!file_exists($path) || !is_readable($path)) {
        throw new \InvalidArgumentException("文件未找到或不可读：{$path}");
    }
    return file_get_contents($path);
})
    ->name('file_reader')
    ->description('根据路径读取文件内容')
    ->mimeType('text/plain');

// 注册一个提示生成器
Mcp::prompt([PromptService::class, 'generateWelcome'])
    ->name('welcome_user')
    ->description('生成个性化的欢迎消息');

// 注册一个闭包作为提示
Mcp::prompt(function(string $topic, string $tone = 'professional'): array {
    return [
        [
            'role' => 'user',
            'content' => "撰写关于 {$topic} 的 {$tone} 总结。使其具有信息性和吸引力。",
        ],
    ];
})
    ->name('topic_summary')
    ->description('生成主题总结提示');

可用的流畅方法：

对于所有元素：

  • name(string $name)：覆盖推断的名称
  • description(string $description)：设置自定义描述

对于工具：

  • annotations(ToolAnnotations $annotations)：添加 MCP 工具注解
  • inputSchema(array $schema)：定义参数的自定义 JSON 模式

对于资源：

  • mimeType(string $mimeType)：指定内容类型
  • size(int $size)：设置内容大小（字节）
  • annotations(Annotations $annotations)：添加 MCP 注解

对于资源模板：

  • mimeType(string $mimeType)：指定内容类型
  • annotations(Annotations $annotations)：添加 MCP 注解

处理器格式：

  • [ClassName::class, 'methodName'] - 类方法
  • InvokableClass::class - 具有 __invoke() 方法的可调用类
  • function(...) { ... } - 可调用（v3.2+）

2. 基于属性的发现

或者，您可以使用 PHP 8 属性标记您的方法或类作为 MCP 元素，在这种情况下，您不需要在 routes/mcp.php 中注册它们：

<?php

namespace App\Services;

use PhpMcp\Server\Attributes\{McpTool, McpResource, McpResourceTemplate, McpPrompt};

class UserService
{
    /**
     * 创建一个新的用户帐户。
     */
    #[McpTool(name: 'create_user')]
    public function createUser(string $email, string $password, string $role = 'user'): array
    {
        // 创建用户的逻辑
        return [
            'id' => 123,
            'email' => $email,
            'role' => $role,
            'created_at' => now()->toISOString(),
        ];
    }

    /**
     * 获取应用程序配置。
     */
    #[McpResource(
        uri: 'config://app/settings',
        mimeType: 'application/json'
    )]
    public function getAppSettings(): array
    {
        return [
            'theme' => config('app.theme', 'light'),
            'timezone' => config('app.timezone'),
            'features' => config('app.features', []),
        ];
    }

    /**
     * 根据ID获取用户资料。
     */
    #[McpResourceTemplate(
        uriTemplate: 'user://{userId}/profile',
        mimeType: 'application/json'
    )]
    public function getUserProfile(string $userId): array
    {
        return [
            'id' => $userId,
            'name' => 'John Doe',
            'email' => 'john@example.com',
            'profile' => [
                'bio' => '软件开发人员',
                'location' => '纽约',
            ],
        ];
    }

    /**
     * 生成欢迎消息提示。
     */
    #[McpPrompt(name: 'welcome_user')]
    public function generateWelcome(string $username, string $role = 'user'): array
    {
        return [
            [
                'role' => 'user',
                'content' => "为 {$username} 创建一个具有角色 {$role} 的个性化欢迎消息。要热情而专业。",
            ],
        ];
    }
}

发现过程：

当以下条件满足时，带有属性的元素会被自动发现：

  • 在配置中启用 auto_discover（默认：true）
  • 您手动运行 php artisan mcp:discover
# 发现并缓存 MCP 元素
php artisan mcp:discover

# 强制重新发现（忽略缓存）
php artisan mcp:discover --force

# 发现但不保存到缓存
php artisan mcp:discover --no-cache

元素优先级

  • 手动注册始终覆盖具有相同标识符的发现元素
  • 发现元素被缓存以提高性能
  • 缓存在新鲜发现运行时自动失效

运行 MCP 服务器

Laravel MCP 提供了三种传输选项，每种都针对不同的部署场景进行了优化：

1. STDIO 传输

最佳用途：直接客户端执行、Cursor IDE、命令行工具

php artisan mcp:serve --transport=stdio

客户端配置（Cursor IDE）：

{
    "mcpServers": {
        "my-laravel-app": {
            "command": "php",
            "args": [
                "/绝对路径/到你的/laravel项目/artisan",
                "mcp:serve",
                "--transport=stdio"
            ]
        }
    }
}

⚠️ 重要：当使用 STDIO 传输时，永远不要在处理程序中写入 STDOUT（使用 Laravel 的日志器或 STDERR 进行调试）。STDOUT 保留用于 JSON-RPC 通信。

2. 集成 HTTP 传输

最佳用途：开发、具有现有 Web 服务器的应用程序、快速设置

集成传输通过您的 Laravel 应用程序的路由提供 MCP：

// 路由自动注册在：
// GET  /mcp       - 流式连接端点
// POST /mcp       - 消息发送端点
// DELETE /mcp     - 会话终止端点

// 如果启用的旧版模式：
// GET  /mcp/sse   - 服务器发送事件端点
// POST /mcp/message - 消息发送端点

CSRF 保护配置：

将 MCP 路由添加到您的 CSRF 排除项中：

Laravel 11+：

// bootstrap/app.php
->withMiddleware(function (Middleware $middleware) {
    $middleware->validateCsrfTokens(except: [
        'mcp',           // 对于流式传输（默认）
        'mcp/*',   // 对于旧版传输（如果启用）
    ]);
})

Laravel 10 及以下：

// app/Http/Middleware/VerifyCsrfToken.php
protected $except = [
    'mcp',           // 对于流式传输（默认）
    'mcp/*',   // 对于旧版传输（如果启用）
];

配置选项：

'http_integrated' => [
    'enabled' => true,
    'route_prefix' => 'mcp',           // URL 前缀
    'middleware' => ['api'],           // 应用的中间件
    'domain' => 'api.example.com',     // 可选域
    'legacy' => false,                 // 使用旧版 SSE 传输
],

客户端配置：

{
    "mcpServers": {
        "my-laravel-app": {
            "url": "https://your-app.test/mcp"
        }
    }
}

服务器环境考虑：

标准同步服务器难以处理持久的 SSE 连接，因为每个活动连接都会占用一个工作进程。这影响了开发和生产环境。

对于开发：

  • PHP 内置服务器（php artisan serve）不起作用 - SSE 流锁定了单个进程
  • Laravel Herd（推荐用于本地开发）
  • 正确配置的 Nginx，具有多个 PHP-FPM 工作者
  • Laravel Octane，使用 Swoole/RoadRunner 进行异步处理
  • 专用 HTTP 服务器（php artisan mcp:serve --transport=http）

对于生产：

  • 专用 HTTP 服务器（强烈推荐）
  • Laravel Octane，使用 Swoole/RoadRunner
  • 正确配置的 Nginx，具有足够的 PHP-FPM 工作者

3. 专用 HTTP 服务器（推荐用于生产）

最佳用途：生产环境、高流量应用、多个并发客户端

启动一个独立的基于 ReactPHP 的 HTTP 服务器：

# 启动专用服务器
php artisan mcp:serve --transport=http

# 带有自定义配置
php artisan mcp:serve --transport=http \
    --host=0.0.0.0 \
    --port=8091 \
    --path-prefix=mcp_api

配置选项：

'http_dedicated' => [
    'enabled' => true,
    'host' => '127.0.0.1',              // 绑定地址
    'port' => 8090,                     // 端口号
    'path_prefix' => 'mcp',             // URL 路径前缀
    'legacy' => false,                  // 使用旧版传输
    'enable_json_response' => false,    // JSON 模式 vs SSE 流传输
    'event_store' => null,              // 用于恢复的事件存储
    'ssl_context_options' => [],        // SSL 配置
],

传输模式：

  • 流式模式（legacy: false）：增强的传输，支持恢复和事件源
  • 旧版模式（legacy: true）：已弃用的 HTTP+SSE 传输。

JSON 响应模式：

'enable_json_response' => true,  // 返回即时 JSON 响应
'enable_json_response'  => false, // 使用 SSE 流传输（默认）
  • JSON 模式：返回即时响应，最适合快速执行的工具
  • SSE 模式：流式传输响应，适合长时间运行的操作

生产部署：

这创建了一个长期运行的过程，应该使用以下方式管理：

  • Supervisor（推荐）
  • systemd
  • Docker 容器
  • 进程管理器

示例 Supervisor 配置：

[program:laravel-mcp]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/laravel/artisan mcp:serve --transport=http
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=1
redirect_stderr=true
stdout_logfile=/var/log/laravel-mcp.log

有关详细的生产部署指南，请参阅 php-mcp/server 文档。

Artisan 命令

Laravel MCP 包含几个 Artisan 命令，用于管理您的 MCP 服务器：

发现命令

从您的代码库中发现并缓存 MCP 元素：

# 发现元素并更新缓存
php artisan mcp:discover

# 强制重新发现（忽略现有缓存）
php artisan mcp:discover --force

# 发现但不更新