grok-MCP AGENTS.md

GrokMCP 维护指南

修改 Worker 前先阅读本文件。GitHub 仓库 nympheon/grok-MCP 的 main 分支是 唯一源码事实来源；Cloudflare Workers Builds 是现有 grokmcp Worker 的常规部署 入口。本项目不是本地 stdio 软件包，也不是多用户服务。

不可破坏的运行契约

• Worker/service 名：grokmcp；
• 公开路由：GET /healthz；
• MCP 路由：/t/<MCP_URL_TOKEN>/mcp；
• 中文管理路由：/admin/t/<ADMIN_URL_TOKEN>；
• Durable Object 类名：GrokState；
• Durable Object 稳定对象名：single-user；
• SQLite 初始迁移标签：v1；
• MCP 表面：只能有 x_search、web_search；
• MCP wire revision：仅 2026-07-28，每个请求返回一个 JSON 响应；
• 默认模型：Worker 变量 GROK_X_SEARCH_MODEL，当前为 grok-4.6；
• xAI 输出文本：只接受当前 REST 结构 output[].content[].output_text.text。

不要恢复旧 initialize/session 传输、SSE、顶层 xAI output_text 兼容分支、原始 帖子列表或账号管理 MCP 工具。成功结果同时提供 structuredContent 和内容相同的 JSON 文本块是当前有意设计，不是旧协议兼容层。

源码职责

• src/worker.ts：在读取请求体前完成 URL token 鉴权，负责公开/管理/MCP 路由、 Host/Origin 检查、表单解析和请求体限制。绝不能记录请求 URL 或请求体。
• src/admin.ts：生成简体中文、无脚本、不可缓存的控制面。所有运行时值必须经过 HTML 转义；错误只按 ToolErrorCode 映射，不得显示原始上游错误。
• src/mcp.ts：定义两个搜索工具、输入 schema、outputSchema 和 handler。不得加入 登录、状态、回调、退出或其他账号工具。
• src/grokState.ts：管理 SQLite、加密 OAuth 尝试/token、刷新串行化、退出顺序和 搜索调用。迁移和加密数据格式属于持久契约。
• src/cryptoVault.ts：使用 AES-256-GCM、每条记录独立 96 位 IV 和用途绑定 AAD。 既有用途字符串不能随意修改。
• src/oauth.ts：实现当前公共 Grok CLI/Hermes 兼容 native client 的 PKCE 与 token 交换。client ID 是公开兼容依赖，不是 secret，但上游可能随时调整。
• src/xaiClient.ts：验证 xAI search 契约、限制响应并解析当前 wire 结构。上游 参数变化时，必须同步更新 schema、运行时验证、fixture、测试和 README。
• src/urlAuth.ts：解析固定形状 token 路径并比较 SHA-256 摘要，不能改回提前退出的 明文字符串比较。
• scripts/secrets.mjs：只服务首次部署或主动轮换，原子创建/迁移权限为 0600 的 本地文件。除明确 URL 命令外不得打印任何值。

Secret 与状态

生产环境必须有三个独立 Worker secret：

• MCP_URL_TOKEN：保护 ChatGPT MCP 连接；
• ADMIN_URL_TOKEN：保护登录、状态、URL 恢复和退出；
• TOKEN_ENCRYPTION_KEY：加密 OAuth 行，绝不能打印、提交或写入日志。

.secrets.local 只用于首次部署或明确轮换，必须被 Git 忽略。常规升级不得重新生成 并上传三个值。npm run deploy 有意不提供 secrets 文件，Cloudflare 会校验所需名称 并保留远端值；npm run deploy:with-secrets 只允许首次部署或经确认的主动轮换。

轮换某个 URL token 只应使对应 URL 失效。轮换 TOKEN_ENCRYPTION_KEY 会让现有 OAuth 密文不可读，随后必须重新登录。除非包含经过验证的数据迁移，不得重命名 GrokState、删除 v1 SQLite 迁移、改变 single-user 对象名或既有 AAD 用途字符串。