FronyBoard

FronyBoard

一个 MCP 服务，让 AI Agent（Claude Code 等）能够使用一流的项目跟踪工具。

Jira 是通过 Web UI 为人类提供的 issue 跟踪工具，而 FronyBoard 将其中的每个部分都替换成 Agent 可直接使用的形式：

Jira	FronyBoard
数据库	专用数据目录中的一个 SQLite 文件
记录	JSON 文档（路线图、周期）+ Markdown
API	MCP 工具
工作流引擎	Schema + 规则验证，在每次写入前作为关卡运行
状态转换	一次 MCP 工具调用（transition_task）

Schema 和操作规则提取自一个真实产品的管理系统（已有 31 个任务通过该系统交付），之后进行了泛化。

安装

需要 uv。运行一行命令即可在 Claude Code 中注册 FronyBoard；首次使用时，uvx 会从 PyPI 获取软件包并缓存：

claude mcp add FronyBoard -- uvx fronyboard

任何能够启动 stdio 命令的 MCP 客户端都可以用同样的方式运行——命令是 uvx fronyboard。它也已列入 MCP Registry，名称为 io.github.Cafelatte1/fronyboard。从克隆的仓库运行时，改为指向本地检出目录（需要 git）：

git clone https://github.com/Cafelatte1/fronyboard
claude mcp add FronyBoard -- uv run --directory <path-to-clone>\backend fronyboard

这是本地（stdio）模式：客户端将服务作为子进程启动，并通过管道与其通信。没有 HTTP、网络或凭据——不会调用 web.py 和 fauth.py。数据写入 %LOCALAPPDATA%\Frony\FronyBoard\data（若未设置 LOCALAPPDATA，则写入 ~/.Frony/FronyBoard/data）；设置 AIRA_DATA_DIR 可更改数据目录。日志（JSON Lines，每次 MCP 工具调用和服务事件各占一行）写入同级的 logs 文件夹——可通过 FRONYBOARD_LOG_DIR 覆盖。

若要让多台机器共用一个 FronyBoard，或在 Claude 和 ChatGPT 应用中使用它，请改为将其作为 HTTP 服务运行——参见docs/self-hosting.md。

项目设置

连接 MCP 服务后，每个会话都会获得工具和通用工作流（通过服务指令提供）。但它无法知道某个代码库属于哪个 FronyBoard 项目——需要在代码库本身中声明：将以下部分添加到其 CLAUDE.md 中（如果项目没有该文件，则创建一个）：

## FronyBoard

This project is tracked by FronyBoard (project key: DLY).
Manage tasks through the FronyBoard MCP tools, following the FronyBoard server instructions.

将 DLY 替换为项目的 key（先使用 create_project 注册一个）。该部分也是选择启用的标记：没有此内容的代码库会被视为不受 FronyBoard 管理。

模型

fronyboard.db
├── projects   one row per project (key e.g. DLY): the roadmap record —
│              yearly overview (goal / now / target / checklist) + quarterly milestones
└── periods    one row per opened period (e.g. 2026Q3): tasks ({KEY}-001, ...)
               + `result` (retrospective, written when the period closes)

一个项目由两类记录组成——路线图，以及每个周期的一条记录。两者都是 JSON 文档；其架构和校验规则位于 backend/src/fronyboard/validation.py。

