Laravel 中文文档

主题

Laravel 技术公众号，欢迎关注

Laravel MCP ​

介绍 ​

Laravel MCP 为 AI 客户端与 Laravel 应用程序通过模型上下文协议进行交互提供了一种简单而优雅的方式。它提供了表达性、流畅的接口来定义服务器、工具、资源和提示，实现由 AI 驱动的与应用程序的交互。

安装 ​

要开始使用，请使用 Composer 包管理器将 Laravel MCP 安装到您的项目中：

shell
composer require laravel/mcp

发布路由 ​

安装 Laravel MCP 后，执行 vendor:publish Artisan 命令来发布 routes/ai.php 文件，您将在其中定义 MCP 服务器：

shell
php artisan vendor:publish --tag=ai-routes

此命令在应用程序的 routes 目录中创建 routes/ai.php 文件，您将使用它来注册 MCP 服务器。

创建服务器 ​

您可以使用 make:mcp-server Artisan 命令创建 MCP 服务器。服务器作为向 AI 客户端公开工具、资源和提示等 MCP 功能的中央通信点：

shell
php artisan make:mcp-server WeatherServer

此命令将在 app/Mcp/Servers 目录中创建一个新的服务器类。生成的服务器类扩展了 Laravel MCP 的基础 Laravel\Mcp\Server 类，并提供了注册工具、资源和提示的属性：

php
<?php

namespace App\Mcp\Servers;

use Laravel\Mcp\Server;

class WeatherServer extends Server
{
    /**
     * MCP服务器的名称。
     */
    protected string $name = 'Weather Server';

    /**
     * MCP服务器的版本。
     */
    protected string $version = '1.0.0';

    /**
     * MCP服务器对LLM的说明。
     */
    protected string $instructions = 'This server provides weather information and forecasts.';

    /**
     * 在此MCP服务器中注册的工具。
     *
     * @var array<int, class-string<\Laravel\Mcp\Server\Tool>>
     */
    protected array $tools = [
        // GetCurrentWeatherTool::class,
    ];

    /**
     * 在此MCP服务器中注册的资源。
     *
     * @var array<int, class-string<\Laravel\Mcp\Server\Resource>>
     */
    protected array $resources = [
        // WeatherGuidelinesResource::class,
    ];

    /**
     * 在此MCP服务器中注册的提示。
     *
     * @var array<int, class-string<\Laravel\Mcp\Server\Prompt>>
     */
    protected array $prompts = [
        // DescribeWeatherPrompt::class,
    ];
}

服务器注册 ​

创建服务器后，您必须在 routes/ai.php 文件中注册它以使其可访问。Laravel MCP 提供两种注册服务器的方法：web 用于 HTTP 可访问的服务器，local 用于命令行服务器。

Web 服务器 ​

Web 服务器是最常见的服务器类型，可通过 HTTP POST 请求访问，非常适合远程 AI 客户端或基于 Web 的集成。使用 web 方法注册 Web 服务器：

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

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

就像普通路由一样，您可以将中间件应用到 Web 服务器以保护它们：

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

本地服务器 ​

本地服务器作为 Artisan 命令运行，非常适合构建本地 AI 助手集成，如 Laravel Boost。使用 local 方法注册本地服务器：

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

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

注册后，您通常不需要手动运行 mcp:start Artisan 命令。相反，配置您的 MCP 客户端（AI 代理）来启动服务器或使用 MCP 检查器。

工具 ​

工具使您的服务器能够向 AI 客户端公开功能。它们允许语言模型执行操作、运行代码或与外部系统交互：

php
<?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');

        // 获取天气...

        return Response::text('The weather is...');
    }

    /**
     * 获取工具的输入模式。
     *
     * @return array<string, \Illuminate\JsonSchema\JsonSchema>
     */
    public function schema(JsonSchema $schema): array
    {
        return [
            'location' => $schema->string()
                ->description('The location to get the weather for.')
                ->required(),
        ];
    }
}

创建工具 ​

要创建工具，运行 make:mcp-tool Artisan 命令：

shell
php artisan make:mcp-tool CurrentWeatherTool

创建工具后，在服务器的 $tools 属性中注册它：

php
<?php

