# Task Hub MCP

跨 AI agent 的本地任务上下文共享。Task Hub 是一个 stdio MCP server，让 Codex、Claude Code、Hermes、VS Code 等客户端读写同一份任务状态。

当你切换 agent 时，新 agent 可以直接加载任务目标、当前进度、关键决策、踩坑记录和文件快照，不必重新翻完整对话。

## 核心设计

- `meta.json` 是任务状态的唯一真源。
- `context.md` 是从 `meta.json` 生成的蒸馏上下文，加载时会自动修复。
- `conversation.jsonl` 保存调用方显式传入的对话消息。
- `revision` 防止旧 agent 覆盖其他 agent 刚保存的新状态。
- MCP server 只维护一套接口，不为不同客户端复制业务逻辑。

## 六个工具

| 工具 | 用途 |
| --- | --- |
| `task_init` | 创建并开始追踪任务 |
| `task_save` | 保存上下文、进度、决策、踩坑、文件和可选对话 |
| `task_load` | 加载指定任务及其当前 revision |
| `task_list` | 按状态或标签列出任务 |
| `task_resume` | 加载 active 任务或恢复 paused 任务 |
| `task_stop` | 暂停任务，或用 `archive=true` 归档任务 |

## 安装

要求 Python 3.10 或更高版本。

```bash
git clone https://github.com/zjuphD/task-hub-mcp.git
cd task-hub-mcp
python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install .
```

开发时使用 editable install：

```bash
.venv/bin/python -m pip install -e .
```

安装后确认命令可用：

```bash
.venv/bin/task-hub-mcp
```

server 使用 stdio，直接启动后安静等待 MCP client 连接属于正常行为。

Windows 虚拟环境中的可执行文件通常位于 `.venv\\Scripts\\task-hub-mcp.exe`。

## 配置 MCP client

以下示例使用安装后的命令。请把 `/absolute/path/to/task-hub-mcp` 替换为仓库的真实绝对路径。

### Codex

在 `~/.codex/config.toml` 中添加：

```toml
[mcp_servers.task-hub]
command = "/absolute/path/to/task-hub-mcp/.venv/bin/task-hub-mcp"
startup_timeout_sec = 30
```

### Hermes

在 `~/.hermes/config.yaml` 中添加：

```yaml
mcp_servers:
  task-hub:
    enabled: true
    command: /absolute/path/to/task-hub-mcp/.venv/bin/task-hub-mcp
    timeout: 120
    connect_timeout: 60
```

检查连接：

```bash
hermes mcp list
hermes mcp test task-hub
```

Hermes 模型侧的工具名通常带 server 前缀，例如 `mcp_task_hub_task_save`。

### Claude Code / VS Code

在 `.mcp.json` 中添加：

```json
{
  "mcpServers": {
    "task-hub": {
      "command": "/absolute/path/to/task-hub-mcp/.venv/bin/task-hub-mcp"
    }
  }
}
```

不同 MCP client 的配置文件位置可能不同，但启动命令相同。

## 存储结构

默认存储目录：

```text
~/.task-hub/tasks/
```

每个任务目录：

```text
~/.task-hub/tasks/<task-id>/
├── meta.json
├── context.md
├── conversation.jsonl
└── artifacts/
```

可通过环境变量覆盖任务目录：

```bash
TASK_HUB_TASKS_DIR=/path/to/tasks
```

如果 MCP client 需要传递环境变量，可以把它放在对应 server 的 `env` 配置中。

## Revision 冲突保护

`task_init`、`task_load`、`task_save`、`task_resume` 和 `task_stop` 都会返回当前 `revision`。

保存前把加载时拿到的 revision 作为 `expected_revision` 传回：

```json
{
  "name": "release-v1",
  "context": "当前蒸馏状态",
  "expected_revision": 3,
  "agent": "codex"
}
```

如果其他 agent 已经把任务更新到 revision 4，这次保存不会产生文件或对话副作用，而是返回：

```json
{
  "success": false,
  "code": "revision_conflict",
  "expected_revision": 3,
  "actual_revision": 4,
  "hint": "Load the latest task state, merge your changes, and save again."
}
```

