MCP PHP SDK

模型上下文协议（MCP）的官方 PHP SDK。它提供了一个与框架无关的 API，用于在 PHP 中实现 MCP 服务器和客户端。

该项目是 PHP 基金会 和 Symfony 项目 合作的成果。它采用了 Symfony 项目的开发实践和标准，包括 编码规范 和 向后兼容性承诺。

在首个重大版本发布之前，该 SDK 被视为实验性，请参阅 路线图 以了解计划中的下一步和功能。

目录

• 安装
• 概述
• 服务器 SDK
• 客户端 SDK
• 文档
• 外部资源
• 使用 MCP SDK 的 PHP 库
• 贡献
• 致谢
• 许可证

安装

composer require mcp/sdk

概述

MCP PHP SDK 提供了模型上下文协议的服务器和客户端实现，使您能够：

• 构建 MCP 服务器：将您的 PHP 应用程序的功能（工具、资源、提示）暴露给 AI 代理
• 构建 MCP 客户端：从您的 PHP 应用程序中连接并交互 MCP 服务器

服务器 SDK

构建 MCP 服务器，以将您的 PHP 应用程序的能力暴露给 Claude、Codex 等 AI 代理。

快速入门

use Mcp\Server;
use Mcp\Server\Transport\StdioTransport;
use Mcp\Capability\Attribute\McpTool;
use Mcp\Capability\Attribute\McpResource;

// 使用 PHP 属性定义能力
class CalculatorCapabilities
{
    #[McpTool]
    public function add(int $a, int $b): int
    {
        return $a + $b;
    }

    #[McpResource(uri: 'config://calculator/settings')]
    public function getSettings(): array
    {
        return ['precision' => 2];
    }
}

// 构建并运行服务器
$server = Server::builder()
    ->setServerInfo('Calculator Server', '1.0.0')
    ->setDiscovery(__DIR__, ['.'])  // 自动发现属性
    ->build();

$transport = new StdioTransport();
$server->run($transport);

服务器能力

• 工具：AI 代理可以调用的可执行函数
• 资源：可读取的数据源（文件、配置、数据库）
• 资源模板：带有 URI 参数的动态资源
• 提示：预定义的 AI 交互模板
• 服务器发起的通信：启发式请求、采样、日志记录、进度通知

注册方法

有多种方式可以注册您的 MCP 能力——选择最适合您应用程序架构的方法：

1. 基于属性的发现 — 使用 PHP 属性定义能力，以便自动发现：

#[McpTool]
public function generateReport(): string { /* ... */ }

#[McpResource(uri: 'config://app/settings')]
public function getConfig(): array { /* ... */ }

2. 手动注册 — 不使用属性而通过编程方式注册能力：

$server = Server::builder()
    ->addTool([Calculator::class, 'add'], 'add_numbers')
    ->addResource([Config::class, 'get'], 'config://app')
    ->build();

3. 混合方法 — 结合两种方法以获得最大灵活性：

$server = Server::builder()
    ->setDiscovery(__DIR__, ['.'])
    ->addTool([ExternalService::class, 'process'], 'external')
    ->build();

传输方式

根据您的部署环境选择合适的传输方式：

1. STDIO 传输 — 用于命令行集成和本地进程：

$transport = new StdioTransport();
$server->run($transport);

2. HTTP 传输 — 用于基于 Web 的服务器和分布式系统：

$transport = new StreamableHttpTransport($request, $responseFactory, $streamFactory);
$response = $server->run($transport);

会话管理

配置会话存储以在请求之间保持状态。选择适合您基础设施的后端：

内存中（默认，适用于 STDIO）：

$server = Server::builder()
    ->setSession(ttl: 7200) // 2 小时
    ->build();

基于文件（适用于单服务器 HTTP 部署）：

$server = Server::builder()
    ->setSession(new FileSessionStore(__DIR__ . '/sessions'))
    ->build();

PSR-16 缓存（例如使用 Redis 进行扩展部署）：

$server = Server::builder()
    ->setSession(new Psr16SessionStore(
        cache: new Psr16Cache($redisAdapter),
        prefix: 'mcp-',
        ttl: 3600
    ))
    ->build();

→ 服务器文档

客户端 SDK

从您的 PHP 应用程序中连接到 MCP 服务器，以访问其工具、资源和提示。

快速入门

use Mcp\Client;
use Mcp\Client\Transport\StdioTransport;

// 构建客户端
$client = Client::builder()
    ->setClientInfo('My Application', '1.0.0')
    ->setInitTimeout(30)
    ->setRequestTimeout(120)
    ->build();

// 连接到服务器
$transport = new StdioTransport(
    command: 'php',
    args: ['/path/to/server.php'],
);

$client->connect($transport);

// 发现并使用能力
$tools = $client->listTools();
$result = $client->callTool('add', ['a' => 5, 'b' => 3]);

$resources = $client->listResources();
$content = $client->readResource('config://calculator/settings');

$client->disconnect();

客户端能力

• 调用工具：列出并执行任何 MCP 服务器上的工具
• 访问资源：读取静态和动态资源
• 提示管理：列出并获取提示模板
• 补全支持：请求参数补全建议

进阶功能

• 进度跟踪：在长时间操作期间实时跟踪进度

$result = $client->callTool(
    name: 'process_data',
    arguments: ['dataset' => 'large_file.csv'],
    onProgress: function (float $progress, ?float $total, ?string $message) {
        echo "进度: {$progress}/{$total} - {$message}\n";
    }
);

