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

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

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

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

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

## 本地运行 MCP Server

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

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

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

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

## 在 Codex 中注册 MCP Server

推荐使用 Codex CLI 注册：

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

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

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

注册后检查：

```bash
codex mcp list
```

你应该能看到类似条目：

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

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

```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
```

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

```toml
[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：

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

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

```text
帮我把发布前检查拆成 todo
```

```text
还有哪些任务没完成？
```

```text
把 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` 中对应的动作类型。

工具返回示例：

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

```json
[]
```