laravel-mcp

Laravel MCP

使用 Laravel 构建 MCP（模型上下文协议）服务的综合指南。包含 5 个类别中的 7 条规则，介绍如何向 AI 客户端公开工具、提示词和资源。

适用场景

在以下情况下参考这些指南：

• 创建 MCP 服务（Web 或本地）
• 构建 AI 客户端可调用的工具
• 定义可复用 AI 交互的提示词
• 公开供 AI 使用的上下文资源
• 使用 OAuth 或 Sanctum 保护 MCP 服务
• 测试 MCP 服务、工具、提示词和资源

按优先级划分的规则类别

优先级	类别	影响	前缀
1	服务	严重	server-
2	工具	高	tool-
3	提示词和资源	中	prompt-、resource-
4	身份验证	高	auth-
5	测试	高	test-

快速参考

1. 服务（严重）

• server-create-register - 创建并注册 Web 或本地 MCP 服务

2. 工具（高）

• tool-create - 创建包含输入/输出架构、依赖注入和注解的工具
• tool-responses - 文本、错误、结构化、流式和多内容响应

3. 提示词和资源（中）

• prompt-create - 创建包含参数、验证和响应的提示词
• resource-create - 使用 URI 模式创建资源和资源模板

4. 身份验证（高）

• auth-protect - 使用 OAuth 2.1、Sanctum 或自定义身份验证保护服务

5. 测试（高）

• test-unit - 使用 MCP Inspector 和单元测试进行测试

基本模式

创建 MCP 服务

<?php

namespace App\Mcp\Servers;

use Laravel\Mcp\Server;
use Laravel\Mcp\Server\Attributes\Instructions;
use Laravel\Mcp\Server\Attributes\Name;
use Laravel\Mcp\Server\Attributes\Version;

#[Name('Weather Server')]
#[Version('1.0.0')]
#[Instructions('This server provides weather information.')]
class WeatherServer extends Server
{
    protected array $tools = [
        CurrentWeatherTool::class,
    ];

    protected array $resources = [];

    protected array $prompts = [];
}

在 routes/ai.php 中注册

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

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

创建工具

<?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 for a location.')]
class CurrentWeatherTool extends Tool
{
    public function handle(Request $request): Response
    {
        $location = $request->get('location');

        return Response::text("The weather in {$location} is sunny, 72°F.");
    }

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

使用方法

阅读各条规则文件，了解详细说明和代码示例。

每个规则文件都包含：

• 带有元数据（标题、影响、标签）的 YAML frontmatter
• 简要说明其重要性
• 附带说明的错误示例
• 附带说明的正确示例
• Laravel 13 和 PHP 8.3 的具体上下文和参考资料

完整编译文档

如需查看包含所有展开规则的完整指南：AGENTS.md