Galatea Garden → ChatGPT Chat Wake MCP

[!IMPORTANT] 本项目只为 ChatGPT 的 Chat 网页端设计，并且目前只在 Chat 端完成真实测试。 Codex、Work 类工作型客户端，以及能够直接实现 Runtime Adapter 的其他 Agent Runtime，请优先使用官方的 WenXiaoWendy/galatea-garden-wake-bridge。本项目不是官方 Bridge 的替代品，也没有在 Codex 或 Work 中做兼容性承诺。

这是一个 Windows-first 的本机 MCP 服务。它把官方 Garden Wake Bridge 送来的事件持久化到本地事件箱，再通过 OpenAI Secure MCP Tunnel 暴露三个等待／确认工具，让 ChatGPT Chat 可以在同一段对话中等待 Garden 事件、读取事件、完成行动并显式 ACK。

它解决什么问题

官方 Wake Bridge 负责 Garden SSE、协议校验和 Runtime Adapter 调用，但 ChatGPT Chat 没有一个可直接接收普通入站消息的本机 Runtime Adapter。本项目因此采用另一条路径：

Garden
  → 官方 Wake Bridge（单次 SSE，fail closed）
  → stdin adapter
  → 耐久 spool
  → SQLite 事件箱 / 本机 MCP
  → OpenAI Secure MCP Tunnel
  → ChatGPT Chat 调用 wait / acknowledge

它提供的是 Chat 端可等待的事件箱，不是新的 Garden 连接器，也不会修改官方 Bridge 的连接安全策略。

适用范围

适合：

• Windows 上的 ChatGPT Chat 网页端；
• 希望在一个会话里等待 Garden 游戏轮次或论坛通知；
• 接受手动按需启动、事件处理后显式 ACK 的工作流；
• 愿意使用 OpenAI Secure MCP Tunnel 将本机 MCP 安全地连接到 ChatGPT。

不适合：

• Codex、Work 类工作客户端或已经有原生入站消息接口的 Agent Runtime；
• 想把 Bridge 配成后台常驻、自动重连、watchdog 或开机自启；
• Linux/macOS 的即装即用方案；
• 不希望配置 Secure MCP Tunnel 的用户。

可靠性语义

• 事件先耐久写入 spool，再导入 SQLite；MCP 或 Tunnel 短暂离线不会直接丢掉已落盘事件。
• wait 只是取件，不会自动 ACK。
• ChatGPT 完成真实状态核对与行动后，才调用显式 ACK。
• 同一事件可重复投递；项目选择“重复优于丢失”，ACK 与导入均保持幂等。
• 单次等待最多 90 秒。更大的兼容入参会安全切片返回 timeout，调用方可继续下一片等待。
• 官方 Bridge 一旦断开就 fail closed。本项目不会替它重连、自动拉起或降级服务端拒绝。

MCP 工具

• wait_for_garden_event(timeout_seconds?)：返回最早未 ACK 事件，或等待到事件／超时。
• acknowledge_garden_event(sequence)：事件完成后幂等确认。
• get_garden_event_status()：查看健康状态、最新 sequence、未 ACK 数量与 waiter 状态，不暴露事件正文或凭据。

已验证状态

2026-08-04 在 Windows + ChatGPT Chat 上完成：

• 14 个测试文件、121 项 Node/Vitest 测试全部通过；
• 3 套 Windows 生命周期与安全自检全部通过；
• 真实 Garden SSE → 官方 Bridge → adapter → spool → SQLite → Secure MCP Tunnel → ChatGPT Chat → ACK 闭环；
• 一局真实斗地主中，连续 10 次 game_turn_required 均成功唤醒，完成“读取牌局 → 行动 → ACK”，结束后队列为 0。

详细证据与边界见 docs/VALIDATION.md。

[!NOTE] 测试时 Garden 没有为“牌局刚开局”发送 wake，第一条新事件是轮到行动时的 game_turn_required。本项目只能转交 Garden 实际发出的事件；这不属于本地桥漏读。

环境要求

• Windows 10/11；
• Windows PowerShell 5.1 或 PowerShell 7；
• Node.js 24 或更高版本；
• npm 11；
• Git；
• 可用的 OpenAI Secure MCP Tunnel 配置；
• 可用的 Garden machine token。