namespace App\Mcp\Servers;

use App\Mcp\Tools\CurrentWeatherTool;
use Laravel\Mcp\Server;

class WeatherServer extends Server
{
    /**
     * 在此MCP服务器中注册的工具。
     *
     * @var array<int, class-string<\Laravel\Mcp\Server\Tool>>
     */
    protected array $tools = [
        CurrentWeatherTool::class,
    ];
}

工具名称、标题和描述 ​

默认情况下，工具的名称和标题派生自类名。例如，CurrentWeatherTool 的名称为 current-weather，标题为 Current Weather Tool。您可以通过定义工具的 $name 和 $title 属性来自定义这些值：

php
class CurrentWeatherTool extends Tool
{
    /**
     * 工具的名称。
     */
    protected string $name = 'get-optimistic-weather';

    /**
     * 工具的标题。
     */
    protected string $title = 'Get Optimistic Weather Forecast';

    // ...
}

工具描述不会自动生成。您应该始终通过在工具上定义 $description 属性来提供有意义的描述：

php
class CurrentWeatherTool extends Tool
{
    /**
     * 工具的描述。
     */
    protected string $description = 'Fetches the current weather forecast for a specified location.';

    //
}

NOTE

描述是工具元数据的关键部分，因为它帮助 AI 模型了解何时以及如何有效地使用工具。

工具输入模式 ​

工具可以定义输入模式来指定它们从 AI 客户端接受的参数。使用 Laravel 的 Illuminate\JsonSchema\JsonSchema 构建器来定义工具的输入要求：

php
<?php

namespace App\Mcp\Tools;

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

class CurrentWeatherTool extends Tool
{
    /**
     * 获取工具的输入模式。
     *
     * @return array<string, JsonSchema>
     */
    public function schema(JsonSchema $schema): array
    {
        return [
            'location' => $schema->string()
                ->description('The location to get the weather for.')
                ->required(),

            'units' => $schema->enum(['celsius', 'fahrenheit'])
                ->description('The temperature units to use.')
                ->default('celsius'),
        ];
    }
}

验证工具参数 ​

JSON Schema 定义为工具参数提供基本结构，但您可能还想执行更复杂的验证规则。

Laravel MCP 与 Laravel 的验证功能无缝集成。您可以在工具的 handle 方法中验证传入的工具参数：

php
<?php

namespace App\Mcp\Tools;

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

class CurrentWeatherTool extends Tool
{
    /**
     * 处理工具请求。
     */
    public function handle(Request $request): Response
    {
        $validated = $request->validate([
            'location' => 'required|string|max:100',
            'units' => 'in:celsius,fahrenheit',
        ]);

        // 使用验证的参数获取天气数据...
    }
}

验证失败时，AI 客户端将根据您提供的错误消息采取行动。因此，提供清晰且可操作的错误消息至关重要：

php
$validated = $request->validate([
    'location' => ['required','string','max:100'],
    'units' => 'in:celsius,fahrenheit',
],[
    'location.required' => 'You must specify a location to get the weather for. For example, "New York City" or "Tokyo".',
    'units.in' => 'You must specify either "celsius" or "fahrenheit" for the units.',
]);

工具依赖注入 ​

Laravel 服务容器用于解析所有工具。因此，您可以在构造函数中类型提示工具可能需要的任何依赖项。声明的依赖项将自动解析并注入到工具实例中：

php
<?php

namespace App\Mcp\Tools;

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

class CurrentWeatherTool extends Tool
{
    /**
     * 创建新的工具实例。
     */
    public function __construct(
        protected WeatherRepository $weather,
    ) {}

    // ...
}

除了构造函数注入，您还可以在工具的 handle() 方法中类型提示依赖项。当方法被调用时，服务容器将自动解析并注入依赖项：

php
<?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 handle(Request $request, WeatherRepository $weather): Response
    {
        $location = $request->get('location');

        $forecast = $weather->getForecastFor($location);

        // ...
    }
}

工具注解 ​

您可以使用注解来增强工具，为 AI 客户端提供额外的元数据。这些注解帮助 AI 模型理解工具的行为和能力。注解通过属性添加到工具中：

php
<?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
{
    //
}

可用注解包括：

