PHP MCP 服务器 SDK

用于构建【模型上下文协议（MCP）】服务器的全面 PHP SDK。通过现代架构、丰富的测试以及灵活的传输选项，用 PHP 快速创建可投入生产的 MCP 服务器。

此 SDK 可让您将 PHP 应用程序的功能作为标准化的 MCP 工具、资源 和提示公开，从而让 AI 助手（如 Anthropic 的 Claude、Cursor IDE、OpenAI 的 ChatGPT 等）能够以 MCP 标准与您的后端进行交互。

🚀 主要特性

• 🏗️ 现代架构：采用 PHP 8.1+ 特性、PSR 标准和模块化设计
• 📡 多种传输方式：支持 stdio、http+sse 以及全新的可流式 HTTP，具备断点续传功能
• 🎯 基于属性的定义：使用 PHP 8 属性（#[McpTool]、#[McpResource] 等）实现零配置元素注册
• 🔧 灵活的处理器：支持闭包、类方法、静态方法和可调用类
• 📝 智能模式生成：根据方法签名自动生成 JSON 模式，可选使用 #[Schema] 属性增强功能
• ⚡ 会话管理：支持多种存储后端的高级会话处理
• 🔄 事件驱动：基于 ReactPHP，实现高并发和非阻塞操作
• 📊 批处理支持：全面支持 JSON-RPC 批量请求
• 💾 智能缓存：对发现的元素进行智能缓存，手动覆盖优先
• 🧪 补全提供者：内置工具和提示的参数补全支持
• 🔌 依赖注入：完全支持 PSR-11 容器，并具备自动装配功能
• 📋 全面测试：丰富的测试套件，包含所有传输方式的集成测试

本包支持【2025-03-26】版本的模型上下文协议，同时具备向后兼容性。

📋 要求

• PHP >= 8.1
• Composer
• 对于 HTTP 传输：事件驱动的 PHP 环境（推荐使用 CLI）
• 扩展：json、mbstring、pcre（通常默认启用）

📦 安装

composer require php-mcp/server

💡 Laravel 用户：建议使用 php-mcp/laravel，以获得更佳的框架集成、配置管理和 Artisan 命令支持。

⚡ 快速入门：带发现功能的 Stdio 服务器

本示例展示了最常见的使用模式——基于属性发现的 stdio 服务器。

1. 定义您的 MCP 元素

创建 src/CalculatorElements.php：

<?php

namespace App;

use PhpMcp\Server\Attributes\McpTool;
use PhpMcp\Server\Attributes\Schema;

class CalculatorElements
{
    /**
     * 将两个数字相加。
     * 
     * @param int $a 第一个数字
     * @param int $b 第二个数字  
     * @return int 两个数字之和
     */
    #[McpTool(name: 'add_numbers')]
    public function add(int $a, int $b): int
    {
        return $a + $b;
    }

    /**
     * 计算幂并进行验证。
     */
    #[McpTool(name: 'calculate_power')]
    public function power(
        #[Schema(type: 'number', minimum: 0, maximum: 1000)]
        float $base,
        
        #[Schema(type: 'integer', minimum: 0, maximum: 10)]
        int $exponent
    ): float {
        return pow($base, $exponent);
    }
}

2. 创建服务器脚本

创建 mcp-server.php：

#!/usr/bin/env php
<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use PhpMcp\Server\Server;
use PhpMcp\Server\Transports\StdioServerTransport;

try {
    // 构建服务器配置
    $server = Server::make()
        ->withServerInfo('PHP 计算器服务器', '1.0.0') 
        ->build();

    // 通过属性发现 MCP 元素
    $server->discover(
        basePath: __DIR__,
        scanDirs: ['src']
    );

    // 通过 stdio 传输开始监听
    $transport = new StdioServerTransport();
    $server->listen($transport);

} catch (\Throwable $e) {
    fwrite(STDERR, "[严重错误] " . $e->getMessage() . "\n");
    exit(1);
}

3. 配置您的 MCP 客户端

添加到您的客户端配置（例如 .cursor/mcp.json）：

{
    "mcpServers": {
        "php-calculator": {
            "command": "php",
            "args": ["/绝对路径/到/您的/mcp-server.php"]
        }
    }
}

4. 测试服务器

您的 AI 助手现在可以调用：

• add_numbers —— 两个整数相加
• calculate_power —— 计算幂并施加验证约束

🏗️ 架构概览

PHP MCP 服务器采用现代化的解耦架构：

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   MCP 客户端    │◄──►│   传输方式      │◄──►│   协议          │
│  (Claude 等)    │    │ (Stdio/HTTP/SSE) │    │   (JSON-RPC)    │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                                         │
                       ┌─────────────────┐               │
                       │ 会话管理器     │◄──────────────┤
                       │ (多后端)        │               │
                       └─────────────────┘               │
                                                         │
┌─────────────────┐    ┌──────────────────┐              │
│   分发器        │◄───│   服务器核心     │◄─────────────┤
│ (方法路由)      │    │   配置           │              │
└─────────────────┘    └──────────────────┘              │
         │                                               │
         ▼                                               │
┌─────────────────┐    ┌──────────────────┐              │
│    注册表       │    │   元素           │◄─────────────┘
│  (元素存储)     │◄──►│ (工具/资源/提示等)│
└─────────────────┘    └──────────────────┘

核心组件

• ServerBuilder：流畅的配置接口（Server::make()->...->build()）
• Server：中央协调器，包含所有已配置的组件
• Protocol：JSON-RPC 2.0 处理器，连接传输方式与核心逻辑
• SessionManager：多后端会话存储（数组、缓存、自定义）
• Dispatcher：方法路由与请求处理
• Registry：元素存储，具备智能缓存与优先级规则
• Elements：已注册的 MCP 组件（工具、资源、提示、模板）

传输选项

1. StdioServerTransport：用于直接启动客户端的标准 I/O
2. HttpServerTransport：用于 Web 集成的 HTTP + 服务器发送事件
3. StreamableHttpServerTransport：增强型 HTTP，支持断点续传和事件溯源

⚙️ 服务器配置

