Laravel 中文文档

主题

Laravel MCP ​

简介 ​

Laravel MCP 提供了一种简单优雅的方式，让 AI 客户端通过 Model Context Protocol 与你的 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\Attributes\Instructions;
use Laravel\Mcp\Server\Attributes\Name;
use Laravel\Mcp\Server\Attributes\Version;
use Laravel\Mcp\Server;

#[Name('Weather Server')]
#[Version('1.0.0')]
#[Instructions('This server provides weather information and forecasts.')]
class WeatherServer extends Server
{
    /**
     * The tools registered with this MCP server.
     *
     * @var array<int, class-string<\Laravel\Mcp\Server\Tool>>
     */
    protected array $tools = [
        // GetCurrentWeatherTool::class,
    ];

    /**
     * The resources registered with this MCP server.
     *
     * @var array<int, class-string<\Laravel\Mcp\Server\Resource>>
     */
    protected array $resources = [
        // WeatherGuidelinesResource::class,
    ];

    /**
     * The prompts registered with this MCP server.
     *
     * @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);

就像普通路由一样，你可以应用 middleware 来保护你的 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 Inspector。

工具 ​

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

php
<?php

namespace App\Mcp\Tools;

use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Attributes\Description;
use Laravel\Mcp\Server\Tool;

#[Description('Fetches the current weather forecast for a specified location.')]
class CurrentWeatherTool extends Tool
{
    /**
     * Handle the tool request.
     */
    public function handle(Request $request): Response
    {
        $location = $request->get('location');

        // 获取天气...

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

    /**
     * Get the tool's input schema.
     *
     * @return array<string, \Illuminate\JsonSchema\Types\Type>
     */
    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
{
    /**
     * The tools registered with this MCP server.
     *
     * @var array<int, class-string<\Laravel\Mcp\Server\Tool>>
     */
    protected array $tools = [
        CurrentWeatherTool::class,
    ];
}

工具名称、标题和描述 ​

默认情况下，工具的名称和标题从类名派生。例如，CurrentWeatherTool 的名称为 current-weather，标题为 Current Weather Tool。你可以使用 Name 和 Title 属性自定义这些值：

php
use Laravel\Mcp\Server\Attributes\Name;
use Laravel\Mcp\Server\Attributes\Title;

#[Name('get-optimistic-weather')]
#[Title('Get Optimistic Weather Forecast')]
class CurrentWeatherTool extends Tool
{
    // ...
}

工具描述不会自动生成。你应该始终使用 Description 属性提供有意义的描述：

php
use Laravel\Mcp\Server\Attributes\Description;

#[Description('Fetches the current weather forecast for a specified location.')]
class CurrentWeatherTool extends Tool
{
    //
}

NOTE

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

工具输入模式 ​

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

php
<?php

namespace App\Mcp\Tools;

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

class CurrentWeatherTool extends Tool
{
    /**
     * Get the tool's input schema.
     *
     * @return array<string, \Illuminate\JsonSchema\Types\Type>
     */
    public function schema(JsonSchema $schema): array
    {
        return [
            'location' => $schema->string()
                ->description('The location to get the weather for.')
                ->required(),

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

工具输出模式 ​

工具可以定义输出模式来指定其响应的结构。这使得需要可解析工具结果的 AI 客户端能够更好地集成。使用 outputSchema 方法定义工具的输出结构：

php
<?php

namespace App\Mcp\Tools;

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

class CurrentWeatherTool extends Tool
{
    /**
     * Get the tool's output schema.
     *
     * @return array<string, \Illuminate\JsonSchema\Types\Type>
     */
    public function outputSchema(JsonSchema $schema): array
    {
        return [
            'temperature' => $schema->number()
                ->description('Temperature in Celsius')
                ->required(),

            'conditions' => $schema->string()
                ->description('Weather conditions')
                ->required(),

            'humidity' => $schema->integer()
                ->description('Humidity percentage')
                ->required(),
        ];
    }
}

验证工具参数 ​

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
{
    /**
     * Handle the tool request.
     */
    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
{
    /**
     * Create a new tool instance.
     */
    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
{
    /**
     * Handle the tool request.
     */
    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表示工具可能与外部实体交互。

注解值可以使用布尔参数显式设置：

php
use Laravel\Mcp\Server\Tools\Annotations\IsReadOnly;
use Laravel\Mcp\Server\Tools\Annotations\IsDestructive;
use Laravel\Mcp\Server\Tools\Annotations\IsOpenWorld;
use Laravel\Mcp\Server\Tools\Annotations\IsIdempotent;
use Laravel\Mcp\Server\Tool;

#[IsReadOnly(true)]
#[IsDestructive(false)]
#[IsOpenWorld(false)]
#[IsIdempotent(true)]
class CurrentWeatherTool extends Tool
{
    //
}

条件工具注册 ​

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

php
<?php

namespace App\Mcp\Tools;

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

class CurrentWeatherTool extends Tool
{
    /**
     * Determine if the tool should be registered.
     */
    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;

/**
 * Handle the tool request.
 */
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.');

要返回图片或音频内容，使用 image 和 audio 方法：

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

return Response::audio(file_get_contents(storage_path('weather/alert.mp3')), 'audio/mp3');

你还可以使用 fromStorage 方法直接从 Laravel 文件系统磁盘加载图片和音频内容。MIME 类型将从文件自动检测：

php
return Response::fromStorage('weather/radar.png');

如果需要，你可以指定特定的磁盘或覆盖 MIME 类型：

php
return Response::fromStorage('weather/radar.png', disk: 's3');

return Response::fromStorage('weather/radar.png', mimeType: 'image/webp');

多内容响应 ​

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

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

/**
 * Handle the tool request.
 *
 * @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')
    ];
}

结构化响应 ​

工具可以使用 structured 方法返回结构化内容。这为需要可解析工具结果的 AI 客户端提供可解析的数据，同时保持与 JSON 编码文本表示的向后兼容性：

php
return Response::structured([
    'temperature' => 22.5,
    'conditions' => 'Partly cloudy',
    'humidity' => 65,
]);

如果你需要在结构化内容旁提供自定义文本，请在响应工厂上使用 withStructuredContent 方法：

php
return Response::make(
    Response::text('Weather is 22.5°C and sunny')
)->withStructuredContent([
    'temperature' => 22.5,
    'conditions' => 'Sunny',
]);

流式响应 ​

对于长时间运行的操作或实时数据流，工具可以从其 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
{
    /**
     * Handle the tool request.
     *
     * @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（Server-Sent Events）流，将每个 yield 的消息作为事件发送到客户端。

Prompts ​

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

创建 Prompts ​

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

shell
php artisan make:mcp-prompt DescribeWeatherPrompt

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

php
<?php

namespace App\Mcp\Servers;

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

class WeatherServer extends Server
{
    /**
     * The prompts registered with this MCP server.
     *
     * @var array<int, class-string<\Laravel\Mcp\Server\Prompt>>
     */
    protected array $prompts = [
        DescribeWeatherPrompt::class,
    ];
}

Prompt 名称、标题和描述 ​

默认情况下，prompt 的名称和标题从类名派生。例如，DescribeWeatherPrompt 的名称为 describe-weather，标题为 Describe Weather Prompt。你可以使用 Name 和 Title 属性自定义这些值：

php
use Laravel\Mcp\Server\Attributes\Name;
use Laravel\Mcp\Server\Attributes\Title;

#[Name('weather-assistant')]
#[Title('Weather Assistant Prompt')]
class DescribeWeatherPrompt extends Prompt
{
    // ...
}

Prompt 描述不会自动生成。你应该始终使用 Description 属性提供有意义的描述：

php
use Laravel\Mcp\Server\Attributes\Description;

#[Description('Generates a natural-language explanation of the weather for a given location.')]
class DescribeWeatherPrompt extends Prompt
{
    //
}

NOTE

描述是 prompt 元数据的关键部分，因为它帮助 AI 模型理解何时以及如何充分利用该 prompt。

Prompt 参数 ​

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

php
<?php

namespace App\Mcp\Prompts;

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

class DescribeWeatherPrompt extends Prompt
{
    /**
     * Get the prompt's arguments.
     *
     * @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,
            ),
        ];
    }
}

验证 Prompt 参数 ​

Prompt 参数会根据其定义自动验证，但你可能还想强制执行更复杂的验证规则。

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

php
<?php

namespace App\Mcp\Prompts;

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

class DescribeWeatherPrompt extends Prompt
{
    /**
     * Handle the prompt request.
     */
    public function handle(Request $request): Response
    {
        $validated = $request->validate([
            'tone' => 'required|string|max:50',
        ]);

        $tone = $validated['tone'];

        // 使用给定的语气生成 prompt 响应...
    }
}

验证失败时，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".',
]);

Prompt 依赖注入 ​

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

php
<?php

namespace App\Mcp\Prompts;

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

class DescribeWeatherPrompt extends Prompt
{
    /**
     * Create a new prompt instance.
     */
    public function __construct(
        protected WeatherRepository $weather,
    ) {}

    //
}

除了构造函数注入外，你还可以在 prompt 的 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
{
    /**
     * Handle the prompt request.
     */
    public function handle(Request $request, WeatherRepository $weather): Response
    {
        $isAvailable = $weather->isServiceAvailable();

        // ...
    }
}

条件 Prompt 注册 ​

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

php
<?php

namespace App\Mcp\Prompts;

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

class CurrentWeatherPrompt extends Prompt
{
    /**
     * Determine if the prompt should be registered.
     */
    public function shouldRegister(Request $request): bool
    {
        return $request?->user()?->subscribed() ?? false;
    }
}

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

Prompt 响应 ​

Prompts 可以返回单个 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
{
    /**
     * Handle the prompt request.
     *
     * @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
{
    /**
     * The resources registered with this MCP server.
     *
     * @var array<int, class-string<\Laravel\Mcp\Server\Resource>>
     */
    protected array $resources = [
        WeatherGuidelinesResource::class,
    ];
}

资源名称、标题和描述 ​

默认情况下，资源的名称和标题从类名派生。例如，WeatherGuidelinesResource 的名称为 weather-guidelines，标题为 Weather Guidelines Resource。你可以使用 Name 和 Title 属性自定义这些值：

php
use Laravel\Mcp\Server\Attributes\Name;
use Laravel\Mcp\Server\Attributes\Title;

#[Name('weather-api-docs')]
#[Title('Weather API Documentation')]
class WeatherGuidelinesResource extends Resource
{
    // ...
}

资源描述不会自动生成。你应该始终使用 Description 属性提供有意义的描述：

php
use Laravel\Mcp\Server\Attributes\Description;

#[Description('Comprehensive guidelines for using the Weather API.')]
class WeatherGuidelinesResource extends Resource
{
    //
}

NOTE

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

资源模板 ​

资源模板 使你的服务器能够公开与包含变量的 URI 模式匹配的动态资源。你可以创建一个处理基于模板模式的多个 URI 的单个资源，而不是为每个资源定义静态 URI。

创建资源模板 ​

要创建资源模板，请在资源类上实现 HasUriTemplate 接口并定义一个返回 UriTemplate 实例的 uriTemplate 方法：

php
<?php

namespace App\Mcp\Resources;

use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Attributes\Description;
use Laravel\Mcp\Server\Attributes\MimeType;
use Laravel\Mcp\Server\Contracts\HasUriTemplate;
use Laravel\Mcp\Server\Resource;
use Laravel\Mcp\Support\UriTemplate;

#[Description('Access user files by ID')]
#[MimeType('text/plain')]
class UserFileResource extends Resource implements HasUriTemplate
{
    /**
     * Get the URI template for this resource.
     */
    public function uriTemplate(): UriTemplate
    {
        return new UriTemplate('file://users/{userId}/files/{fileId}');
    }

    /**
     * Handle the resource request.
     */
    public function handle(Request $request): Response
    {
        $userId = $request->get('userId');
        $fileId = $request->get('fileId');

        // 获取并返回文件内容...

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

当资源实现 HasUriTemplate 接口时，它将被注册为资源模板而非静态资源。AI 客户端可以使用与模板模式匹配的 URI 请求资源，URI 中的变量将被自动提取并在资源的 handle 方法中可用。

URI 模板语法 ​

URI 模板使用花括号中的占位符来定义 URI 中的变量段：

php
new UriTemplate('file://users/{userId}');
new UriTemplate('file://users/{userId}/files/{fileId}');
new UriTemplate('https://api.example.com/{version}/{resource}/{id}');

访问模板变量 ​

当 URI 匹配你的资源模板时，提取的变量会自动合并到请求中，可以使用 get 方法访问：

php
<?php

namespace App\Mcp\Resources;

use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Contracts\HasUriTemplate;
use Laravel\Mcp\Server\Resource;
use Laravel\Mcp\Support\UriTemplate;

class UserProfileResource extends Resource implements HasUriTemplate
{
    public function uriTemplate(): UriTemplate
    {
        return new UriTemplate('file://users/{userId}/profile');
    }

    public function handle(Request $request): Response
    {
        // 访问提取的变量
        $userId = $request->get('userId');

        // 如果需要，访问完整的 URI
        $uri = $request->uri();

        // 获取用户资料...

        return Response::text("Profile for user {$userId}");
    }
}

Request 对象提供提取的变量和请求的原始 URI，为你处理资源请求提供完整的上下文。

资源 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\Attributes\MimeType;
use Laravel\Mcp\Server\Attributes\Uri;
use Laravel\Mcp\Server\Resource;

#[Uri('weather://resources/guidelines')]
#[MimeType('application/pdf')]
class WeatherGuidelinesResource extends Resource
{
}

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

资源请求 ​

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

php
<?php

namespace App\Mcp\Resources;

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

class WeatherGuidelinesResource extends Resource
{
    /**
     * Handle the resource request.
     */
    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
{
    /**
     * Create a new resource instance.
     */
    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
{
    /**
     * Handle the resource request.
     */
    public function handle(WeatherRepository $weather): Response
    {
        $guidelines = $weather->guidelines();

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

资源注解 ​

你可以使用注解增强资源，为 AI 客户端提供额外的元数据。注解通过属性添加到资源：

php
<?php

namespace App\Mcp\Resources;

use Laravel\Mcp\Enums\Role;
use Laravel\Mcp\Server\Annotations\Audience;
use Laravel\Mcp\Server\Annotations\LastModified;
use Laravel\Mcp\Server\Annotations\Priority;
use Laravel\Mcp\Server\Resource;

#[Audience(Role::User)]
#[LastModified('2025-01-12T15:00:58Z')]
#[Priority(0.9)]
class UserDashboardResource extends Resource
{
    //
}

可用的注解包括：

注解类型描述
#[Audience]Role 或数组指定目标受众（Role::User、Role::Assistant 或两者）。
#[Priority]float0.0 到 1.0 之间的数值，表示资源的重要性。
#[LastModified]stringISO 8601 时间戳，显示资源最后更新时间。

条件资源注册 ​

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

php
<?php

namespace App\Mcp\Resources;

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

class WeatherGuidelinesResource extends Resource
{
    /**
     * Determine if the resource should be registered.
     */
    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;

/**
 * Handle the resource request.
 */
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 类型将由资源配置的 MIME 类型决定：

php
<?php

namespace App\Mcp\Resources;

use Laravel\Mcp\Server\Attributes\MimeType;
use Laravel\Mcp\Server\Resource;

#[MimeType('image/png')]
class WeatherGuidelinesResource extends Resource
{
    //
}

错误响应 ​

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

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

元数据 ​

Laravel MCP 还支持 MCP 规范中定义的 _meta 字段，某些 MCP 客户端或集成需要该字段。元数据可以应用于所有 MCP 原语，包括工具、资源和 prompts，以及它们的响应。

你可以使用 withMeta 方法将元数据附加到单个响应内容：

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

/**
 * Handle the tool request.
 */
public function handle(Request $request): Response
{
    return Response::text('The weather is sunny.')
        ->withMeta(['source' => 'weather-api', 'cached' => true]);
}

对于适用于整个响应信封的结果级元数据，用 Response::make 包装你的响应，并在返回的响应工厂实例上调用 withMeta：

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

/**
 * Handle the tool request.
 */
public function handle(Request $request): ResponseFactory
{
    return Response::make(
        Response::text('The weather is sunny.')
    )->withMeta(['request_id' => '12345']);
}

要将元数据附加到工具、资源或 prompt 本身，请在类上定义 $meta 属性：

php
use Laravel\Mcp\Server\Attributes\Description;
use Laravel\Mcp\Server\Tool;

#[Description('Fetches the current weather forecast.')]
class CurrentWeatherTool extends Tool
{
    protected ?array $meta = [
        'version' => '2.0',
        'author' => 'Weather Team',
    ];

    // ...
}

认证 ​

就像路由一样，你可以使用 middleware 对 Web MCP 服务器进行认证。为 MCP 服务器添加认证将要求用户在使用服务器的任何功能之前进行身份验证。

有两种方式可以认证对 MCP 服务器的访问：通过 Laravel Sanctum 进行简单的基于令牌的认证或通过 Authorization HTTP 头传递的任何令牌。或者，你可以使用 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 middleware 应用到你的 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 的安装和部署指南将 Passport 添加到你的应用。在继续之前，你应该有一个 OAuthenticatable 模型、新的认证守卫和 passport 密钥。

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

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

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

php
use Laravel\Passport\Passport;

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Passport::authorizationView(function ($parameters) {
        return view('mcp.authorize', $parameters);
    });
}

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

NOTE

在此场景中，我们只是使用 OAuth 作为底层可认证模型的转换层。我们忽略了 OAuth 的许多方面，例如 scopes。

使用现有的 Passport 安装 ​

如果你的应用已经在使用 Laravel Passport，Laravel MCP 应该可以在你现有的 Passport 安装中无缝工作，但目前不支持自定义 scopes，因为 OAuth 主要用作底层可认证模型的转换层。

Laravel MCP 通过上面讨论的 Mcp::oauthRoutes 方法添加、公告和使用单个 mcp:use scope。

Passport 与 Sanctum ​

OAuth2.1 是 Model Context Protocol 规范中文档化的认证机制，在 MCP 客户端中得到最广泛的支持。因此，我们建议尽可能使用 Passport。

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

Sanctum ​

如果你想使用 Sanctum 保护你的 MCP 服务器，只需在 routes/ai.php 文件中将 Sanctum 的认证 middleware 添加到你的服务器即可。然后，确保你的 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 令牌，你可以通过将任何你想要的 middleware 分配给 Mcp::web 路由来认证你的 MCP 服务器。你的自定义 middleware 可以手动检查 Authorization 头来认证传入的 MCP 请求。

授权 ​

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

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

/**
 * Handle the tool request.
 */
public function handle(Request $request): Response
{
    if (! $request->user()->can('read-weather')) {
        return Response::error('Permission denied.');
    }

    // ...
}

测试服务器 ​

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

MCP Inspector ​

MCP Inspector 是一个用于测试和调试 MCP 服务器的交互式工具。使用它连接到你的服务器、验证认证，并尝试工具、资源和 prompts。

你可以为任何注册的服务器运行 inspector：

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

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

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

单元测试 ​

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

首先，创建一个新的测试用例并在注册它的服务器上调用所需的原语。例如，要测试 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
/**
 * Test a tool.
 */
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.');
}

同样，你可以测试 prompts 和资源：

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();