skylight-mcp

skylight-mcp

适用于 Skylight Calendar 的 MCP 服务，提供 114 个工具，涵盖日历事件（读写）、共享列表（读写）、家务和奖励（读写）、任务盒项目（读写）、餐食（读写）、AI 自动创建（餐食计划和活动创意生成器，支持草稿审核/批准）、消息和相册（读写）、照片/视频上传，以及相框/设备/账户设置、日历和成员管理（读写，包括预设头像和自定义照片头像）。

每个 API 请求都会携带 skylight-api-version: 2026-05-01 标头（与官方移动应用一致）；缺少该标头时，部分功能会返回 422 错误，提示“API version does not support …”。

MCP 协议支持

该服务使用官方 TypeScript SDK v2，并通过 stdio 支持无状态的 2026-07-28 协议修订版。客户端无需初始化握手即可发现和调用工具。现有客户端仍可使用 2025-11-25 握手。

传输方式仍为 stdio。宿主可以通过经过身份验证的 HTTP 对外提供服务。此软件包不会打开网络监听端口。

身份验证

该服务采用无头的电子邮件地址+密码 OAuth2 授权码流程，无需 SSO、2FA 或浏览器扩展。若你已有令牌，请使用 SKYLIGHT_REFRESH_TOKEN 进行配置；也可以使用 SKYLIGHT_EMAIL + SKYLIGHT_PASSWORD 登录并获取令牌。

首次调用工具时，服务会向 https://app.ourskylight.com 执行以下四个步骤：

1. GET /auth/session/new — 获取 Rails CSRF 令牌和会话 Cookie。
2. POST /auth/session — 使用电子邮件地址 + 密码登录（必须先于 OAuth 授权）。
3. GET /oauth/authorize — 发送 S256 PKCE code_challenge（服务要求提供），并通过重定向接收一次性授权码。
4. POST /oauth/token — 使用授权码和匹配的 code_verifier 换取 bearer access_token + refresh_token（目前有效期为 24 小时；客户端会读取返回的 expires_in，而非假定固定时长）。

OAuth 重定向会始终留在身份验证来源站点内。相对重定向会根据当前 URL 解析。配置的回调会提供授权码，但不会接收请求或会话 Cookie。遇到意外目标时，流程会失败，且错误中不会包含重定向 URL。

随后，客户端会主动刷新令牌（约在令牌过期前 60 秒），并在任何 401 错误时立即刷新。目前尚未观察到机器人防护墙，无头流程可直接通过 Node 运行。

**未设置环境变量 → 正常启动：**如果没有设置凭据，服务仍会正常启动，不会报错。身份验证会延迟到首次调用工具时进行，因此 MCP 宿主可以先完成安装时的工具列表读取，再配置凭据。

在自己的代码中使用身份验证辅助函数

该软件包还导出了 Skylight 的会话登录和令牌刷新功能，因此独立程序无需复制 src/ 即可进行身份验证：

import { login, refresh } from 'skylight-mcp/auth';

const tokens = await login({
  authBaseUrl: 'https://app.ourskylight.com',
  email: process.env.SKYLIGHT_EMAIL!,
  password: process.env.SKYLIGHT_PASSWORD!,
});
// Skylight rotates refresh tokens: store the one each call returns.
const next = await refresh({ authBaseUrl: 'https://app.ourskylight.com', refreshToken: tokens.refreshToken });

这是唯一的库入口；软件包中的其他内容均属于 MCP 服务。该软件包仅支持 ESM，并附带类型声明。

相框模型

Skylight 中的所有数据都归属于一个相框（家庭中心设备）。首次使用时，客户端会自动发现账户中的唯一相框。如果账户中有多个相框，请将 SKYLIGHT_FRAME_ID 设置为所需相框的 ID。每个读取相框范围数据的工具都接受可选的 frameId 参数，用于覆盖默认值。

工具

