Skip to main content
Glama
zjuphD

Task Hub MCP

by zjuphD
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

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

This server cannot be installed

-
license - not tested
-
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/zjuphD/task-hub-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server