README

这是一个Webman框架与官方MCP PHP SDK深度集成的插件，并在SDK基础上进行了扩展，可快速创建MCP服务器。

此插件依赖于官方的MCP PHP SDK，以下文档仅展示插件与sdk的差异。

特性

一键启动，安装后即可启动，同时支持配置复杂的功能。
一个项目支持多个MCP服务器，并按服务器名称隔离配置。
与Webman框架深度集成，HTTP支持路由模式和自定义进程模式。
自动注册MCP服务到主流IDE（VSCode、Cursor、通义灵码等）。
支持 STDIO、Streamable HTTP 高性能传输。
支持协程与非协程，从而提高了在sse场景下高性能传输。
内置常用20+个MCP开发工具，提升开发效率。

安装

# 稳定版本
composer require luoyue/webman-mcp
# 开发预览版本
composer require luoyue/webman-mcp:^dev-master mcp/sdk:^dev-main

环境要求

PHP >= 8.1
webman^2.1
webman/cache^2.1

可选依赖

webman/redis（可选）
Swoole/Swow/Fiber协程（可选，提升SSE性能）
monolog/monolog（可选，用于记录服务器日志）
phpunit/phpunit（可选，用于无关传输的测试）

注解

注解名称	描述
McpTool	标记一个PHP方法为MCP工具，使其可以被AI调用执行特定功能
McpPrompt	标记一个PHP方法为MCP提示生成器，用于生成对话提示消息
McpResource	标记一个PHP方法为MCP资源处理器，用于处理特定资源URI的请求
McpResourceTemplate	标记一个PHP方法为MCP资源模板，用于定义资源URI模板
Schema	定义方法或参数的JSON Schema，用于参数验证和类型检查
CompletionProvider	为参数提供自动完成功能，指定可能的值或提供者类

启动方式

# 启动 MCP STDIO 服务器, mcp为服务器名称，配置文件中定义
php webman mcp:server mcp

# 启动 MCP HTTP 服务器(分为两种，一种是嵌入到路由中，另一种是自定义进程)
php webman start

快速开始

1. 使用命令行工具创建模板代码（也可直接使用插件自带的配置）

# 创建文件后可根据模板代码实现逻辑
php webman mcp:make template

实际上并不太需要此命令创建代码，因为使用方法已足够简单，只需在方法中声明注解即可。

2. 配置客户端连接配置

打开app.php，修改auto_register_client配置为您常用的客户端。

<?php

use Luoyue\WebmanMcp\Enum\McpClientRegisterEnum;

return [
    'enable' => true,
    // 自动注册MCP服务到ide中
    'auto_register_client' => McpClientRegisterEnum::CURSOR_IDE,
];

什么？没有您的客户端？我们非常欢迎您提交相关PR。

3. 测试您的服务器

# 使用 MCP Inspector 测试（需要node与npx）
php webman mcp:inspector mcp

内置工具

命令行工具

工具	参数	描述
mcp:server	service	启动MCP服务器
mcp:list		MCP服务列表
mcp:make	type	生成MCP配置或模板代码
mcp:inspector	service	启动MCP Inspector调试工具

示例：

## 查看定义的mcp服务列表以及配置信息
php webman mcp:list

MCP开发工具

类别	名称	描述
tool	sequential_thinking	让ai进入深度思考
tool	system_info	获取webman框架信息，php版本信息，系统信息，是否使用协程
tool	get_config	获取config配置信息
tool	get_env	获取env环境变量信息
tool	list_process	获取进程列表
tool	list_routes	获取路由列表
tool	match_routes	匹配url对应的路由信息
tool	list_dependence	获取项目依赖列表
tool	list_extensions	获取当前环境已加载的php扩展
tool	get_extension_funcs	获取扩展已加载的函数
tool	list_events	获取事件列表
tool	eval_code	执行php代码
tool	build_phar	将项目代码打包为phar文件
tool	build_bin	将项目代码打包为linux二进制可执行文件
tool	database_connections	获取数据库连接配置信息列表
tool	database_execute_sql	执行原始sql脚本
tool	redis_connections	获取数据库redis配置信息列表
tool	redis_execute_raw	执行原始Redis命令
tool	redis_execute_lua	执行Redis Lua脚本
tool	redis_execute_lua_sha	使用sha1执行Redis Lua脚本