基本配置

use PhpMcp\Server\Server;
use PhpMcp\Schema\ServerCapabilities;

$server = Server::make()
    ->withServerInfo('我的应用服务器', '2.1.0')
    ->withCapabilities(ServerCapabilities::make(
        resources: true,
        resourcesSubscribe: true,
        prompts: true,
        tools: true
    ))
    ->withPaginationLimit(100)
    ->build();

带依赖项的高级配置

use Psr\Log\Logger;
use Psr\SimpleCache\CacheInterface;
use Psr\Container\ContainerInterface;

$server = Server::make()
    ->withServerInfo('生产环境服务器', '1.0.0')
    ->withLogger($myPsrLogger)                    // PSR-3 日志记录器
    ->withCache($myPsrCache)                      // PSR-16 缓存  
    ->withContainer($myPsrContainer)              // PSR-11 容器
    ->withSession('cache', 7200)                  // 基于缓存的会话，TTL 2小时
    ->withPaginationLimit(50)                     // 限制列表响应
    ->build();

会话管理选项

// 内存中会话（默认，非持久化）
->withSession('array', 3600)

// 基于缓存的会话（重启后仍有效）  
->withSession('cache', 7200)

// 自定义会话处理器（实现 SessionHandlerInterface）
->withSessionHandler(new MyCustomSessionHandler(), 1800)

🎯 定义 MCP 元素

服务器提供了两种强大的方式来定义 MCP 元素：基于属性的发现（推荐）和手动注册。两者可以结合使用，且手动注册优先。

元素类型

• 🔧 工具：可执行的函数/操作（例如 calculate、send_email、query_database）
• 📄 资源：静态内容/数据（例如 config://settings、file://readme.txt）
• 📋 资源模板：带有 URI 模式的动态资源（例如 user://{id}/profile）
• 💬 提示：对话开场白/模板（例如 summarize、translate）

1. 🏷️ 基于属性的发现（推荐）

使用 PHP 8 属性将方法或可调用类标记为 MCP 元素。服务器将通过文件系统扫描来发现它们。

use PhpMcp\Server\Attributes\{McpTool, McpResource, McpResourceTemplate, McpPrompt};

class UserManager
{
    /**
     * 创建新用户账户。
     */
    #[McpTool(name: 'create_user')]
    public function createUser(string $email, string $password, string $role = 'user'): array
    {
        // 创建用户逻辑
        return ['id' => 123, 'email' => $email, 'role' => $role];
    }

    /**
     * 获取用户配置。
     */
    #[McpResource(
        uri: 'config://user/settings',
        mimeType: 'application/json'
    )]
    public function getUserConfig(): array
    {
        return ['theme' => 'dark', 'notifications' => true];
    }

    /**
     * 根据 ID 获取用户个人资料。
     */
    #[McpResourceTemplate(
        uriTemplate: 'user://{userId}/profile',
        mimeType: 'application/json'
    )]
    public function getUserProfile(string $userId): array
    {
        return ['id' => $userId, 'name' => 'John Doe'];
    }

    /**
     * 生成欢迎消息提示。
     */
    #[McpPrompt(name: 'welcome_user')]
    public function welcomeUserPrompt(string $username, string $role): array
    {
        return [
            ['role' => 'user', 'content' => "为 {$username} 创建一条欢迎信息，角色为 {$role}"]
        ];
    }
}

发现过程：

// 先构建服务器
$server = Server::make()
    ->withServerInfo('我的应用服务器', '1.0.0')
    ->build();

// 然后发现元素
$server->discover(
    basePath: __DIR__,
    scanDirs: ['src/Handlers', 'src/Services'],  // 需要扫描的目录
    excludeDirs: ['src/Tests'],                  // 需要跳过的目录
    saveToCache: true                            // 缓存结果（默认为 true）
);

可用属性：

• #[McpTool]：可执行的操作
• #[McpResource]：可通过 URI 访问的静态内容
• #[McpResourceTemplate]：带有 URI 模板的动态资源
• #[McpPrompt]：对话模板和提示生成器

2. 🔧 手动注册

在调用 build() 之前，使用 ServerBuilder 以编程方式注册元素。这在动态注册、闭包或您希望获得明确控制时非常有用。

use App\Handlers\{EmailHandler, ConfigHandler, UserHandler, PromptHandler};
use PhpMcp\Schema\{ToolAnnotations, Annotations};

$server = Server::make()
    ->withServerInfo('手动注册服务器', '1.0.0')
    
    // 注册带有处理方法的工具
    ->withTool(
        [EmailHandler::class, 'sendEmail'],     // 处理方法：[类, 方法]
        name: 'send_email',                     // 工具名称（可选）
        description: '向用户发送电子邮件',     // 描述（可选）
        annotations: ToolAnnotations::make(     // 注解（可选）
            title: '发送电子邮件工具'
        )
    )
    
    // 将可调用类注册为工具
    ->withTool(UserHandler::class)             // 处理方法：可调用类
    
    // 将闭包注册为工具
    ->withTool(
        function(int $a, int $b): int {         // 处理方法：闭包
            return $a + $b;
        },
        name: 'add_numbers',
        description: '将两个数字相加'
    )
    
    // 注册带有闭包的资源
    ->withResource(
        function(): array {                     // 处理方法：闭包
            return ['timestamp' => time(), 'server' => 'php-mcp'];
        },
        uri: 'config://runtime/status',         // URI（必填）
        mimeType: 'application/json'           // MIME 类型（可选）
    )
    
    // 注册资源模板
    ->withResourceTemplate(
        [UserHandler::class, 'getUserProfile'],
        uriTemplate: 'user://{userId}/profile'  // URI 模板（必填）
    )
    
    // 注册带有闭包的提示
    ->withPrompt(
        function(string $topic, string $tone = 'professional'): array {
            return [
                ['role' => 'user', 'content' => "写一篇关于 {$topic} 的文章，语气为 {$tone}"]
            ];
        },
        name: 'writing_prompt'                  // 提示名称（可选）
    )
    
    ->build();

