Laravel MCP

• 简介
• 安装
  • 发布路由
• 创建服务器
  • 服务器注册
  • Web 服务器
  • 本地服务器
• 工具
  • 创建工具
  • 工具输入模式
  • 工具输出模式
  • 验证工具参数
  • 工具依赖注入
  • 工具注解
  • 条件性工具注册
  • 工具响应
• 提示
  • 创建提示
  • 提示参数
  • 验证提示参数
  • 提示依赖注入
  • 条件性提示注册
  • 提示响应
• 资源
  • 创建资源
  • 资源模板
  • 资源 URI 和 MIME 类型
  • 资源请求
  • 资源依赖注入
  • 资源注解
  • 条件性资源注册
  • 资源响应
• 元数据
• 认证
  • OAuth 2.1
  • Sanctum
• 授权
• 测试服务器
  • MCP 检查器
  • 单元测试

简介

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

安装

首先，使用 Composer 包管理器将 Laravel MCP 安装到你的项目中：

composer require laravel/mcp

发布路由

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

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

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

创建服务器

你可以使用 make:mcp-server Artisan 命令创建 MCP 服务器。服务器充当中央通信点，向 AI 客户端暴露 MCP 功能，如工具、资源和提示：

php artisan make:mcp-server WeatherServer

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

<?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('此服务器提供天气信息和预报。')]
class WeatherServer extends Server
{
    /**
     * 在此 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 服务器：

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

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

就像普通路由一样，你可以应用中间件来保护你的 Web 服务器：

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

本地服务器

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

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

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

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

工具

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

<?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('获取指定位置的当前天气预报。')]
class CurrentWeatherTool extends Tool
{
    /**
     * 处理工具请求。
     */
    public function handle(Request $request): Response
    {
        $location = $request->get('location');

        // 获取天气...

        return Response::text('天气是...');
    }

    /**
     * 获取工具的输入模式。
     *
     * @return array<string, \Illuminate\JsonSchema\Types\Type>
     */
    public function schema(JsonSchema $schema): array
    {
        return [
            'location' => $schema->string()
                ->description('要获取天气的位置。')
                ->required(),
        ];
    }
}

创建工具

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

php artisan make:mcp-tool CurrentWeatherTool

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

<?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 属性自定义这些值：

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

#[Name('get-optimistic-weather')]
#[Title('获取乐观天气预报')]
class CurrentWeatherTool extends Tool
{
    // ...
}

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

use Laravel\Mcp\Server\Attributes\Description;

#[Description('获取指定位置的当前天气预报。')]
class CurrentWeatherTool extends Tool
{
    //
}

NOTE

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

工具输入模式

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

<?php

namespace App\Mcp\Tools;

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

class CurrentWeatherTool extends Tool
{
    /**
     * 获取工具的输入模式。
     *
     * @return array<string, \Illuminate\JsonSchema\Types\Type>
     */
    public function schema(JsonSchema $schema): array
    {
        return [
            'location' => $schema->string()
                ->description('要获取天气的位置。')
                ->required(),

            'units' => $schema->string()
                ->enum(['celsius', 'fahrenheit'])
                ->description('要使用的温度单位。')
                ->default('celsius'),
        ];
    }
}

工具输出模式

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

<?php

namespace App\Mcp\Tools;

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

class CurrentWeatherTool extends Tool
{
    /**
     * 获取工具的输出模式。
     *
     * @return array<string, \Illuminate\JsonSchema\Types\Type>
     */
    public function outputSchema(JsonSchema $schema): array
    {
        return [
            'temperature' => $schema->number()
                ->description('摄氏度温度')
                ->required(),

            'conditions' => $schema->string()
                ->description('天气状况')
                ->required(),

            'humidity' => $schema->integer()
                ->description('湿度百分比')
                ->required(),
        ];
    }
}

验证工具参数

JSON 模式定义为工具参数提供了基本结构，但你可能还想强制执行更复杂的验证规则。

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

<?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 客户端将根据你提供的错误消息采取行动。因此，提供清晰且可操作的消息至关重要：

$validated = $request->validate([
    'location' => ['required','string','max:100'],
    'units' => 'in:celsius,fahrenheit',
],[
    'location.required' => '你必须指定一个位置来获取天气。例如，“New York City”或“Tokyo”。',
    'units.in' => '你必须为温度单位指定“celsius”或“fahrenheit”。',
]);

工具依赖注入

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

<?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

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

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	表示该工具可能与外部实体交互。

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

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

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 方法：

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

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

    return Response::text('天气摘要：晴朗，72°F');
}

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

return Response::error('无法获取天气数据。请重试。');

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

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 类型将从文件中自动检测：

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

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

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

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

多内容响应

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

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

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

    return [
        Response::text('天气摘要：晴朗，72°F'),
        Response::text('**详细预报**\n- 上午：65°F\n- 下午：78°F\n- 晚上：70°F')
    ];
}

结构化响应

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

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

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

