Laravel 集成 php-mcp/server

一、认识 php-mcp/server：AI 与 Laravel 之间的「翻译官」

php-mcp/server 是 MCP 协议的 PHP 核心实现，其核心作用是将 Laravel 应用的功能（方法、数据等）标准化为 AI 助手可理解的「工具（Tools）」「资源（Resources）」和「提示（Prompts）」，让 AI 助手能像调用本地功能一样操作你的应用。

为什么选择在 Laravel 中使用它？

框架兼容性：Laravel 支持 PSR 标准，与 php-mcp/server 完美兼容，无需修改框架核心代码。

开发便捷性：通过 PHP 8 的 Attributes（注解）特性，可快速标记需要暴露给 AI 的功能。

场景丰富性：从智能客服、订单查询到动态提示生成，覆盖多种 AI 与应用交互场景。

二、环境准备与安装：5 分钟完成基础配置

1. 依赖要求

PHP 版本 ≥ 8.1（需支持 Attributes 特性）

Laravel 版本 ≥ 9.0

Composer（用于包管理）

2. 安装扩展包

php-mcp/server 提供了核心功能，而 php-mcp/laravel-server 是专为 Laravel 优化的扩展包（推荐使用），包含 Artisan 命令、配置文件等便捷功能。

# 安装 Laravel 专用包（自动包含核心库）
composer require php-mcp/laravel-server

安装完成后，扩展包会自动注册服务提供者，无需手动配置。如需自定义配置，可发布配置文件：

php artisan vendor:publish --provider="PhpMcp\Laravel\McpServiceProvider"

发布后，配置文件位于 config/mcp.php，可设置服务器端口、传输方式、扫描目录等参数。

三、核心功能实现：定义 MCP 元素让 AI 「看懂」你的应用

php-mcp/server 的核心是通过 PHP 8 的 Attributes 注解，将 Laravel 中的方法标记为 MCP 协议支持的「工具」「资源」或「提示」，让 AI 助手能识别并调用。

1. 定义 MCP 工具（Tool）：让 AI 调用应用方法

工具（Tool）是 AI 可直接调用的业务逻辑方法，例如计算订单金额、查询用户信息等。通过 #[McpTool] 注解标记方法即可。

// app/Services/OrderService.php
namespaceApp\Services;

usePhpMcp\Server\Attributes\McpTool;
usePhpMcp\Server\Attributes\Schema;

class OrderService
{
    /**
     * 计算订单总金额（含税费）
     * 
     * @param float $subtotal 订单小计
     * @param float $taxRate 税率（如 0.08 表示 8%）
     * @return float 总金额
     */
    #[McpTool(name: 'calculate_order_total')]
    publicfunction calculateTotal(
        #[Schema(description: '订单小计金额')]
        float $subtotal,
        #[Schema(description: '税率（小数形式）', minimum: 0, maximum: 0.3)]
        float $taxRate
    ): float {
        return$subtotal * (1 + $taxRate);
    }
}

name：工具的唯一标识，AI 通过该名称调用。

[Schema]：定义参数的描述、范围等元信息，帮助 AI 理解参数含义。

2. 定义 MCP 资源（Resource）：让 AI 访问应用数据

资源（Resource）是 AI 可读取的应用数据，如配置信息、数据库内容、文章列表等。通过 #[McpResourceTemplate] 注解定义动态资源，支持按参数筛选。

// app/Services/ArticleResource.php
namespaceApp\Services;

usePhpMcp\Server\Attributes\McpResourceTemplate;
usePhpMcp\Server\Attributes\CompletionProvider;
useApp\Models\Article;

class ArticleResource
{
    /**
     * 按分类获取帮助文章列表
     * 
     * @param string $category 文章分类（如「售后」「账户」）
     * @return array 文章列表
     */
    #[McpResourceTemplate(
        uriTemplate: 'help://articles/{category}',
        mimeType: 'application/json',
        description: '获取指定分类的帮助文章'
    )]
    publicfunction getArticlesByCategory(
        #[CompletionProvider(values: ['售后', '账户', '订单', '支付'])]
        string $category
    ): array {
        returnArticle::where('category', $category)
            ->select('id', 'title', 'content')
            ->get()
            ->toArray();
    }
}

uriTemplate：资源的唯一 URI 模板，AI 通过 help://articles/售后访问「售后」分类的文章。

CompletionProvider：提供参数的可选值，AI 会自动提示用户支持的分类，避免无效查询。

3. 定义 MCP 提示（Prompt）：让 AI 生成动态指令

提示（Prompt）是 AI 可使用的动态指令模板，例如根据用户输入生成个性化提问。通过 #[McpPrompt] 注解定义。

// app/Services/PromptService.php
namespaceApp\Services;

usePhpMcp\Server\Attributes\McpPrompt;
useApp\Models\User;

