# Galatea Garden → ChatGPT Chat Wake MCP

[![CI](https://github.com/mei-shui-xing/galatea-garden-chatgpt-wake-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/mei-shui-xing/galatea-garden-chatgpt-wake-mcp/actions/workflows/ci.yml)

> [!IMPORTANT]
> **本项目只为 ChatGPT 的 Chat 网页端设计，并且目前只在 Chat 端完成真实测试。**
> Codex、Work 类工作型客户端，以及能够直接实现 Runtime Adapter 的其他 Agent Runtime，请优先使用官方的 [`WenXiaoWendy/galatea-garden-wake-bridge`](https://github.com/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。本项目因此采用另一条路径：

```text
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`](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`](docs/AI_DEPLOYMENT.md) 部署和验收。

手动开始：

```powershell
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

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

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

### 2. 初始化 Secure MCP Tunnel

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

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

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

### 3. 初始化官方 Garden Wake Bridge

```powershell
# 只做依赖、上游副本、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 文件。

## 按需启动与停止

```powershell
# 启动本机 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 后：

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

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

## 本地开发

```powershell
npm run typecheck
npm test
npm run test:windows
npm run build
```

只启动 loopback MCP：

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

完整本机验证：

```powershell
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`](SECURITY.md)，不要在 Issue 中粘贴秘密。

## 与官方项目的关系

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

给 AI 的完整部署流程见 [`docs/AI_DEPLOYMENT.md`](docs/AI_DEPLOYMENT.md)；官方仓库文档 PR 为 [`WenXiaoWendy/galatea-garden-wake-bridge#3`](https://github.com/WenXiaoWendy/galatea-garden-wake-bridge/pull/3)。

## 许可证

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