• 采样支持：处理服务器 LLM 的采样请求

$samplingHandler = new SamplingRequestHandler($myCallback);
$client = Client::builder()
    ->setCapabilities(new ClientCapabilities(sampling: true))
    ->addRequestHandler($samplingHandler)
    ->build();

• 日志通知：接收服务器的日志消息

$loggingHandler = new LoggingNotificationHandler($myCallback);
$client = Client::builder()
    ->addNotificationHandler($loggingHandler)
    ->build();

传输方式

使用与您的设置匹配的传输方式连接到 MCP 服务器：

1. STDIO 传输 — 连接到本地服务器进程：

$transport = new StdioTransport(
    command: 'php',
    args: ['/path/to/server.php'],
);

$client->connect($transport);

2. HTTP 传输 — 连接到远程或基于 Web 的服务器：

$transport = new HttpTransport('http://localhost:8000');

$client->connect($transport);

→ 客户端文档

文档

核心概念

• 服务器构建器 — 完整的 ServerBuilder 参考与配置
• 客户端 — 用于连接和与 MCP 服务器通信的客户端 SDK
• 传输方式 — STDIO 和 HTTP 传输的设置与使用
• MCP 元素 — 创建工具、资源、提示和模板
• 服务器-客户端通信 — 抽样、日志记录、进度和通知
• 事件 — 使用事件钩入服务器生命周期

学习与示例

• 示例 — 服务器和客户端的全面示例讲解
• ROADMAP.md — 计划中的功能与开发路线图

外部资源

• Model Context 协议文档 — 官方 MCP 文档
• Model Context 协议规范 — 协议规范
• 官方支持的服务器 — 参考服务器实现

使用 MCP SDK 的 PHP 库

• pronskiy/mcp — 额外的开发者体验层
• symfony/mcp-bundle — Symfony 集成组件包
• josbeir/cakephp-synapse — CakePHP 集成插件

贡献

我们热衷于支持各层次经验的贡献者，并非常欢迎您的参与。

请参阅 贡献指南，在您 提交问题 和 发送拉取请求 之前开始行动。

致谢

本 SDK 的起点是 PHP-MCP 项目，由 Kyrian Obikwelu 发起，以及 Symfony AI 计划。我们感谢这两个项目及其贡献者所做出的工作，正是他们的努力为本 SDK 打下了坚实的基础。

许可证

本项目对新贡献采用 Apache License, Version 2.0 许可证，现有代码则采用 MIT 许可证 — 详情请参阅 LICENSE 文件。

MCP PHP SDK 快速上手指南

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows (需配置好 PHP 环境)
• PHP 版本：建议 PHP 8.1 或更高版本
• 依赖管理：必须安装 Composer
• 前置知识：了解基本的 PHP 面向对象编程和 Composer 使用

提示：国内开发者若遇到 Composer 下载缓慢，推荐使用国内镜像源加速安装：

composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/

安装步骤

通过 Composer 将 mcp/sdk 添加到您的项目中：

composer require mcp/sdk

基本使用

MCP PHP SDK 支持构建 服务端 (Server) 和 客户端 (Client)。以下是两种模式的最简示例。

1. 构建 MCP 服务端 (Server)

创建一个 PHP 文件（例如 server.php），定义工具能力并启动服务。此示例使用 StdioTransport，适合通过命令行与 AI 代理（如 Claude）交互。

<?php
// server.php

use Mcp\Server;
use Mcp\Server\Transport\StdioTransport;
use Mcp\Capability\Attribute\McpTool;
use Mcp\Capability\Attribute\McpResource;

// 1. 定义能力类
class CalculatorCapabilities
{
    #[McpTool]
    public function add(int $a, int $b): int
    {
        return $a + $b;
    }

    #[McpResource(uri: 'config://calculator/settings')]
    public function getSettings(): array
    {
        return ['precision' => 2];
    }
}

// 2. 构建并运行服务器
$server = Server::builder()
    ->setServerInfo('Calculator Server', '1.0.0')
    ->setDiscovery(__DIR__, ['.'])  // 自动发现当前目录下的属性标记
    ->build();

$transport = new StdioTransport();
$server->run($transport);

运行方式： 在终端中直接运行该脚本，它将等待标准输入并与调用者通信：

php server.php

2. 构建 MCP 客户端 (Client)

创建另一个 PHP 文件（例如 client.php），用于连接上述服务端并调用功能。

<?php
// client.php

use Mcp\Client;
use Mcp\Client\Transport\StdioTransport;

// 1. 构建客户端
$client = Client::builder()
    ->setClientInfo('My Application', '1.0.0')
    ->setInitTimeout(30)
    ->build();

// 2. 连接到本地运行的服务端进程
$transport = new StdioTransport(
    command: 'php',
    args: ['server.php'], // 指向刚才创建的 server.php
);

$client->connect($transport);

// 3. 发现并调用工具
$tools = $client->listTools();
echo "可用工具：" . implode(', ', array_column($tools, 'name')) . "\n";

$result = $client->callTool('add', ['a' => 5, 'b' => 3]);
echo "计算结果 (5+3): " . $result . "\n";

// 4. 读取资源
$content = $client->readResource('config://calculator/settings');
print_r($content);

$client->disconnect();

运行方式：

php client.php

输出示例：

可用工具：add
计算结果 (5+3): 8
Array
(
    [precision] => 2
)