内容
# skylight-mcp
[](https://github.com/chrischall/skylight-mcp/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/skylight-mcp)
[](LICENSE)
适用于 [Skylight 日历](https://www.ourskylight.com) 的 MCP 服务器 — 涵盖 102 种工具，支持日历事件（读写）、共享列表（读写）、家务和奖励（读写）、任务盒项目（读写）、餐食（读写）、AI 自动创建（餐食计划 + 活动创意生成器，支持草稿审查/批准）、消息和相册（读写），以及框架/设备/账户设置 + 日历 + 成员管理（读写）。
每个 API 请求都携带 `skylight-api-version: 2026-05-01` 头部（与官方移动应用匹配）；如果没有这个头部，部分功能将返回 422 错误，提示“API 版本不支持 …”。
## 认证
服务器使用无头邮箱+密码 OAuth2 授权码流程 — 无 SSO、无 2FA、无浏览器扩展要求。凭证始终为 `SKYLIGHT_EMAIL` + `SKYLIGHT_PASSWORD`。
在首次调用工具时，服务器会对 `https://app.ourskylight.com` 执行四个步骤：
1. `GET /auth/session/new` — 获取 Rails CSRF token 和 session cookie。
2. `POST /auth/session` — 使用邮箱 + 密码登录（必须在 OAuth 授权之前）。
3. `GET /oauth/authorize` — 通过重定向接收一次性授权码。
4. `POST /oauth/token` — 将授权码兑换为 bearer `access_token` + `refresh_token`（7 天有效期）。
客户端然后会主动刷新 token（在过期前约 60 秒）和被动地在任何 401 错误时刷新 token。没有观察到机器人墙 — 无头流程直接从 Node.js 工作。
**无环境变量 → 清洁启动：** 如果凭证未设置，服务器仍会启动而不会报错。认证将被推迟到第一个工具调用，因此 MCP 主机可以在凭证配置完成之前完成安装时的工具列表。
## 框架模型
Skylight 中的所有数据都限定在 *框架*（家庭中心设备）内。首次使用时，客户端会自动发现账户上的单个框架。如果账户有多个框架，请设置 `SKYLIGHT_FRAME_ID` 为所需的框架 ID。所有读取框架范围数据的工具都接受可选的 `frameId` 参数来覆盖默认值。
## 工具
| 模块 | 工具 | 读写权限 | 描述 |
|---|---|---|---|
| frames | `skylight_list_frames` | 只读 | 列出账户上的所有框架 |
| frames | `skylight_get_frame` | 只读 | 获取特定框架的详细信息 |
| frames | `skylight_list_frame_members` | 只读 | 列出与框架关联的成员 |
| frames | `skylight_list_devices` | 只读 | 列出链接到框架的物理设备 |
| frames | `skylight_get_plus_access` | 只读 | 获取 Skylight Plus 订阅/权益状态 |
| frames | `skylight_get_reward_points` | 只读 | 获取每个家庭成员的奖励积分余额 |
| frames | `skylight_get_household_config` | 只读 | 获取框架的家庭配置 |
| frames | `skylight_list_calendars` | 只读 | 列出框架的日历账户和活动日历 |
| frames | `skylight_get_event_notification_settings` | 只读 | 获取框架的日历事件通知设置 |
| frames | `skylight_resolve_member` | 只读 | 将家庭成员名称解析为其类别 ID |
| frames | `skylight_get_calendar` | 只读 | 获取单个日历账户 |
| frames | `skylight_list_nudges` | 只读 | 列出指定日期范围内的提醒（nudges） |
| frames | `skylight_update_frame` | 读写 | 更新框架的显示/睡眠设置 |
| frames | `skylight_rename_frame` | 读写 | 重命名框架 |
| frames | `skylight_update_profile` | 读写 | 更新框架配置文件（名称、生日） |
| frames | `skylight_update_household_config` | 读写 | 更新家庭配置 |
| frames | `skylight_set_reminder_profile` | 读写 | 设置全局提醒节奏（interval_weeks） |
| frames | `skylight_add_webcal` | 读写 | 订阅框架到 webcal/ICS 日历 URL |
| frames | `skylight_update_calendar` | 读写 | 设置连接账户的哪些子日历是活动的 |
| frames | `skylight_delete_source_calendar` | 读写 | 删除连接的源日历（包括 webcal 订阅） |
| frames | `skylight_set_default_calendar` | 读写 | 设置新事件的默认源日历 |
| frames | `skylight_link_apple_calendar` | 读写 | 使用应用特定密码链接 Apple/iCloud 日历 |
| frames | `skylight_categorize_source_calendar` | 读写 | 将源日历的事件归因于一个或多个家庭成员 |
| frames | `skylight_create_source_calendar` | 读写 | 从原始提供程序属性创建源日历（高级） |
| frames | `skylight_invite_user` | 读写 | 通过电子邮件邀请用户加入框架 |
| frames | `skylight_approve_user` | 读写 | 批准待处理的框架用户 |
| frames | `skylight_remove_user` | 读写 | 从框架中删除用户 |
| frames | `skylight_delete_category` | 读写 | 删除类别/家庭成员（可选 `reassign_to_category_id`，推断） |
| frames | `skylight_update_family_member` | 读写 | 更新家庭成员的配置文件 — 生日、饮食偏好（名称是类别标签；通过 `skylight_update_category` 设置） |
| frames | `skylight_update_category` | 读写 | 更新类别 — 重命名/重新着色，或将标签转换为家庭成员配置文件（`linked_to_profile`） |
| frames | `skylight_set_device_album` | 读写 | 设置设备显示哪个照片相册（推断） |
| frames | `skylight_rename_device` | 读写 | 重命名 Skylight 设备 |
| events | `skylight_list_events` | 只读 | 列出指定日期范围内的日历事件 |
| events | `skylight_get_event` | 只读 | 获取特定事件的详细信息 |
| events | `skylight_create_event` | 读写 | 创建新的日历事件（可选 `category_ids` 分配成员） |
| events | `skylight_update_event` | 读写 | 更新现有的日历事件（可选 `category_ids` 分配成员） |
| events | `skylight_delete_event` | 读写 | 删除日历事件 |
| events | `skylight_list_categories` | 只读 | 列出框架的事件类别 |
| events | `skylight_list_source_calendars` | 只读 | 列出链接到框架的外部源日历 |
| events | `skylight_list_recent_invited_emails` | 只读 | 列出最近邀请的电子邮件地址 |
| events | `skylight_update_event_notification_settings` | 读写 | 更新日历事件通知设置 |
| lists | `skylight_list_lists` | 只读 | 列出框架上的所有共享列表 |
| lists | `skylight_get_list_items` | 只读 | 获取特定共享列表中的项目 |
| lists | `skylight_create_list` | 读写 | 创建新的共享列表（标签 + 颜色 + 类型） |
| lists | `skylight_update_list` | 读写 | 更新列表的名称、颜色或类型 |
| lists | `skylight_delete_list` | 读写 | 删除共享列表 |
| lists | `skylight_add_list_item` | 读写 | 向共享列表添加项目 |
| lists | `skylight_update_list_item` | 读写 | 重命名列表项目、标记/取消标记或设置其部分 |
| lists | `skylight_delete_list_item` | 读写 | 从共享列表中删除项目 |
| lists | `skylight_delete_list_items` | 读写 | 批量删除特定列表项目 |
| lists | `skylight_move_list_item` | 读写 | 重新排序列表项目 |
| lists | `skylight_clear_list` | 读写 | 删除列表中的所有项目（单个批量删除） |
| lists | `skylight_set_list_item_section` | 读写 | 将列表项目移动到命名部分（或清除） |
| chores | `skylight_list_chores` | 只读 | 列出指定日期范围内的家务 |
| chores | `skylight_search_chores` | 只读 | 搜索家务（包括未计划/模板家务） |
| chores | `skylight_create_chore` | 读写 | 创建新的家务（摘要 + 类别） |
| chores | `skylight_create_recurring_chore` | 读写 | 创建重复家务或例行程序（RRULE） |
| chores | `skylight_complete_chore` | 读写 | 标记家务完成 |
| chores | `skylight_uncomplete_chore` | 读写 | 重新打开（取消完成）家务 |
| chores | `skylight_update_chore` | 读写 | 更新家务（支持重复 + `apply_to`） |
| chores | `skylight_complete_chore_instance` | 读写 | 标记特定重复家务实例完成 |
| chores | `skylight_delete_chore` | 读写 | 删除家务（实例或整个系列通过 `apply_to`） |
| chores | `skylight_list_rewards` | 只读 | 列出为框架配置的奖励 |
| rewards | `skylight_get_reward` | 只读 | 获取一个奖励 |
| rewards | `skylight_create_reward` | 读写 | 创建奖励（名称 + 描述 + point_value + respawn_on_redemption + category_ids） |
| rewards | `skylight_update_reward` | 读写 | 更新奖励 |
| rewards | `skylight_delete_reward` | 读写 | 删除奖励 |
| rewards | `skylight_redeem_reward` | 读写 | 兑换奖励 |
| rewards | `skylight_unredeem_reward` | 读写 | 撤销奖励兑换 |
| rewards | `skylight_add_reward_points` | 读写 | 向成员授予或扣除奖励积分 |
| meals | `skylight_list_recipes` | 只读 | 列出框架的餐食配方 |
| meals | `skylight_list_meal_categories` | 只读 | 列出框架的餐食类别 |
| meals | `skylight_get_recipe` | 只读 | 获取一个餐食配方 |
| meals | `skylight_create_recipe` | 读写 | 创建餐食配方（meal_category_id + 摘要） |
| meals | `skylight_update_recipe` | 读写 | 更新餐食配方 |
| meals | `skylight_delete_recipe` | 读写 | 删除餐食配方 |
| meals | `skylight_add_recipe_to_grocery_list` | 读写 | 将餐食配方的食材添加到购物清单 |
| meals | `skylight_plan_meal` | 读写 | 在日期上计划餐食（可选重复，链接配方，添加到购物清单） |
| messages | `skylight_list_messages` | 只读 | 列出发送到框架的消息 |
| messages | `skylight_list_albums` | 只读 | 列出框架上的照片相册 |
| messages | `skylight_get_message` | 只读 | 获取一个框架消息 |
| messages | `skylight_create_album` | 读写 | 创建照片相册 |
| messages | `skylight_update_album` | 读写 | 更新照片相册（重命名，隐藏在幻灯片中） |
| messages | `skylight_delete_album` | 读写 | 删除照片相册 |
| messages | `skylight_add_to_album` | 读写 | 将消息/照片添加到相册 |
| messages | `skylight_remove_from_album` | 读写 | 从相册中删除消息/照片 |
| messages | `skylight_add_message_comment` | 读写 | 评论框架消息/照片 |
| messages | `skylight_set_message_caption` | 读写 | 设置消息/照片的标题 |
| messages | `skylight_like_message` | 读写 | 点赞框架消息/照片 |
| messages | `skylight_unlike_message` | 读写 | 取消点赞消息/照片 |
| messages | `skylight_delete_message` | 读写 | 删除框架消息/照片 |
| messages | `skylight_delete_messages` | 读写 | 批量删除框架中的消息/照片 |
| tasks | `skylight_list_tasks` | 只读 | 列出任务盒项目 |
| tasks | `skylight_create_task` | 读写 | 创建任务盒项目 |
| tasks | `skylight_update_task` | 读写 | 更新任务盒项目 |
| tasks | `skylight_delete_task` | 读写 | 删除任务盒项目 |
| ai | `skylight_generate_meal_plan` | 读写 | 为给定日期生成 AI 餐食计划（草稿餐食安排 — 异步） |
| ai | `skylight_generate_activity_ideas` | 读写 | 为位置 + 时间范围生成 AI 活动/事件创意（草稿事件 — 异步） |
| ai | `skylight_get_auto_creation_intent` | 只读 | 获取 AI 自动创建意图（状态 + 草稿结果） |
| ai | `skylight_list_auto_creation_drafts` | 只读 | 列出 AI 意图草拟的事件（在批准前审查） |
| ai | `skylight_approve_auto_creation` | 读写 | 将 AI 草拟的事件批准为真实日历事件 |
| ai | `skylight_undo_auto_creation` | 读写 | 撤销/丢弃 AI 自动创建意图及其草稿 |
## 配置
### 必需
```
SKYLIGHT_EMAIL=you@example.com
SKYLIGHT_PASSWORD=your-password
```
### 可选
| 环境变量 | 默认值 | 用途 |
|---|---|---|
| `SKYLIGHT_FRAME_ID` | 自动发现 | 在账户有多个框架时强制使用特定框架 |
| `SKYLIGHT_NAME` | *(无)* | 用于启动日志的友好标签 |
| `SKYLIGHT_BASE_URL` | `https://app.ourskylight.com/api` | 重写 API 基本 URL |
将 `.env` 文件视为密码文件 — 它被 gitignore，请勿提交。
## 本地开发
```
npm install
npm run build
npm test
npm run dev # 需要带有凭证的 .env 文件
```
测试：vitest，100% 行/分支/函数/语句覆盖率强制执行。所有测试都是模拟的 — CI 中无网络调用。
由 AI (Claude) 开发和维护。请自行判断使用。
连接信息
猜你喜欢
暂无推荐服务器