Laravel MCP Server (Bramato)

Laravel MCP服务器（bramato/Laravel MCP服务器）

用于构建的Laravel基础包 模型上下文协议（MCP） 服务器。

此包提供了处理不同传输方式（Stdio、HTTP、通过Reverb的WebSocket）上的MCP请求的基本基础设施。它使用优秀的 sajya/服务器 库内部用于强大的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：为每个传输配置详细信息（例如，中的HTTP路径 transports.http.path).
• authentication：基本身份验证设置（支持 none 或 token 通过 authentication.driver).对于令牌身份验证，请在中指定标头名称 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,
           ];
       }
   }

1. 在中注册 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']];
       }
   }

1. 在中注册 config/mcp.php:

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

用法

如何运行服务器取决于启用的传输：

• 标准输入输出：运行Artisan命令： php artisan mcp:server --transport=stdio.
• 超文本传输协议：确保您的网络服务器（例如。， php artisan serve 或Nginx/Apache）正在运行。将JSON-RPC POST请求发送到中配置的路径 mcp.transports.http.path （默认值： /mcp-rpc).
• WebSocket（反向）:

1. 在主应用程序中安装并配置Laravel Reverb： php artisan reverb:install. 1. 确保 websocket 运输列在 enabled_transports 在……里面 config/mcp.php. 1. 启动Reverb服务器： php artisan reverb:start. 1. 将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规范没有定义客户端和服务器之间的身份验证或授权机制。此套餐提供：

• 工具白名单：仅在 tools 数组in config/mcp.php 可以执行。
• 基本令牌身份验证：您可以通过启用基于令牌的身份验证 authentication 配置部分。

重要确实如此 你的责任 在您的系统中实现细粒度的授权逻辑 ToolInterface::execute 和 ResourceInterface::getContents 方法。使用Laravel的盖茨和策略或其他授权机制来确保请求客户端具有访问特定资源或执行特定工具的必要权限。

贡献

请看 CONTRIBUTING.md 详情（如有）。

许可证

MIT许可证（MIT）。请查看 许可证.md 文件以获取更多信息。