<p align="center"> <img src="https://freeimage.host/i/3cp00Ob" alt="Laravel MCP Server Logo" width="300"> </p>

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

一个用于构建 模型上下文协议 (MCP) 服务器的基础 Laravel 包。

<!-- 考虑稍后在此处添加构建状态/代码覆盖率徽章 -->

此包提供了处理通过不同传输方式（Stdio、HTTP、WebSocket 通过 Reverb）的 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 目录中创建一个 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'; } // 此资源的唯一 URI
       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(); // 示例：获取经过身份验证的用户
           if (!$user) {
               return null; // 或者抛出一个映射到错误的异常
           }
           return [
               'id' => $user->id,
               'name' => $user->name,
               'email' => $user->email,
           ];
       }
   }
   

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

   // config/mcp.php
   return [
       // ... 其他配置
       '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; // 示例 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
       {
           // 使用 JSON Schema 格式定义预期参数
           return [
               'type' => 'object',
               'properties' => [
                   'user_id' => ['type' => 'integer', 'description' => '目标用户的 ID'],
                   'message' => ['type' => 'string', 'description' => '通知消息内容'],
               ],
               'required' => ['user_id', 'message'],
           ];
       }
   
       public function execute(array $arguments): mixed
       {
           Log::info('Executing sendNotification tool', $arguments);
           // ** 在此处添加您的逻辑 **
           // 示例：验证输入，查找用户，调度一个 Job
           // ProcessNotificationJob::dispatch($arguments['user_id'], $arguments['message']);
           return ['status' => 'queued', 'user_id' => $arguments['user_id']];
       }
   }
   

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

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

用法

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

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

测试

该软件包包含使用 PHPUnit 和 Orchestra Testbench 的基本测试套件。

# 从软件包目录 (packages/bramato/laravel-mcp-server)
../../vendor/bin/phpunit

# 或者从项目根目录
./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 文件了解更多信息。