该服务器支持三种灵活的处理程序格式：[ClassName::class, 'methodName'] 用于类方法处理程序，InvokableClass::class 用于可调用类处理程序（具有 __invoke 方法的类），以及任何 PHP 可调用对象，包括闭包、静态方法如 [SomeClass::class, 'staticMethod'] 或函数名。基于类的处理程序通过配置的 PSR-11 容器进行解析，以实现依赖注入。手动注册的元素不会被缓存，并且优先于具有相同标识符的已发现元素。

[!重要] 当使用闭包作为处理程序时，服务器仅根据 PHP 类型提示生成最小化的 JSON 模式，因为没有文档块或类上下文可用。若要获取包含验证约束、描述和格式的更详细模式，您可以选择以下两种方式：

• 使用 #[Schema] 属性以增强模式生成
• 在使用 ->withTool() 注册工具时，提供自定义的 $inputSchema 参数

🏆 元素优先级与发现

优先级规则：

• 手动注册的元素始终覆盖具有相同标识符的已发现/已缓存元素
• 已发现的元素会被缓存以提高性能（可配置）
• 缓存会在每次重新发现时自动失效

发现流程：

$server->discover(
    basePath: __DIR__,
    scanDirs: ['src/Handlers', 'src/Services'],  // 扫描这些目录
    excludeDirs: ['tests', 'vendor'],            // 跳过这些目录
    force: false,                                // 强制重新扫描（默认：false）
    saveToCache: true                            // 保存到缓存（默认：true）
);

缓存行为：

• 只有已发现的元素会被缓存（绝不会缓存手动注册的元素）
• 缓存在 build() 期间自动加载（如果可用）
• 新的 discover() 调用会清除并重建缓存
• 使用 force: true 可绕过已运行发现检查

🚀 运行服务器（传输方式）

服务器核心与传输方式无关。根据您的部署需求选择合适的传输方式：

1. 📟 Stdio 传输

最适合：直接客户端执行、命令行工具、简单部署

use PhpMcp\Server\Transports\StdioServerTransport;

$server = Server::make()
    ->withServerInfo('Stdio 服务器', '1.0.0')
    ->build();

$server->discover(__DIR__, ['src']);

// 创建 stdio 传输（默认使用 STDIN/STDOUT）
$transport = new StdioServerTransport();

// 开始监听（阻塞调用）
$server->listen($transport);

客户端配置：

{
    "mcpServers": {
        "my-php-server": {
            "command": "php",
            "args": ["/absolute/path/to/server.php"]
        }
    }
}

⚠️ 重要提示：使用 stdio 传输时，切勿在处理程序中向 STDOUT 写入内容（调试时请使用 STDERR）。STDOUT 保留用于 JSON-RPC 通信。

2. 🌐 HTTP + 服务器发送事件传输（已弃用）

⚠️ 注意：此传输方式已在最新 MCP 协议版本中弃用，但仍保留以兼容旧版本。对于新项目，请使用 StreamableHttpServerTransport，它提供了增强功能和更好的协议合规性。

最适合：需要向后兼容的旧应用

use PhpMcp\Server\Transports\HttpServerTransport;

$server = Server::make()
    ->withServerInfo('HTTP 服务器', '1.0.0')
    ->withLogger($logger)  // 推荐用于 HTTP
    ->build();

$server->discover(__DIR__, ['src']);

// 创建 HTTP 传输
$transport = new HttpServerTransport(
    host: '127.0.0.1',      // MCP 协议禁止使用 0.0.0.0
    port: 8080,             // 端口号
    mcpPathPrefix: 'mcp'    // URL 前缀 (/mcp/sse, /mcp/message)
);

$server->listen($transport);

客户端配置：

{
    "mcpServers": {
        "my-http-server": {
            "url": "http://localhost:8080/mcp/sse"
        }
    }
}

端点：

• SSE 连接：GET /mcp/sse
• 消息发送：POST /mcp/message?clientId={clientId}

3. 🔄 可流式 HTTP 传输（推荐）

适用场景：生产部署、远程 MCP 服务器、多客户端、可恢复连接

use PhpMcp\Server\Transports\StreamableHttpServerTransport;

$server = Server::make()
    ->withServerInfo('Streamable Server', '1.0.0')
    ->withLogger($logger)
    ->withCache($cache)     // 恢复功能所需
    ->build();

$server->discover(__DIR__, ['src']);

// 创建支持恢复功能的可流式传输
$transport = new StreamableHttpServerTransport(
    host: '127.0.0.1',      // MCP 协议禁止使用 0.0.0.0
    port: 8080,
    mcpPathPrefix: 'mcp',
    enableJsonResponse: false,  // 使用 SSE 流式传输（默认）
    stateless: false            // 启用无状态模式，适用于无会话客户端
);

$server->listen($transport);

JSON 响应模式：

enableJsonResponse 选项控制响应的交付方式：

• false（默认）：使用服务器发送事件（SSE）流式传输响应。适合处理时间较长的工具。
• true：立即返回 JSON 响应，不开启 SSE 流。适用于执行速度快、无需流式传输的工具。

// 对于执行快速的工具，启用 JSON 模式
$transport = new StreamableHttpServerTransport(
    host: '127.0.0.1',
    port: 8080,
    enableJsonResponse: true  // 立即返回 JSON 响应
);

无状态模式：

对于会话管理存在问题的客户端，可启用无状态模式：

$transport = new StreamableHttpServerTransport(
    host: '127.0.0.1',
    port: 8080,
    stateless: true  // 每个请求独立处理
);

在无状态模式下，会话 ID 在内部生成但不会暴露给客户端，每个请求都被视为独立请求，不会保留持久化会话状态。

特性：

• 可恢复连接：客户端可重新连接并重播遗漏的事件
• 事件溯源：所有事件均存储以供重播
• JSON 模式：可选仅返回 JSON 响应，适合快速工具
• 增强会话管理：持久化会话状态
• 多客户端支持：专为并发客户端设计
• 无状态模式：适用于简单客户端的无会话操作

📋 模式生成与验证

