FronyBoard

FronyBoard

AI エージェント（Claude Code など）に、本格的なプロジェクトトラッカーを提供する MCP サーバーです。

Jira がウェブ UI を介して人間向けの課題トラッカーであるのに対し、FronyBoard は各要素をエージェントがネイティブに利用できるものに置き換えます。

Jira	FronyBoard
データベース	専用のデータディレクトリにある SQLite ファイル 1 つ
レコード	JSON ドキュメント（ロードマップ、期間）＋ Markdown
API	MCP ツール
ワークフローエンジン	スキーマ＋ルール検証。すべての書き込み前にゲートとして実行
状態遷移	MCP ツールの呼び出し（transition_task）

スキーマと運用ルールは、実際の製品の管理システム（31 件のタスクを運用）から抽出し、一般化したものです。

インストール

uv が必要です。1 行のコマンドで FronyBoard を Claude Code に登録できます。初回使用時に 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 ツールの呼び出しごとに 1 行と、サーバーイベント）は、隣接する 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 をプロジェクトのキーに置き換えてください（まず 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)

プロジェクトは2種類のレコードで構成されます。ロードマップと、期間ごとに1つのレコードです。どちらも JSON ドキュメントであり、スキーマとそれを検証するルールは backend/src/fronyboard/validation.py にあります。

• タスク ID はプロジェクト全体で連番になります（DLY-042）。期間をまたいで番号が増え続け、再利用されることはありません。FronyBoard とコードベースを結び付ける唯一のものです。ブランチ名（feat/DLY-042/short-desc）に使用し、タスクにブランチを記録します。
• タスクはタイトル（v0.33.0、AIR-086）に、ステータス、タグ、depends_on、ブランチ、各300文字以内の1行メモ2つを加えたものです。エージェントはタイトルとステータスを読みます。誰も読まなかった25行の本文と、タスクのスケジュールにしか使われなかった月／週の枠は廃止されました。時刻は meta.completed_at に記録します。
• 2つのメモは、それぞれ異なるタイミングで異なる問いに答えます（v0.38.0、AIR-090）。content は作成時に記入し、タスクが存在する理由、つまりその背景にある必要性や、意図的に対象外とした範囲を記します。選択したアプローチはここには含めません（AIR-092）。エージェントはここにもコミットにも同じ内容を書いていたため、コミットだけに記録するようになりました。check は transition_task(status="done") で必須となり、タスクが完了したことを何が証明するか、つまりコマンドとその出力、または読者が実際に確認できる事柄を記します。作業前に求める自由記述のメモは計画を言い換えるだけになりがちです。12セッションのベンチマークでは、作成時にメモが固定され、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 が含まれます。recent_done は、最近完了した10件のタスクについて、content、check、完了時刻を示します。すでに構築されたものこそ、セッションを最初から始めるときに最も必要とされる情報であり、それを探すために2回目の呼び出しをする人はいません（AIR-090）。ただし、これはあくまで報告内容の記録です。ボードが示すのはエージェントの報告であり、証拠はコードです。
• タスクの 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（タイムゾーンなし）で設定します。started_at は最初に in_progress へ遷移したとき、completed_at は done になったときに設定されます（タスクが done でなくなった場合は削除されます）。エージェントがこれらを記入することはありません。
• 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 になります。

すべての変更は書き込み前に検証されます。無効な変更は、エラー一覧全体とともに拒否されます。close_period は、todo または in_progress のタスクが残っている間は処理を拒否します。プロジェクトごとに書き込みをシリアル化するため、同時に接続するクライアントが ID の競合や更新の消失を引き起こすことはありません。

セルフホスティング

同じパッケージは、常時稼働する HTTP サーバー（fronyboard serve）としても実行できます。ネットワーク上のすべてのマシン向けにストリーミング可能な HTTP 経由で MCP を提供し、人間向けの読み取り専用ウェブダッシュボード、デバイスごとの 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（ベアラーミドルウェア）、fauth.py（FronyAuth クライアント）、log.py、web.py（JSON API と静的ファイルの配信）、server.py（MCP ツールのインターフェースと CLI）が含まれます。frontend/ はダッシュボード（React + Vite）で、バックエンドが配信する静的ファイルとしてビルドされます。ビルド出力の frontend/dist はコミットされているため、サーバーに Node のツールチェーンは不要です。

docs/ にある3つのドキュメントでは、コードだけでは分からない、自分のマシン上でこのサービスを運用する方法を説明しています。

• docs/self-hosting.md — FronyBoard を共有サーバーとして運用する方法：クライアント、ダッシュボード、ホストアプリ、デプロイ
• docs/operations.md — ホームサーバーの運用手順