laravel-mcp

Laravel MCP 技能

全面协助开发 Laravel MCP（Model Context Protocol）。Laravel MCP 提供了一种简单优雅的方式，让 AI 客户端通过 Model Context Protocol 与 Laravel 应用交互，从而能够定义服务器、工具、资源和提示词，支持 AI 驱动的交互。

何时使用此技能

出现以下情况时应触发此技能：

• 为 Laravel 应用构建 MCP 服务
• 创建可在 Laravel 中执行操作的 AI 工具
• 为 AI 交互定义可复用的提示词
• 向 AI 客户端开放 Laravel 资源（数据/内容）
• 为 MCP 实现 OAuth 2.1 或 Sanctum 身份验证
• 注册并配置 MCP 路由（Web 或本地）
• 测试 MCP 服务和工具
• 使用 Laravel JSON Schema 构建器处理工具输入
• 实现流式响应或进度通知
• 使用 MCP 构建 AI 驱动的 Laravel 功能

核心概念

核心组件

MCP 服务：对外提供 MCP 功能的中央通信端点。每个服务包含：

• name：服务标识符
• version：服务版本
• instructions：服务用途说明
• tools：工具类数组
• resources：资源类数组
• prompts：提示词类数组

工具：让 AI 客户端能够执行操作。工具可以：

• 使用 Laravel 的 JSON Schema 构建器定义输入架构
• 使用 Laravel 验证规则验证参数
• 支持依赖注入
• 返回一个或多个响应
• 使用生成器流式传输响应
• 使用 #[IsReadOnly] 和 #[IsIdempotent] 等注解

提示词：可复用的提示词模板，通过定义参数和验证，为常见查询提供标准化的结构方式。

资源：让服务能够向 AI 客户端开放可读取的数据和内容，包括支持自定义 MIME 类型和 URI 的文本响应及二进制数据响应。

快速参考

1. 基本 MCP 服务定义

<?php
namespace App\Mcp\Servers;

use Laravel\Mcp\Server;

class WeatherServer extends Server
{
    protected string $name = 'Weather Server';
    protected string $version = '1.0.0';
    protected string $instructions = 'This server provides weather information and forecasts.';

    protected array $tools = [
        // CurrentWeatherTool::class,
    ];

    protected array $resources = [
        // WeatherGuidelinesResource::class,
    ];

    protected array $prompts = [
        // DescribeWeatherPrompt::class,
    ];
}

2. 带输入架构的工具

<?php
namespace App\Mcp\Tools;

use Illuminate\JsonSchema\JsonSchema;
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Tool;

class CurrentWeatherTool extends Tool
{
    protected string $description = 'Fetches the current weather forecast for a specified location.';

    public function handle(Request $request): Response
    {
        $location = $request->get('location');
        // Get weather...
        return Response::text('The weather is...');
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'location' => $schema->string()
                ->description('The location to get the weather for.')
                ->required(),
        ];
    }
}

3. 带验证的工具

public function handle(Request $request): Response
{
    $validated = $request->validate([
        'location' => 'required|string|max:100',
        'units' => 'in:celsius,fahrenheit',
    ], [
        'location.required' => 'You must specify a location.',
        'units.in' => 'You must specify either "celsius" or "fahrenheit".',
    ]);
    // Fetch weather data...
}

4. 带依赖注入的工具

<?php
namespace App\Mcp\Tools;

use App\Repositories\WeatherRepository;
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Tool;

class CurrentWeatherTool extends Tool
{
    public function __construct(
        protected WeatherRepository $weather,
    ) {}

    public function handle(Request $request, WeatherRepository $weather): Response
    {
        $location = $request->get('location');
        $forecast = $weather->getForecastFor($location);
        // ...
    }
}

5. 带注解的工具

<?php
namespace App\Mcp\Tools;

use Laravel\Mcp\Server\Tools\Annotations\IsIdempotent;
use Laravel\Mcp\Server\Tools\Annotations\IsReadOnly;
use Laravel\Mcp\Server\Tool;

#[IsIdempotent]
#[IsReadOnly]
class CurrentWeatherTool extends Tool
{
    // ...
}

6. 流式工具响应

<?php
namespace App\Mcp\Tools;

use Generator;
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Tool;

class CurrentWeatherTool extends Tool
{
    public function handle(Request $request): Generator
    {
        $locations = $request->array('locations');

        foreach ($locations as $index => $location) {
            yield Response::notification('processing/progress', [
                'current' => $index + 1,
                'total' => count($locations),
                'location' => $location,
            ]);
            yield Response::text($this->forecastFor($location));
        }
    }
}

7. 提示词定义

<?php
namespace App\Mcp\Prompts;

use Laravel\Mcp\Server\Prompt;
use Laravel\Mcp\Server\Prompts\Argument;

class DescribeWeatherPrompt extends Prompt
{
    protected string $description = 'Generates a natural-language explanation of the weather.';

    public function arguments(): array
    {
        return [
            new Argument(
                name: 'tone',
                description: 'The tone to use in the weather description.',
                required: true,
            ),
        ];
    }

    public function handle(Request $request): array
    {
        $tone = $request->string('tone');
        return [
            Response::text("You are a weather assistant. Provide a {$tone} tone.")->asAssistant(),
            Response::text("What is the current weather like in New York City?"),
        ];
    }
}

8. 资源定义

<?php
namespace App\Mcp\Resources;

use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Resource;

class WeatherGuidelinesResource extends Resource
{
    protected string $description = 'Comprehensive guidelines for using the Weather API.';
    protected string $uri = 'weather://resources/guidelines';
    protected string $mimeType = 'application/pdf';

