# 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](https://github.com/ycy726619/codex-choice-mcp)
> 工具接入到当前 Agent 工具中，并配置任何阻塞式流程/提问优先使用 choice 工具。

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

```powershell
pnpm install
pnpm test
```

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

```text
mcp__choice__request_choice
```

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

## 调用示例

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

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

```json
{
  "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