注解类型描述
#[IsReadOnly]boolean表示工具不修改其环境。
#[IsDestructive]boolean表示工具可能执行破坏性更新（仅在非只读时有意义）。
#[IsIdempotent]boolean表示使用相同参数重复调用没有额外效果（当非只读时）。
#[IsOpenWorld]boolean表示工具可能与外部实体交互。

条件工具注册 ​

您可以通过在工具类中实现 shouldRegister 方法在运行时有条件地注册工具。此方法允许您根据应用程序状态、配置或请求参数确定是否应该使用工具：

php
<?php

namespace App\Mcp\Tools;

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

class CurrentWeatherTool extends Tool
{
    /**
     * 确定是否应该注册工具。
     */
    public function shouldRegister(Request $request): bool
    {
        return $request?->user()?->subscribed() ?? false;
    }
}

当工具的 shouldRegister 方法返回 false 时，它不会出现在可用工具列表中，也不能被 AI 客户端调用。

工具响应 ​

工具必须返回 Laravel\Mcp\Response 的实例。Response 类为创建不同类型的响应提供了几种方便的方法：

对于简单的文本响应，使用 text 方法：

php
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;

/**
 * 处理工具请求。
 */
public function handle(Request $request): Response
{
    // ...

    return Response::text('Weather Summary: Sunny, 72°F');
}

要指示工具执行期间发生了错误，使用 error 方法：

php
return Response::error('Unable to fetch weather data. Please try again.');

多内容响应 ​

工具可以通过返回 Response 实例的数组返回多个内容片段：

php
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;

/**
 * 处理工具请求。
 *
 * @return array<int, \Laravel\Mcp\Response>
 */
public function handle(Request $request): array
{
    // ...

    return [
        Response::text('Weather Summary: Sunny, 72°F'),
        Response::text('**Detailed Forecast**\n- Morning: 65°F\n- Afternoon: 78°F\n- Evening: 70°F')
    ];
}

流式响应 ​

对于长时间运行的操作或实时数据流，工具可以从其 handle 方法返回生成器。这使得能够在最终响应之前向客户端发送中间更新：

php
<?php

namespace App\Mcp\Tools;

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

class CurrentWeatherTool extends Tool
{
    /**
     * 处理工具请求。
     *
     * @return \Generator<int, \Laravel\Mcp\Response>
     */
    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));
        }
    }
}

使用基于 Web 的服务器时，流式响应会自动打开 SSE（服务器发送事件）流，将每个产生的消息作为事件发送给客户端。

提示 ​

提示使您的服务器能够共享 AI 客户端可以用来与语言模型交互的可重用提示模板。它们提供了一种标准化的方式来构建常见查询和交互。

创建提示 ​

要创建提示，运行 make:mcp-prompt Artisan 命令：

shell
php artisan make:mcp-prompt DescribeWeatherPrompt

创建提示后，在服务器的 $prompts 属性中注册它：

php
<?php

namespace App\Mcp\Servers;

use App\Mcp\Prompts\DescribeWeatherPrompt;
use Laravel\Mcp\Server;

class WeatherServer extends Server
{
    /**
     * 在此MCP服务器中注册的提示。
     *
     * @var array<int, class-string<\Laravel\Mcp\Server\Prompt>>
     */
    protected array $prompts = [
        DescribeWeatherPrompt::class,
    ];
}

提示名称、标题和描述 ​

默认情况下，提示的名称和标题派生自类名。例如，DescribeWeatherPrompt 的名称为 describe-weather，标题为 Describe Weather Prompt。您可以通过在提示上定义 $name 和 $title 属性来自定义这些值：

php
class DescribeWeatherPrompt extends Prompt
{
    /**
     * 提示的名称。
     */
    protected string $name = 'weather-assistant';

    /**
     * 提示的标题。
     */
    protected string $title = 'Weather Assistant Prompt';

    // ...
}

提示描述不会自动生成。您应该始终通过在提示上定义 $description 属性来提供有意义的描述：

php
class DescribeWeatherPrompt extends Prompt
{
    /**
     * 提示的描述。
     */
    protected string $description = 'Generates a natural-language explanation of the weather for a given location.';

    //
}

NOTE

