Skip to main content
Glama
ycy726619

codex-choice-mcp

by ycy726619
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript

codex-choice-mcp

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

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

它解决什么问题

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

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

Related MCP server: achmadya-dev/mcp-core

能做什么

  • 每次请求包含 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

Available Tools

1 tool
request_choice请求用户选择A
Read-only

请求支持 MCP form elicitation 的客户端收集 1-3 个结构化选择，并返回稳定选项 ID。适用于少量、互斥、阻塞式决策；第一项视为默认推荐。不得收集密码、访问令牌或支付凭据。

ParametersJSON Schema
NameRequiredDescriptionDefault
messageNo请选择下一步操作。
questionsYes

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, so safety is known. The description adds that the tool is blocking, first option is default, and forbids sensitive data. No contradiction with annotations. Sufficient transparency for a read-only user input tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three concise sentences in Chinese, front-loaded with purpose. Every sentence adds value: purpose, usage guidelines, and security constraints. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple tool with 2 parameters, no output schema, and comprehensive annotations, the description covers behavior (blocking, default, security) and return value (stable option IDs). It is complete enough for effective use, though a brief note on the response format would be helpful.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so description should compensate. It mentions collecting structured choices (the 'questions' parameter) and default recommendation, but does not describe the 'message' parameter nor explain the individual fields in the questions array beyond what the schema provides. Adds some behavioral context but lacks parameter-specific details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: to request the client to collect structured choices and return stable option IDs. It specifies the number of choices (1-3), suitability for blocking decisions, and security constraints. This is specific and unambiguous, earning a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear usage guidelines: suitable for small, mutually exclusive, blocking decisions; first item default; prohibits sensitive data. It does not explicitly say when not to use, but the context is strong. With no sibling tools, this is effective.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev0.1.0
    • First observedrequest_choice
Deploy Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.2/5.0

Scored across 1 tool

Disambiguation5/5

Only one tool exists, so there is no possibility of confusion between tools. The agent can clearly identify its purpose.

Naming Consistency5/5

With a single tool, there is no inconsistency to evaluate. The name 'request_choice' follows a clear verb_noun pattern.

Tool Count3/5

The tool count of 1 is borderline thin for a server. While it may be acceptable for a very focused utility, it lacks breadth for more complex choice management scenarios.

Completeness4/5

The tool covers the core action of requesting a choice and returning stable option IDs. However, missing capabilities like listing, updating, or canceling choices suggest minor gaps for the domain.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Easy MCP Server

    joshwyatt
    A
    license
    Not graded
    quality
    D
    maintenance
    A simple toolkit for creating MCP servers with stdio and SSE transport, auto-validating tools via Pydantic.
    MIT

  • achmadya-dev/mcp-core

    achmadya-dev
    A
    license
    Not graded
    quality
    A
    maintenance
    Provides a shared MCP SDK wrapper for building MCP servers with stdio transport, tool registration, JSON-safe responses, and environment helpers.
    38
    MIT

  • mcp-stdio

    Balneario-de-Cofrentes
    A
    license
    Not graded
    quality
    C
    maintenance
    A minimal, zero-dependency MCP server that enables defining and running tools over stdio transport, without extra features like HTTP or resources.
    27
    1
    MIT

  • mcpmini

    AnswerDotAI
    A
    license
    Not graded
    quality
    A
    maintenance
    Minimal MCP server allowing Python functions to be served as MCP tools over stdio or HTTP, with a built-in client for connecting to MCP servers.
    2
    Apache 2.0