模块	工具	读/写	描述
frames	skylight_list_frames	R	列出账户上的所有相框
frames	skylight_get_frame	R	获取特定相框的详细信息
frames	skylight_list_frame_members	R	列出与相框关联的成员
frames	skylight_list_devices	R	列出关联到相框的实体设备
frames	skylight_get_plus_access	R	获取 Skylight Plus 订阅／权益状态
frames	skylight_get_reward_points	R	获取每位家庭成员的奖励积分余额
frames	skylight_get_household_config	R	获取相框的家庭配置
frames	skylight_list_calendars	R	列出相框的日历账户和启用的日历
frames	skylight_get_event_notification_settings	R	获取相框的日历事件通知设置
frames	skylight_resolve_member	R	将家庭成员姓名解析为其类别 ID
frames	skylight_get_calendar	R	获取一个日历账户
frames	skylight_list_nudges	R	列出指定日期范围内的提醒
frames	skylight_update_frame	W	更新相框显示／休眠设置
frames	skylight_rename_frame	W	重命名相框
frames	skylight_update_profile	W	更新相框个人资料（姓名、生日）
frames	skylight_update_household_config	W	更新家庭配置
frames	skylight_set_reminder_profile	W	设置全局提醒频率（interval_weeks）
frames	skylight_add_webcal	W	让相框订阅 webcal／ICS 日历 URL
frames	skylight_update_calendar	W	设置已连接账户中启用哪些子日历
frames	skylight_delete_source_calendar	W	移除已连接的源日历（包括 webcal 订阅）
frames	skylight_set_default_calendar	W	设置新事件的默认源日历
frames	skylight_link_apple_calendar	W	关联 Apple／iCloud 日历；应用专用密码从 SKYLIGHT_APPLE_APP_PASSWORD 获取，不会作为工具参数传入（需确认）
frames	skylight_categorize_source_calendar	W	将源日历的事件归属到一位或多位家庭成员
frames	skylight_create_source_calendar	W	根据原始提供方属性创建源日历（高级）
frames	skylight_invite_user	W	通过电子邮件邀请用户加入相框（需确认）
frames	skylight_approve_user	W	批准待处理的相框用户（需确认）
frames	skylight_remove_user	W	从相框中移除用户（需确认；预览中会显示成员姓名）
frames	skylight_delete_category	W	删除类别／家庭成员（可选 reassign_to_category_id，推断；需确认，预览中会显示成员姓名）
frames	skylight_update_family_member	W	更新家庭成员的个人资料——生日、饮食偏好（姓名即类别标签；通过 skylight_update_category 设置）
frames	skylight_update_category	W	更新类别——重命名／更改颜色，或将标签转换为家庭成员个人资料（linked_to_profile）
frames	skylight_create_category	W	创建类别／家庭成员（可选 linked_to_profile、avatar_id）
frames	skylight_list_avatars	R	列出预设头像库（表情符号／图标图片）
frames	skylight_set_member_avatar	W	将家庭成员的头像设置为自定义照片（需确认）
frames	skylight_set_device_album	W	设置设备显示哪个相册（推断）
frames	skylight_rename_device	W	重命名 Skylight 设备
events	skylight_list_events	R	列出指定日期范围内的日历事件
events	skylight_get_event	R	获取特定事件的详细信息
events	skylight_create_event	W	创建新的日历事件（可选 category_ids，用于分配成员；设置 invited_emails 时需确认，预览中会列出所有收件人）
events	skylight_update_event	W	更新现有日历事件（可选 category_ids，用于分配成员；设置 invited_emails 时需确认）
events	skylight_delete_event	W	删除日历事件
events	skylight_list_categories	R	列出相框的事件类别
events	skylight_list_source_calendars	R	列出关联到相框的外部源日历
events	skylight_list_recent_invited_emails	R	列出最近邀请过的电子邮件地址
events	skylight_update_event_notification_settings	W	更新日历事件通知设置
lists	skylight_list_lists	R	列出相框上的所有共享清单
lists	skylight_get_list_items	R	获取特定共享清单中的项目
lists	skylight_create_list	W	创建新的共享清单（标签 + 颜色 + 类型）
lists	skylight_update_list	W	更新清单的名称、颜色或类型
lists	skylight_delete_list	W	删除共享清单及其项目（清单中有项目时需确认；预览中会列出这些项目）
lists	skylight_add_list_item	W	向共享清单添加项目
lists	skylight_update_list_item	W	重命名清单项目、勾选／取消勾选项目，或设置其分区
lists	skylight_delete_list_item	W	从共享清单中删除项目
lists	skylight_delete_list_items	W	批量删除指定清单项目
lists	skylight_move_list_item	W	调整清单项目的顺序
lists	skylight_clear_list	W	移除清单中的所有项目（一次批量删除；需确认，预览中会列出这些项目）
lists	skylight_set_list_item_section	W	将清单项目移至指定名称的分区（或清除分区）
chores	skylight_list_chores	R	列出指定日期范围内的家务任务
chores	skylight_search_chores	R	搜索家务任务（包括未安排时间／模板任务）
chores	skylight_create_chore	W	创建新的家务任务（摘要 + 类别）
chores	skylight_create_recurring_chore	W	创建重复家务任务或例行事项（RRULE）
chores	skylight_complete_chore	W	将家务任务标记为已完成
chores	skylight_uncomplete_chore	W	重新打开家务任务（取消完成状态）
chores	skylight_update_chore	W	更新家务任务（支持重复规则 + apply_to）
chores	skylight_complete_chore_instance	W	将某次重复家务任务标记为已完成
chores	skylight_delete_chore	W	删除家务任务（通过 apply_to 指定某次任务或整个系列）
chores	skylight_list_rewards	R	列出为相框配置的奖励
rewards	skylight_get_reward	R	获取一项奖励
rewards	skylight_create_reward	W	创建奖励（名称 + 描述 + 积分值 + 兑换后是否重新生成 + category_ids）
rewards	skylight_update_reward	W	更新奖励
rewards	skylight_delete_reward	W	删除奖励
rewards	skylight_redeem_reward	W	兑换奖励
rewards	skylight_unredeem_reward	W	撤销奖励兑换
rewards	skylight_add_reward_points	W	向成员发放或扣除奖励积分
meals	skylight_list_meals	R	列出指定日期范围内的计划餐食（date_min 和 date_max 均为必填项）
meals	skylight_list_recipes	R	列出相框的餐食食谱
meals	skylight_list_meal_categories	R	列出相框的餐食类别
meals	skylight_get_recipe	R	获取一份餐食食谱
meals	skylight_create_recipe	W	创建餐食食谱（meal_category_id + 摘要）
meals	skylight_update_recipe	W	更新餐食食谱
meals	skylight_delete_recipe	W	删除餐食食谱
meals	skylight_add_recipe_to_grocery_list	W	将食谱的食材添加到购物清单
meals	skylight_plan_meal	W	计划某日的餐食（可选择重复、关联食谱、添加到购物清单）
meals	skylight_update_meal	W	在选定的重复范围内更新计划餐食（名称、食谱、时段、备注、日期、重复规则）
meals	skylight_delete_meal	W	移除计划餐食——单次、此后所有餐食或整个系列（需确认）
messages	skylight_list_messages	R	列出发布到相框的消息（读取分页动态流，最多 20 页）
messages	skylight_list_albums	R	列出相框上的相册
messages	skylight_get_message	R	获取一条相框消息
messages	skylight_create_album	W	创建相册
messages	skylight_update_album	W	更新相册（重命名、从幻灯片播放中隐藏）
messages	skylight_delete_album	W	删除相册
messages	skylight_add_to_album	W	将消息／照片添加到相册
messages	skylight_remove_from_album	W	从相册中移除消息／照片
messages	skylight_copy_messages_to_frames	W	将消息／照片复制到账户上的其他相框（推断）
messages	skylight_add_message_comment	W	评论相框消息／照片
messages	skylight_set_message_caption	W	设置消息／照片说明
messages	skylight_like_message	W	为相框消息／照片点赞
messages	skylight_unlike_message	W	取消对消息／照片的点赞
messages	skylight_delete_message	W	删除相框消息／照片
messages	skylight_delete_messages	W	批量删除相框中的消息／照片（需确认，预览中会逐一列出 ID 及其说明）
tasks	skylight_list_tasks	R	列出任务盒项目
tasks	skylight_create_task	W	创建任务盒项目
tasks	skylight_update_task	W	更新任务盒项目
tasks	skylight_delete_task	W	删除任务盒项目
ai	skylight_generate_meal_plan	W	为指定日期生成 AI 餐食计划（草拟餐食安排——异步）
ai	skylight_generate_activity_ideas	W	为指定地点和时间范围生成 AI 活动／事件创意（草拟事件——异步）
ai	skylight_get_auto_creation_intent	R	获取 AI 自动创建意图（状态 + 草稿结果）
ai	skylight_list_auto_creation_drafts	R	列出 AI 意图草拟的事件（批准前请先审核）
ai	skylight_list_auto_creation_intents	R	列出相框上的所有 AI 自动创建意图
ai	skylight_list_auto_creation_items	R	列出 AI 意图创建的所有草稿项目（餐食、活动、清单项目）
ai	skylight_approve_auto_creation	W	将 AI 草拟的事件批准并加入实际日历
ai	skylight_undo_auto_creation	W	撤销／丢弃 AI 自动创建意图及其草稿
photos	skylight_upload_photo	W	从本地文件向相框上传照片／视频（需确认）
photos	skylight_import_events_from_photo	W	使用 Skylight 的 AI 从传单／邀请函照片中导入日历事件（尽力而为；需确认）
health	skylight_healthcheck	R	报告连接器是否正常工作：解析到的凭据、Skylight 是否接受该凭据，以及需要修复的内容

