深入了解 PHP 版本的 MCP SDK：整合大型语言模型的实用指南

在人工智能领域，大型语言模型（LLM）正在改变开发者构建应用程序的方式。然而，将这些模型整合到项目中可能会面临挑战，尤其是在为模型提供正确上下文以生成有意义的响应时。**模型上下文协议（MCP）**及其PHP实现——MCP SDK for PHP——应运而生，旨在帮助开发者解决这一问题。本文将带您了解 MCP SDK for PHP 的基本概念、使用方法以及其在与 LLM 协作中的价值。本文面向具有一定技术背景的读者（至少大学水平），但会以清晰、实用的方式解释相关概念。

我们将从安装开始，逐步介绍如何创建 MCP 服务器和客户端，并通过官方文档中的示例进行详细说明。阅读完本文后，您将对如何在 PHP 项目中应用这一工具拥有扎实的理解。让我们开始吧。

什么是 MCP SDK for PHP？

**模型上下文协议（MCP）**是一种标准化的方式，允许应用程序为大型语言模型提供上下文信息，如资源、提示或工具。它将准备上下文的任务与实际的 LLM 交互分离，使整个过程更加有条理且可重用。MCP SDK for PHP将这一协议引入 PHP 生态系统，使开发者能够构建遵循 MCP 规则的客户端和服务器。

为什么使用它？

想象一下，您正在开发一个依赖 LLM 生成文本、回答问题或执行任务的应用程序。如果没有一种结构化的方式来提供信息，您将不得不手动处理交互的每一个细节。MCP SDK for PHP 通过提供以下功能简化了这一过程：

创建服务器，为 LLM 提供上下文（如提示或资源）。
构建客户端，连接到这些服务器并获取所需信息。
使用 stdio 或 SSE 等方法标准化通信。

该 SDK 基于 MCP 的官方 Python SDK，专为在尖端 AI 解决方案中工作的 PHP 开发者量身定制。如果您正在将 LLM 集成到 Web 应用程序、命令行工具或其他基于 PHP 的系统中，它将特别有用。

安装 MCP SDK for PHP

在开始编码之前，您需要安装 SDK。它可以通过 Composer（PHP 的依赖管理器）轻松安装。

安装步骤

运行以下命令：

composer require logiscape/mcp-sdk-php

等待 Composer 下载并安装该包及其依赖项。

系统要求

为确保一切顺利运行，您的系统必须满足以下最低要求：

PHP 8.1 或更高版本：SDK 使用现代 PHP 特性，因此需要较新版本。
ext-curl：此扩展用于网络相关功能。
ext-pcntl（可选）：如果您在命令行（CLI）环境中运行 SDK，建议安装此扩展以增强进程控制。

安装完成后，您就可以开始构建 MCP 服务器了。

使用 SDK 创建 MCP 服务器

MCP 服务器是向 LLM 提供上下文的组件。它可以暴露提示、资源或工具等内容，供模型使用。在本节中，我们将通过官方文档中的示例，逐步构建一个提供提示的简单服务器。

示例：一个基本的 MCP 服务器

以下是创建处理提示请求的服务器的完整代码：

<?php

require 'vendor/autoload.php';

use Mcp\Server\Server;
use Mcp\Server\ServerRunner;
use Mcp\Types\Prompt;
use Mcp\Types\PromptArgument;
use Mcp\Types\PromptMessage;
use Mcp\Types\ListPromptsResult;
use Mcp\Types\TextContent;
use Mcp\Types\Role;
use Mcp\Types\GetPromptResult;
use Mcp\Types\GetPromptRequestParams;

// 创建服务器实例
$server = new Server('example-server');

// 处理列出可用提示的请求
$server->registerHandler('prompts/list', function($params) {
    $prompt = new Prompt(
        name: 'example-prompt',
        description: '一个示例提示模板',
        arguments: [
            new PromptArgument(
                name: 'arg1',
                description: '一个示例参数',
                required: true
            )
        ]
    );
    return new ListPromptsResult([$prompt]);
});