class PromptService
{
    /**
     * 生成用户个性化推荐提示
     * 
     * @param int $userId 用户 ID
     * @return array AI 提示消息
     */
    #[McpPrompt(name: 'generate_recommendation_prompt')]
    publicfunction makeRecommendationPrompt(int $userId): array
    {
        $user = User::findOrFail($userId);
        $history = $user->orders()->pluck('product_name')->implode(', ');
        
        return [
            [
                'role' => 'user',
                'content' => "用户 {$user->name} 曾购买：{$history}，请推荐 3 个相似产品。"
            ]
        ];
    }
}

AI 调用该提示后，会根据用户历史生成精准的推荐指令，提升推荐效果。

四、服务器配置与启动：让 AI 「找到」你的应用

定义好工具、资源和提示后，需启动 MCP 服务器，让 AI 助手能连接并调用这些元素。php-mcp/laravel-server 提供了便捷的 Artisan 命令。

1. 启动服务器

通过 mcp:serve 命令启动服务器，支持多种传输方式（本地 / 远程调用）：

# 本地 AI 客户端（如 Cursor）：使用 stdio 传输（无网络，低延迟）

php artisan mcp:serve --transport=stdio

# 远程 AI 客户端（如 Claude 网页版）：使用 HTTP 传输

php artisan mcp:serve --transport=streamable-http --port=8001

stdio：适合本地开发，AI 与服务器通过命令行通信。

streamable-http：适合生产环境，支持远程调用和并发连接。

2. 服务器配置详解

在 config/mcp.php 中可自定义服务器参数：

return [
    // 服务器信息（供 AI 识别）
    'server_info' => [
        'name' => 'Laravel MCP 服务器',
        'version' => '1.0.0',
    ],
    // 扫描 MCP 元素的目录（自动发现工具/资源/提示）
    'scan_directories' => [
        app_path('Services'), // 默认扫描 app/Services 目录
    ],
    // 缓存配置（提升性能）
    'cache' => [
        'enabled' => true,
        'ttl' => 3600, // 缓存 1 小时
    ],
];

五、AI 客户端连接：让 AI 助手「接入」应用

AI 助手（如 Cursor、Claude）需配置 MCP 服务器地址，才能调用 Laravel 中的工具和资源。

1. Cursor 客户端配置

在项目根目录创建 .cursor/mcp.json，指定服务器路径：

{
  "mcpServers": {
    "laravel-app": {
      "command": "php",
      "args": ["/path/to/laravel/project/artisan", "mcp:serve", "--transport=stdio"]
    }
  }
}

重启 Cursor 后，AI 会自动识别服务器，可直接调用 calculate_order_total 工具或访问 help://articles/售后资源。

2. Claude 客户端配置

在 Claude 桌面端的「设置 > 已连接应用 > MCP 服务器」中添加：

名称：Laravel 应用

类型：HTTP

URL：http://your-server-ip:8001/mcp

六、实战案例：智能客服机器人（动态回复用户问题）

以「客服机器人通过文章列表回复用户问题」为例，完整流程如下：

1. 数据准备：存储帮助文章

创建 articles 表存储帮助文档，结构如下：

字段	类型	说明
id	int	文章 ID
title	varchar	标题（如「退款流程」）
content	text	内容（Markdown 格式）
category	varchar	分类（如「售后」）

2. 定义资源与工具

资源：help://articles/{category}（按分类获取文章）。

工具：search_articles_by_keyword（按关键词检索文章）。

// 工具：按关键词检索文章
#[McpTool(name: 'search_articles_by_keyword')]
public function searchArticles(string $keyword): array
{
    return Article::where('title', 'like', "%{$keyword}%")
        ->orWhere('content', 'like', "%{$keyword}%")
        ->get()
        ->toArray();
}

3. 用户交互流程

用户提问：「如何申请退款？」

AI 调用 search_articles_by_keyword 工具，关键词为「退款」。

工具返回「售后」分类中包含「退款」的文章。

AI 从文章中提取步骤，生成回复：「申请退款步骤：1. 进入订单页…」。

七、优化与扩展：让 AI 交互更高效

1. 传输方式选择

传输方式	适用场景	优势
stdio	本地开发、单客户端	无网络延迟
streamable-http	生产环境、多客户端	支持断线重连、并发访问

2. 性能优化

缓存 MCP 元素：启用配置中的 cache，减少重复扫描（默认开启）。

数据库查询优化：资源方法中使用 select 筛选字段，避免查询冗余数据。

异步处理：结合 Laravel 队列，处理耗时的工具调用（如大数据计算）。

3. 功能扩展

多轮对话支持：通过 MCP 会话缓存，让 AI 记住上下文（如用户历史提问）。

权限控制：在工具 / 资源方法中添加用户身份验证，限制敏感操作。

多语言支持：资源内容存储多语言版本，AI 根据用户语言返回对应内容。

转载作品，原作者：Laravel全栈实践，文章来源：https://mp.weixin.qq.com/s/mwtYzGmULnEHul2IX9kqxQ

Laravel 集成 php-mcp/server

发表回复