在 Laravel 中使用 php-mcp/laravel 包注册 MCP 工具的方法

在 Laravel 中使用 php-mcp/laravel 包注册 MCP 工具主要有三种方式，以下是详细指南：

---

方法一：属性注解自动注册（推荐）

通过 #[McpTool] 属性自动发现工具类：

// app/Tools/EmailTool.php
namespace App\Tools;

use PhpMcp\Laravel\Server\Attributes\McpTool;
use App\Mail\MarketingEmail;

class EmailTool {
    #[McpTool(
        name: "send_marketing_email",
        description: "发送营销邮件",
        params: [
            'recipient' => 'string|required|email',
            'subject' => 'string|required|max:100',
            'campaign_id' => 'int'
        ]
    )]
    public function handle(array $params): array {
        Mail::to($params['recipient'])
            ->send(new MarketingEmail(
                $params['subject'], 
                $params
            ));
        
        return ['status' => 'sent', 'message_id' => Str::uuid()];
    }
}

⚠️ 需确保在 config/mcp.php 中启用自动发现：

'discovery' => [
    'auto_register' => true,
    'paths' => [
        app_path('Tools'), // 扫描的目录
    ],
],

---

方法二：手动路由注册

在 MCP 路由文件中显式注册：

// routes/mcp.php
use PhpMcp\Laravel\Facades\Mcp;
use App\Tools\EmailTool;

// 注册单个工具方法
Mcp::tool('send_bulk_email', [EmailTool::class, 'sendBulk'])
    ->description('批量发送邮件')
    ->params([
        'recipients' => 'array|required',
        'template' => 'string|required'
    ]);

// 注册整个工具类（自动扫描类中所有 #[McpTool] 方法）
Mcp::registerTool(EmailTool::class);

---

方法三：服务提供者注册

在服务提供者中批量注册工具：

// app/Providers/McpServiceProvider.php
namespace App\Providers;

use PhpMcp\Laravel\Server\Mcp;
use Illuminate\Support\ServiceProvider;
use App\Tools\{EmailTool, NotificationTool};

class McpServiceProvider extends ServiceProvider {
    public function boot() {
        // 注册单个工具
        Mcp::tool('send_alert', [NotificationTool::class, 'sendAlert']);
        
        // 注册整个工具类
        Mcp::registerTool(EmailTool::class);
    }
}

注册服务提供者到 config/app.php：

'providers' => [
    // ...
    App\Providers\McpServiceProvider::class,
],

---

📌 验证注册结果

运行 Artisan 命令查看已注册工具：

php artisan mcp:list-tools

输出示例：

+---------------------+----------------------------+
| Tool Name           | Description                |
+---------------------+----------------------------+
| send_marketing_email| 发送营销邮件               |
| send_bulk_email     | 批量发送邮件               |
| send_alert          |                            |
+---------------------+----------------------------+

---

🚨 关键注意事项

1. 参数校验规则：

   • 使用 Laravel 验证语法定义参数规则（如 'email' => 'required|email:rfc,dns'）
   • 错误时会自动返回 400 错误

2. 安全实践：

   // 在工具类中使用授权检查
   #[McpTool(name: "send_sensitive_email")]
   public function sendSensitive(array $params) {
       if (!Auth::user()->can('send_emails')) {
           abort(403, '无操作权限');
       }
       // ...
   }
   

3. 异步操作：

   #[McpTool(name: "send_large_attachment", is_async: true)]
   public function sendLargeAttachment() {
       ProcessAttachmentJob::dispatch(...)->onQueue('emails');
       return ['status' => 'queued'];
   }
   

4. 路由保护：

   // routes/mcp.php
   Mcp::route()
       ->middleware(['auth:api', 'throttle:100/minute']);
   

建议优先使用 属性注解自动注册，简洁高效且易于维护。复杂场景可结合服务提供者进行集中管理。