PHP MCP 服务器

英文版

这是一个基于PHP的MCP（模型控制协议）服务器框架，支持通过注解优雅地定义MCP服务。

项目概述

本项目提供了一个完整的MCP服务器实现，具有以下特性：

• 基于注解的MCP服务定义
• 支持三种处理器类型：工具、提示和资源
• 支持两种传输方式：标准输入输出和服务器发送事件（SSE）
• 支持Swow和Swoole两种环境
• 完整的日志系统
• Docker支持

系统需求

• PHP >= 8.1
• Composer
• Swow扩展 > 1.5 或 Swoole > 5.1
• Docker（可选）

快速开始

安装

# 1. 克隆项目
git clone https://github.com/he426100/php-mcp-server
cd php-mcp-server

# 2. 安装依赖
composer install

# 3. 可选，安装 Swow 扩展（如果没有）
./vendor/bin/swow-builder --install

关于Swow扩展的详细安装说明，请参阅Swow官方文档

运行示例服务器

php bin/console mcp:test-server

常用命令参数

参数	描述	默认值	选项
--transport	传输类型	stdio	stdio, sse
--port	监听SSE的端口	8000

注解使用指南

此框架提供了三个核心注解用于定义MCP服务：

1. 工具注解

用于定义实用类处理器：

use Mcp\Annotation\Tool;

class MyService {
    #[Tool(
        name: 'calculate-sum',
        description: '计算两个数的和',
        parameters: [
            'num1' => [
                'type' => 'number',
                'description' => '第一个数字',
                'required' => true
            ],
            'num2' => [
                'type' => 'number',
                'description' => '第二个数字',
                'required' => true
            ]
        ]
    )]
    public function sum(int $num1, int $num2): int 
    {
        return $num1 + $num2;
    }
}

2. 提示注解

用于定义提示模板处理器：

use Mcp\Annotation\Prompt;

class MyService {
    #[Prompt(
        name: 'greeting',
        description: '生成问候语',
        arguments: [
            'name' => [
                'description' => '要问候的人名',
                'required' => true
            ]
        ]
    )]
    public function greeting(string $name): string 
    {
        return "Hello, {$name}!";
    }
}

3. 资源注解

用于定义资源处理器：

use Mcp\Annotation\Resource;

class MyService {
    #[Resource(
        uri: 'example://greeting',
        name: 'Greeting Text',
        description: '问候语资源',
        mimeType: 'text/plain'
    )]
    public function getGreeting(): string 
    {
        return "Hello from MCP server!";
    }
}

创建自定义服务

1. 创建服务类：

namespace Your\Namespace;

use Mcp\Annotation\Tool;
use Mcp\Annotation\Prompt;
use Mcp\Annotation\Resource;

class CustomService 
{
    #[Tool(name: 'custom-tool', description: '自定义工具')]
    public function customTool(): string 
    {
        return "Custom tool result";
    }
}

2. 创建命令类：

namespace Your\Namespace\Command;

use He426100\McpServer\Command\AbstractMcpServerCommand;
use Your\Namespace\CustomService;

class CustomServerCommand extends AbstractMcpServerCommand 
{
    protected string $serverName = 'custom-server';
    protected string $serviceClass = CustomService::class;

    protected function configure(): void 
    {
        parent::configure();
        $this->setName('custom:server')
            ->setDescription('运行自定义 MCP 服务器');
    }
}

注解参数描述

工具注解参数

参数	类型	描述	是否必需
Name	string	工具名称	是
Description	string	工具描述	是
Parameters	array	参数定义	否

提示注解参数

参数	类型	描述	是否必需
Name	string	提示模板名称	是
Description	string	提示模板描述	是
Arguments	array	参数定义	否

资源注解参数

参数	类型	描述	是否必需
URI	string	资源URI	是
Name	string	资源名称	是
Description	string	资源描述	是
MimeType	string	MIME类型	否

注解函数返回类型描述

工具注解函数支持的返回类型

返回类型	描述	转换结果
TextContent/ImageContent/EmbeddedSource	直接返回内容对象	保持不变
TextContent/ImageContent/EmbeddedSource 数组	内容对象数组	保持不变
ResourceContents	资源内容对象	转换为EmbeddedResource
字符串或标量类型转换	如字符串、整数、浮点数、布尔值	转换为TextContent
Null	空值	转换为空字符串的TextContent
数组或对象	复杂数据结构	转换为JSON格式的TextContent

提示注解函数支持的返回类型

返回类型	描述	转换结果
PromptMessage	消息对象	保持不变
PromptMessage 数组	消息对象数组	保持不变
内容对象	如TextContent/ImageContent等	转换为用户角色的PromptMessage
字符串或标量类型转换	如字符串、整数、浮点数、布尔值	转换为带有TextContent的用户消息
Null	空值	转换为空内容的用户消息
数组或对象	复杂数据结构	转换为JSON格式的用户消息

资源注解函数支持的返回类型

返回类型	描述	转换结果
TextResourceContents/BlobResourceContents	资源内容对象	保持不变
ResourceContents 数组	资源内容对象数组	保持不变
字符串或可转换为字符串的对象	文本内容	根据MIME类型转换为相应的资源内容
Null	空值	转换为空的TextResourceContents
数组或对象	复杂数据结构	转换为JSON格式的资源内容

注意：

• 对于大于2MB的文件，内容将自动截断
• 文本类型（text/*）的MIME类型将使用TextResourceContents
• 其他MIME类型将使用BlobResourceContents

日志配置

服务器日志默认保存在runtime/server_log.txt中，可以通过继承AbstractMcpServerCommand进行修改：

protected string $logFilePath = '/custom/path/to/log.txt';

Docker支持

构建并运行容器：

docker build -t php-mcp-server .
docker run --name=php-mcp-server -p 8000:8000 -itd php-mcp-server mcp:test-server --transport sse

SSE地址：http://127.0.0.1:8000/sse

使用CPX

您可以通过CPX（Composer Package Executor）直接运行此项目，无需事先安装：

前提条件

1. 全局安装CPX：

composer global require cpx/cpx

2. 确保Composer的全局bin目录在您的PATH中

使用方法

# 运行测试服务器
cpx he426100/php-mcp-server mcp:test-server

# 使用SSE传输模式
cpx he426100/php-mcp-server mcp:test-server --transport=sse

# 查看可用命令
cpx he426100/php-mcp-server list

许可证

MIT许可证

贡献

欢迎提交Issue和Pull Requests。

作者

he426100
logiscape