服务器会自动为工具参数生成 JSON 模式，采用一种复杂的优先级系统，结合 PHP 类型提示、文档块信息以及可选的 #[Schema] 属性。这些生成的模式既用于输入验证，也用于向 MCP 客户端提供模式信息。

模式生成优先级

服务器在生成模式时遵循以下优先级顺序：

1. 带有 definition 的 #[Schema] 属性：完全覆盖模式（最高优先级）
2. 参数级别的 #[Schema] 属性：针对特定参数的模式增强
3. 方法级别的 #[Schema] 属性：方法范围内的模式配置
4. PHP 类型提示 + 文档块：从代码中自动推断（最低优先级）

当 Schema 属性中提供了 definition 时，所有自动推断将被忽略，直接使用完整的定义。

参数级别的模式属性

use PhpMcp\Server\Attributes\{McpTool, Schema};

#[McpTool(name: 'validate_user')]
public function validateUser(
    #[Schema(format: 'email')]              // PHP 已知是字符串
    string $email,
    
    #[Schema(
        pattern: '^[A-Z][a-z]+$',
        description: '首字母大写的名称'
    )]
    string $name,
    
    #[Schema(minimum: 18, maximum: 120)]    // PHP 已知是整数
    int $age
): bool {
    return filter_var($email, FILTER_VALIDATE_EMAIL) !== false;
}

方法级别的模式

/**
 * 处理用户数据并进行嵌套验证。
 */
#[McpTool(name: 'create_user')]
#[Schema(
    properties: [
        'profile' => [
            'type' => 'object',
            'properties' => [
                'name' => ['type' => 'string', 'minLength' => 2],
                'age' => ['type' => 'integer', 'minimum' => 18],
                'email' => ['type' => 'string', 'format' => 'email']
            ],
            'required' => ['name', 'email']
        ]
    ],
    required: ['profile']
)]
public function createUser(array $userData): array
{
    // PHP 类型提示提供基础的 'array' 类型
    // 方法级别的 Schema 添加对象结构验证
    return ['id' => 123, 'status' => 'created'];
}

完全模式覆盖（仅限方法级别）

#[McpTool(name: 'process_api_request')]
#[Schema(definition: [
    'type' => 'object',
    'properties' => [
        'endpoint' => ['type' => 'string', 'format' => 'uri'],
        'method' => ['type' => 'string', 'enum' => ['GET', 'POST', 'PUT', 'DELETE']],
        'headers' => [
            'type' => 'object',
            'patternProperties' => [
                '^[A-Za-z0-9-]+$' => ['type' => 'string']
            ]
        ]
    ],
    'required' => ['endpoint', 'method']
])]
public function processApiRequest(string $endpoint, string $method, array $headers): array
{
    // 当提供 definition 时，PHP 类型提示完全被忽略
    // 上述模式定义具有最高优先级
    return ['status' => 'processed', 'endpoint' => $endpoint];
}

⚠️ 重要提示：完全模式覆盖应尽量少用。它会绕过所有自动模式推断，要求您手动定义整个 JSON 模式。只有在您对 JSON 模式规范非常熟悉且有复杂验证需求、无法通过优先级系统实现时，才使用此方式。大多数情况下，参数级别和方法级别的 #[Schema] 属性已能提供足够的灵活性。

🎨 返回值格式化

服务器会自动将您的处理器返回值格式化为合适的 MCP 内容类型：

自动格式化

// 简单值会自动包装为 TextContent
public function getString(): string { return "Hello World"; }           // → TextContent
public function getNumber(): int { return 42; }                        // → TextContent  
public function getBool(): bool { return true; }                       // → TextContent
public function getArray(): array { return ['key' => 'value']; }       // → TextContent (JSON)

// 空值处理
public function getNull(): ?string { return null; }                    // → TextContent("(null)")
public function returnVoid(): void { /* 无返回 */ }                 // → 空内容

高级内容类型

use PhpMcp\Schema\Content\{TextContent, ImageContent, AudioContent, ResourceContent};

public function getFormattedCode(): TextContent
{
    return TextContent::code('<?php echo "Hello";', 'php');
}

public function getMarkdown(): TextContent  
{
    return TextContent::make('# 标题\n\n内容这里');
}

public function getImage(): ImageContent
{
    return ImageContent::make(
        data: base64_encode(file_get_contents('image.png')),
        mimeType: 'image/png'
    );
}

public function getAudio(): AudioContent
{
    return AudioContent::make(
        data: base64_encode(file_get_contents('audio.mp3')),
        mimeType: 'audio/mpeg'
    );
}

文件与流处理

// 文件对象会自动读取并格式化
public function getFileContent(): \SplFileInfo
{
    return new \SplFileInfo('/path/to/file.txt');  // 自动检测 MIME 类型
}

// 流资源会被完整读取
public function getStreamContent()
{
    $stream = fopen('/path/to/data.json', 'r');
    return $stream;  // 将自动读取并关闭
}

// 结构化资源响应
public function getStructuredResource(): array
{
    return [
        'text' => '文件内容这里',
        'mimeType' => 'text/plain'
    ];
    
    // 或者用于二进制数据：
    // return [
    //     'blob' => base64_encode($binaryData),
    //     'mimeType' => 'application/octet-stream'
    // ];
}

🔄 批量处理

服务器会自动处理 JSON-RPC 批量请求：

// 客户端可在一次 HTTP 调用中发送多个请求：
[
    {"jsonrpc": "2.0", "id": "1", "method": "tools/call", "params": {...}},
    {"jsonrpc": "2.0", "method": "notifications/ping"},              // 通知
    {"jsonrpc": "2.0", "id": "2", "method": "tools/call", "params": {...}}
]

// 服务器返回批量响应（不包括通知）：
[
    {"jsonrpc": "2.0", "id": "1", "result": {...}},
    {"jsonrpc": "2.0", "id": "2", "result": {...}}
]

🔧 高级功能

补全提供程序

补全提供程序使 MCP 客户端能够在用户界面中提供自动补全建议。它们专为资源模板和提示设计，以帮助用户发现模板变量或提示参数等动态部分的可用选项。

