b52tot/workbuddy-board
WorkBuddy Board
WorkBuddy 写的 WorkBuddy 看板 —— 让英雄查英雄。不耽误打游戏了。
给 MCP Agent 用的桌面任务看板。四列任务常驻桌面,agent 干到哪一步、有没有卡住, 抬眼就能看到 —— 不用切窗口,也不用点开浏览器。
零第三方依赖(只用 Python 标准库),单文件 exe,双击即用。
快速开始
打开 exe —— 下载
BoardWidget.exe,双击运行。注册 MCP —— 挂件右下角点 ⚙,在 MCP 那一行点「注册」。
重启 WorkBuddy —— MCP 配置只在客户端启动时读一次;重启后到连接器管理页点「信任」。
开始用 —— agent 干到哪一步、有没有卡住,实时出现在桌面上。
不用装 Python、不用部署服务 —— 看板后端和 MCP 端点都打包在这一个 exe 里。
Related MCP server: AgentTasker
特性
能力 | 说明 |
桌面挂件 | 无边框常驻 + 置顶,可拖动 / 缩放 / 调透明度,收起后变 62px 条形 |
任务卡片 | 标题、说明、标签、优先级、自定义字段 |
进度条 | 声明 |
停滞检测 | 非终态列 + 超过阈值无任何上报 ⇒ 卡片标黄,顶部给计数 |
列分组 | 栏目顺序 / 标题 / 颜色 / WIP 上限全部可配 |
状态流转 | 白名单约束,非法流转会报错并提示合法目标 |
变更流水 | 每次改动自动记事件,随时可查「谁在何时把什么从哪移到哪」 |
存储 | SQLite 单文件,WAL 模式 |
MCP 工具 | 15 个,agent 可直接读写看板 |
网页看板 | 单端口 HTTP,1 秒轮询,深浅色主题 |
接入 WorkBuddy
挂件自带「注册 MCP」按钮(上面的第 2 步)。手工接入的话:
第一步 准备配置:
cp config.example.json config.json第二步 编辑 ~/.workbuddy/mcp.json,在 mcpServers 里加一项:
{
"mcpServers": {
"board": {
"type": "stdio",
"command": "C:\\绝对路径\\python.exe",
"args": ["C:\\绝对路径\\workbuddy-board\\server\\mcp_server.py"],
"timeout": 120000
}
}
}command / args 都用绝对路径,不需要 cwd —— 配置文件与 db_path 都按
代码位置定位,不由进程 CWD 决定,所以宿主从哪个目录拉起都一样。
不要往
env里塞项目配置。 WorkBuddy 的 MCP 连接指纹把env的 key 集合算在内, 加 key 会让已授信的 server 退回待授信、下次启动重新弹授权。
第三步 重启客户端 → 到连接器管理页右上角的「自定义」入口点「信任」。
工具(15 个)
宿主会自动加 mcp__board__ 前缀。
工具 | 用途 |
| 读看板完整快照(列、任务、统计、进度、停滞) |
| 读当前生效的配置 |
| 任务增删改查 |
| 按列或标签筛选 / 列出栏目 |
| 状态流转 |
| 推进进度(只增不减、传绝对值所以幂等) |
| 疑似停滞的任务(非终态列 + 超阈值无上报) |
| 变更流水(支持 |
| 归档出主视图 / 还原回看板 |
| 清空看板(需显式 |
配置
复制 config.example.json 为 config.json 后修改。所有键都可省略,省略即用默认值
(一个配置文件都没有也能跑)。
查找顺序:--config 参数 → 环境变量 WBB_CONFIG → ./config.json。
board
键 | 类型 | 默认 | 说明 |
| string |
| 看板标题 |
| string |
| SQLite 路径,自动建目录 |
| array | 待办/进行中/阻塞/已完成 | 栏目定义,见下 |
| object | 见示例 | 状态流转白名单 |
| array |
| 自定义字段 schema |
| bool |
| 是否强制 WIP 上限 |
| int |
| 前端轮询间隔 |
| bool |
| 隐藏空列 |
columns 每一项:
{ "id": "doing", "title": "进行中", "color": "blue", "wip_limit": 5, "is_terminal": false }id—— 稳定标识。改了等于换了一列,旧任务会找不到列,定好别动color——gray/blue/amber/green/red/purple/teal/pink/coralwip_limit—— 在制品上限,null表示不限;超限时迁入会被拒绝is_terminal—— 终态列,用于统计完成率。至少要有一个
transitions —— 未列出的流转会被拒绝,报错里会列出该列允许的目标:
{ "todo": ["doing", "blocked", "done"], "doing": ["todo", "blocked", "done"] }fields —— 未在此定义的键不允许写入:
[
{ "key": "version", "type": "text", "label": "版本号" },
{ "key": "risk", "type": "enum", "label": "风险等级", "values": ["低", "中", "高"] },
{ "key": "progress", "type": "progress", "label": "进度" }
]type 取 text / number / enum / bool / progress;
enum 必须给 values,progress 必须给 label。
web
键 | 类型 | 默认 | 说明 |
| string |
| 监听地址(默认仅本机) |
| int |
| 端口 |
| bool |
| 启动时自动开浏览器 |
| bool |
| 网页端是否允许写操作 |
以
_开头的键视为注释、会被忽略;其余未知键会报错 —— 避免「改了配置却没生效」这种最难排查的问题。
看板本身不含业务词汇。examples/config.custom-columns.json 演示了把它改成
发布流程看板(六个列 + 专属流转 + 五个字段),不用改一行代码。
从源码跑
需要 Python ≥ 3.10,无需安装依赖。
git clone https://github.com/b52tot/workbuddy-board.git
cd workbuddy-board
cp config.example.json config.json
python examples/demo_seed.py # 可选:灌一份示例数据
python -m server.web_server # 网页看板 → http://127.0.0.1:8791让它常驻(前台进程关终端就停):
python svc.py start | status | restart | stopstatus 除了探活,还会核对「运行中的库」与「配置期望的库」是否一致 ——
health 200 只证明有东西在监听,不证明用的是你要的那个库。
挂件本身(需要 pip install pywebview):
python widget/host.py跑测试:
python -m pytest tests -q # 数据层
python -m server.mcp_server --selftest # MCP 协议自检(不碰数据库)
python widget/fulltest.py # 界面全功能测试(先跑 widget/make_inline.py)用 Docker 跑 MCP server
零依赖,所以镜像里没有 pip install 这一步。主要给两类场景:跑在隔离环境里,
以及让 Glama 这类目录站自动做一次「能起来、能应答」的检查。
docker build -t workbuddy-board .
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"1"}}}' \
| docker run -i --rm workbuddy-board容器里的 config.json 直接来自 config.example.json(不另写一份,避免两处漂移),
库落在 /app/data/board.db。要持久化就 -v wbb-data:/app/data。
网页界面不包含在这个镜像里 —— MCP server 用不到它。
项目结构
workbuddy-board/
├── board/ 数据层(唯一写入方,纯标准库)
│ ├── config.py 配置加载 + 校验
│ ├── models.py 数据模型与状态机校验
│ ├── store.py ★ 所有写操作的唯一入口,自动登记事件
│ └── schema.sql 建表语句
├── server/
│ ├── mcp_server.py MCP stdio 工具(手写 JSON-RPC,不依赖 mcp SDK)
│ └── web_server.py HTTP 看板
├── web/ 展示层(无构建步骤)
├── widget/ 桌面挂件(pywebview)
│ ├── host.py 宿主进程:窗口 / 托盘 / 日志
│ ├── widget.js widget.css
│ └── boardwidget.spec PyInstaller 打包配置
├── examples/ 最小配置 / 换业务示例 / 示例数据
├── tests/ 数据层 + HTTP 契约 + MCP 协议 + 挂件状态
└── svc.py 服务管理:脱离会话启动 / 停止 / 探活所有写操作都收敛到 board/store.py,且每次写都登记一条事件 ——
于是任何时刻都能回答「这个任务是怎么走到现在这一步的」。
常见问题
能看到页面但一直是空的?
确认 db_path 指向的库和灌数据的库是同一个。
移动任务报「不允许从 X 流转到 Y」?
流转规则在 board.transitions,报错信息会列出该列允许的目标。
报「不是合法的配置项」?
拼写错误。看报错里的可用键列表;注释请用 _ 开头。
想看某个任务是怎么一步步走到现在的?
GET /api/events?task_id=<id>,或在网页上点开卡片看「变更流水」。
更新日志
见 CHANGELOG.md。
许可
MIT,见 LICENSE。
Available Tools
15 toolsarchive_doneA
把「完成已久」的已完成任务归档出主视图。归档 = 打标记,一条都不删,随时可用 restore_archived 拿回来。平时无需手动调:看板快照会自动巡检,按配置 board.archive_done_after_days(默认 3 天)归档。这里传 older_than_days 可以临时改用另一个保留期。
Inputs: older_than_days.
board_configA
读取当前生效的看板配置:栏目、合法流转、自定义字段、数据库路径、Web 端口。在决定「能移到哪一列」「有哪些自定义字段」之前先看它。
Inputs: no named parameters.
board_resetA
清空看板上的全部任务。破坏性操作,必须显式传 confirm=true 才会执行。
Inputs: actor, confirm.
board_snapshotA
读取看板完整快照:栏目定义、每列下的任务、统计(总数/已完成/百分比)。想看当前进展、或要渲染看板时用它。compact=true 时只返回任务 id 与标题,任务很多时可显著减小返回体积。
Inputs: compact.
create_taskB
在看板上新建一个任务。column_id 省略时放到第一列;fields 只接受在配置 board.fields 中定义过的键,传未定义的键会报错。
Inputs: title (required), tags, actor, fields, +4 more.
delete_taskB
删除一个任务。会同时登记一条 delete 事件(任务数据不可恢复)。
Inputs: task_id (required), actor.
get_taskC
读取单个任务的完整字段。
Inputs: task_id (required).
list_columnsA
列出所有栏目(列)及其顺序、颜色、在制品上限。
Inputs: no named parameters.
list_eventsA
读取变更流水(谁在什么时候把什么从哪列移到哪列)。since_seq 支持增量拉取;给定 task_id 可看单个任务的完整历史。
Inputs: limit, task_id, since_seq.
list_stalledA
列出疑似停滞的任务:仍在非终态列、且超过阈值秒数没有任何写入。语义是「上报中断」而非「进度值没变」 —— 所以长任务必须周期性调用 update_progress 上报,否则会被误标。返回里带 idle_sec(静默了多久)。
Inputs: now, threshold_sec.
list_tasksA
按列或标签筛选任务。想看「进行中都有什么」时用 column_id 过滤。默认不返回已归档的任务(完成已久、已挪出主视图的);要看历史就传 include_archived=true。归档不是删除,数据一直都在。
Inputs: tag, column_id, include_archived.
move_taskA
把任务移到另一列(状态流转)。流转合法性由配置 board.transitions 决定,非法流转会报错并列出该列允许的目标。before_task_id 可指定插到某任务之前。
Inputs: task_id (required), to_column (required), actor, before_task_id.
restore_archivedB
把归档的任务还原回主视图。给 task_id 还原那一个;不给则全部还原。
Inputs: task_id.
update_progressA
推进某个任务的进度字段(长耗时任务用)。进度只增不减:传入比当前更小的值会被显式拒绝并告诉你当前值是多少(对齐 MCP 规范 progress 语义)。current 传绝对值而非增量,因此重复调用是幂等的、重试不会推两遍。建议长任务周期性上报 —— 否则会被 list_stalled 判定为停滞。
Inputs: current (required), task_id (required), done, actor, +4 more.
update_taskB
更新任务的标题/说明/标签/自定义字段/优先级。只改传入的部分。
Inputs: task_id (required), tags, actor, title, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Tools are largely distinct: task CRUD, board snapshot/config, progress, stalled, events, archive/restore, reset each have clear purposes. Minor overlap exists between board_config and list_columns, and between board_snapshot and list_tasks, but descriptions clarify their different scopes.
Most tool names follow a consistent snake_case verb_noun pattern (create_task, move_task, list_events, etc.). The board_* prefixed read and reset tools (board_snapshot, board_config, board_reset) deviate slightly, with board_reset being noun_verb rather than verb_noun.
15 tools is within a reasonable range for a kanban board server and each tool covers a distinct operation. Some convenience read tools (list_columns vs board_config) are slightly redundant, making the set a touch heavy but still manageable.
Task lifecycle is well covered with create, read, update, delete, move, progress, archive, restore, and event logging. Notable gaps remain: there are no tools to create/update/delete columns or modify board configuration, so agents cannot change the board structure itself.
Maintenance
Related MCP Connectors
Task & board management for AI agents + humans. Kanban, comments, digests via MCP.
A task list shared by you and your coding agents (Claude Code, Cursor, Codex and any MCP client). Agents plan each task into steps, report live progress to a board, and block on questions you answer from your phone.
Task management your AI agents can actually run. One line becomes a context-ready task over MCP.
Kanban board for teams and coding agents: manage tasks, subtasks, sprints and wiki pages via MCP.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceSelf-hosted kanban board that dispatches AI agent fleets against tickets. The embedded Streamable HTTP /mcp endpoint exposes 7 tools to list projects, read boards and tickets, and create, move and comment tickets from any MCP client.31AGPL 3.0

AgentTaskerofficial
AlicenseNot gradedqualityBmaintenanceEnables AI agents to create, query, update, claim, hand off, and complete tasks on a local SQLite-backed, project-namespaced kanban board through stdio MCP tools, including filtering for ready/blocked/stale work and exchanging task attachments. It also lets agents list projects and manage statuses, ownership, and evidence without any server or accounts.MIT- AlicenseNot gradedqualityBmaintenanceDesktop task board that coding agents keep themselves: they register goals, plan steps and progress over MCP, and wait for your sign-off. Local SQLite, three tools.2MIT
- AlicenseNot gradedqualityCmaintenanceLocal kanban board & harness for coding agents over MCP: agents claim and move tasks, read and write notes, and build Auto-code workflows, within per-folder permissions and an audit log.1Apache 2.0