Codex MCP 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：已有说明草稿，文件名疑似拼写错误；正式文档见本文件。

Related MCP server: Todo Markdown MCP Server

提供的 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。

同时还暴露了一个 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。

数据存储

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 改为：

[]