Codex Todo Assistant

这个项目演示如何为 Codex 接入一个本地 MCP Server，并通过 AGENTS.md 约束 Codex 在任务规划场景中使用 MCP tools。

当前 demo 提供的是一个 todo 规划助手：用户要求组织、拆解、跟踪任务时，Codex 会调用本地 MCP tools，而不是只在对话里临时记忆任务。

文件说明

• todo_mcp_server.py：MCP Server 主程序，基于 mcp.server.fastmcp.FastMCP，通过 stdio 运行。
• requirements.txt：Python 依赖，目前只有 mcp[cli]。
• todos.json：todo 数据文件，MCP tools 会读写这个文件。
• AGENTS.md：给 Codex 的项目级指令，定义什么时候使用 todo MCP tools，以及如何拆解任务。
• READMD.md：已有说明草稿，文件名疑似拼写错误；正式文档见本文件。

提供的 MCP tools

todo_mcp_server.py 暴露了以下工具：

• add_todo(title, priority)：新增 todo，priority 可为 low、normal、high。
• list_todos(include_completed)：列出 todo，可选择是否包含已完成项。
• complete_todo(todo_id)：按 ID 标记 todo 为已完成。
• clear_todos(only_completed)：清空 todo，或只清理已完成项。
• get_todo_summary()：按状态和优先级汇总 todo。
• generate_task_flow(name, flow_id)：将当前 todo 生成符合 TaskFlow protobuf 结构的执行流。

同时还暴露了一个 MCP resource：

• todo://all：读取全部 todo 数据。

安装 Python 依赖

建议使用虚拟环境，避免污染系统 Python 环境。

下面命令中的 <path> 表示你本机存放项目的父目录，例如 /path/to。

cd <path>/codex-mcp-todo-assistant
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

如果你不使用虚拟环境，也可以直接安装：

cd <path>/codex-mcp-todo-assistant
python3 -m pip install -r requirements.txt

本地运行 MCP Server

这个 MCP Server 使用 stdio transport，通常由 Codex 启动，不需要你手动长期运行。

如需做最基本的启动检查，可以执行：

cd <path>/codex-mcp-todo-assistant
python3 todo_mcp_server.py

该命令会进入 stdio 服务状态，等待 MCP client 通信；手动运行时没有交互输出是正常的。需要退出时按 Ctrl+C。

在 Codex 中注册 MCP Server

推荐使用 Codex CLI 注册：

codex mcp add todo_skill_demo -- python3 <path>/codex-mcp-todo-assistant/todo_mcp_server.py

如果你使用上面创建的虚拟环境，建议把命令里的 python3 换成虚拟环境解释器：

codex mcp add todo_skill_demo -- <path>/codex-mcp-todo-assistant/.venv/bin/python <path>/codex-mcp-todo-assistant/todo_mcp_server.py

注册后检查：

codex mcp list

你应该能看到类似条目：

Name             Command  Args                                                    Status
todo_skill_demo  python3  <path>/codex-mcp-todo-assistant/todo_mcp_server.py          enabled

也可以手动编辑 ~/.codex/config.toml，加入以下配置：

[mcp_servers.todo_skill_demo]
command = "python3"
args = ["<path>/codex-mcp-todo-assistant/todo_mcp_server.py"]
startup_timeout_sec = 10
tool_timeout_sec = 30

使用虚拟环境时，对应写法是：

[mcp_servers.todo_skill_demo]
command = "<path>/codex-mcp-todo-assistant/.venv/bin/python"
args = ["<path>/codex-mcp-todo-assistant/todo_mcp_server.py"]
startup_timeout_sec = 10
tool_timeout_sec = 30

修改配置后，重新启动 Codex，让 MCP Server 配置生效。

使用方式

进入本项目目录后启动 Codex：

cd <path>/codex-mcp-todo-assistant
codex

然后可以用自然语言让 Codex 管理任务，例如：

帮我把发布前检查拆成 todo

还有哪些任务没完成？

把 3 号任务标记完成

由于 AGENTS.md 已定义项目级工作流，Codex 在识别到计划、拆解、跟踪、更新任务等请求时，会使用 MCP tools 读写 todos.json。

TaskFlow 生成规则

generate_task_flow 会将 todo 列表转换为可用于 UpsertTaskFlowRequest.flow 或 RunTaskFlowRequest.inline_flow 的 TaskFlow 结构：

• 每个 todo 对应一个 TaskNode，节点 ID 为 todo-{id}。
• action_params 保存 todo 标题、优先级、数值优先级、ID 和完成状态。
• 节点按 todo 顺序排列，并通过 CONDITION_ON_SUCCESS 的 TaskEdge 串行连接。
• 节点使用 JOIN_ALL 和 PREEMPT_AND_RESUME，成功条件为 completed = true。
• ActionType 暂用枚举零值 0；接入具体机器人能力时应映射为 capability_type.proto 中对应的动作类型。

工具返回示例：

{
  "success": true,
  "flow": {
    "flow_id": "todo-task-flow",
    "name": "发布前检查",
    "nodes": [
      {
        "node_id": "todo-1",
        "action_type": 0,
        "action_params": {
          "title": "运行回归测试",
          "priority": "high",
          "priority_value": 3,
          "todo_id": 1,
          "completed": false
        },
        "join_type": "JOIN_ALL",
        "preemption_rule": "PREEMPT_AND_RESUME",
        "success_condition": {"completed": true},
        "timeout_ms": 0
      }
    ],
    "edges": []
  }
}

数据存储

todo 数据保存在项目根目录的 todos.json。这是 demo 用的本地 JSON 存储，不适合多用户并发写入或生产环境使用。

常见问题

codex mcp list 看不到 server

确认是否执行过注册命令，并检查 ~/.codex/config.toml 中是否存在 [mcp_servers.todo_skill_demo]。

Codex 无法启动 MCP Server

优先检查：

• python3 是否可用。
• 是否已安装依赖：python3 -m pip install -r requirements.txt。
• todo_mcp_server.py 是否使用绝对路径注册。
• 如果使用虚拟环境，command 是否指向 .venv/bin/python。

todo 数据异常

todo_mcp_server.py 会读取 todos.json。如果文件不是合法 JSON list，server 会按空列表处理。需要重置 demo 数据时，可以把 todos.json 改为：

[]