注意：工具和资源可通过标准 MCP 命令（tools/list、resources/list）进行查找，因此无需使用补全提供程序。补全提供程序仅用于资源模板（URI 变量）和提示参数。

#[CompletionProvider] 属性支持三种类型的补全源：

1. 自定义提供程序类

对于复杂的补全逻辑，实现 CompletionProviderInterface：

use PhpMcp\Server\Contracts\CompletionProviderInterface;
use PhpMcp\Server\Contracts\SessionInterface;
use PhpMcp\Server\Attributes\{McpResourceTemplate, CompletionProvider};

class UserIdCompletionProvider implements CompletionProviderInterface
{
    public function __construct(private DatabaseService $db) {}

    public function getCompletions(string $currentValue, SessionInterface $session): array
    {
        // 从数据库获取动态补全
        return $this->db->searchUsers($currentValue);
    }
}

class UserService
{
    #[McpResourceTemplate(uriTemplate: 'user://{userId}/profile')]
    public function getUserProfile(
        #[CompletionProvider(provider: UserIdCompletionProvider::class)]  // 类字符串 - 由容器解析
        string $userId
    ): array {
        return ['id' => $userId, 'name' => 'John Doe'];
    }
}

您也可以传递预配置的提供程序实例：

class DocumentService  
{
    #[McpPrompt(name: 'document_prompt')]
    public function generatePrompt(
        #[CompletionProvider(provider: new UserIdCompletionProvider($database))]  // 预配置实例
        string $userId,
        
        #[CompletionProvider(provider: $this->categoryProvider)]  // 属性中的实例
        string $category
    ): array {
        return [['role' => 'user', 'content' => "为用户 {$userId} 生成 {$category} 文档"]];
    }
}

2. 简单列表补全

对于静态补全列表，使用 values 参数：

use PhpMcp\Server\Attributes\{McpPrompt, CompletionProvider};

class ContentService
{
    #[McpPrompt(name: 'content_generator')]
    public function generateContent(
        #[CompletionProvider(values: ['blog', 'article', 'tutorial', 'guide', 'documentation'])]
        string $contentType,
        
        #[CompletionProvider(values: ['beginner', 'intermediate', 'advanced', 'expert'])]
        string $difficulty
    ): array {
        return [['role' => 'user', 'content' => "创建一个 {$difficulty} 级别的 {$contentType}"]];
    }
}

3. 枚举类型补全

对于枚举类，使用 enum 参数：

enum Priority: string
{
    case LOW = 'low';
    case MEDIUM = 'medium';
    case HIGH = 'high';
    case CRITICAL = 'critical';
}

enum Status  // 单位枚举（无后备值）
{
    case DRAFT;
    case PUBLISHED;
    case ARCHIVED;
}

class TaskService
{
    #[McpTool(name: 'create_task')]
    public function createTask(
        string $title,
        
        #[CompletionProvider(enum: Priority::class)]  // 字符串支持的枚举使用 values
        string $priority,
        
        #[CompletionProvider(enum: Status::class)]    // 单位枚举使用 case 名称
        string $status
    ): array {
        return ['id' => 123, 'title' => $title, 'priority' => $priority, 'status' => $status];
    }
}

手动注册补全提供程序

$server = Server::make()
    ->withServerInfo('补全演示', '1.0.0')
    
    // 使用提供程序类（由容器解析）
    ->withPrompt(
        [DocumentHandler::class, 'generateReport'],
        name: 'document_report'
        // 补全提供程序会自动从方法属性中发现
    )
    
    // 使用闭包并内联补全提供程序
    ->withPrompt(
        function(
            #[CompletionProvider(values: ['json', 'xml', 'csv', 'yaml'])]
            string $format,
            
            #[CompletionProvider(enum: Priority::class)]
            string $priority
        ): array {
            return [['role' => 'user', 'content' => "以 {$format} 格式导出数据，优先级为 {$priority}"]];
        },
        name: 'export_data'
    )
    
    ->build();

补全提供程序解析

服务器会自动处理提供程序解析：

• 类字符串 (MyProvider::class) → 通过 PSR-11 容器解析，并进行依赖注入
• 实例 (new MyProvider()) → 直接原样使用
• 值数组 (['a', 'b', 'c']) → 自动包装为 ListCompletionProvider
• 枚举类 (MyEnum::class) → 自动包装为 EnumCompletionProvider

重要提示：补全提供程序仅在 MCP 客户端界面中为用户提供建议。用户仍可输入任意值，因此无论补全提供程序有何限制，您都应在处理器中始终对参数进行验证。

自定义依赖注入

您的 MCP 元素处理器可以使用构造函数依赖注入来访问数据库、API 或其他业务逻辑服务。当处理器具有构造函数依赖时，您必须提供一个预配置的 PSR-11 容器，其中包含这些依赖。

默认情况下，服务器使用 BasicContainer —— 一种简单的实现，尝试通过实例化无参构造函数的类来自动注入依赖。对于需要配置的依赖（如数据库连接），您可以手动将其添加到 BasicContainer，或者使用更高级的 PSR-11 容器，例如 PHP-DI 或 Laravel 的容器。

use Psr\Container\ContainerInterface;

class DatabaseService
{
    public function __construct(private \PDO $pdo) {}
    
    #[McpTool(name: 'query_users')]
    public function queryUsers(): array
    {
        $stmt = $this->pdo->query('SELECT * FROM users');
        return $stmt->fetchAll();
    }
}

// 选项 1：使用基本容器并手动添加依赖
$basicContainer = new \PhpMcp\Server\Defaults\BasicContainer();
$basicContainer->set(\PDO::class, new \PDO('sqlite::memory:'));

// 选项 2：使用任何兼容 PSR-11 的容器（PHP-DI、Laravel 等）
$container = new \DI\Container();
$container->set(\PDO::class, new \PDO('mysql:host=localhost;dbname=app', $user, $pass));

$server = Server::make()
    ->withContainer($basicContainer)  // 处理器会自动注入依赖
    ->build();

资源订阅

use PhpMcp\Schema\ServerCapabilities;