描述是提示元数据的关键部分，因为它帮助 AI 模型了解何时以及如何最好地使用提示。

提示参数 ​

提示可以定义参数，允许 AI 客户端使用特定值自定义提示模板。使用 arguments 方法定义提示接受的参数：

php
<?php

namespace App\Mcp\Prompts;

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

class DescribeWeatherPrompt extends Prompt
{
    /**
     * 获取提示的参数。
     *
     * @return array<int, \Laravel\Mcp\Server\Prompts\Argument>
     */
    public function arguments(): array
    {
        return [
            new Argument(
                name: 'tone',
                description: 'The tone to use in the weather description (e.g., formal, casual, humorous).',
                required: true,
            ),
        ];
    }
}

验证提示参数 ​

提示参数根据其定义自动验证，但您可能还想执行更复杂的验证规则。

Laravel MCP 与 Laravel 的验证功能无缝集成。您可以在提示的 handle 方法中验证传入的提示参数：

php
<?php

namespace App\Mcp\Prompts;

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

class DescribeWeatherPrompt extends Prompt
{
    /**
     * 处理提示请求。
     */
    public function handle(Request $request): Response
    {
        $validated = $request->validate([
            'tone' => 'required|string|max:50',
        ]);

        $tone = $validated['tone'];

        // 使用给定语调生成提示响应...
    }
}

验证失败时，AI 客户端将根据您提供的错误消息采取行动。因此，提供清晰且可操作的错误消息至关重要：

php
$validated = $request->validate([
    'tone' => ['required','string','max:50'],
],[
    'tone.*' => 'You must specify a tone for the weather description. Examples include "formal", "casual", or "humorous".',
]);

提示依赖注入 ​

Laravel 服务容器用于解析所有提示。因此，您可以在构造函数中类型提示提示可能需要的任何依赖项。声明的依赖项将自动解析并注入到提示实例中：

php
<?php

namespace App\Mcp\Prompts;

use App\Repositories\WeatherRepository;
use Laravel\Mcp\Server\Prompt;

class DescribeWeatherPrompt extends Prompt
{
    /**
     * 创建新的提示实例。
     */
    public function __construct(
        protected WeatherRepository $weather,
    ) {}

    //
}

除了构造函数注入，您还可以在提示的 handle 方法中类型提示依赖项。当方法被调用时，服务容器将自动解析并注入依赖项：

php
<?php

namespace App\Mcp\Prompts;

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

class DescribeWeatherPrompt extends Prompt
{
    /**
     * 处理提示请求。
     */
    public function handle(Request $request, WeatherRepository $weather): Response
    {
        $isAvailable = $weather->isServiceAvailable();

        // ...
    }
}

条件提示注册 ​

您可以通过在提示类中实现 shouldRegister 方法在运行时有条件地注册提示。此方法允许您根据应用程序状态、配置或请求参数确定是否应该使用提示：

php
<?php

namespace App\Mcp\Prompts;

use Laravel\Mcp\Request;
use Laravel\Mcp\Server\Prompt;

class CurrentWeatherPrompt extends Prompt
{
    /**
     * 确定是否应该注册提示。
     */
    public function shouldRegister(Request $request): bool
    {
        return $request?->user()?->subscribed() ?? false;
    }
}

当提示的 shouldRegister 方法返回 false 时，它不会出现在可用提示列表中，也不能被 AI 客户端调用。

提示响应 ​

提示可以返回单个 Laravel\Mcp\Response 或 Laravel\Mcp\Response 实例的可迭代对象。这些响应封装了将发送给 AI 客户端的内容：

php
<?php

namespace App\Mcp\Prompts;

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

class DescribeWeatherPrompt extends Prompt
{
    /**
     * 处理提示请求。
     *
     * @return array<int, \Laravel\Mcp\Response>
     */
    public function handle(Request $request): array
    {
        $tone = $request->string('tone');

        $systemMessage = "You are a helpful weather assistant. Please provide a weather description in a {$tone} tone.";

        $userMessage = "What is the current weather like in New York City?";

        return [
            Response::text($systemMessage)->asAssistant(),
            Response::text($userMessage),
        ];
    }
}

您可以使用 asAssistant() 方法指示响应消息应被视为来自 AI 助手，而常规消息被视为用户输入。