配置

必填 — 以下二选一

你已有的刷新令牌（推荐：权限范围有限、可撤销，且不会触及受速率限制的登录端点）：

SKYLIGHT_REFRESH_TOKEN=your-refresh-token

或登录凭据对，系统会为你生成刷新令牌：

[email protected]
SKYLIGHT_PASSWORD=your-password

同时设置两者也有效，而且是最稳妥的配置：优先使用令牌；如果令牌已过期，则会静默登录并生成替代令牌。仅使用令牌时，过期令牌会被报告为已过期——服务会明确说明，而不会声称尚未配置。

提供的刷新令牌只能使用一次。 Skylight 每次使用刷新令牌时都会轮换令牌，因此服务首次启动时会用掉 SKYLIGHT_REFRESH_TOKEN，并继续使用轮换后的令牌——该令牌仅保存在令牌缓存中。仅使用令牌时，请确保缓存已启用且可写，并且切勿在两台主机间共用一个令牌：如果启动时发现环境变量中的令牌已被使用，就无法在没有登录凭据对的情况下恢复。

可选

环境变量	默认值	用途
SKYLIGHT_FRAME_ID	自动发现	账户有多个相框时，指定要使用的相框
SKYLIGHT_NAME	（无）	用于启动日志的易读名称
SKYLIGHT_BASE_URL	https://app.ourskylight.com/api	覆盖 API 基础 URL
SKYLIGHT_APPLE_APP_PASSWORD	（无）	应用专用密码（来自 appleid.apple.com），由 skylight_link_apple_calendar 发送给 Skylight。根据设计，此密码只能通过环境变量提供：它不会作为工具参数，因此不会经过模型、对话记录或主机的工具调用日志
SKYLIGHT_APPLE_ID	（无）	skylight_link_apple_calendar 使用的 Apple ID 邮箱；工具的 email 参数会覆盖此值
SKYLIGHT_UPLOAD_DIR	~/Pictures 和 ~/Downloads（托管环境：仅 $MCP_DATA_DIR/uploads）	skylight_upload_photo、skylight_import_events_from_photo 和 skylight_set_member_avatar 可从中上传文件的目录（多个目录以 : 分隔，Windows 上以 ; 分隔；允许使用 ~）。任何其他路径都会在确认预览前被拒绝；打开文件时，确认后的读取操作会再次检查路径。始终启用路径限制：未设置时使用默认目录，而非“任意位置”（同时始终执行文件类型、隐藏文件、符号链接、大小和内容检查）