$server = Server::make()
    ->withCapabilities(ServerCapabilities::make(
        resourcesSubscribe: true,  // 启用资源订阅
        prompts: true,
        tools: true
    ))
    ->build();

// 在您的资源处理器中，您可以通知客户端发生的变化：
#[McpResource(uri: 'file://config.json')]
public function getConfig(): array
{
    // 当配置发生变化时，通知订阅者
    $this->notifyResourceChange('file://config.json');
    return ['setting' => 'value'];
}

可恢复性和事件存储

对于使用 StreamableHttpServerTransport 的生产部署，您可以通过提供自定义事件存储来实现可恢复性与事件溯源：

use PhpMcp\Server\Contracts\EventStoreInterface;
use PhpMcp\Server\Defaults\InMemoryEventStore;
use PhpMcp\Server\Transports\StreamableHttpServerTransport;

// 使用内置的内存事件存储（用于开发和测试）
$eventStore = new InMemoryEventStore();

// 或者实现您自己的持久化事件存储
class DatabaseEventStore implements EventStoreInterface
{
    public function storeEvent(string $streamId, string $message): string
    {
        // 将事件存储到数据库并返回唯一事件ID
        return $this->database->insert('events', [
            'stream_id' => $streamId,
            'message' => $message,
            'created_at' => now()
        ]);
    }

    public function replayEventsAfter(string $lastEventId, callable $sendCallback): void
    {
        // 重放事件以实现可恢复性
        $events = $this->database->getEventsAfter($lastEventId);
        foreach ($events as $event) {
            $sendCallback($event['id'], $event['message']);
        }
    }
}

// 配置传输层并指定事件存储
$transport = new StreamableHttpServerTransport(
    host: '127.0.0.1',
    port: 8080,
    eventStore: new DatabaseEventStore()  // 启用可恢复性
);

自定义会话处理器

通过创建实现 SessionHandlerInterface 的类，您可以实现自定义会话存储：

use PhpMcp\Server\Contracts\SessionHandlerInterface;

class DatabaseSessionHandler implements SessionHandlerInterface
{
    public function __construct(private \PDO $db) {}

    public function read(string $id): string|false
    {
        $stmt = $this->db->prepare('SELECT data FROM sessions WHERE id = ?');
        $stmt->execute([$id]);
        $session = $stmt->fetch(\PDO::FETCH_ASSOC);
        return $session ? $session['data'] : false;
    }

    public function write(string $id, string $data): bool
    {
        $stmt = $this->db->prepare(
            'INSERT OR REPLACE INTO sessions (id, data, updated_at) VALUES (?, ?, ?)'
        );
        return $stmt->execute([$id, $data, time()]);
    }

    public function destroy(string $id): bool
    {
        $stmt = $this->db->prepare('DELETE FROM sessions WHERE id = ?');
        return $stmt->execute([$id]);
    }

    public function gc(int $maxLifetime): array
    {
        $cutoff = time() - $maxLifetime;
        $stmt = $this->db->prepare('DELETE FROM sessions WHERE updated_at < ?');
        $stmt->execute([$cutoff]);
        return []; // 如果需要，返回已清理的会话ID数组
    }
}

// 使用自定义会话处理器
$server = Server::make()
    ->withSessionHandler(new DatabaseSessionHandler(), 3600)
    ->build();

中间件支持

HttpServerTransport 和 StreamableHttpServerTransport 均支持符合 PSR-7 标准的中间件，用于拦截和修改 HTTP 请求与响应。中间件允许您将认证、日志记录、CORS 处理和请求验证等通用功能提取为可复用组件。

中间件必须是一个有效的 PHP 可调用对象，它接受一个 PSR-7 的 ServerRequestInterface 作为第一个参数，以及一个 callable 作为第二个参数。

use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Message\ResponseInterface;
use React\Promise\PromiseInterface;

class AuthMiddleware
{
    public function __invoke(ServerRequestInterface $request, callable $next)
    {
        $apiKey = $request->getHeaderLine('Authorization');
        if (empty($apiKey)) {
            return new Response(401, [], 'Authorization required');
        }
        
        $request = $request->withAttribute('user_id', $this->validateApiKey($apiKey));
        $result = $next($request);
        
        return match (true) {
            $result instanceof PromiseInterface => $result->then(fn($response) => $this->handle($response)),
            $result instanceof ResponseInterface => $this->handle($response),
            default => $result
        };
    }
    
    private function handle($response)
    {
        return $response instanceof ResponseInterface
            ? $response->withHeader('X-Auth-Provider', 'mcp-server')
            : $response;
    }
}

$middlewares = [
    new AuthMiddleware(),
    new LoggingMiddleware(),
    function(ServerRequestInterface $request, callable $next) {
        $result = $next($request);
        return match (true) {
            $result instanceof PromiseInterface => $result->then(function($response) {
                return $response instanceof ResponseInterface 
                    ? $response->withHeader('Access-Control-Allow-Origin', '*')
                    : $response;
            }),
            $result instanceof ResponseInterface => $result->withHeader('Access-Control-Allow-Origin', '*'),
            default => $result
        };
    }
];

$transport = new StreamableHttpServerTransport(
    host: '127.0.0.1',
    port: 8080,
    middlewares: $middlewares
);

重要注意事项：

• 响应处理：中间件必须同时处理 $next($request) 返回的同步 ResponseInterface 和异步 PromiseInterface，因为 ReactPHP 是异步运行的。
• 可调用模式：推荐使用可调用类，并单独定义 handle() 方法来处理响应，这样可以复用异步逻辑。
• 执行顺序：中间件按照提供的顺序执行，最后一个中间件最接近您的 MCP 处理器。

SSL 上下文配置

对于 StreamableHttpServerTransport 的 HTTPS 部署，您可以配置 SSL 上下文选项：

$sslContext = [
    'ssl' => [
        'local_cert' => '/path/to/certificate.pem',
        'local_pk' => '/path/to/private-key.pem',
        'verify_peer' => false,
        'allow_self_signed' => true,
    ]
];

$transport = new StreamableHttpServerTransport(
    host: '0.0.0.0',
    port: 8443,
    sslContext: $sslContext
);