// 处理获取特定提示的请求
$server->registerHandler('prompts/get', function(GetPromptRequestParams $params) {
    $name = $params->name;
    $arguments = $params->arguments;

    if ($name !== 'example-prompt') {
        throw new \InvalidArgumentException("未知提示: {$name}");
    }

    // 安全地获取参数值
    $argValue = $arguments ? $arguments->arg1 : 'none';

    $prompt = new Prompt(
        name: 'example-prompt',
        description: '一个示例提示模板',
        arguments: [
            new PromptArgument(
                name: 'arg1',
                description: '一个示例参数',
                required: true
            )
        ]
    );

    return new GetPromptResult(
        messages: [
            new PromptMessage(
                role: Role::USER,
                content: new TextContent(
                    text: "带有参数的示例提示文本: $argValue"
                )
            )
        ],
        description: '示例提示'
    );
});

// 设置并运行服务器
$initOptions = $server->createInitializationOptions();
$runner = new ServerRunner($server, $initOptions);
$runner->run();

将此文件保存为 example_server.php。让我们分析一下这段代码。

工作原理

服务器设置：
- 我们创建了一个名为 'example-server' 的 Server 实例，用于在 MCP 生态系统中标识该服务器。
注册处理器：
- 服务器使用处理器来响应特定请求。这里定义了两个处理器：
  - 'prompts/list'：返回可用提示的列表。在本例中，只有一个名为 'example-prompt' 的提示，带有必需参数 'arg1'。
  - 'prompts/get'：按名称检索特定提示。它检查请求的提示是否为 'example-prompt'，获取 'arg1' 的值（如果缺失则默认为 'none'），并返回包含该值的消息。
运行服务器：
- ServerRunner 类使用默认初始化选项启动服务器。启动后，它通过 stdio 或其他支持的传输方式监听客户端请求。

此服务器现已准备好向任何连接到它的 MCP 客户端提供提示数据。接下来，我们将构建一个客户端来与该服务器交互。

构建 MCP 客户端

MCP 客户端连接到服务器以访问其资源。在本例中，我们将创建一个客户端，连接到 example_server.php 并列出其可用的提示。

示例：一个基本的 MCP 客户端

以下是代码：

<?php

require 'vendor/autoload.php';

use Mcp\Client\Client;
use Mcp\Client\Transport\StdioServerParameters;
use Mcp\Types\TextContent;

// 定义服务器连接参数
$serverParams = new StdioServerParameters(
    command: 'php',           // 可执行文件
    args: ['example_server.php'], // 服务器脚本路径
    env: null                 // 可选环境变量
);

// 创建客户端实例
$client = new Client();

try {
    echo("开始连接\n");
    // 连接到服务器
    $session = $client->connect(
        commandOrUrl: $serverParams->getCommand(),
        args: $serverParams->getArgs(),
        env: $serverParams->getEnv()
    );

    echo("开始列出可用提示\n");
    // 获取提示列表
    $promptsResult = $session->listPrompts();

    // 显示提示
    if (!empty($promptsResult->prompts)) {
        echo "可用提示:\n";
        foreach ($promptsResult->prompts as $prompt) {
            echo "  - 名称: " . $prompt->name . "\n";
            echo "    描述: " . $prompt->description . "\n";
            echo "    参数:\n";
            if (!empty($prompt->arguments)) {
                foreach ($prompt->arguments as $argument) {
                    echo "      - " . $argument->name . " (" . ($argument->required ? "必需" : "可选") . "): " . $argument->description . "\n";
                }
            } else {
                echo "      (无)\n";
            }
        }
    } else {
        echo "没有可用的提示。\n";
    }

} catch (\Exception $e) {
    echo "错误: " . $e->getMessage . "\n";
    exit(1);
} finally {
    // 清理并关闭连接
    if (isset($client)) {
        $client->close();
    }
}

将此文件保存为 example_client.php。要运行它，请使用：

php example_client.php

工作原理

