laravel-mcp-server-(bramatolaravel-mcp-server)

🚀 Laravel MCP 服务器

Laravel MCP 服务器是一个基于模型上下文协议（Model Context Protocol，简称 MCP）的扩展包，为 Laravel 应用提供统一接口，用于管理模型资源和执行工具。该协议明确了客户端与服务器的交互方式，让客户端能通过标准方法请求模型数据或执行特定操作。

🚀 快速开始

Laravel MCP 服务器是基于模型上下文协议（MCP）的扩展包，为 Laravel 应用管理模型资源和执行工具提供统一接口，使客户端能通过标准方法与服务器交互。

✨ 主要特性

• 提供统一接口管理 Laravel 应用的模型资源和工具执行。
• 支持标准输入输出（Stdio）、HTTP 运行时和 WebSocket（通过 Reverb）三种启动方式。
• 具备工具白名单和基本令牌认证等安全特性。

📦 安装指南

依赖安装

要在你的 Laravel 项目中使用 Laravel MCP 服务器，请先安装以下依赖：

composer require bramato/laravel-mcp-server

配置发布

将包的配置文件发布到项目的配置目录：

php artisan vendor:publish --provider="Bramato\LaravelMcpServer\ServiceProvider"

安装后配置

完成安装后，请在 config/mcp.php 文件中根据你的需求进行相应的配置。

💻 使用示例

基础用法

启动 MCP 服务器

标准输入输出（Stdio）

要启动一个基于标准输入输出的 MCP 服务器，可以在控制台执行以下命令：

php artisan mcp:server --transport=stdio

这将启动一个交互式的 MCP 服务器，支持通过标准输入发送请求，并在标准输出返回响应。

HTTP 运行时

要启用 HTTP 运行时，请确保配置了 MCP 的 HTTP 路径。默认情况下，MCP 使用 /mcp-rpc 路径来处理 HTTP 请求。启动你的 Laravel 开发服务器或配置好反向代理后，可以通过发送 POST 请求到该路径来与 MCP 服务进行交互。

WebSocket（通过 Reverb）

要启用 WebSocket 支持，请先安装并配置好 Laravel 的 Reverb 扩展包：

php artisan reverb:install

然后在 config/mcp.php 文件中将 websocket 加入到 enabled_transports 数组，并启动 Reverb 服务器：

php artisan reverb:start

高级用法

客户端代码示例

use Bramato\LaravelMcpServer\Client\McpClient;

$client = new McpClient('http://localhost:8000/mcp-rpc');

// 获取资源数据
$response = $client->get('example.resource', $modelId);
echo json_encode($response);

// 执行工具操作
$response = $client->execute('example.tool', [
    'parameter1' => 'value1',
]);
echo json_encode($response);

服务器端代码示例

use Bramato\LaravelMcpServer\Resource\McpResource;
use Bramato\LaravelMcpServer\Tool\McpTool;

class ExampleResource extends McpResource {
    public function get(Model $model) {
        // 返回模型数据
        return [
            'id' => $model->id,
            'name' => $model->name,
        ];
    }
}

class ExampleTool extends McpTool {
    public function execute(array $parameters) {
        // 执行工具操作
        return 'Operation completed successfully';
    }
}

📚 详细文档

安全注意事项

MCP 协议本身并未定义客户端与服务器之间的身份验证或授权机制。因此，我们提供以下安全特性来保护你的 MCP 服务：

• 工具白名单：只有在 config/mcp.php 文件中明确列出的工具才能被执行。
• 基本令牌认证：可以通过配置启用基于令牌的身份验证。

⚠️ 重要提示

你必须自行实现精细的授权逻辑，以确保客户端请求的资源或执行的操作符合你的应用权限策略。建议使用 Laravel 的 Gates 和 Policies 来管理这些权限。

测试

运行测试套件

要运行内置的 PHPUnit 测试套件，请按照以下步骤操作：

• 在包目录中运行：

../../vendor/bin/phpunit

• 或者在项目根目录中运行：

./vendor/bin/phpunit packages/bramato/laravel-mcp-server/tests

编写自定义测试

为了确保 MCP 服务的功能正常，建议编写自定义的集成测试。你可以参考 tests/_factory.php 文件中的示例来创建和配置 MCP 客户端实例，并发送各种请求以验证预期的行为。

配置选项

以下是 MCP 服务器的主要配置选项：

return [
    // 启用的传输方式
    'enabled_transports' => ['http', 'stdio', 'websocket'],

    // HTTP 相关配置
    'http' => [
        'path' => '/mcp-rpc',
        'middleware' => [
            \Bramato\LaravelMcpServer\Http\Middleware\McpAuthentication::class,
        ],
    ],

    // WebSocket 相关配置（仅当使用 Reverb 时生效）
    'websocket' => [
        'driver' => 'reverb',
        'prefix' => 'mcp-ws',
    ],

    // 资源和工具的定义
    'resources' => [
        // 示例资源定义
        'example.resource' => [
            'description' => '这是一个示例资源',
            'schema' => [
                // 定义资源的输入和输出 schema
            ],
        ],
    ],

    'tools' => [
        // 示例工具定义
        'example.tool' => [
            'description' => '这是一个示例工具，用于执行特定操作',
            'parameters' => [
                // 工具所需的参数定义
            ],
        ],
    ],
];

创建资源

基本结构

每个资源应该包含以下属性：

public function __construct() {
}

/**
 * 获取资源的元数据。
 *
 * @return array
 */
public function meta(): array {
    return [];
}

/**
 * 获取指定模型实例的数据。
 *
 * @param Model $model
 * @return mixed
 */
public function get(Model $model) {
    // 返回模型数据
}

/**
 * 处理客户端对资源的请求。
 *
 * @param Request $request
 * @return Response
 */
public function handle(Request $request): Response {
    // 根据请求类型处理逻辑
}

创建工具

基本结构

每个工具应该包含以下属性：

public function __construct() {
}

/**
 * 获取工具的元数据。
 *
 * @return array
 */
public function meta(): array {
    return [];
}

/**
 * 执行工具操作。
 *
 * @param array $parameters
 * @return mixed
 */
public function execute(array $parameters) {
    // 返回执行结果
}

🔧 技术细节

Laravel MCP 服务器基于模型上下文协议（MCP），该协议定义了客户端与服务器之间的交互方式。服务器通过不同的传输方式（如 Stdio、HTTP、WebSocket）接收客户端的请求，并根据配置的资源和工具定义进行处理。在安全方面，通过工具白名单和基本令牌认证来保护服务，但需要开发者自行实现精细的授权逻辑。

📄 许可证

文档中未提及许可证相关信息。

更多资源

• 官方文档：Laravel MCP 服务器文档
• GitHub 仓库：Bramato/LaravelMcpServer