PUAX MCP Server 近期重大更新：全新 Streamable-HTTP 架构与通用客户端支持

概述

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. 简化的架构

// 新架构
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 支持三种模式：

使用示例

// 自动检测模式
 = 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. 空对象序列化

// 修复前: {"params": []} - 解析错误
// 修复后: {"params": {}} - 正确解析

2. Session ID 管理

• 自动从响应头提取 mcp-session-id
• 自动在后续请求中携带

3. SSE 响应解析

// 自动解析 data: {...} 格式
event: message
data: {"result": {"tools": [...]}}

四、测试验证

测试场景

我们对新版本进行了全面测试：

✅ 健康检查通过
✅ 自动检测协议类型: SSE
✅ 初始化成功 (sessionId 从 header 提取)
✅ 获取工具列表 (9 个工具)
✅ 调用 search_skills 工具
✅ 调用 list_skills 工具 (分类筛选)

兼容性测试

五、如何升级

服务端升级

# 拉取最新代码
git pull origin main

# 重新编译
npm run build

# 启动服务
npm start

客户端配置

{
  "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 拥有百变角色！