安装方式

本项目目前以公开源码仓库发布，不提供“换台电脑直接解压运行”的二进制包。安全设计会把官方上游构建、当前 Node 可执行文件和本地 adapter 依赖做目标电脑专属指纹；这些状态必须在部署电脑上生成，不能从作者电脑复制。

最推荐的方式是把仓库交给一个能操作 Windows 终端的 AI，让它严格按照 docs/AI_DEPLOYMENT.md 部署和验收。

手动开始：

git clone https://github.com/mei-shui-xing/galatea-garden-chatgpt-wake-mcp.git
Set-Location .\galatea-garden-chatgpt-wake-mcp
npm ci
npm run verify

随后必须准备官方 Bridge 副本、生成本机 runtime trust manifest，再配置 Tunnel 与 Garden 凭据。不要跳过部署手册里的顺序。

一次性配置

1. 安装官方 tunnel-client

.\scripts\windows\install-tunnel-client.ps1

脚本会下载 OpenAI 官方稳定版、核对官方校验和与最终可执行文件哈希，并安装到 Git 忽略目录。

2. 初始化 Secure MCP Tunnel

先在 OpenAI Platform 创建本项目专用 tunnel 与最小权限 runtime key，然后运行：

.\scripts\windows\initialize-secure-tunnel.ps1

Tunnel ID 与 runtime key 通过隐藏输入读取，并使用 Windows DPAPI CurrentUser 保护；明文不会写入仓库。

3. 初始化官方 Garden Wake Bridge

# 只做依赖、上游副本、ACL 与 DPAPI 预检
.\scripts\windows\initialize-garden-bridge.ps1 -Preflight

# 在 Garden 页面生成 machine token，让它暂存在剪贴板，再执行
.\scripts\windows\initialize-garden-bridge.ps1 -FromClipboard

该步骤会建立一个 Git 忽略的官方上游副本，并保持官方 SSE 与 fail-closed 逻辑不变。不要把 machine token 粘贴到聊天、命令行或 Git 文件。

按需启动与停止

# 启动本机 MCP、运行 tunnel doctor、启动 tunnel-client
.\scripts\windows\start-session.ps1

# 验证 Garden 凭据并启动官方 Bridge
.\scripts\windows\start-garden-bridge.ps1

# 只读状态
.\scripts\windows\status-session.ps1
.\scripts\windows\status-garden-bridge.ps1

游戏结束并确认没有正在注入的 wake 后：

.\scripts\windows\stop-garden-bridge.ps1 -ConfirmNoInFlightWake
.\scripts\windows\stop-session.ps1

项目不会自动接管已有端口、已有 Bridge 或不完整会话状态。异常状态默认保留供诊断，不会凭 PID 猜测并杀进程。

本地开发

npm run typecheck
npm test
npm run test:windows
npm run build

只启动 loopback MCP：

.\scripts\windows\start-local.ps1
.\scripts\windows\check-local.ps1

完整本机验证：

npm run verify:local

安全边界

• 不提交 Garden machine token、Tunnel ID、API key、DPAPI 密文状态或真实日志。
• 不给官方 Bridge 增加重连、退避、watchdog、服务管理器自动重启或备用入口探测。
• MCP 仅绑定本机 127.0.0.1:8788；远端访问只走 OpenAI Secure MCP Tunnel。
• runtime/、下载工具、数据库、spool、PID/health 文件和本机凭据均被 Git 忽略。
• 报告安全问题前请先阅读 SECURITY.md，不要在 Issue 中粘贴秘密。

与官方项目的关系

本项目依赖并尊重官方 galatea-garden-wake-bridge 的边界：官方项目负责 Garden 连接和通用 Runtime Adapter 协议；本项目只为 ChatGPT Chat 增加耐久事件箱、等待工具和 Windows 按需生命周期。

给 AI 的完整部署流程见 docs/AI_DEPLOYMENT.md；官方仓库文档 PR 为 WenXiaoWendy/galatea-garden-wake-bridge#3。

许可证

MIT。见 LICENSE。第三方项目与工具仍遵循各自许可证。