famboard

famboard

famboard 是 Familia 托管 MCP 服务的轻量本地桥接程序。Familia 是家庭共享日程、任务、清单、计划和附件的规划工具。

该桥接程序不保存任何家庭数据，也不会自行制定计划。它会在本地提供上游服务工具列表，内容与从实时端点捕获的完全一致，并将每次工具调用转发至上游，原样返回结果。无论读取还是写入，都会经过同一路径：通过 famboard 创建任务或编辑计划，就意味着在 Familia 本身、在调用者自己的家庭中创建或编辑任务或计划。

工具

日程和概览读取：

• familia_list_households — 调用者可使用的家庭、家族或共享看板，以及成员姓名和用户 ID。不需要参数。
• familia_list_household_members — 一个家庭中的活跃成员和待加入成员。必填：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 请求。上游 通过 initialize 返回 Mcp-Session-Id 标头后， 该值会随此会话的每个后续请求发送，并在进程 的整个生命周期内复用。回复可能是纯 JSON，也可能是 服务器发送的事件；两种格式都会读取。

成功的上游结果会原样传递， 包括上游设置的任何 isError 标志。 失败情况——JSON-RPC 错误、非 2xx 状态码、无法读取的响应，或 无法完成的请求——会作为 isError 结果返回，其 文本以 famboard error: 开头（此呈现方式是 本次重建自行添加的标注）。

CLI

每个工具也可作为子命令使用，接受一个 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。