Laravel MCP

简介

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

安装

首先，使用 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);

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

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

        // Get weather...

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

INFO

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

工具输入 Schema

工具可以定义输入模式来指定它们从 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'),
        ];
    }
}

工具输出 Schema

工具可以定义输出模式来指定其响应的结构。这可以更好地与需要可解析工具结果的人工智能客户端集成。使用 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 模式定义为工具参数提供了基本结构，但你可能还想强制执行更复杂的验证规则。

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',
        ]);

        // Fetch weather data using the validated arguments...
    }
}

验证失败时，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 客户端提供额外的元数据。这些注释有助于人工智能模型理解该工具的行为和功能。通过属性将注释添加到工具中：

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

可用的注释包括：

Annotation	Type	说明
`#[IsReadOnly]`	boolean	Indicates the tool does not modify its environment.
`#[IsDestructive]`	boolean	Indicates the tool may perform destructive updates (only meaningful when not read-only).
`#[IsIdempotent]`	boolean	Indicates repeated calls with same arguments have no additional effect (when not read-only).
`#[IsOpenWorld]`	boolean	Indicates the tool may interact with external entities.

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

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 方法返回 generator。这使得可以在最终响应之前向客户端发送中间更新：

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（服务器发送事件）流，将每条生成的消息作为事件发送到客户端。

提示词

Prompts 使你的服务器能够共享可重用的提示模板，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
{
    /**
     * The prompts registered with this MCP server.
     *
     * @var array<int, class-string<\Laravel\Mcp\Server\Prompt>>
     */
    protected array $prompts = [
        DescribeWeatherPrompt::class,
    ];
}

提示词名称、标题与描述

默认情况下，提示的名称和标题源自类名。例如，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
{
    // ...
}

提示描述不会自动生成。你应该始终使用 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
{
    //
}

INFO

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

提示词参数

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

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

验证提示词参数

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

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
{
    /**
     * Handle the prompt request.
     */
    public function handle(Request $request): Response
    {
        $validated = $request->validate([
            'tone' => 'required|string|max:50',
        ]);

        $tone = $validated['tone'];

        // Generate the prompt response using the given 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
{
    /**
     * Create a new prompt instance.
     */
    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
{
    /**
     * Handle the prompt request.
     */
    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
{
    /**
     * Determine if the prompt should be registered.
     */
    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
{
    /**
     * 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助手，而将常规消息视为用户输入。

资源

Resources 使你的服务器能够公开 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
{
    //
}

INFO

描述是资源元数据的关键部分，因为它有助于 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');

        // Fetch and return the file content...

        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
    {
        // Access the extracted variable
        $userId = $request->get('userId');

        // Access the full URI if needed
        $uri = $request->uri();

        // Fetch user profile...

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

资源请求

与工具和提示不同，资源不能定义输入 schema 或参数。不过，你仍可在资源的 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
{
    //
}

可用的注释包括：

Annotation	Type	说明
`#[Audience]`	Role or array	Specifies the intended audience (`Role::User`, `Role::Assistant`, or both).
`#[Priority]`	float	A numerical score between 0.0 and 1.0 indicating resource importance.
`#[LastModified]`	string	An ISO 8601 timestamp showing when the resource was last updated.

条件注册资源

你可以通过在资源类中实现 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 原语，包括工具、资源和提示及其响应。

你可以使用 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']);
}

要将元数据附加到工具、资源或提示本身，请在类上定义 $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',
    ];

    // ...
}

身份验证

就像路由一样，你可以使用中间件对 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 发现和客户端注册路由。然后，将 Passport 的 auth:api 中间件应用到 routes/ai.php 文件中的 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 模型、新的身份验证防护和护照钥匙。

接下来，你应该发布 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 代理的身份验证尝试。

授权画面示例

INFO

在这种情况下，我们只是使用 OAuth 作为底层可验证模型的转换层。我们忽略了 OAuth 的许多方面，例如范围。

使用已有 Passport 安装

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

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

Passport 与 Sanctum

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

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

Sanctum

如果你想使用 Sanctum 保护你的 MCP 服务器，只需将 Sanctum 的身份验证中间件添加到你的服务器的 routes/ai.php 文件中即可。然后，确保你的 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;

/**
 * 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 服务器的交互式工具。使用它连接到你的服务器、验证身份验证并尝试工具、资源和提示。

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

shell

# Web server...
php artisan mcp:inspector mcp/weather

# Local server named "weather"...
php artisan mcp:inspector weather

此命令启动 MCP Inspector 并提供客户端设置，你可以将其复制到 MCP 客户端以确保所有内容均配置正确。如果你的 Web 服务器受身份验证中间件保护，请确保在连接时包含所需的标头，例如 Authorization 不记名令牌。

单元测试

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

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

PestPHPUnit

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

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

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

Laravel MCP ​

简介 ​

安装 ​

发布路由 ​

创建服务器 ​

服务器注册 ​

Web 服务器 ​

本地服务器 ​

工具 ​

创建工具 ​

工具名称、标题与描述 ​

工具输入 Schema ​

工具输出 Schema ​

验证工具参数 ​

工具依赖注入 ​

工具注解 ​

条件注册工具 ​

工具响应 ​

多内容响应 ​

结构化响应 ​

流式响应 ​

提示词 ​

创建提示词 ​

提示词名称、标题与描述 ​

提示词参数 ​

验证提示词参数 ​

提示词依赖注入 ​

条件注册提示词 ​

提示词响应 ​

资源 ​

创建资源 ​

资源名称、标题与描述 ​

资源模板 ​

创建资源模板 ​

URI 模板语法 ​

访问模板变量 ​

资源 URI 与 MIME 类型 ​

资源请求 ​

资源依赖注入 ​

资源注解 ​

条件注册资源 ​

资源响应 ​

Blob 响应 ​

错误响应 ​

元数据 ​

身份验证 ​

OAuth 2.1 ​

全新安装 Passport ​

使用已有 Passport 安装 ​

Passport 与 Sanctum ​

Sanctum ​

自定义 MCP 认证 ​

授权 ​

测试服务器 ​

MCP Inspector ​

单元测试 ​

Laravel MCP

简介

安装

发布路由

创建服务器

服务器注册

Web 服务器

本地服务器

工具

创建工具

工具名称、标题与描述

工具输入 Schema

工具输出 Schema

验证工具参数

工具依赖注入

工具注解

条件注册工具

工具响应

多内容响应

结构化响应

流式响应

提示词

创建提示词

提示词名称、标题与描述

提示词参数

验证提示词参数

提示词依赖注入

条件注册提示词

提示词响应

资源

创建资源

资源名称、标题与描述

资源模板

创建资源模板

URI 模板语法

访问模板变量

资源 URI 与 MIME 类型

资源请求

资源依赖注入

资源注解

条件注册资源

资源响应

Blob 响应

错误响应

元数据

身份验证

OAuth 2.1

全新安装 Passport

使用已有 Passport 安装

Passport 与 Sanctum

Sanctum

自定义 MCP 认证

授权

测试服务器

MCP Inspector

单元测试