famboard

famboard

famboard は、Familia のホステッド MCP サーバーへの小規模なローカルブリッジです。Familia は、家庭で共有するスケジュール、タスク、チェックリスト、予定、添付ファイルを管理するプランナーです。

このブリッジは家庭のデータを保持せず、独自に予定を立てることもありません。稼働中のエンドポイントから取得した上流サーバーのツール一覧を、そのままローカルで提供し、各ツール呼び出しを上流へ転送して、結果を変更せずに返します。読み取りも書き込みも同じ経路を通ります。famboard を通じてタスクを作成したり予定を編集したりすると、呼び出し元自身の家庭について、Familia 上でタスクを作成したり予定を編集したりすることになります。

ツール

スケジュールと概要の読み取り：

• familia_list_households — 呼び出し元が利用できる家庭、家族、共有ボードの一覧。メンバー名とユーザー ID も含まれます。引数はありません。
• familia_list_household_members — 1 つの家庭のアクティブなメンバーと保留中のメンバー。必須：householdId。
• familia_get_day_overview — 日付または期間のタスク、予定、カレンダーイベント。
• familia_get_today_schedule — 今日の予定一覧。期限超過の概要も含まれます。
• familia_get_tomorrow_schedule — 明日の予定一覧。期限超過の概要も含まれます。
• familia_get_next_up — 個人または家庭の範囲における、次に予定されている項目。
• familia_get_weekly_overview — 1～14 日間の複数日にわたる計画概要。
• familia_get_inbox — 対応が必要な項目。
• familia_list_past_due — 期限超過のタスクや未完了の残件。カレンダーイベントは含まれません。
• familia_search_items — テキストでタスク、予定、カレンダーイベントを検索します。必須：query。
• familia_find_free_days — 利用を妨げる予定がない連続した日を検索します。必須の引数はありません。

タスクと予定：

• familia_create_task — 責任に基づくタスク、家事、リマインダーを作成します。繰り返しやチェックリストを設定することもできます。必須：householdId、title。
• familia_create_list_task — 買い物リスト、持ち物リスト、その他のチェックリストタスクを作成します。必須：householdId、title、items。
• familia_create_plan — イベント、旅行、学校行事、休暇などの予定項目を作成します。必須： householdId、title。
• familia_update_task — タスクの名前変更、日程変更、担当者の変更、完了を行います。必須：agreementId。
• familia_cancel_task — タスクの記録を削除せずにキャンセルします。必須：agreementId。
• familia_delete_task — タスクを完全に削除します。必須：agreementId。
• familia_update_plan — 予定のタイトル、スケジュール、場所、参加者、リンクされたタスクを編集します。必須： planItemId。
• familia_delete_plan — 予定項目を削除します。必須： planItemId。
• familia_batch_write — タスク、リストタスク、予定、添付ファイルへの複数の書き込みを、順序どおりに一括実行します。必須： operations。

添付ファイル：

• familia_list_attachments — タスクまたは予定に添付された写真やリスト。必須：targetType、targetId。
• familia_attach_image — JPEG、PNG、WebP 画像をタスクまたは予定に添付します。必須：targetType、 targetId。
• familia_create_list_attachment — タスクまたは予定に新しいチェックリストを追加します。必須：targetType、targetId、 items。
• familia_update_list_attachment — 既存のリスト添付ファイルの内容を置き換えます。必須： attachmentId、items。
• familia_delete_attachment — 写真またはリストの添付ファイルを削除します。必須：attachmentId。

設定

• FAMILIA_MCP_URL（任意）— 上流エンドポイントを上書きします。デフォルトは https://mcp.family.asynq.org/mcp です。 （この上書き用フックは、この再構築で独自に追加したものとして明示されています。）
• FAMILIA_API_KEY（任意）— 設定すると、すべての上流リクエストに Authorization: Bearer <key> ヘッダーが付加されます。設定されていない場合、認証ヘッダーは送信されません。（この転送機能も、再構築で追加したものとして明示されています。元のインターフェースはキーなしで取得されました。）

転送の仕組み

最初のツール呼び出しで、クライアントはアップストリームとのストリーミング可能な HTTP セッションを開きます。JSON-RPC の initialize リクエスト（protocolVersion 2025-03-26、clientInfo の name famboard）、続いて notifications/initialized 通知、その後、呼び出し元の引数を変更せずに渡す tools/call リクエストを送信します。アップストリームが Mcp-Session-Id ヘッダーを付けて initialize に応答すると、 その値はセッションの以降のすべてのリクエストに引き継がれ、 プロセスの存続期間中は同じセッションが再利用されます。応答は 通常の JSON またはサーバー送信イベントとして届く場合があり、 どちらも読み取られます。

アップストリームが成功した結果は、アップストリームが設定した isError フラグも含め、そのまま渡されます。 JSON-RPC エラー、2xx 以外のステータス、読み取り不能な応答、 完了できないリクエストといった失敗は、テキストが famboard error: で始まる isError 結果として返されます（この表示は この再構築で独自に付けたラベルです）。

CLI

各ツールは、1 つの JSON 引数文字列を受け取るサブコマンドでもあります （引数が不要なツールでは省略します）。

npx @reneturcios/famboard familia_list_households
npx @reneturcios/famboard familia_search_items '{"query":"dentist"}'
npx @reneturcios/famboard familia_create_task '{"householdId":"hh-1","title":"Take bins out"}'
npx @reneturcios/famboard --version

終了コード：成功時は 0、isError 結果の場合は 1、使用方法に誤りがある場合は 2 です。

MCP サーバー

npx -y @reneturcios/famboard mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "famboard": {
      "command": "npx",
      "args": ["-y", "@reneturcios/famboard", "mcp"]
    }
  }
}

Docker

docker run -i ghcr.io/cloudcorprecords/famboard
docker run --rm ghcr.io/cloudcorprecords/famboard --version

コンテナーのデフォルトコマンドは mcp なので、最初の形式は stdio MCP サーバーとして動作します。それ以外の引数は通常どおり CLI に渡されます。

開発

npm install
npm run build
npm test
npm run dev

テストスイートは、スタブ化された JSON-RPC アップストリームに対してのみ実行されます。実際のネットワーク呼び出しはありません。

ライセンス

MIT — LICENSE を参照してください。