日志记录

发送客户端日志

请参考官方文档

记录服务器错误日志

根据2025-11-25规范，STDIO传输允许将任何日志记录到stderr中且客户端可以捕获stderr并视为非致命错误，stdout则必须用于传输json-rpc消息。

日志模式	STDIO传输	Streamable HTTP传输
file	✅	✅
stdout	❌	✅
stderr	✅	✅

从以上表格中看出：

在开发环境中使用stderr很方便的将日在控制台中且不影响运行。
在生产环境中使用file记录日志可以将日志保存在磁盘中，方便后续维护。

配置monolog（必须是插件目录下的log.php）：

<?php

return [
    //文件日志记录
    'mcp_file_log' => [
        'handlers' => [
            [
                'class' => Monolog\Handler\RotatingFileHandler::class,
                'constructor' => [
                    runtime_path() . '/logs/mcp.log',
                    7, //$maxFiles
                    Monolog\Logger::NOTICE,
                ],
                'formatter' => [
                    'class' => Monolog\Formatter\LineFormatter::class,
                    'constructor' => [null, 'Y-m-d H:i:s', true],
                ],
            ]
        ]
    ],
    // stderr日志记录
    'mcp_error_stderr' => [
        'handlers' => [
            [
                'class' => Monolog\Handler\StreamHandler::class,
                'constructor' => [
                    STDERR, // stderr流
                    Monolog\Logger::NOTICE, // 设置NOTICE可减少不必要的调试信息
                ],
                'formatter' => [
                    'class' => Monolog\Formatter\LineFormatter::class,
                    'constructor' => [null, 'Y-m-d H:i:s', true],
                ],
            ]
        ]
    ]
];

然后我们可以在mcp.php中配置以下逻辑：

return [
    'mcp' => [
        'logger' => config('app.debug', true) ? 'mcp_error_stderr' : 'mcp_file_log'
  ]
]

与webman的兼容问题

McpTool注解如何将Controller结合使用

由于webman控制器和mcp消息处理机制差异，无法完美兼容，需要稍加改动即可适配。具体代码如下：

<?php

use Mcp\Server\RequestContext;
use Luoyue\WebmanMcp\McpHelper;
use Workerman\Protocols\Http\Response;

class McpController
{

    /**
     * tool示例代码
     *
     * @param RequestContext|null $context MCP请求上下文，设置为可选适配controller
     * @return array 返回包含会话ID的状态信息
     */
    #[McpTool(name: 'example_tool')]
    public function exampleTool(?RequestContext $context): Response|array
    {
        $result = [
            'status' => 'ok',
            'params' => request()->all(),
        ];
        // controller将自动忽略此行代码
        $context?->getClientLogger()->info('example_tool', $result);
        return McpHelper::is_mcp_server_request() ? $result : response($result);
    }
}

协程环境与非协程环境的限制

此插件已将SDK中SSE轮询阻塞函数usleep替换为workerman自带的非阻塞方法Timer::sleep()，结果如下：

协程环境下：阻塞部分变为非阻塞，原有业务代码不受影响。
非协程环境下：相关代码依然为阻塞状态，严重影响业务代码，阻塞周期为0.1秒为单位，可使用自定义进程与webman进程分离，从而达到互不干扰。

STDIO传输和phpunit单元测试的限制

STDIO传输与phpunit单元测试中具有相同的缺点：

在linux/macos系统中此功能可能不受影响，在windows系统中，由于平台限制，无法将其设置为非阻塞。
根据上面的问题，在webman中无法使用依赖workerman环境中的函数：定时器、定时任务、协程、http-client等。

参考文档

学习资料：

MCP 元素 - 创建工具、资源和提示
示例 - 全面的示例演练

外部资源：

许可证

本项目采用 MIT 许可证 - 详情请见 LICENSE 文件。

luoyue / webman-mcp

Maintainers

Details