codex-choice-mcp

一个小型、非官方的本地 MCP stdio 服务。它通过 MCP form elicitation 请求结构化选择； 在已测试的 Codex Desktop 环境中，客户端会将请求显示为可点击表单，并返回稳定的选项 ID。

状态：早期实验版本。它没有修改 Codex，不会替代内置的 request_user_input，也不能决定 Agent 何时调用该工具。

它解决什么问题

当 Agent 只需要用户在少量互斥方案中做决定时，纯文本回复会增加输入成本，也可能产生 “第一个”“按你说的”等解析歧义。本工具提供一个 request_choice MCP 工具，把选择 标准化为稳定 ID，并明确区分接受、拒绝和取消。

它只提供交互能力，不包含工作流策略、权限规则、任务日志或自动调用逻辑。

能做什么

• 每次请求包含 1–3 个问题。
• 每个问题包含 2–3 个业务选项，并自动附加“其它”。
• 第一项作为默认推荐项。
• 返回 selectedId、selectedLabel 和可选的 otherText。
• decline 和 cancel 返回空答案，不会被当成授权。

上述数量限制是本项目的设计选择，不是 MCP 或 Codex 的协议限制。

不能做什么

• 不保证模型一定调用该工具。
• 不保证所有 MCP 客户端都显示相同界面；UI 由客户端决定。
• 不替代审批、权限、审计或工作流引擎。
• 不提供持久化、远程托管、身份认证或操作日志。
• 不适合调查问卷、复杂表单或敏感信息采集。

安装

一句话配置：请你把 ycy726619/codex-choice-mcp 工具接入到当前 Agent 工具中，并配置任何阻塞式流程/提问优先使用 choice 工具。

要求 Node.js 18 或更高版本，以及 pnpm。

pnpm install
pnpm test

把 examples/config.toml 中的路径替换为本仓库 src/server.mjs 的绝对路径，再将配置加入 Codex 的 config.toml。以 choice 作为 MCP server 名称时，工具名为：

mcp__choice__request_choice

修改 MCP 配置后，完全退出并重新打开 Codex 客户端。

调用示例

{
  "message": "请选择下一步。",
  "questions": [
    {
      "id": "next_step",
      "header": "下一步",
      "question": "接下来怎么处理？",
      "options": [
        {
          "id": "continue",
          "label": "继续（推荐）",
          "description": "按当前方案继续。"
        },
        {
          "id": "pause",
          "label": "暂停",
          "description": "停止执行并等待后续指示。"
        }
      ]
    }
  ]
}

接受后的结构化结果示例：

{
  "action": "accept",
  "answers": [
    {
      "questionId": "next_step",
      "selectedId": "continue",
      "selectedLabel": "继续（推荐）",
      "otherText": null
    }
  ]
}

优点

• 使用稳定 ID，减少自然语言解析歧义。
• 拒绝和取消不会被误判为批准。
• MCP server 源码没有主动联网逻辑，核心代码较小，便于审查。
• 通过标准 MCP 工具接口接入，不需要修改 Codex 客户端。
• 自动化测试会启动真实 stdio server，验证工具发现、elicitation 请求和结构化返回。

已知限制

• 依赖客户端支持 MCP form elicitation。
• MCP 只规定请求与响应，不规定客户端必须使用弹窗或任何特定 UI。
• 第一项既是默认项也是推荐项，可能产生锚定效应或误选。
• MCP 表单使用扁平 Schema，客户端不一定能根据“其它”选项动态显示或隐藏说明框。
• 工具的输入和输出仍由所使用的客户端及模型处理；“本地 stdio”不等于所有数据只在本机。
• 已在 Windows Codex Desktop 和 OpenCode 中完成实际调用验证。理论上可兼容支持 MCP form elicitation 的其它 Agent 客户端，但尚未逐一验证，不保证全部可用。

安全边界

不要通过 form elicitation 请求密码、API Key、访问令牌、支付凭据或其它授权秘密。 用户关闭、取消或拒绝表单时，调用方必须停止把该交互当作授权。

验证记录

环境	状态	验证日期
Codex Desktop / Windows / Default 模式	人工验证通过；客户端版本号未记录	2026-07-18
OpenCode / 版本及操作系统未记录	用户人工验证通过	2026-07-18
其它支持 MCP form elicitation 的 Agent 客户端	尚未逐一验证	—

项目定位

这是社区实验项目，与 OpenAI 没有隶属或官方背书关系。“Codex”仅用于说明已测试的客户端。

MCP elicitation 规范： https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation

Codex MCP 配置说明： https://learn.chatgpt.com/docs/extend/mcp

License

MIT