SSL 上下文参考：有关完整的 SSL 上下文选项，请参阅 PHP SSL 上下文选项文档。

🔍 错误处理与调试

服务器提供了全面的错误处理与调试功能：

异常处理

工具处理器在出现错误时可以抛出任意 PHP 异常。服务器会自动将这些异常转换为适合 MCP 客户端的 JSON-RPC 错误响应。

#[McpTool(name: 'divide_numbers')]
public function divideNumbers(float $dividend, float $divisor): float
{
    if ($divisor === 0.0) {
        // 包含描述性信息的任何异常都会发送给客户端
        throw new \InvalidArgumentException('除数不能为零');
    }
    
    return $dividend / $divisor;
}

#[McpTool(name: 'calculate_factorial')]
public function calculateFactorial(int $number): int
{
    if ($number < 0) {
        throw new \InvalidArgumentException('负数没有阶乘定义');
    }
    
    if ($number > 20) {
        throw new \OverflowException('数字过大，阶乘会导致溢出');
    }
    
    // 实现继续...
    return $this->factorial($number);
}

服务器会将这些异常转换为 MCP 客户端能够理解并显示给用户的适当 JSON-RPC 错误响应。

日志记录与调试

use Psr\Log\LoggerInterface;

class DebugAwareHandler
{
    public function __construct(private LoggerInterface $logger) {}
    
    #[McpTool(name: 'debug_tool')]
    public function debugTool(string $data): array
    {
        $this->logger->info('正在处理调试工具', ['input' => $data]);
        
        // 对于标准输入输出传输，使用 STDERR 输出调试信息
        fwrite(STDERR, "调试：处理数据长度: " . strlen($data) . "\n");
        
        return ['processed' => true];
    }
}

🚀 生产环境部署

由于 $server->listen() 运行的是一个持久进程，您可以根据自己的基础设施需求采用任何合适的策略进行部署。该服务器可以部署在 VPS、云实例、容器或任何支持长时间运行进程的环境中。

以下是两种常见的部署方案供您参考：

方案一：使用 Supervisor + Nginx 的 VPS（推荐）

适用场景：大多数生产环境部署，性价比高，完全可控

# 1. 在 VPS 上安装您的应用
git clone https://github.com/yourorg/your-mcp-server.git /var/www/mcp-server
cd /var/www/mcp-server
composer install --no-dev --optimize-autoloader

# 2. 安装 Supervisor
sudo apt-get install supervisor

# 3. 创建 Supervisor 配置文件
sudo nano /etc/supervisor/conf.d/mcp-server.conf

Supervisor 配置文件：

[program:mcp-server]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/mcp-server/server.php --transport=http --host=127.0.0.1 --port=8080
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=1
redirect_stderr=true
stdout_logfile=/var/log/mcp-server.log
stdout_logfile_maxbytes=10MB
stdout_logfile_backups=3

Nginx 配置（带 SSL）：

# /etc/nginx/sites-available/mcp-server
server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name mcp.yourdomain.com;

    # SSL 配置
    ssl_certificate /etc/letsencrypt/live/mcp.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/mcp.yourdomain.com/privkey.pem;
    
    # 安全头设置
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;

    # MCP 服务器代理
    location / {
        proxy_http_version 1.1;
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        
        # 对 SSE 连接很重要
        proxy_buffering off;
        proxy_cache off;
        
        proxy_pass http://127.0.0.1:8080/;
    }
}

# 将 HTTP 重定向到 HTTPS
server {
    listen 80;
    listen [::]:80;
    server_name mcp.yourdomain.com;
    return 301 https://$server_name$request_uri;
}

启动服务：

# 启用并启动 Supervisor
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start mcp-server:*

# 启用并启动 Nginx
sudo systemctl enable nginx
sudo systemctl restart nginx

# 检查状态
sudo supervisorctl status

客户端配置：

{
  "mcpServers": {
    "my-server": {
      "url": "https://mcp.yourdomain.com/mcp"
    }
  }
}

方案二：Docker 部署

适用场景：容器化环境、Kubernetes、云平台

生产 Dockerfile：

FROM php:8.3-fpm-alpine

# 安装系统依赖
RUN apk --no-cache add \
    nginx \
    supervisor \
    && docker-php-ext-enable opcache

# 安装 PHP 扩展以支持 MCP
RUN docker-php-ext-install pdo_mysql pdo_sqlite opcache

# 创建应用目录
WORKDIR /var/www/mcp

# 复制应用代码
COPY . /var/www/mcp
COPY docker/nginx.conf /etc/nginx/nginx.conf
COPY docker/supervisord.conf /etc/supervisord.conf
COPY docker/php.ini /usr/local/etc/php/conf.d/production.ini

# 安装 Composer 依赖
RUN composer install --no-dev --optimize-autoloader --no-interaction

# 设置权限
RUN chown -R www-data:www-data /var/www/mcp

# 暴露端口
EXPOSE 80

# 启动 Supervisor
CMD ["/usr/bin/supervisord", "-c", "/etc/supervisord.conf"]

docker-compose.yml：

services:
  mcp-server:
    build: .
    ports:
      - "8080:80"
    environment:
      - MCP_ENV=production
      - MCP_LOG_LEVEL=info
    volumes:
      - ./storage:/var/www/mcp/storage
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost/health"]
      interval: 30s
      timeout: 10s
      retries: 3

  # 可选：如果需要数据库，可添加
  database:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: secure_password
      MYSQL_DATABASE: mcp_server
    volumes:
      - mysql_data:/var/lib/mysql
    restart: unless-stopped

volumes:
  mysql_data:

安全最佳实践

1. 防火墙配置：

# 只开放必要的端口
sudo ufw allow ssh
sudo ufw allow 80
sudo ufw allow 443
sudo ufw deny 8080  # MCP 端口不应对外公开
sudo ufw enable

2. SSL/TLS 设置：

# 安装 Certbot 以获取 Let's Encrypt 证书
sudo apt install certbot python3-certbot-nginx

# 生成 SSL 证书
sudo certbot --nginx -d mcp.yourdomain.com

