Sphere MCP游戏服务器
用于Unicity游戏平台的MCP（模型上下文协议）服务器。通过Nostr为LLM提供支付门控日通行证的游戏访问权限。
特性
- 日间通行证系统：用户只需支付一次费用即可24小时访问所有游戏
- Nostr集成：通过Nostr协议发送的付款请求
- Unicity区块链：使用名称标签进行身份和支付路由
- 自动标识：服务器在首次运行时创建自己的区块链身份
- HTTP传输：支持传统SSE和现代可流式HTTP
可用游戏
| ID | 名称 | 描述 |
|---|---|---|
unicity-quake | Unicity Quake | 快节奏多人竞技场射击游戏 |
boxy-run | Boxy Run | 获得区块链奖励的无尽跑步者 |
unirun | Unirun | Unicity本地无尽跑者 |
MCP工具
| 工具 | 参数 | 说明 |
|---|---|---|
list_games | - | 列出所有可用游戏 |
check_access | unicity_id | 检查访问状态和日通行证有效性 |
get_game | unicity_id, game | 获取特定游戏的访问权限（必要时启动付款） |
confirm_payment | unicity_id, game （可选） | 等待付款确认 |
get_wallet_balance | password | 获取MCP钱包余额（管理员） |
所有需要用户身份的工具 unicity_id 作为一个参数，使API无状态并适用于多用户场景。
HTTP端点
服务器在HTTP（默认端口3001）上运行，具有两种传输协议：
传统SSE（MCP检查员，老客户）
| 端点 | 方法 | 描述 |
|---|---|---|
/sse | GET | 建立SSE流，返回POST端点 |
/messages?sessionId=xxx | POST | 发送JSON-RPC消息 |
流式HTTP（现代客户端）
| 端点 | 方法 | 描述 |
|---|---|---|
/mcp | POST | 发送JSON-RPC请求 |
/mcp | GET | SSE流用于响应 |
会话ID通过传递 mcp-session-id 头球
健康检查
| 端点 | 方法 | 描述 |
|---|---|---|
/health | GET | 返回 { status, sseSessions, httpSessions } |
快速开始
1.配置环境
cp .env.example .env编辑 .env 具有所需值：
# Required
MCP_NAMETAG=gaming-mcp
PAYMENT_COIN_ID=your_coin_id_here2.使用Docker Compose运行
docker compose up -d服务器将：
- 生成新的私钥（保存到
./data/identity.json) - 在Unicity区块链上创建一个名字标签
- 发布名称标签的Nost绑定
- 开始监听MCP连接
3.查看日志
docker compose logs -f测试MCP
选项1:MCP检查员（推荐）
MCP检查器提供了一个与服务器交互的web UI：
# Start the server
npm run build && npm start
# In another terminal, connect inspector to HTTP endpoint
npx @modelcontextprotocol/inspector --url http://localhost:3001/sse这将打开一个浏览器UI，您可以在其中交互式地调用工具。
选项2：卷曲（健康检查）
curl http://localhost:3001/health选项3:Claude桌面集成
添加到您的Claude桌面配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：
{
"mcpServers": {
"gaming": {
"url": "http://localhost:3001/sse"
}
}
}工作流示例
- 用户列出可用游戏：
Tool: list_games- 用户使用其Unicity ID请求游戏：
Tool: get_game
Args: { "unicity_id": "alice", "game": "unicity-quake" }- 如果没有日票，则要求付款。 用户在其Unicity钱包中收到付款请求。
- 用户确认付款：
Tool: confirm_payment
Args: { "unicity_id": "alice" }- 成功付款后，用户将获得游戏URL和24小时访问权限。
配置
| 变量 | 必填 | 默认 | 描述 |
|---|---|---|---|
MCP_NAMETAG | 是 | - | 此MCP服务器的名称标签 |
PAYMENT_COIN_ID | 是 | - | 用于支付的硬币ID |
MCP_PRIVATE_KEY_HEX | 否 | 自动生成 | 私钥（十六进制） |
NOSTR_RELAY_URL | 没有 | wss://nostr-relay.testnet.unicity.network | 诺斯特接力 |
AGGREGATOR_URL | 没有 | https://goggregator-test.unicity.network | Unicity聚合器 |
AGGREGATOR_API_KEY | 否 | （测试网密钥） | 聚合器API密钥 |
PAYMENT_AMOUNT | 没有 | 1000000000 | 付款金额 |
DAY_PASS_HOURS | 没有 | 24 | 日通持续时间 |
PAYMENT_TIMEOUT_SECONDS | 没有 | 120 | 付款超时 |
DATA_DIR | 没有 | ./data | 数据持久性目录 |
ADMIN_PASSWORD | 否 | 自动生成 | 钱包访问的管理员密码 |
HTTP_PORT | 没有 | 3001 | HTTP服务器端口 |
数据持久层
服务器将身份和名称标签数据存储在 DATA_DIR:
identity.json-私钥（请妥善保管！）nametag-{name}.json-铸造名牌代币
将此目录作为卷装载，以便在容器重新启动时保持不变。
发展
# Install dependencies
npm install
# Build
npm run build
# Run locally
npm start
# Watch mode
npm run dev建筑
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ LLM Client │────▶│ MCP Server │────▶│ Nostr Relay │
│ (Claude, etc.) │ │ (HTTP transport)│ │ │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ Unicity │ │ User Wallet │
│ Aggregator │ │ (Sphere app) │
└─────────────────┘ └─────────────────┘许可证
麻省理工学院