资源 ​

资源使您的服务器能够公开 AI 客户端在与语言模型交互时可以读取和用作上下文的数据和内容。它们提供了一种共享静态或动态信息（如文档、配置或任何有助于告知 AI 响应的数据）的方式。

创建资源 ​

要创建资源，运行 make:mcp-resource Artisan 命令：

shell
php artisan make:mcp-resource WeatherGuidelinesResource

创建资源后，在服务器的 $resources 属性中注册它：

php
<?php

namespace App\Mcp\Servers;

use App\Mcp\Resources\WeatherGuidelinesResource;
use Laravel\Mcp\Server;

class WeatherServer extends Server
{
    /**
     * 在此MCP服务器中注册的资源。
     *
     * @var array<int, class-string<\Laravel\Mcp\Server\Resource>>
     */
    protected array $resources = [
        WeatherGuidelinesResource::class,
    ];
}

资源名称、标题和描述 ​

默认情况下，资源的名称和标题派生自类名。例如，WeatherGuidelinesResource 的名称为 weather-guidelines，标题为 Weather Guidelines Resource。您可以通过在资源上定义 $name 和 $title 属性来自定义这些值：

php
class WeatherGuidelinesResource extends Resource
{
    /**
     * 资源的名称。
     */
    protected string $name = 'weather-api-docs';

    /**
     * 资源的标题。
     */
    protected string $title = 'Weather API Documentation';

    // ...
}

资源描述不会自动生成。您应该始终通过在资源上定义 $description 属性来提供有意义的描述：

php
class WeatherGuidelinesResource extends Resource
{
    /**
     * 资源的描述。
     */
    protected string $description = 'Comprehensive guidelines for using the Weather API.';

    //
}

NOTE

描述是资源元数据的关键部分，因为它帮助 AI 模型了解何时以及如何有效地使用资源。

资源 URI 和 MIME 类型 ​

每个资源都由唯一的 URI 标识，并具有关联的 MIME 类型，帮助 AI 客户端理解资源的格式。

默认情况下，资源的 URI 基于资源的名称生成，因此 WeatherGuidelinesResource 的 URI 为 weather://resources/weather-guidelines。默认 MIME 类型为 text/plain。

您可以通过在资源上定义 $uri 和 $mimeType 属性来自定义这些值：

php
<?php

namespace App\Mcp\Resources;

use Laravel\Mcp\Server\Resource;

class WeatherGuidelinesResource extends Resource
{
    /**
     * 资源的URI。
     */
    protected string $uri = 'weather://resources/guidelines';

    /**
     * 资源的MIME类型。
     */
    protected string $mimeType = 'application/pdf';
}

URI 和 MIME 类型帮助 AI 客户端确定如何适当地处理和解释资源内容。

资源请求 ​

与工具和提示不同，资源不能定义输入模式或参数。但是，您仍然可以在资源的 handle 方法中与请求对象交互：

php
<?php

namespace App\Mcp\Resources;

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

class WeatherGuidelinesResource extends Resource
{
    /**
     * 处理资源请求。
     */
    public function handle(Request $request): Response
    {
        // ...
    }
}

资源依赖注入 ​

Laravel 服务容器用于解析所有资源。因此，您可以在构造函数中类型提示资源可能需要的任何依赖项。声明的依赖项将自动解析并注入到资源实例中：

php
<?php

namespace App\Mcp\Resources;

use App\Repositories\WeatherRepository;
use Laravel\Mcp\Server\Resource;

class WeatherGuidelinesResource extends Resource
{
    /**
     * 创建新的资源实例。
     */
    public function __construct(
        protected WeatherRepository $weather,
    ) {}

    // ...
}

除了构造函数注入，您还可以在资源的 handle 方法中类型提示依赖项。当方法被调用时，服务容器将自动解析并注入依赖项：

php
<?php

namespace App\Mcp\Resources;

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

class WeatherGuidelinesResource extends Resource
{
    /**
     * 处理资源请求。
     */
    public function handle(WeatherRepository $weather): Response
    {
        $guidelines = $weather->guidelines();

        return Response::text($guidelines);
    }
}

条件资源注册 ​