    public function handle(Request $request): Response
    {
        return Response::text($weatherData);
    }
}

9. 服务注册（Web）

use App\Mcp\Servers\WeatherServer;
use Laravel\Mcp\Facades\Mcp;

Mcp::web('/mcp/weather', WeatherServer::class);

// With middleware
Mcp::web('/mcp/weather', WeatherServer::class)
    ->middleware(['throttle:mcp']);

10. 服务注册（本地）

use App\Mcp\Servers\WeatherServer;
use Laravel\Mcp\Facades\Mcp;

Mcp::local('weather', WeatherServer::class);

11. OAuth 2.1 身份验证设置

use App\Mcp\Servers\WeatherExample;
use Laravel\Mcp\Facades\Mcp;

Mcp::oauthRoutes();

Mcp::web('/mcp/weather', WeatherExample::class)
    ->middleware('auth:api');

12. Sanctum 身份验证

use App\Mcp\Servers\WeatherExample;
use Laravel\Mcp\Facades\Mcp;

Mcp::web('/mcp/demo', WeatherExample::class)
    ->middleware('auth:sanctum');

参考文件

此技能在 references/ 中提供了全面的文档：

• other.md - Laravel 12.x 官方文档中的完整 Laravel MCP 文档，包括：
  • 安装和设置说明
  • 创建服务、工具、资源和提示词
  • 使用 JSON Schema 构建器定义输入架构
  • 验证和依赖注入
  • 流式响应和进度通知
  • 身份验证（OAuth 2.1 和 Sanctum）
  • 注册（Web 和本地路由）
  • 测试和检查

需要详细信息时，使用 view 阅读具体参考文件。

使用此技能

面向初学者

首先了解核心概念：

1. 安装：通过 composer require laravel/mcp 安装 Laravel MCP
2. 设置：运行 php artisan vendor:publish --tag=ai-routes 创建 routes/ai.php
3. 首个服务：使用 php artisan make:mcp-server 生成首个服务
4. 注册：使用 Mcp::web() 或 Mcp::local() 将服务添加到 routes/ai.php

先使用 #[IsReadOnly] 注解构建简单的只读工具，再尝试修改数据的工具。

面向中级用户

专注于构建健壮的工具：

• 使用 JSON Schema 构建器进行精确的输入验证
• 利用 Laravel 的验证规则处理复杂约束
• 实现依赖注入，编写简洁且易于测试的代码
• 使用提示词创建可复用的 AI 交互模式
• 开放资源，为 AI 客户端提供上下文

面向高级用户

实现可用于生产环境的功能：

• 添加 OAuth 2.1 或 Sanctum 身份验证，以保护 MCP 服务
• 对长时间运行的操作使用流式响应，并发送进度通知
• 使用中间件进行速率限制和自定义身份验证
• 使用 #[IsIdempotent] 注解创建幂等工具
• 构建复杂的多工具工作流
• 使用 MCP Inspector 进行调试和测试

导航提示

• 快速实现：使用上方的快速参考部分了解常见模式
• 深入学习：阅读 references/other.md，查看完整文档
• 示例：所有代码示例都包含正确的命名空间和导入语句
• 测试：参阅文档，了解 MCP Inspector 的用法和单元测试

常见模式

创建新的 MCP 服务

# Generate server class
php artisan make:mcp-server WeatherServer

# Edit app/Mcp/Servers/WeatherServer.php
# Add tools, resources, and prompts

# Register in routes/ai.php
Mcp::web('/mcp/weather', WeatherServer::class);

输入架构模式

// Simple required string
'location' => $schema->string()->required()

// Optional with default
'units' => $schema->string()->default('celsius')

// Number with constraints
'temperature' => $schema->number()->minimum(0)->maximum(100)

// Array of items
'cities' => $schema->array()->items($schema->string())

// Object with properties
'forecast' => $schema->object()->properties([
    'temperature' => $schema->number(),
    'humidity' => $schema->number(),
])

响应模式

// Text response
return Response::text('The weather is sunny');

// Multiple responses
return [
    Response::text('First message'),
    Response::text('Second message'),
];

// Notification (streaming)
yield Response::notification('processing/progress', ['status' => 'processing']);

资源

安装

composer require laravel/mcp
php artisan vendor:publish --tag=ai-routes

官方文档

• Laravel MCP 文档：https://laravel.com/docs/12.x/mcp
• Model Context Protocol 规范：https://modelcontextprotocol.io/

相关 Laravel 功能

• JSON Schema Builder：用于定义工具输入架构
• Validation：用于验证工具参数
• Service Container：用于在工具和资源中进行依赖注入
• OAuth/Sanctum：用于身份验证

说明

• 此技能根据 Laravel 12.x MCP 官方文档生成
• 所有代码示例均使用规范的 PHP 8+ 语法和类型化属性
• 示例展示了 Laravel 优雅的 API 设计
• 工具支持同步响应和流式响应
• 身份验证为可选项，但建议在生产环境中启用
• 同时支持通过 Web（HTTP）和本地（CLI）注册服务

提示与最佳实践

1. 从简单开始：先从标记了 #[IsReadOnly] 的只读工具开始
2. 验证输入：始终定义架构，并使用验证来检查用户输入
3. 使用 DI：利用依赖注入来管理存储库和服务
4. 流式传输进度：对于长时间运行的操作，使用生成器流式传输进度
5. 保护服务：在生产环境中添加身份验证中间件
6. 充分测试：使用 MCP Inspector 和单元测试验证功能
7. 编写完善的文档：为服务、工具、提示词和资源撰写清晰的说明
8. 遵循约定：使用 Laravel 的服务容器模式和命名约定