• 任务 ID 是项目范围内的连续序列（DLY-042）——它们会跨周期持续递增，且绝不重复使用。它们是 FronyBoard 与代码库之间唯一的关联：将其用于分支名称（feat/DLY-042/short-desc），并在任务中记录分支。
• 任务就是一个标题（v0.33.0，AIR-086），再加上状态、标签、depends_on、分支，以及两条各不超过 300 个字符的单行备注。Agent 会读取标题和状态；那段没人读的 25 行正文，以及仅用于安排任务的月份／周次栏位，都已移除。时间记录在 meta.completed_at 中。
• 两条备注在不同时间回答不同的问题（v0.38.0，AIR-090）。content 在创建时填写，说明任务为何存在——它背后的压力，或有意排除的范围。选择的方案不属于其中（AIR-092）：Agent 会在这里写一次，又在提交记录中写一次，因此方案只保留在提交记录中。调用 transition_task(status="done") 时必须填写 check，说明什么可以证明任务已完成——执行的命令及其输出，或读者可以亲自查看的可观察结果。工作开始前要求填写一条自由备注，只能重述计划：在一项 12 次会话的基准测试中，Agent 为每个任务写的备注都只是改述其标题，因为备注在创建时固定，且从未调用 update_task。重新打开任务时会清除其 check；此时便不再有任何完成证明。
• 引用链：period → roadmap milestone（季度）。仅此一条，而且里程碑是可选的（v0.40.0，AIR-095）：不关联里程碑的周期同样有效，其任务的检查方式也与其他任务相同。
• 状态——里程碑：planned | active | done； 任务：todo | in_progress | done | blocked | cancelled。
• cancelled 是软删除——没有硬删除。取消任务必须提供原因，记录（及其 ID）会永久保留，并且默认从查询结果中隐藏（list_tasks 接受 include_cancelled）。blocked = 可能恢复，cancelled = 不会继续；转换已取消任务的状态会将其恢复。
• 延续任务：如果任务的生命周期超出所属周期，不要移动它——在下一个周期中以新 ID 重新创建，并在结项回顾中记录对应关系。
• get_status 就是完整的恢复信息——总览、每个周期的未完成任务，以及 recent_done：最近完成的十个任务，包括其 content、check 和完成时间。对冷启动会话而言，最需要的是已构建的内容，而且没人会再发起第二次调用来查找它（AIR-090）。它仍然只是对情况的记录：看板展示 Agent 报告的内容，代码才是证据。
• 任务上的 depends_on 列出它所基于的较早任务（也可以来自其他项目）。它只指向过去——没有正向索引，因为只存储一个方向、再按需反向推导，读起来经常像是反过来的，足以说明不值得保留正向索引（v0.36.0，AIR-089）。该字段在 v0.37.0 之前名为 follows；启动迁移会将其重命名。它是一个指针，不是锁：list_tasks 和 get_status 会将尚未完成的条目标记为 waiting_on，且绝不会因此阻塞任务。
• 时间戳（meta.created_at / updated_at / started_at / completed_at）由服务端以无时区 UTC 时间写入——首次转换为 in_progress 时写入 started_at，转换为 done 时写入 completed_at（任务离开 done 状态时则会再次移除）。Agent 绝不写入这些时间戳。
• result 字段用于结项——文件其余部分仅保存当前状态，因此“结果为何如此”由该字段记录：判断和原因，而非计数。该字段是否存在，决定一个周期是否已结项。

工具

领域	工具
项目	create_project、update_project、list_projects、get_roadmap、get_status、validate
路线图	set_overview、set_check、upsert_milestone
周期	open_period、close_period、get_retrospective
规划	create_task、update_task、transition_task
查询	list_tasks、get_task、search_tasks、recent_activity

update_task 和 transition_task 会根据任务 ID 前缀推断项目 （DLY-042 → DLY），因此其 key 参数可选。对已关闭的周期再次调用 close_period 会重写其回顾。

典型流程：

create_project
→ create_task (opens the current quarter)
→ transition_task in_progress (with branch) → ... → transition_task done
→ close_period (retrospective)

规划是可选的，并非前提。create_task 会自行开启当前季度（使用 FRONYBOARD_TZ，否则使用服务器所在时区）；open_period 可开启任何其他季度， 无论是否有里程碑。只要有年度和季度目标，就可以通过 set_overview 和 upsert_milestone 添加这些目标。添加到已开启季度的里程碑会设为 active； 关闭季度时则会将其标记为 done。

每次变更都会先经过验证，之后才会写入任何内容；无效变更会被拒绝，并返回完整的错误列表。如果任务仍处于 todo 或 in_progress 状态，close_period 会拒绝执行。写入操作按项目串行处理，因此并发客户端不会发生 ID 冲突或更新丢失。

自托管

同一个软件包也可以作为常驻 HTTP 服务运行（fronyboard serve）：通过可流式 HTTP 为网络中的每台机器提供 MCP，只读 Web 仪表板供用户查看，按设备设置 API 密钥，并为托管的 Claude / ChatGPT 应用提供 OAuth。 身份验证委托给独立服务 FronyAuth。 上述 stdio 安装不需要这些功能。 若要在自己的机器上查看仪表板而无需启用这些功能，请运行 fronyboard serve --local （仅限环回地址，无需登录），然后打开 http://127.0.0.1:8642。 docs/self-hosting.md 介绍设置方法； docs/operations.md 是日常运维手册。

开发

uv run --directory backend pytest      # backend
cd frontend; npm test                  # dashboard

此仓库是一个单体仓库。backend/src/fronyboard/ — store.py（SQLite，数据根目录）、 validation.py（架构校验）、service.py（操作）、auth.py（Bearer 中间件）+ fauth.py（FronyAuth 客户端）、log.py、web.py（JSON API + 静态资源服务）、 server.py（MCP 工具接口 + CLI）。frontend/ — 仪表板（React + Vite），构建为由后端提供服务的静态文件；其构建输出 frontend/dist 已提交，因此服务无需 Node 工具链。

docs/ 下的三份文档介绍了代码无法说明的内容——如何在自己的机器上运行：

• docs/self-hosting.md — 将 FronyBoard 作为共享服务运行：客户端、仪表板、托管应用、部署
• docs/operations.md — 家用服务器运维手册