连接设置：
- StdioServerParameters 类指定如何启动服务器（使用 php 运行 example_server.php）。
客户端初始化：
- 创建一个新的 Client 实例来管理连接。
连接和查询：
- 客户端连接到服务器并调用 listPrompts() 以检索提示列表。然后，它打印每个提示的详细信息，包括名称、描述和参数。
错误处理：
- 代码包含 try-catch 块以处理错误（例如，服务器未运行时），以及 finally 块以确保连接正确关闭。

运行此代码时，您将看到类似以下的输出：

开始连接
开始列出可用提示
可用提示:
  - 名称: example-prompt
    描述: 一个示例提示模板
    参数:
      - arg1 (必需): 一个示例参数

这展示了 MCP SDK for PHP 中客户端-服务器交互的实际应用。

探索高级功能

SDK 提供了一些额外的工具，以简化开发过程。以下是文档中提到的两个关键功能。

用于调试的日志记录

在构建或排查 MCP 应用程序时，详细的日志记录至关重要。SDK 支持在客户端和服务器端进行日志记录。虽然文档未提供具体的 PHP 示例，但它指出您可以启用详细日志记录以跟踪请求、响应和错误。例如：

在服务器端，您可以在处理器中记录传入的请求。
在客户端，您可以记录连接尝试或提示结果。

此功能在开发过程中特别有用，以确保一切按预期运行。

使用 MCP Web 客户端

SDK 在 webclient 目录中包含一个基于 Web 的客户端，用于在浏览器中测试 MCP 服务器。对于希望以可视化方式与服务器交互的开发者来说，这是一个实用的工具。

设置方法

将 webclient 目录的内容复制到 Web 服务器的公共目录（例如，cPanel 上的 public_html）。
确保在同一目录中安装 MCP SDK，方法是运行：
```
composer require logiscape/mcp-sdk-php
```
打开浏览器并导航到 index.php。

使用 Web 客户端

在界面中，输入 php 到 Command 字段，输入 test_server.php 到 Arguments 字段。
点击 Connect to Server。
您现在可以测试服务器暴露的提示、工具或资源。

Web 客户端还包括一个调试面板，显示客户端和服务器之间交换的 JSON-RPC 消息，这对于理解通信流程非常有帮助。

重要注意事项

此工具仅用于开发和测试。在没有额外安全措施的情况下，不建议在生产环境中使用。
在典型的 PHP Web 托管环境中，不支持长时间运行的进程，因此 Web 客户端会在每次请求时启动新的连接，并在请求完成后关闭连接。

总结

MCP SDK for PHP 是一个强大的工具，可帮助您将大型语言模型集成到 PHP 应用程序中。通过遵循模型上下文协议，它提供了一种结构化的方式来管理上下文，使您的 AI 项目更加高效和可扩展。在本指南中，我们介绍了：

安装：如何使用 Composer 安装 SDK。
MCP 服务器：构建一个为 LLM 提供提示的服务器。
MCP 客户端：创建一个连接并检索数据的客户端。
高级工具：使用日志记录和 Web 客户端进行开发。

无论您是在开发 Web 应用程序、CLI 工具还是实验性 AI 项目，SDK 都提供了一个坚实的起点。它专为希望探索 LLM 的开发者设计，而无需陷入上下文管理的复杂性。

欲了解更多详情，请查阅官方 MCP 文档。准备好开始了吗？安装 SDK，尝试示例，并探索它如何融入您的下一个项目。

本文完全基于提供的 mcp-sdk-php.md 文档，为技术读者提供了清晰、实用且详细的解释。文章结构合理，易于理解，同时通过可操作的步骤和示例提供真正的价值。

PHP MCP SDK终极实践：3分钟构建LLM上下文管理神器

深入了解 PHP 版本的 MCP SDK：整合大型语言模型的实用指南

什么是 MCP SDK for PHP？

为什么使用它？

安装 MCP SDK for PHP

安装步骤

系统要求

使用 SDK 创建 MCP 服务器

示例：一个基本的 MCP 服务器

工作原理

构建 MCP 客户端

示例：一个基本的 MCP 客户端

工作原理

探索高级功能

用于调试的日志记录

使用 MCP Web 客户端

设置方法

使用 Web 客户端

重要注意事项

总结

相关文章