return Response::make(
    Response::text('天气为 22.5°C，晴朗')
)->withStructuredContent([
    'temperature' => 22.5,
    'conditions' => 'Sunny',
]);

流式响应

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

<?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 命令：

php artisan make:mcp-prompt DescribeWeatherPrompt

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

<?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 属性自定义这些值：

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

#[Name('weather-assistant')]
#[Title('天气助手提示')]
class DescribeWeatherPrompt extends Prompt
{
    // ...
}

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

use Laravel\Mcp\Server\Attributes\Description;

#[Description('为给定位置生成自然语言天气解释。')]
class DescribeWeatherPrompt extends Prompt
{
    //
}

NOTE

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

提示参数

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

<?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: '天气描述中使用的语气（例如，正式、随意、幽默）。',
                required: true,
            ),
        ];
    }
}

验证提示参数

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

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

<?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 客户端将根据你提供的错误消息采取行动。因此，提供清晰且可操作的消息至关重要：

$validated = $request->validate([
    'tone' => ['required','string','max:50'],
],[
    'tone.*' => '你必须为天气描述指定一个语气。例如，“formal”、“casual”或“humorous”。',
]);

提示依赖注入

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

<?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

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

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

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 = "你是一个乐于助人的天气助手。请用 {$tone} 的语气描述天气。";

        $userMessage = "纽约市现在的天气怎么样？";

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

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

资源

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

创建资源

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

php artisan make:mcp-resource WeatherGuidelinesResource

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

<?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 属性自定义这些值：

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

#[Name('weather-api-docs')]
#[Title('天气 API 文档')]
class WeatherGuidelinesResource extends Resource
{
    // ...
}

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

use Laravel\Mcp\Server\Attributes\Description;

#[Description('使用天气 API 的综合指南。')]
class WeatherGuidelinesResource extends Resource
{
    //
}

NOTE

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

资源模板

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

创建资源模板

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

<?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('按 ID 访问用户文件')]
#[MimeType('text/plain')]
class UserFileResource extends Resource implements HasUriTemplate
{
    /**
     * 获取此资源的 URI 模板。
     */
    public function uriTemplate(): UriTemplate
    {
        return new UriTemplate('file://users/{userId}/files/{fileId}');
    }

    /**
     * 处理资源请求。
     */
    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 中的变量段：

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

访问模板变量

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

<?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("用户 {$userId} 的资料");
    }
}

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

资源 URI 和 MIME 类型

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

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

你可以使用 Uri 和 MimeType 属性自定义这些值：

<?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 客户端确定如何正确处理和解释资源内容。

资源请求

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

<?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

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

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

资源注解

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

<?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]	float	介于 0.0 和 1.0 之间的数字分数，表示资源的重要性。
#[LastModified]	string	指示资源最后更新时间的 ISO 8601 时间戳。

条件性资源注册

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

<?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 方法：

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

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

    return Response::text($weatherData);
}

Blob 响应

要返回二进制大对象内容，请使用 blob 方法，并提供 blob 内容：

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

返回 blob 内容时，MIME 类型将由资源配置的 MIME 类型决定：

<?php

namespace App\Mcp\Resources;

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

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

错误响应

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

return Response::error('无法获取指定位置的天气数据。');

元数据

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

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

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

/**
 * 处理工具请求。
 */
public function handle(Request $request): Response
{
    return Response::text('天气晴朗。')
        ->withMeta(['source' => 'weather-api', 'cached' => true]);
}

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

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

/**
 * 处理工具请求。
 */
public function handle(Request $request): ResponseFactory
{
    return Response::make(
        Response::text('天气晴朗。')
    )->withMeta(['request_id' => '12345']);
}

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

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

#[Description('获取当前天气预报。')]
class CurrentWeatherTool extends Tool
{
    protected ?array $meta = [
        'version' => '2.0',
        'author' => '天气团队',
    ];

    // ...
}

认证

就像路由一样，你可以通过中间件对 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 中间件应用到你的 Mcp::web 路由：

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 授权视图：

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

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

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 的许多方面，例如作用域。

使用现有 Passport 安装

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

Laravel MCP 通过上面讨论的 Mcp::oauthRoutes 方法添加、公布并使用单个 mcp:use 作用域。

Passport 与 Sanctum 的选择

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

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

Sanctum

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

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 工具和资源中执行授权检查：

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

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

    // ...
}

测试服务器

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

MCP 检查器

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

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

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

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

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

单元测试

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

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

Pest

test('工具', 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.');
});

PHPUnit

/**
 * 测试一个工具。
 */
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.');
}

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

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

你也可以通过在调用原语之前链式调用 actingAs 方法来模拟已认证用户：

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

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

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

$response->assertOk();

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

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

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

$response->assertHasErrors();

$response->assertHasErrors([
    '出错了。',
]);

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

$response->assertHasNoErrors();

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

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

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

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

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

$response->assertNotificationCount(5);

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

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