兼容旧客户端时可以不传 `expected_revision`，此时保持最后写入者覆盖的行为。跨 agent 工作流建议始终传入。

## 工具参数

### task_init

```json
{
  "name": "任务名",
  "description": "任务目标，可选",
  "tags": ["可选标签"]
}
```

### task_save

```json
{
  "name": "任务名或 task id",
  "context": "当前蒸馏状态",
  "progress": "本次进度，可选",
  "decisions": ["新决策，可选"],
  "pitfalls": ["新踩坑，可选"],
  "artifacts": [
    {
      "path": "/absolute/path/to/file",
      "description": "文件说明"
    }
  ],
  "agent": "codex",
  "messages": [
    {
      "role": "user",
      "content": "用户消息"
    }
  ],
  "expected_revision": 1
}
```

MCP server 无法自动读取 agent 私有会话窗口。只有调用方显式传入 `messages` 时，消息才会写入 `conversation.jsonl`。

部分 MCP client 会把数组包装成 `{"item": [...]}`、`{"items": [...]}` 或 `{"value": [...]}`；server 会自动归一化这些输入。

### task_load

```json
{
  "name": "任务名或 task id",
  "include_conversation": false
}
```

### task_list

```json
{
  "status": "active",
  "tag": "可选标签"
}
```

`status` 可选值为 `active`、`paused`、`archived`。

### task_resume

```json
{
  "name": "可选任务名或 task id"
}
```

- 指定 active 任务时直接加载。
- 指定 paused 任务时恢复为 active。
- 不指定任务时优先加载最近的 active 任务；如果没有 active 任务，则恢复最近的 paused 任务。
- archived 任务不能恢复。

### task_stop

```json
{
  "name": "任务名或 task id",
  "reason": "停止原因，可选",
  "archive": false,
  "expected_revision": 2
}
```

默认状态变为 paused；`archive=true` 时状态变为 archived。

## Artifact 限制

默认单个 artifact 最大为 50 MiB。超限文件会跳过并作为 warning 返回。

```bash
TASK_HUB_MAX_ARTIFACT_BYTES=104857600
```

设为 `0` 可以关闭大小限制。还可以限制允许读取的目录，多个目录使用操作系统路径分隔符连接：

```bash
TASK_HUB_ALLOWED_ARTIFACT_ROOTS=/workspace/project:/workspace/results
```

启用允许目录后，符号链接也会按解析后的真实路径检查。

## 可靠性与隐私

- `meta.json` 和 `context.md` 使用临时文件、`fsync` 和原子替换。
- `context.md` 发生缺失或过期时，`task_load` 会从 `meta.json` 自动重建。
- Unix 系统使用文件锁串行化同一任务的写入；创建任务使用全局锁避免同名竞争。
- `revision` 解决文件锁无法发现的语义级旧状态覆盖。
- artifact 同名时自动生成唯一文件名。
- `conversation.jsonl` 的坏行会被标记并跳过，不会导致整个任务加载失败。

Task Hub 以当前用户权限运行。保存的上下文、对话和 artifact 可能包含源代码、绝对路径、密钥或其他隐私数据；不要把 `~/.task-hub/tasks/` 直接提交到公开仓库。对不完全信任的 agent，建议配置 `TASK_HUB_ALLOWED_ARTIFACT_ROOTS`。

## 开发验证

```bash
python -m compileall -q task_hub_mcp tests
python -m unittest discover -s tests -v
python -m pip wheel --no-deps . -w dist
```

MCP 握手验证：

```python
import asyncio
from pathlib import Path

from mcp import ClientSession
from mcp.client.stdio import StdioServerParameters, stdio_client


async def main():
    executable = Path(".venv/bin/task-hub-mcp").resolve()
    params = StdioServerParameters(command=str(executable))
    async with stdio_client(params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            print([tool.name for tool in tools.tools])


asyncio.run(main())
```

预期工具列表：

```text
task_init, task_save, task_load, task_list, task_resume, task_stop
```

## License

MIT