文件看板 MCP chenyinrusi/dsh-kanban-mcp

dsh-kanban-mcp

由文件系统驱动的四泳道看板（todo / doing / blocked / done），以只读 MCP 服务器和 Python API 的形式暴露。可与 DeepSeek Harness 及任何 MCP 客户端配合使用。

看板不过是一棵由 markdown 卡片组成的目录树：

/YYYY/YYYY-MM/YYYY-MM-DD/{todo,doing,blocked,done}/YYYYMMDD-HHMMSS__agent__slug__status.md

这个设计正是关键所在：看板在重启后依然存在，可在 git 中进行 diff，无需数据库，并且可以被任何文件工具检查。本包负责管理这些文件，并通过 MCP 将看板暴露给智能体。

安装

pip install "dsh-kanban-mcp" # Python API
pip install "dsh-kanban-mcp[mcp]" # + MCP server (fastmcp)

需要 Python 3.10+。

运行 MCP 服务器

python -m kanban_mcp # stdio transport
or: kanban-mcp

在 DeepSeek Harness（MCP 设置——内置的 MCP 客户端）或任何 MCP 客户端中注册它。这些工具接受一个可选的 base_dir 参数（默认 .agent/kanban），因此一个服务器可以指向任何看板。

工具（只读）

| 工具 | 描述 |
| kanban_board | 完整的四泳道看板，包含卡片详情（agent、work_item、purpose、status、outcome、priority、时间戳） |
| kanban_status | 每个泳道的卡片数量 + 总数 |
| kanban_doing | 当前进行中的卡片 |
| kanban_blocked | 被阻塞的卡片 |
| kanban_done_today | 今天完成的卡片 |

所有工具均为只读。卡片的创建 / 更新 / 移动可通过 KanbanManager Python API 实现（见下文）；写入工具已列入计划，但尚未通过 MCP 暴露。

Python API

from kanban_mcp import KanbanManager, LaneStatus

kanban = KanbanManager(base_dir=".agent/kanban")

card = kanban.create_doing_card(
agent="coder",
work_item="build-api",
purpose="Build the REST API endpoint",
)
kanban.update_card(card, outcome="GET /users implemented")
kanban.move_to_done("coder", "build-api", "API endpoint complete")

board = kanban.get_board() # full board
stats = kanban.stats() # per-lane counts
blocked = kanban.get_blocked_cards()

写入操作通过原子性的临时文件 + os.replace 完成，因此并发读取者永远不会看到写了一半的卡片。

为什么用文件而不是数据库

- 可 Git diff —— 卡片变更可以像代码一样被审查。
- 重启后依然存在 —— 没有守护进程，没有锁，没有迁移。
- 可检查 —— 任何文件工具都可以直接读取卡片。
- 可移植 —— cp -r 该目录，你就有了一个新看板。

开发

pip install -e ".[dev]"
pytest

许可证

MIT © 2026 Chen (Jarry) Pan