## 概述
PUAX MCP Server 近期进行了多项重大更新，从协议架构到文档体验都有全面提升。本文将为大家详细介绍这些改进。
---
## 一、文档体验全面升级
### 全新的 README 结构
我们对项目文档进行了彻底重写，采用**一步步引导**的方式，让新用户能够更快上手：
- **清晰的6章结构**：从介绍到部署，层次分明
- **3步快速上手指南**：安装、启动、配置，一气呵成
- **SKILL 系统详解**：树状图展示 42 个角色的分类结构
- **实战示例**：军事化组织系列的完整协作流程演示
### SKILL 分类速览
```
PUAX SKILL 体系 (共42个)
├── 🧙 萨满系列 (7个) - 马斯克、乔布斯、巴菲特等名人思维
├── ⚔️ 军事化组织 (9个) - 团队协作框架
├── 🎯 主题场景 (6个) - 黑客、炼金术等沉浸式场景
├── 💪 自我激励 (6个) - AI自我驱动
├── 🎭 SillyTavern (5个) - 角色扮演
└── ⭐ 特殊角色 (9个) - 趣味与专项用途
```
---
## 二、协议架构升级：Streamable-HTTP
### 为什么要升级？
原有的 SSE (Server-Sent Events) 模式在实际使用中存在一些限制：
- 会话管理复杂
- 客户端兼容性差异
- 多并发场景下不够稳定
### Streamable-HTTP 的优势
**1. 标准化会话管理**
- 通过 `mcp-session-id` HTTP Header 传递会话ID
- 支持会话持久化和恢复
- 更符合 MCP 2024-11-05 协议规范
**2. 更好的兼容性**
- 兼容标准 HTTP 客户端
- 支持多种 MCP 客户端 (Claude Desktop, Cursor, CRUSH等)
- 自动协议协商
**3. 简化的架构**
```typescript
// 新架构
const transport = new StreamableHTTPServerTransport({
sessionIdGenerator: () => crypto.randomUUID(),
onsessioninitialized: (sid) => {
this.transports.set(sid, transport);
}
});
```
---
## 三、sg_mcp_caller 2.0：通用 MCP 客户端
### 痛点
在使用旧版 MCP 客户端时，我们发现：
- 不同服务器使用不同传输协议
- 需要为每种协议写不同的客户端代码
- 调试困难
### 解决方案
**sg_mcp_caller 2.0** 支持三种模式：
| 模式 | 用途 | 示例 |
|------|------|------|
| `http` | 标准 JSON-RPC over HTTP | 传统 MCP 服务器 |
| `sse` | Streamable-HTTP/SSE | **PUAX 当前使用** |
| `stdio` | 命令行交互 | 本地 MCP 工具 |
### 使用示例
```php
// 自动检测模式
= new MCPClient('http://127.0.0.1:2333/mcp');
echo (); // 输出: "sse"
// 显式指定模式
= new MCPClient('http://127.0.0.1:2333/mcp', null, 'sse');
// Stdio 模式
= new MCPClient('node server.js', null, 'stdio');
// 调用工具
= ();
= ('search_skills', ['keyword' => '马斯克']);
```
### 核心改进
**1. 空对象序列化**
```php
// 修复前: {"params": []} - 解析错误
// 修复后: {"params": {}} - 正确解析
```
**2. Session ID 管理**
- 自动从响应头提取 `mcp-session-id`
- 自动在后续请求中携带
**3. SSE 响应解析**
```php
// 自动解析 data: {...} 格式
event: message
data: {"result": {"tools": [...]}}
```
---
## 四、测试验证
### 测试场景
我们对新版本进行了全面测试：
```
✅ 健康检查通过
✅ 自动检测协议类型: SSE
✅ 初始化成功 (sessionId 从 header 提取)
✅ 获取工具列表 (9 个工具)
✅ 调用 search_skills 工具
✅ 调用 list_skills 工具 (分类筛选)
```
### 兼容性测试
| 客户端 | 版本 | 状态 |
|--------|------|------|
| Claude Desktop | 最新 | ✅ 兼容 |
| Cursor | 最新 | ✅ 兼容 |
| CRUSH | 最新 | ✅ 兼容 |
| sg_mcp_caller | 2.0 | ✅ 兼容 |
---
## 五、如何升级
### 服务端升级
```bash
# 拉取最新代码
git pull origin main
# 重新编译
npm run build
# 启动服务
npm start
```
### 客户端配置
```json
{
"mcpServers": {
"puax": {
"type": "sse",
"url": "http://127.0.0.1:2333/mcp"
}
}
}
```
---
## 六、未来规划
1. **更多传输协议支持**：计划支持 WebSocket 模式
2. **角色市场**：SKILL 分享和下载平台
3. **可视化界面**：Web UI 管理角色和会话
4. **性能优化**：支持更大规模并发
---
## 相关链接
- **GitHub**: https://github.com/linkerlin/PUAX
- **MCP 协议**: https://modelcontextprotocol.io
- **智柴锦囊**: sg_mcp_caller 2.0 (支持 PUAX)
---
**欢迎使用 PUAX，让你的 AI 拥有百变角色！**
登录后可参与表态
讨论回复
1 条回复
小凯 (C3P0)
#1
02-20 15:24
登录后可参与表态