Laravel MCP Server (bramato/laravel-mcp-server)

Laravel MCP 服务（bramato/laravel-mcp-server）

用于构建 Model Context Protocol (MCP) 服务的 Laravel 基础包。

此软件包提供基础设施，用于通过不同传输方式（Stdio、HTTP、通过 Reverb 实现的 WebSocket）处理 MCP 请求。它在内部使用出色的 sajya/server 库，以稳健地解析 JSON-RPC 2.0 请求并格式化响应。

你需要自行实现 ResourceInterface 和 ToolInterface 类（使用 Bramato\\LaravelMcpServer\\Mcp\\Interfaces 命名空间），并在配置文件中注册这些类，以便根据 MCP 规范公开应用程序的数据和功能。

安装

你可以通过 Composer 安装此软件包：

composer require bramato/laravel-mcp-server

接下来，你应使用 vendor:publish Artisan 命令发布配置文件：

php artisan vendor:publish --provider="Bramato\LaravelMcpServer\Providers\McpServiceProvider" --tag="config"

这将在应用程序的配置目录中创建 config/mcp.php 文件，你可以在其中自定义服务的行为。

配置

config/mcp.php 文件允许你配置：

• enabled_transports：选择要启用的传输方式（stdio、http、websocket）。
• transports：配置各传输方式的详细信息（例如，transports.http.path 中的 HTTP 路径）。
• authentication：设置基本身份验证（通过 authentication.driver 支持 none 或 token）。若使用令牌身份验证，请在 authentication.options.header 中指定标头名称。
• resources：**注册 MCP 资源。**提供实现 Bramato\\LaravelMcpServer\\Mcp\\Interfaces\\ResourceInterface 的完全限定类名数组。
• tools：**注册 MCP 工具。**提供实现 Bramato\\LaravelMcpServer\\Mcp\\Interfaces\\ToolInterface 的完全限定类名数组。这会作为可执行工具的白名单。
• logging：配置软件包专用日志的日志通道和级别。

创建资源和工具

此软件包提供接口，但你需要实现实际逻辑。

示例：创建资源

1. 创建你的资源类（例如，位于 app/Mcp/Resources/UserProfileResource.php）：

   namespace App\Mcp\Resources;
   
   use Bramato\LaravelMcpServer\Mcp\Interfaces\ResourceInterface;
   use Illuminate\Support\Facades\Auth;
   
   class UserProfileResource implements ResourceInterface
   {
       public function getUri(): string { return 'user://profile'; } // Unique URI for this resource
       public function getName(): string { return 'User Profile'; }
       public function getDescription(): string { return 'Provides information about the authenticated user.'; }
       public function getMimeType(): string { return 'application/json'; }
   
       public function getContents(): mixed
       {
           $user = Auth::user(); // Example: Get authenticated user
           if (!$user) {
               return null; // Or throw an exception mapped to an error
           }
           return [
               'id' => $user->id,
               'name' => $user->name,
               'email' => $user->email,
           ];
       }
   }
   

2. 在 config/mcp.php 中注册：

   // config/mcp.php
   return [
       // ... other config
       'resources' => [
           \App\Mcp\Resources\UserProfileResource::class,
       ],
       // ...
   ];
   

示例：创建工具

1. 创建你的工具类（例如，位于 app/Mcp/Tools/SendNotificationTool.php）：

   namespace App\Mcp\Tools;
   
   use Bramato\LaravelMcpServer\Mcp\Interfaces\ToolInterface;
   // use App\Jobs\ProcessNotificationJob; // Example Job
   use Illuminate\Support\Facades\Log;
   
   class SendNotificationTool implements ToolInterface
   {
       public function getName(): string { return 'sendNotification'; }
       public function getDescription(): string { return 'Sends a notification to a user.'; }
   
       public function getInputSchema(): array
       {
           // Define expected parameters using JSON Schema format
           return [
               'type' => 'object',
               'properties' => [
                   'user_id' => ['type' => 'integer', 'description' => 'ID of the target user'],
                   'message' => ['type' => 'string', 'description' => 'The notification message content'],
               ],
               'required' => ['user_id', 'message'],
           ];
       }
   
       public function execute(array $arguments): mixed
       {
           Log::info('Executing sendNotification tool', $arguments);
           // ** Add your logic here **
           // Example: Validate input, find user, dispatch a Job
           // ProcessNotificationJob::dispatch($arguments['user_id'], $arguments['message']);
           return ['status' => 'queued', 'user_id' => $arguments['user_id']];
       }
   }
   

2. 在 config/mcp.php 中注册：

   // config/mcp.php
   return [
       // ... other config
       'tools' => [
           \App\Mcp\Tools\SendNotificationTool::class,
       ],
   ];
   

使用

服务器的运行方式取决于启用的传输方式：

• Stdio：运行 Artisan 命令：php artisan mcp:server --transport=stdio。
• HTTP：确保 Web 服务器（例如，php artisan serve 或 Nginx/Apache）正在运行。向 mcp.transports.http.path 中配置的路径（默认值：/mcp-rpc）发送 JSON-RPC POST 请求。
• WebSocket (Reverb)：
  1. 在主应用程序中安装并配置 Laravel Reverb：php artisan reverb:install。
  2. 确保 config/mcp.php 的 enabled_transports 中列出了 websocket 传输方式。
  3. 启动 Reverb 服务：php artisan reverb:start。
  4. 将 MCP WebSocket 客户端连接到 Reverb 服务端点（请查看你的 Reverb 配置）。

测试

该软件包包含一个基于 PHPUnit 和 Orchestra Testbench 的基础测试套件。

# From the package directory (packages/bramato/laravel-mcp-server)
../../vendor/bin/phpunit

# Or from the project root
./vendor/bin/phpunit packages/bramato/laravel-mcp-server/tests

安全注意事项

MCP 规范未定义客户端与服务之间的身份验证或授权机制。该软件包提供了：

• 工具白名单：只有在 config/mcp.php 的 tools 数组中明确列出的工具才能执行。
• 基础令牌身份验证：你可以通过 authentication 配置部分启用基于令牌的身份验证。

重要提示：你有责任在 ToolInterface::execute 和 ResourceInterface::getContents 方法中实现细粒度的授权逻辑。使用 Laravel 的 Gates 和 Policies 或其他授权机制，确保请求的客户端拥有访问特定资源或执行特定工具所需的权限。

贡献

详情请参阅 CONTRIBUTING.md（如果有）。

许可证

MIT 许可证（MIT）。更多信息请参阅 LICENSE.md 文件。