请像对待密码文件一样对待 .env——它已加入 gitignore，请勿提交。

确认

部分写入操作会在执行前要求你确认：上传本地照片或头像；邀请、批准或移除用户；删除家庭成员；关联 Apple 日历；向公众开放相框；创建或更新包含 invited_emails 的活动（Skylight 会向每个地址发送电子邮件，预览中会列出这些地址）；批量删除（skylight_delete_messages、skylight_clear_list，以及对非空列表执行 skylight_delete_list），预览会列出所有将被删除的项目；以及 apply_to 范围超出指定单次事件的餐食或家务编辑、删除操作。能够显示确认提示的客户端（Claude Code）会显示提示，除非设置了 MCP_CONFIRM_ELICITATION=off。其他情况下，首次调用不会进行任何更改，并会返回将要发送内容的完整预览和一个 confirmToken；只有使用该令牌和相同参数再次调用，才会执行操作，而且仅执行一次。

变量	默认值
MCP_CONFIRM_MODE	ask-user	客户端无法显示确认提示（claude.ai、Claude Desktop）时，写入操作的处理方式。ask-user：分两步执行——首次调用不做任何更改，并返回预览和令牌；模型必须先在聊天中获得你的批准，才能再次携带令牌调用。auto：同样分两步执行，但模型查看预览后可以自行使用令牌。refuse：此类客户端上的写入操作会被拒绝。能够显示提示的客户端（Claude Code）始终会收到真正的提示，除非设置了 MCP_CONFIRM_ELICITATION=off。无法识别的值会按 refuse 处理。
MCP_CONFIRM_ELICITATION	on	off 表示绝不显示确认提示，因此所有客户端都会采用 MCP_CONFIRM_MODE 指定的处理方式。如果客户端声称支持提示但实际上从不显示提示（写入操作会卡住——opencode 2.0.x），请为该客户端设置此项。其他任何值都会保持为 on，并在 stderr 上显示警告。
MCP_CONFIRM_TTL_SECONDS	600	令牌的有效时长。
MCP_CONFIRM_SECRET	每个进程随机生成	签名密钥；仅当令牌必须在服务重启后继续有效时才设置。

