hyperf/mcp-server-incubator
3.3
If you are the rightful owner of mcp-server-incubator and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
The Hyperf MCP Server is a high-performance Model Context Protocol server built on the Hyperf framework, offering comprehensive tools, prompts, and resource management capabilities.
Tools
add_numbers
Calculates the sum of two numbers.
multiply
Calculates the product of two numbers.
text_processor
Processes text input with various transformations.
Hyperf MCP Server
一个基于 Hyperf 框架的 Model Context Protocol (MCP) 服务器实现，提供了完整的工具、提示和资源管理功能，支持 Redis 会话管理和基于注解的配置。基于 dtyq/php-mcp 核心库构建。
特性
- 🚀 高性能: 基于 Hyperf 协程框架，支持高并发访问
- 🔧 注解驱动: 使用注解快速定义 MCP 工具、提示和资源
- 📦 Redis 会话管理: 内置 Redis 会话管理器，支持分布式部署
- 🎯 类型安全: 完整的类型提示和 JSON Schema 验证
- 🔒 安全性: 支持会话过期、元数据存储和访问控制
- 🏗️ 多服务器架构: 支持多个 MCP 服务器实例，便于功能分组和管理
- 🎨 灵活配置: 支持服务器分组管理和动态启用/禁用功能
安装
系统要求
- PHP 8.1 或更高版本
- Hyperf 3.0 或更高版本
- Redis 扩展
- Redis 服务器
使用 Composer 安装
composer require hyperf/mcp-server-incubator
发布配置文件
如果你需要自定义配置，可以发布配置文件：
php bin/hyperf.php vendor:publish hyperf/mcp-server-incubator
快速开始
1. 配置服务
在你的 Hyperf 应用中发布配置：
<?php
// config/autoload/dependencies.php
return [
\Dtyq\PhpMcp\Server\Transports\Http\SessionManagerInterface::class => \Hyperf\McpServer\RedisSessionManager::class,
\Dtyq\PhpMcp\Shared\Auth\AuthenticatorInterface::class => \Dtyq\PhpMcp\Shared\Auth\NullAuthenticator::class,
\Dtyq\PhpMcp\Shared\Kernel\Packer\PackerInterface::class => \Dtyq\PhpMcp\Shared\Kernel\Packer\OpisClosurePacker::class,
];
2. 定义工具
使用 #[Tool] 注解定义 MCP 工具：
<?php
use Hyperf\McpServer\Annotation\Tool;
class CalculatorService
{
#[Tool(
name: 'add_numbers',
description: '计算两个数字的和',
server: 'math',
version: '1.0.0'
)]
public function addNumbers(int $a, int $b): int
{
return $a + $b;
}
#[Tool(
name: 'multiply',
description: '计算两个数字的乘积',
server: 'math',
version: '1.0.0'
)]
public function multiply(float $x, float $y): float
{
return $x * $y;
}
}
3. 定义提示
使用 #[Prompt] 注解定义智能提示：
<?php
use Hyperf\McpServer\Annotation\Prompt;
class PromptService
{
#[Prompt(
name: 'code_review',
description: '代码审查提示模板',
server: 'development',
version: '1.0.0'
)]
public function codeReviewPrompt(string $language, string $code): string
{
return "请审查以下 {$language} 代码：\n\n```{$language}\n{$code}\n```\n\n请关注：\n- 代码质量\n- 潜在问题\n- 改进建议";
}
}
4. 定义资源
使用 #[Resource] 注解定义可访问的资源：
<?php
use Hyperf\McpServer\Annotation\Resource;
class DocumentService
{
#[Resource(
name: 'api_docs',
uri: 'mcp://docs/api',
description: 'API 文档资源',
mimeType: 'application/json',
server: 'docs',
version: '1.0.0'
)]
public function getApiDocs(): array
{
return [
'title' => 'API Documentation',
'version' => '1.0.0',
'endpoints' => [
// API 端点定义
]
];
}
}
5. 启动服务器
创建控制器处理 MCP 请求：
<?php
use Hyperf\HttpServer\Annotation\Controller;
use Hyperf\HttpServer\Annotation\RequestMapping;
use Hyperf\McpServer\Server;
#[Controller]
class McpController
{
public function __construct(
private Server $server
) {}
#[RequestMapping(path: '/mcp', methods: ['GET', 'POST'])]
public function handle()
{
return $this->server->handle();
}
#[RequestMapping(path: '/mcp/math', methods: ['GET', 'POST'])]
public function handleMath()
{
// 只处理 math 服务器的工具
return $this->server->handle('math', '1.0.0');
}
}
完整示例
这里是一个完整的服务示例，展示如何使用所有注解功能：
<?php
use Hyperf\McpServer\Annotation\Tool;
use Hyperf\McpServer\Annotation\Prompt;
use Hyperf\McpServer\Annotation\Resource;
class ComprehensiveService
{
// 数学工具 - 使用 math 服务器
#[Tool(
name: 'math_add',
description: 'Add two numbers',
server: 'math',
version: '1.0.0'
)]
public function addNumbers(int $a, int $b): int
{
return $a + $b;
}
#[Tool(
name: 'math_multiply',
description: 'Multiply two numbers',
server: 'math',
version: '1.0.0'
)]
public function multiplyNumbers(float $x, float $y): float
{
return $x * $y;
}
// 文本处理工具 - 使用 text 服务器
#[Tool(
name: 'text_processor',
description: 'Process text input with various transformations',
server: 'text',
version: '1.0.0'
)]
public function processText(string $input, string $operation = 'upper'): string
{
return match($operation) {
'upper' => strtoupper($input),
'lower' => strtolower($input),
'reverse' => strrev($input),
default => $input
};
}
// 代码审查提示 - 使用 development 服务器
#[Prompt(
name: 'code_review',
description: 'Generate code review prompt',
server: 'development',
version: '1.0.0'
)]
public function codeReviewPrompt(string $language, string $code): string
{
return "请审查以下 {$language} 代码：\n\n```{$language}\n{$code}\n```\n\n请关注：\n- 代码质量\n- 潜在问题\n- 改进建议";
}
// API 文档资源 - 使用 docs 服务器
#[Resource(
name: 'api_docs',
uri: 'mcp://docs/api',
description: 'API documentation resource',
mimeType: 'application/json',
server: 'docs',
version: '1.0.0'
)]
public function getApiDocs(): array
{
return [
'title' => 'API Documentation',
'version' => '1.0.0',
'endpoints' => [
[
'path' => '/api/tools',
'method' => 'GET',
'description' => 'List all available tools'
],
[
'path' => '/api/prompts',
'method' => 'GET',
'description' => 'List all available prompts'
]
]
];
}
// 可以禁用的工具示例
#[Tool(
name: 'experimental_feature',
description: 'An experimental feature that can be disabled',
enabled: false,
version: '1.0.0'
)]
public function experimentalFeature(): string
{
return 'This feature is currently disabled';
}
}
高级配置
Redis 配置
<?php
// config/autoload/redis.php
return [
'default' => [
'host' => env('REDIS_HOST', 'localhost'),
'auth' => env('REDIS_AUTH', null),
'port' => (int) env('REDIS_PORT', 6379),
'db' => (int) env('REDIS_DB', 0),
'pool' => [
'min_connections' => 1,
'max_connections' => 10,
'connect_timeout' => 10.0,
'wait_timeout' => 3.0,
'heartbeat' => -1,
],
],
];
会话 TTL 和生命周期管理
RedisSessionManager 提供了完整的会话生命周期管理：
<?php
// 创建自定义 TTL 的会话管理器
// config/autoload/dependencies.php
return [
\Hyperf\McpServer\RedisSessionManager::class => function ($container) {
return new \Hyperf\McpServer\RedisSessionManager(
$container->get(\Dtyq\PhpMcp\Shared\Kernel\Packer\PackerInterface::class),
$container->get(\Hyperf\Redis\RedisFactory::class),
3600 // 1小时会话过期时间
);
},
];
会话监控和管理
<?php
// 获取会话详细信息
$sessionDetails = $sessionManager->getSessionDetails($sessionId);
// 返回: ['created_at' => 1234567890, 'last_activity' => 1234567890, 'ttl' => 3600]
// 获取活动会话总数
$activeCount = $sessionManager->getSessionCount();
// 手动清理过期会话
$cleanedCount = $sessionManager->cleanupExpiredSessions();
注解参考
#[Tool]
| 参数 | 类型 | 描述 | 默认值 |
|---|---|---|---|
name | string | 工具名称 | 方法名 |
description | string | 工具描述 | 空字符串 |
inputSchema | array | 输入参数 Schema | 自动生成 |
server | string | 服务器名称 | 空字符串 |
version | string | 服务器版本 | 空字符串 |
enabled | bool | 是否启用 | true |
#[Prompt]
| 参数 | 类型 | 描述 | 默认值 |
|---|---|---|---|
name | string | 提示名称 | 方法名 |
description | string | 提示描述 | 空字符串 |
arguments | array | 提示参数 | 自动生成 |
server | string | 服务器名称 | 空字符串 |
version | string | 服务器版本 | 空字符串 |
enabled | bool | 是否启用 | true |
#[Resource]
| 参数 | 类型 | 描述 | 默认值 |
|---|---|---|---|
name | string | 资源名称 | 方法名 |
uri | string | 资源 URI | 自动生成 |
description | string | 资源描述 | 空字符串 |
mimeType | string|null | MIME 类型 | null |
size | int|null | 资源大小 | null |
server | string | 服务器名称 | 空字符串 |
version | string | 服务器版本 | 空字符串 |
enabled | bool | 是否启用 | true |
isTemplate | bool | 是否为模板 | false |
uriTemplate | array | URI 模板参数 | 空数组 |
API 文档
McpServerManager
MCP 服务器管理器，支持多服务器架构和版本管理。
方法
handle(string $server = '', string $version = '1.0.0', ?RequestInterface $request = null): ResponseInterface- 处理指定服务器和版本的 MCP 请求get(string $server = '', string $version = '1.0.0'): McpServer- 获取指定的 MCP 服务器实例createMcpServer(string $name = 'McpServer', string $version = '1.0.0'): McpServer- 创建新的 MCP 服务器实例
RedisSessionManager
基于 Redis 的会话管理器实现。
方法
createSession(): string- 创建新会话isValidSession(string $sessionId): bool- 检查会话是否有效updateSessionActivity(string $sessionId): bool- 更新会话活动时间terminateSession(string $sessionId): bool- 终止会话getActiveSessions(): array- 获取所有活动会话 IDcleanupExpiredSessions(): int- 清理过期会话setSessionMetadata(string $sessionId, array $metadata): bool- 设置会话元数据getSessionMetadata(string $sessionId): ?array- 获取会话元数据getSessionDetails(string $sessionId): ?array- 获取会话详细信息（包含创建时间、最后活动时间、TTL）getSessionCount(): int- 获取活动会话总数
项目结构
src/
├── ConfigProvider.php # Hyperf 配置提供者
├── McpServerManager.php # MCP 服务器管理器
├── RedisSessionManager.php # Redis 会话管理器
├── Server.php # MCP 服务器类（向后兼容）
├── Annotation/ # 注解定义
│ ├── McpAnnotation.php # 基础注解类
│ ├── Prompt.php # 提示注解
│ ├── Resource.php # 资源注解
│ └── Tool.php # 工具注解
└── Collector/ # 注解收集器
└── McpCollector.php # MCP 注解收集器
核心组件
ConfigProvider
自动配置 Hyperf 依赖注入容器，注册默认的会话管理器、认证器和序列化器。
McpServerManager
MCP 服务器管理器，支持多服务器架构，提供：
- 多服务器实例管理
- 基于服务器名称的路由
- 工具、提示和资源的自动注册
- 统一的请求处理接口
RedisSessionManager
基于 Redis 的会话管理实现，提供：
- 会话创建和验证
- 自动过期管理
- 元数据存储
- 活动会话跟踪
注解系统
#[Tool]: 定义可调用的工具方法#[Prompt]: 定义智能提示模板#[Resource]: 定义可访问的资源
McpCollector
自动收集和注册所有带有 MCP 注解的方法，支持服务器分组管理和动态启用/禁用。
性能和最佳实践
会话管理优化
- 会话 TTL 设置: 根据实际业务需求设置合适的会话过期时间，避免过长或过短
- Redis 连接池: 使用连接池来优化 Redis 连接性能
- 批量操作: 对于大量会话操作，考虑使用 Redis 管道或事务
注解使用建议
- 合理分组: 使用
server参数对相关功能进行分组，便于管理和调试 - 描述信息: 为每个工具、提示和资源提供清晰的描述信息
- 类型提示: 充分利用 PHP 类型提示，框架会自动生成输入 Schema
- 禁用功能: 使用
enabled: false临时禁用某些功能，而不是删除代码
多服务器架构
Hyperf MCP Server 支持多服务器架构，允许你将不同类型的功能分组到不同的服务器中：
<?php
// 数学计算服务器
#[Tool(name: 'add', server: 'math', version: '1.0.0')]
public function add(int $a, int $b): int { return $a + $b; }
// 文本处理服务器
#[Tool(name: 'uppercase', server: 'text', version: '1.0.0')]
public function uppercase(string $text): string { return strtoupper($text); }
// 默认服务器
#[Tool(name: 'general_tool', version: '1.0.0')]
public function generalTool(): string { return 'Hello'; }
不同的路由可以处理不同的服务器：
<?php
// 处理数学相关的请求
#[RequestMapping(path: '/mcp/math')]
public function handleMath() {
return $this->mcpServerManager->handle('math', '1.0.0');
}
// 处理文本相关的请求
#[RequestMapping(path: '/mcp/text')]
public function handleText() {
return $this->mcpServerManager->handle('text', '1.0.0');
}
错误处理
<?php
use Dtyq\PhpMcp\Shared\Exceptions\ToolError;
#[Tool(name: 'safe_divide', description: 'Safely divide two numbers')]
public function safeDivide(float $a, float $b): float
{
if ($b === 0.0) {
throw new ToolError('Division by zero is not allowed');
}
return $a / $b;
}
向后兼容性
项目保留了 Server 类以提供向后兼容性。如果你使用的是旧版本的代码，可以继续使用：
<?php
use Hyperf\McpServer\Server;
#[Controller]
class McpController
{
public function __construct(private Server $server) {}
#[RequestMapping(path: '/mcp')]
public function handle()
{
return $this->server->handler(); // 使用默认服务器
}
}
但建议升级到新的 McpServerManager 以享受多服务器架构的优势。
开发和测试
运行测试套件：
composer test
运行代码分析：
composer analyse
修复代码风格：
composer cs-fix
贡献
欢迎贡献代码！请遵循以下步骤：
- Fork 这个项目
- 创建你的特性分支 (
git checkout -b feature/AmazingFeature) - 提交你的修改 (
git commit -m 'Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 打开一个 Pull Request
许可证
该项目基于 MIT 许可证开源。查看 文件了解更多详情。
相关链接
- Hyperf 框架
- Model Context Protocol
- dtyq/php-mcp - 核心 MCP 实现库
- Redis
更新日志
v1.0.0 (开发中)
- 初始版本发布
- 支持基于注解的工具、提示和资源定义（
#[Tool]、#[Prompt]、#[Resource]） - Redis 会话管理，支持 UUID v4 格式的会话 ID
- 多服务器架构支持，允许功能分组到不同的服务器实例
- 新增版本管理支持：所有注解现在都支持
version参数，实现更精细的版本控制 - 完整的类型安全支持
- 会话监控和管理功能
- 支持会话元数据存储
- McpServerManager 统一管理多个 MCP 服务器实例
- 支持服务器级别的版本管理，允许同一服务器的不同版本共存