您可以通过在资源类中实现 shouldRegister 方法在运行时有条件地注册资源。此方法允许您根据应用程序状态、配置或请求参数确定是否应该使用资源：

php
<?php

namespace App\Mcp\Resources;

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

class WeatherGuidelinesResource extends Resource
{
    /**
     * 确定是否应该注册资源。
     */
    public function shouldRegister(Request $request): bool
    {
        return $request?->user()?->subscribed() ?? false;
    }
}

当资源的 shouldRegister 方法返回 false 时，它不会出现在可用资源列表中，也不能被 AI 客户端访问。

资源响应 ​

资源必须返回 Laravel\Mcp\Response 的实例。Response 类为创建不同类型的响应提供了几种方便的方法：

对于简单的文本内容，使用 text 方法：

php
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;

/**
 * 处理资源请求。
 */
public function handle(Request $request): Response
{
    // ...

    return Response::text($weatherData);
}

Blob 响应 ​

要返回 blob 内容，使用 blob 方法，提供 blob 内容：

php
return Response::blob(file_get_contents(storage_path('weather/radar.png')));

返回 blob 内容时，MIME 类型将由资源类上的 $mimeType 属性的值确定：

php
<?php

namespace App\Mcp\Resources;

use Laravel\Mcp\Server\Resource;

class WeatherGuidelinesResource extends Resource
{
    /**
     * 资源的MIME类型。
     */
    protected string $mimeType = 'image/png';

    //
}

错误响应 ​

要指示资源检索期间发生了错误，使用 error() 方法：

php
return Response::error('Unable to fetch weather data for the specified location.');

认证 ​

您可以像路由一样使用中间件来认证 Web MCP 服务器。这将要求用户在使用服务器的任何功能之前进行认证。

有两种方式来认证对 MCP 服务器的访问：通过Laravel Sanctum进行简单的基于令牌的认证，或通过Authorization HTTP 头传递的任何其他任意 API 令牌。或者，您可以使用Laravel Passport通过 OAuth 进行认证。

OAuth 2.1 ​

保护基于 Web 的 MCP 服务器最强大的方式是通过Laravel Passport使用 OAuth。

通过 OAuth 认证 MCP 服务器时，您将在 routes/ai.php 文件中调用 Mcp::oauthRoutes 方法来注册所需的 OAuth2 发现和客户端注册路由。然后，在您的 routes/ai.php 文件中将 Passport 的 auth:api 中间件应用到您的 Mcp::web 路由：

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

Mcp::oauthRoutes();

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

新的 Passport 安装 ​

如果您的应用程序还没有使用 Laravel Passport，请先遵循 Passport 的安装和部署步骤。在继续之前，您应该有一个OAuthenticatable模型、新的认证守卫和 passport 密钥。

接下来，您应该发布 Laravel MCP 提供的 Passport 授权视图：

shell
php artisan vendor:publish --tag=mcp-views

然后，使用 Passport::authorizationView 方法指示 Passport 使用此视图。通常，此方法应该在应用程序的 AppServiceProvider 的 boot 方法中调用：

php
use Laravel\Passport\Passport;

/**
 * 引导任何应用程序服务。
 */
public function boot(): void
{
    Passport::authorizationView(function ($parameters) {
        return view('mcp.authorize', $parameters);
    });
}

此视图将在认证期间向最终用户显示，以拒绝或批准 AI 代理的认证尝试。

现有的 Passport 安装 ​

如果您的应用程序已经在使用 Laravel Passport，Laravel MCP 应该在您现有的 Passport 安装中无缝工作，但目前不支持自定义作用域，因为 OAuth 主要用作基础可认证模型的翻译层。

Laravel MCP 通过上面讨论的 Mcp::oauthRoutes() 方法，添加、广告和使用单个 mcp:use 作用域。

Passport vs. Sanctum ​

OAuth2.1 是模型上下文协议规范中记录的认证机制，在 MCP 客户端中支持最广泛。因此，我们建议在可能的情况下使用 Passport。

如果您的应用程序已经在使用Sanctum，那么添加 Passport 可能会很麻烦。在这种情况下，我们建议使用 Sanctum 而不使用 Passport，直到您有明确的、必要的要求来使用只支持 OAuth 的 MCP 客户端。