📚 示例与使用场景

请查看 examples/ 目录中的完整示例：

可用示例

• 01-discovery-stdio-calculator/ - 带属性发现的基本标准输入计算器
• 02-discovery-http-userprofile/ - 带用户个人资料管理的HTTP服务器
• 03-manual-registration-stdio/ - 手动元素注册模式
• 04-combined-registration-http/ - 手动与发现元素的组合
• 05-stdio-env-variables/ - 环境变量处理
• 06-custom-dependencies-stdio/ - 带任务管理的依赖注入
• 07-complex-tool-schema-http/ - 高级模式验证示例
• 08-schema-showcase-streamable/ - 全面模式功能展示

运行示例

# 切换到某个示例目录
cd examples/01-discovery-stdio-calculator/

# 使服务器可执行
chmod +x server.php

# 运行服务器（或在您的MCP客户端中进行配置）
./server.php

🚧 从v2.x迁移

如果要从版本2.x迁移，请注意以下关键变化：

模式更新

• 使用php-mcp/schema包来处理DTO，不再使用内部类
• 内容类型已移至PhpMcp\Schema\Content\*命名空间
• 更新了方法签名，以提供更好的类型安全性

会话管理

• 新增多后端会话管理机制
• 使用->withSession()或->withSessionHandler()进行配置
• 会话现在可在重新连接时保持持久化（配合缓存后端）

传输变更

• 新增StreamableHttpServerTransport，支持断点续传
• 增强了错误处理和事件溯源功能
• 改进了批量请求处理能力

🧪 测试

# 安装开发依赖
composer install --dev

# 运行测试套件
composer test

# 带覆盖率运行测试（需安装Xdebug）
composer test:coverage

# 运行代码风格检查
composer lint

🤝 贡献

我们欢迎贡献！请参阅CONTRIBUTING.md了解相关指南。

📄 许可证

MIT许可证（MIT）。详情请参阅LICENSE。

🙏 致谢

• 基于模型上下文协议规范构建
• 由ReactPHP提供异步操作支持
• 采用PSR标准以实现最大程度的互操作性

PHP MCP Server SDK 快速上手指南

本指南帮助中国开发者快速使用 PHP MCP Server SDK 构建符合 Model Context Protocol (MCP) 标准的服务端，使 AI 助手（如 Claude、Cursor、ChatGPT）能够调用你的 PHP 应用功能。

环境准备

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

• PHP 版本: >= 8.1 (需开启 json, mbstring, pcre 扩展，通常默认开启)
• 包管理器: Composer
• 运行环境:
  • 若使用 stdio 传输：任意 CLI 环境即可。
  • 若使用 HTTP/SSE 传输：推荐事件驱动环境 (如 ReactPHP)。
• IDE/客户端: 支持 MCP 协议的客户端 (如 Cursor IDE, Claude Desktop 等)。

💡 Laravel 用户提示: 如果你在使用 Laravel 框架，建议直接使用 php-mcp/laravel 包，它提供了更好的框架集成和 Artisan 命令支持。

安装步骤

使用 Composer 安装核心库。国内开发者若遇到下载速度慢的问题，可配置阿里云镜像源加速。

1. (可选) 配置国内镜像源

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

2. 安装 SDK 在项目根目录执行：

composer require php-mcp/server

基本使用

以下示例展示如何创建一个基于 stdio 的最简 MCP 服务器，并通过属性注解自动注册工具。

第一步：定义 MCP 工具

创建文件 src/CalculatorElements.php，使用 #[McpTool] 属性标记需要暴露给 AI 的方法。

<?php

namespace App;

use PhpMcp\Server\Attributes\McpTool;
use PhpMcp\Server\Attributes\Schema;

class CalculatorElements
{
    /**
     * 两数相加
     * 
     * @param int $a 第一个数字
     * @param int $b 第二个数字  
     * @return int 求和结果
     */
    #[McpTool(name: 'add_numbers')]
    public function add(int $a, int $b): int
    {
        return $a + $b;
    }

    /**
     * 计算幂次方（带参数验证）
     */
    #[McpTool(name: 'calculate_power')]
    public function power(
        #[Schema(type: 'number', minimum: 0, maximum: 1000)]
        float $base,
        
        #[Schema(type: 'integer', minimum: 0, maximum: 10)]
        int $exponent
    ): float {
        return pow($base, $exponent);
    }
}

第二步：创建服务器入口脚本

创建文件 mcp-server.php，初始化服务器并扫描上述类。

#!/usr/bin/env php
<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use PhpMcp\Server\Server;
use PhpMcp\Server\Transports\StdioServerTransport;

try {
    // 1. 构建服务器配置
    $server = Server::make()
        ->withServerInfo('PHP Calculator Server', '1.0.0') 
        ->build();

    // 2. 自动发现带有注解的 MCP 元素
    $server->discover(
        basePath: __DIR__,
        scanDirs: ['src'] // 扫描 src 目录
    );

    // 3. 启动 stdio 监听
    $transport = new StdioServerTransport();
    $server->listen($transport);

} catch (\Throwable $e) {
    fwrite(STDERR, "[CRITICAL ERROR] " . $e->getMessage() . "\n");
    exit(1);
}

赋予执行权限：

chmod +x mcp-server.php

第三步：配置 MCP 客户端

在你的 AI 客户端配置文件中添加该服务器。以 Cursor IDE 为例，编辑 .cursor/mcp.json：

{
    "mcpServers": {
        "php-calculator": {
            "command": "php",
            "args": ["/absolute/path/to/your/mcp-server.php"]
        }
    }
}

⚠️ 注意：请将 /absolute/path/to/your/mcp-server.php 替换为你本地文件的绝对路径。

第四步：测试运行

重启你的 AI 客户端或重新加载 MCP 服务。现在你可以直接在对话框中让 AI 执行以下操作：

• "帮我计算 5 加 3" (调用 add_numbers)
• "计算 2 的 10 次方" (调用 calculate_power)

SDK 会自动处理参数验证、JSON Schema 生成以及与 AI 的通信协议。