内容
# PhpMCP
**纯 PHP 编写的高质量 MCP 服务器合集**
PhpMCP 是一套完整的、生产就绪的 [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 服务器集，全部使用 PHP 8.5 原生编写，**零外部依赖**。
每台服务器实现了 MCP 2025-11-25 协议规范，通过 STDIO 传输层提供工具（Tools）、资源（Resources）和提示模板（Prompts），供 Claude、ChatGPT、Cursor 等 AI 代理在运行时动态发现和调用。
---
## ✨ 核心特性
| 指标 | 数值 |
|------|------|
| **服务器数量** | 10 |
| **工具（可调用函数）** | 98 |
| **资源（可读数据）** | 20 |
| **提示模板** | 14 |
| **零依赖** | ✓ — 纯 PHP，无需 Composer |
| **协议版本** | MCP 2025-11-25 (JSON-RPC 2.0) |
| **传输方式** | STDIO |
| **PHP 版本** | 8.5+ |
| **开源协议** | MIT |
### 服务器列表
| # | 服务器 | 工具数 | 资源数 | 提示数 | 说明 |
|---|--------|--------|--------|--------|------|
| 1 | **Weather** | 4 | 2 | 2 | 城市天气查询、预报、对比（15个城市） |
| 2 | **Calculator** | 14 | 2 | 1 | 14种数学运算：加减乘除、幂、根号、三角、对数、阶乘、GCD、LCM |
| 3 | **FileSystem** | 11 | 1 | 1 | 文件读/写/复制/移动/删除，目录遍历，搜索 |
| 4 | **DateTime** | 10 | 2 | 2 | 时间获取、时区转换、日期差、格式化、周数 |
| 5 | **Text Processing** | 15 | 1 | 1 | 大小写转换、正则、编解码、拆分/合并、修剪、换行 |
| 6 | **Database** | 8 | 3 | 1 | SQLite 演示数据库，SELECT 查询，员工统计，项目汇总 |
| 7 | **WebTool** | 8 | 2 | 1 | URL 抓取、网站状态、元数据提取、URL 验证、二维码 |
| 8 | **SystemInfo** | 10 | 2 | 1 | OS、PHP 配置、内存、磁盘、环境变量、进程信息 |
| 9 | **Code Assistant** | 10 | 2 | 2 | 语法验证、代码行统计、函数提取、文档块生成、UUID |
| 10 | **Translation** | 8 | 3 | 2 | 多语种翻译、短语查询、音译、语言检测（20+语种） |
---
## 🚀 快速开始
### 环境要求
- PHP 8.5 或更高版本
- 扩展：`json`、`mbstring`、`pcre`（通常默认已启用）
- **Database** 服务器需要：`sqlite3`、`pdo_sqlite`
- **WebTool** 服务器需要：`curl`、`dom`、`xml`
### 启动服务器
通过 STDIO 管道发送 JSON-RPC 消息：
```bash
# Windows
php servers\weather.php
# Linux / macOS
php servers/weather.php
```
或使用启动脚本：
```bash
run_server.bat weather
```
### 从 MCP 客户端连接
在客户端配置中添加服务器（例如 Claude Desktop、Cursor 等）：
```json
{
"mcpServers": {
"php-calculator": {
"command": "php",
"args": ["C:/path/to/servers/calculator.php"]
},
"php-weather": {
"command": "php",
"args": ["C:/path/to/servers/weather.php"]
}
}
}
```
### 本地测试
```bash
# 协议级测试（初始化、工具、资源、提示）
php test_server.php servers/calculator.php all
# 工具功能测试
php test_tools.php servers/calculator.php
```
---
## 📦 架构设计
### 框架层
所有服务器继承自共享基类 `framework/McpServer.php`，该基类提供：
- **JSON-RPC 2.0** 消息解析与响应格式化
- **MCP 生命周期**：`initialize` → `notifications/initialized` → 操作阶段
- **方法路由**：`tools/list`、`tools/call`、`resources/list`、`resources/read`、`prompts/list`、`prompts/get`、`ping`
- **错误处理**：标准 JSON-RPC 错误码及描述信息
- **通知机制**：服务器主动推送事件
### 协议流程
```
客户端 服务器
│ │
├─ initialize ─────────────────>│
│<─ 协议版本、能力声明 ──────────│
│ │
├─ notifications/initialized ───>│
│ │
├─ tools/list ─────────────────>│
│<─ 工具定义列表 ───────────────│
│ │
├─ tools/call {名称, 参数} ────>│
│<─ 执行结果 {content} ─────────│
│ │
├─ resources/list ─────────────>│
│<─ 资源列表 ──────────────────│
│ │
├─ prompts/list ───────────────>│
│<─ 提示模板列表 ──────────────│
```
### 新增一台服务器
```php
<?php
require_once __DIR__ . '/../framework/McpServer.php';
use Mcp\McpServer;
class MyServer extends McpServer
{
protected function getServerInfo(): array
{
return ['name' => 'My Server', 'version' => '1.0.0'];
}
protected function getTools(): array
{
return [
[
'name' => 'hello',
'description' => 'Say hello',
'inputSchema' => [
'type' => 'object',
'properties' => [
'name' => ['type' => 'string', 'description' => 'Your name'],
],
'required' => ['name'],
],
],
];
}
protected function callTool(string $name, array $arguments): array
{
return [
'content' => [['type' => 'text', 'text' => "Hello, {$arguments['name']}!"]],
];
}
}
$server = new MyServer();
$server->run();
```
---
## 🧪 测试
```bash
# 测试所有协议方面
php test_server.php servers/calculator.php all
# 测试特定方面
php test_server.php servers/weather.php tools
# 使用真实参数测试工具功能
php test_tools.php servers/database.php
```
---
## 🔧 配置说明
无需配置文件，所有服务器开箱即用。
### Windows：启用所需扩展
编辑 `php.ini`，取消以下扩展的注释：
```ini
extension=curl
extension=fileinfo
extension=mbstring
extension=openssl
extension=pdo_sqlite
extension=sqlite3
extension=dom
extension=xml
```
---
## 📄 开源协议
本项目采用 **MIT 许可证** — 详见 [LICENSE](LICENSE) 文件。
---
## 🌐 相关资源
- [Model Context Protocol 官方网站](https://modelcontextprotocol.io)
- [MCP 协议规范](https://spec.modelcontextprotocol.io)
- [官方 MCP PHP SDK](https://github.com/modelcontextprotocol/php-sdk)
- [JSON-RPC 2.0 规范](https://www.jsonrpc.org/specification)
<br>
<h1 align="center">PhpMCP</h1>
<p align="center"><strong>纯 PHP 编写的高质量 MCP 服务器合集</strong></p>
<p align="center">
<strong>PhpMCP</strong> 是一套完整的、生产就绪的 <a href="https://modelcontextprotocol.io">Model Context Protocol (MCP)</a> 服务器集，
全部使用 PHP 8.5 原生编写，<strong>零外部依赖</strong>。
</p>
<p align="center">
每台服务器实现了 MCP 2025-11-25 协议规范，通过 STDIO 传输层提供工具（Tools）、资源（Resources）和提示模板（Prompts），
供 Claude、ChatGPT、Cursor 等 AI 代理在运行时动态发现和调用。
</p>
