PHP MCP（模型上下文协议）
](https://php.net)  
一个简单且可扩展的PHP实现的模型上下文协议（MCP），用于构建基于人工智能的应用程序。此包提供了一个完整的MCP服务器和客户端实现，并支持工具、资源和提示的使用。
📋 目录
🚀 特性
- 🎯 简洁明了的API - 易于使用和理解
- 🔧 可扩展架构 - 设计时考虑了可扩展性
- 📡 多种传输方式 - 支持stdio和自定义传输方式
- 🛡️ 类型安全 - 全面支持PHP 8.1+的类型安全，采用严格类型
- 🧪 经过充分测试 - 全面的测试套件，功能覆盖100%
- 📚 文档齐全 - 清晰的示例和全面的文档
- 🔌 符合MCP标准 - 完整模型上下文协议规范支持
- ⚡ 高性能 - 为生产使用进行了优化
- 🏷️ 注释支持 - PHP 8 中的属性用于编写简洁、自文档化的代码
📦 安装
composer require mayur-saptal/php-mcp🏃♂️ 快速入门
什么是MCP？
模型上下文协议（MCP）是一种标准，用于将人工智能助手连接到外部数据源和工具。它使人工智能客户端能够：
- 执行工具 在您的服务器上调用函数（计算、API调用等）
- 访问资源 - 读取文件、数据库或任何数据源
- 生成提示 - 为特定任务创建上下文感知的提示
创建一个简单服务器
getParams();
return ['result' => 'Hello from ' . ($params['name'] ?? 'PHP MCP')];
}
public function handleNotification(Notification $notification): void
{
// Handle notifications if needed
}
public function getMethod(): string
{
return 'my-method';
}
}
// Create and start server
$transport = new StdioTransport();
$server = new Server($transport);
$server->registerHandlers([
new InitializeHandler(['my-method' => []]),
new InitializedHandler(),
new MyHandler()
]);
$server->run();创建一个客户端
connect();
$client->initialize(['my-method' => []]);
$client->initialized();
$result = $client->request('my-method', ['name' => 'World']);
echo json_encode($result); // {"result": "Hello from World"}
$client->disconnect();建筑学
核心组件
- 协议请求、响应、通知和错误的消息类别
- 交通通信层（stdio、HTTP、WebSocket 等）
- 服务器处理传入的消息并将其路由到相应的处理程序
- 客户发送请求并处理响应
- 处理程序/处理器特定方法的业务逻辑
消息类型
Request- 方法调用期望得到响应Response- 成功响应请求ErrorResponse- 对请求的错误响应Notification- 调用方法，不期待响应
MCP（可能指某种特定系统或平台的缩写，具体含义需根据上下文确定）功能：工具、资源和提示
工具
工具允许AI客户端在您的服务器上执行函数。它们非常适合用于计算、API调用、文件操作等。
registerTool('calculator', [
'description' => 'Perform mathematical calculations',
'inputSchema' => [
'type' => 'object',
'properties' => [
'expression' => [
'type' => 'string',
'description' => 'Mathematical expression to evaluate'
]
],
'required' => ['expression']
]
], function (array $args) {
$expression = $args['expression'];
// Safe evaluation logic here
return "Result: " . eval("return {$expression};");
});
// Register a weather tool
$toolsHandler->registerTool('weather', [
'description' => 'Get weather information',
'inputSchema' => [
'type' => 'object',
'properties' => [
'city' => ['type' => 'string', 'description' => 'City name']
],
'required' => ['city']
]
], function (array $args) {
$city = $args['city'];
// Call weather API here
return "Weather in {$city}: 22°C, Sunny";
});
$server->registerHandler($toolsHandler);资源
资源提供了访问文件、数据或任何AI客户端可读内容的途径。非常适合用于配置文件、日志、文档等。
registerResource('file://config.json', [
'name' => 'Server Configuration',
'description' => 'Current server configuration',
'mimeType' => 'application/json'
], function (array $params) {
$config = [
'server' => ['name' => 'My Server', 'version' => '1.0.0'],
'features' => ['tools', 'resources', 'prompts']
];
return json_encode($config, JSON_PRETTY_PRINT);
});
// Register a log file resource
$resourcesHandler->registerResource('file://logs/app.log', [
'name' => 'Application Logs',
'description' => 'Application log file',
'mimeType' => 'text/plain'
], function (array $params) {
return file_get_contents('/path/to/your/app.log');
});
$server->registerHandler($resourcesHandler);提示
提示词帮助AI客户端为特定任务（如代码审查、文档编写或调试）生成上下文感知的提示。
registerPrompt('code_review', [
'description' => 'Get assistance with code review',
'arguments' => [
[
'name' => 'code',
'description' => 'The code to review',
'required' => true
],
[
'name' => 'language',
'description' => 'Programming language',
'required' => false
]
]
], function (array $args) {
$code = $args['code'];
$language = $args['language'] ?? 'PHP';
return [
[
'role' => 'user',
'content' => [
'type' => 'text',
'text' => "Please review this {$language} code:\n\n```{$language}\n{$code}\n```\n\nFocus on:\n1. Code quality\n2. Potential bugs\n3. Best practices"
]
]
];
});
$server->registerHandler($promptsHandler);注释支持
PHP MCP 支持 PHP 8 的属性（注解），允许您直接在代码中定义功能。这使得开发过程更快捷且更直观。
快速标注示例
'object',
'properties' => [
'expression' => ['type' => 'string', 'description' => 'Math expression']
],
'required' => ['expression']
]
)]
public function calculate(array $args): string
{
return "Result: " . eval("return {$args['expression']};");
}
#[Resource(
uri: 'file://config.json',
name: 'Server Configuration',
mimeType: 'application/json'
)]
public function getConfig(array $params): string
{
return json_encode(['server' => 'running'], JSON_PRETTY_PRINT);
}
#[Prompt(
name: 'code_review',
description: 'Get code review assistance',
arguments: [
['name' => 'code', 'description' => 'Code to review', 'required' => true]
]
)]
public function generateCodeReviewPrompt(array $args): array
{
return [[
'role' => 'user',
'content' => ['type' => 'text', 'text' => "Review this code: {$args['code']}"]
]];
}
}
// Auto-register all annotations
$annotationReader = new AnnotationReader();
$annotationReader->registerClass(
new MyService(),
$toolsHandler,
$resourcesHandler,
$promptsHandler
);注释的好处
- 🎯 自我文档化 - 能力在实现位置即被定义
- ⚡ 自动注册 - 无需手动注册处理器
- 🔧 类型安全 - 完整的集成开发环境（IDE）支持和类型检查
- 📚 更整洁的代码 - 更少的样板代码和配置
如需完整的注释文档，请参阅 ANNOTATIONS.md 翻译为中文是：“注释.md” 或 “标注文件.md”（具体翻译可能根据上下文有所调整，但基本意思是表示这是一个包含注释或标注内容的Markdown文件）。
高级用法
定制运输
logger->info('Handling database request');
$params = $request->getParams();
$query = $params['query'] ?? '';
$stmt = $this->database->prepare($query);
$stmt->execute();
return $stmt->fetchAll(PDO::FETCH_ASSOC);
}
public function handleNotification(Notification $notification): void
{
// Handle notifications
}
public function getMethod(): string
{
return 'database.query';
}
}具备所有功能的完整服务器
[],
'resources' => [],
'prompts' => []
]);
// Set up tools
$toolsHandler = new ToolsHandler();
$toolsHandler->registerTool('my_tool', [...], function($args) { ... });
// Set up resources
$resourcesHandler = new ResourcesHandler();
$resourcesHandler->registerResource('file://config.json', [...], function($params) { ... });
// Set up prompts
$promptsHandler = new PromptsHandler();
$promptsHandler->registerPrompt('my_prompt', [...], function($args) { ... });
// Register all handlers
$server->registerHandlers([
$initHandler,
new InitializedHandler(),
$toolsHandler,
$resourcesHandler,
$promptsHandler
]);
$server->run();示例
检查一下 examples/ 完整示例目录：
simple-server.php- 基本服务器实现simple-client.php- 基本客户端实现advanced-server.php- 功能齐全的服务器，配备工具、资源和提示advanced-client.php- 客户展示所有MCP（多协议控制器/管理控制面板等，具体含义根据上下文确定）功能annotation-example.php- 使用PHP 8注解的服务器annotation-client.php- 客户端测试基于注解的服务器
运行示例
- 启动高级服务器：
php examples/advanced-server.php- 在另一个终端中，运行客户端：
php examples/advanced-client.php这些高级示例展示了：
- 工具计算器、天气查询、文件信息
- 资源配置文件、日志、文档
- 提示代码审查、文档生成、调试辅助
注释示例展示了：
- 基于注解的工具使用
#[Tool]属性 - 基于注解的资源使用
#[Resource]属性 - 基于注释的提示使用
#[Prompt]属性 - 自动注册自动发现和注册能力
测试
composer test贡献
- 为仓库创建分支（或：克隆仓库）
- 创建一个特性分支
- 进行你的更改
- 添加测试
- 提交拉取请求
许可证
MIT 许可证 - 详情请参见 LICENSE 文件。
要求
- PHP 8.1 或更高版本
- JSON 扩展
- cURL 扩展（用于 HTTP 传输）
路线图
- \[ \] HTTP/WebSocket 传输实现
- \[ \] 中间件支持
- \[ \] 支持异步/等待（Async/await）
- \[ \] 更多内置处理程序
- \[ \] 性能优化