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 或更高版本。

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：

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

安装后确认命令可用：

.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 中添加：

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

Hermes

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

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

检查连接：

hermes mcp list
hermes mcp test task-hub

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

Claude Code / VS Code

在 .mcp.json 中添加：

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

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

存储结构

默认存储目录：

~/.task-hub/tasks/

每个任务目录：

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

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

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 传回：

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

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

{
  "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

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

task_save

{
  "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

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

task_list

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

status 可选值为 active、paused、archived。

task_resume

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

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

task_stop

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

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

Artifact 限制

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

TASK_HUB_MAX_ARTIFACT_BYTES=104857600

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

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。

开发验证

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

MCP 握手验证：

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())

预期工具列表：

task_init, task_save, task_load, task_list, task_resume, task_stop

License

MIT