Sanctum ​

如果您想使用 Sanctum 保护您的 MCP 服务器，只需在您的 routes/ai.php 文件中将 Sanctum 的认证中间件添加到您的服务器。然后，确保您的 MCP 客户端提供 Authorization: Bearer <token> 头以确保成功认证：

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

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

自定义 MCP 认证 ​

如果您的应用程序发布自己的自定义 API 令牌，您可以通过将任何您希望的中间件分配给 Mcp::web 路由来认证您的 MCP 服务器。您的自定义中间件可以手动检查 Authorization 头来认证传入的 MCP 请求。

授权 ​

您可以通过 $request->user() 方法访问当前认证的用户，允许您在 MCP 工具和资源中执行授权检查：

php
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;

/**
 * 处理工具请求。
 */
public function handle(Request $request): Response
{
    if (! $request->user()->can('read-weather')) {
        return Response::error('Permission denied.');
    }

    // ...
}

测试服务器 ​

您可以使用内置的 MCP 检查器或编写单元测试来测试您的 MCP 服务器。

MCP 检查器 ​

MCP 检查器是用于测试和调试 MCP 服务器的交互式工具。使用它连接到您的服务器、验证认证并试用工具、资源和提示。

您可以为任何已注册的服务器运行检查器：

shell
# Web服务器...
php artisan mcp:inspector /mcp/weather

# 名为"weather"的本地服务器...
php artisan mcp:inspector weather

此命令启动 MCP 检查器并提供您可以复制到 MCP 客户端的客户端设置，以确保一切配置正确。如果您的 Web 服务器受到认证中间件保护，请确保在连接时包含所需的头，如 Authorization bearer 令牌。

单元测试 ​

您可以为 MCP 服务器、工具、资源和提示编写单元测试。

要开始，创建一个新的测试用例并在注册它的服务器上调用所需的原语。例如，要测试 WeatherServer 上的工具：

php
test('tool', function () {
    $response = WeatherServer::tool(CurrentWeatherTool::class, [
        'location' => 'New York City',
        'units' => 'fahrenheit',
    ]);

    $response
        ->assertOk()
        ->assertSee('The current weather in New York City is 72°F and sunny.');
});
php
/**
 * 测试工具。
 */
public function test_tool(): void
{
    $response = WeatherServer::tool(CurrentWeatherTool::class, [
        'location' => 'New York City',
        'units' => 'fahrenheit',
    ]);

    $response
        ->assertOk()
        ->assertSee('The current weather in New York City is 72°F and sunny.');
}

类似地，您可以测试提示和资源：

php
$response = WeatherServer::prompt(...);
$response = WeatherServer::resource(...);

您还可以通过在调用原语之前链接 actingAs 方法来作为认证用户进行操作：

php
$response = WeatherServer::actingAs($user)->tool(...);

收到响应后，您可以使用各种断言方法来验证响应的内容和状态。

您可以使用 assertOk 方法断言响应成功。这会检查响应没有任何错误：

php
$response->assertOk();

您可以使用 assertSee 方法断言响应包含特定文本：

php
$response->assertSee('The current weather in New York City is 72°F and sunny.');

您可以使用 assertHasErrors 方法断言响应包含错误：

php
$response->assertHasErrors();

$response->assertHasErrors([
    'Something went wrong.',
]);

您可以使用 assertHasNoErrors 方法断言响应不包含错误：

php
$response->assertHasNoErrors();

您可以使用 assertName()、assertTitle() 和 assertDescription() 方法断言响应包含特定元数据：

php
$response->assertName('current-weather');
$response->assertTitle('Current Weather Tool');
$response->assertDescription('Fetches the current weather forecast for a specified location.');

您可以使用 assertSentNotification 和 assertNotificationCount 方法断言发送了通知：

php
$response->assertSentNotification('processing/progress', [
    'step' => 1,
    'total' => 5,
]);

$response->assertSentNotification('processing/progress', [
    'step' => 2,
    'total' => 5,
]);

$response->assertNotificationCount(5);

最后，如果您希望检查原始响应内容，可以使用 dd 或 dump 方法输出响应进行调试：

php
$response->dd();
$response->dump();