famboard

famboard

famboard is a small local bridge to Familia's hosted MCP server, a planner that households share for their schedules, tasks, checklists, plans and attachments.

The bridge keeps no family data and plans nothing on its own. It serves the upstream server's tool list locally, exactly as captured from the live endpoint, and forwards each tool call upstream, returning the result untouched. Reads and writes alike travel that path: creating a task or editing a plan through famboard is creating or editing it in Familia itself, on the caller's own households.

Tools

Schedule and overview reads:

• familia_list_households — the households, families or shared boards available to the caller, with member names and user ids. No arguments.
• familia_list_household_members — active and pending members of one household. Required: householdId.
• familia_get_day_overview — tasks, plans and calendar events for a date or time window.
• familia_get_today_schedule — today's agenda, with an overdue summary.
• familia_get_tomorrow_schedule — tomorrow's agenda, with an overdue summary.
• familia_get_next_up — the next upcoming items, in personal or household scope.
• familia_get_weekly_overview — a multi-day planning overview, 1 to 14 days.
• familia_get_inbox — items needing attention.
• familia_list_past_due — overdue tasks and other unfinished leftovers; calendar events are excluded.
• familia_search_items — find tasks, plans and calendar events by text. Required: query.
• familia_find_free_days — runs of consecutive days without hard availability blockers. No required arguments.

Tasks and plans:

• familia_create_task — a responsibility-style task, chore or reminder, optionally recurring or carrying a checklist. Required: householdId, title.
• familia_create_list_task — a shopping list, packing list or other checklist task. Required: householdId, title, items.
• familia_create_plan — a plan item for an event, trip, school activity, holiday or similar. Required: householdId, title.
• familia_update_task — rename, reschedule, reassign or complete a task. Required: agreementId.
• familia_cancel_task — cancel a task without deleting its record. Required: agreementId.
• familia_delete_task — permanently delete a task. Required: agreementId.
• familia_update_plan — edit a plan's title, schedule, location, participants or linked tasks. Required: planItemId.
• familia_delete_plan — delete a plan item. Required: planItemId.
• familia_batch_write — run several task, list-task, plan or attachment writes as one ordered batch. Required: operations.

Attachments:

• familia_list_attachments — photos and lists attached to a task or plan. Required: targetType, targetId.
• familia_attach_image — attach a JPEG, PNG or WebP image to a task or plan. Required: targetType, targetId.
• familia_create_list_attachment — add a new checklist to a task or plan. Required: targetType, targetId, items.
• familia_update_list_attachment — replace the contents of an existing list attachment. Required: attachmentId, items.
• familia_delete_attachment — delete a photo or list attachment. Required: attachmentId.

Configuration

• FAMILIA_MCP_URL (optional) — override the upstream endpoint. Defaults to https://mcp.family.asynq.org/mcp. (The override hook is this rebuild's own labelled reconstruction.)
• FAMILIA_API_KEY (optional) — when set, every upstream request carries an Authorization: Bearer <key> header. When it is not set, no auth header is sent. (This forwarding is also a labelled reconstruction; the original surface was captured keyless.)

Forwarding mechanics

On the first tool call the client opens a streamable HTTP session with the upstream: a JSON-RPC initialize request (protocolVersion 2025-03-26, clientInfo name famboard), then a notifications/initialized notification, then the tools/call request carrying the caller's arguments unchanged. When the upstream answers initialize with an Mcp-Session-Id header, that value rides on every later request of the session, which is reused for the life of the process. Replies may arrive as plain JSON or as server-sent events; both are read.

Successful upstream results pass through verbatim, including any isError flag the upstream sets. Failures — a JSON-RPC error, a non-2xx status, an unreadable response, or a request that cannot be completed — come back as an isError result whose text starts with famboard error: (this rendering is this rebuild's own labelled reconstruction).

CLI

Each tool is also a subcommand taking one JSON argument string (omit it for tools that take none):

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

Exit codes: 0 on success, 1 on an isError result, 2 on a usage error.

MCP server

npx -y @reneturcios/famboard mcp

MCP client config:

{
  "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

The container's default command is mcp, so the first form is a stdio MCP server; any other arguments reach the CLI normally.

Development

npm install
npm run build
npm test
npm run dev

The test suite runs entirely against a stubbed JSON-RPC upstream — no live network calls.

License

MIT — see LICENSE.