令牌缓存

首次登录后，OAuth 令牌对会缓存在 $MCP_DATA_DIR/.skylight-mcp/tokens.json（若未设置则使用 $HOME），并以 0600 权限写入。之后启动时会复用该缓存，而不再重新执行四步登录流程——这很重要，因为 Skylight 的登录端点会限制请求频率，而缩容至零的托管服务会不断冷启动。

只会写入令牌；你的电子邮件地址和密码仍保存在环境中。 过期的缓存令牌会被刷新，而不是重新登录；如果服务器拒绝刷新令牌，则会改用全新登录，因此过期文件不会让你无法登录。

缓存会绑定到生成它的凭据——密码对或提供的 SKYLIGHT_REFRESH_TOKEN。轮换该凭据，或让服务改用其他账户时，缓存令牌会被丢弃，不再继续使用。文件中仅存储加盐摘要；不会写入电子邮件地址、密码或提供的令牌。

设置 SKYLIGHT_TOKEN_CACHE=false 可关闭缓存并在每次启动时登录；设置 SKYLIGHT_TOKEN_FILE 可指定缓存位置。

如果写入失败（数据目录为只读或空间已满），服务器会在 stderr 上记录错误，并继续使用内存中的令牌运行——只有下次启动时才会受到影响。使用登录凭据对时，这只意味着需要登录一次。若仅使用 SKYLIGHT_REFRESH_TOKEN，则会导致无法登录，因为 Skylight 会在首次使用时轮换该令牌，而轮换后的令牌将无法保存。因此，仅使用令牌的部署不会冒险使用该令牌：未提供登录凭据对时设置 SKYLIGHT_TOKEN_CACHE=false 属于配置错误；服务器会在首次刷新前检查缓存是否可写，若不可写则令牌不会被消耗，并会使调用失败。若通过检查后写入仍然失败，服务器会在 stderr 上明确报告。

本地开发

npm install
npm run build
npm test
npm run dev   # requires .env with credentials

测试：使用 vitest，并强制要求行、分支、函数和语句覆盖率均达到 100%。所有测试都使用模拟，不会在 CI 中发起网络请求。

由 AI（Claude）开发和维护。请自行斟酌使用。