skylight-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

TL;DR

MCP server for Skylight Calendar — 114 tools across calendar events (read+write), shared lists (read+write), chores and rewards (read+write), task-box items (read+write), meals (read+write), AI auto-creation (meal-plan + activity-idea generators with draft review/approve), messages and albums (read+write), photo/video upload, and frame/device/account settings + calendar + member/category management (read+write, incl. preset and custom-photo avatars).

Every request carries the skylight-api-version: 2026-05-01 header (src/client.ts), matching the official mobile app — without it some features 422 with "API version does not support …".

Auth resolution lives in src/auth.ts. Two credentials are accepted: a SKYLIGHT_REFRESH_TOKEN you already hold (skips the login endpoint entirely), or SKYLIGHT_EMAIL + SKYLIGHT_PASSWORD, which mint one via a headless OAuth2 authorization-code flow (Node-direct). See "Auth resolution" below.

The login is lazy and cached: resolveAuth() hands SkylightClient a bootstrap function rather than tokens, and TokenManager runs it only when the on-disk cache (src/token-store.ts) has nothing usable. A cached live token costs nothing; a cached expired one costs a refresh; only an empty or unusable cache spends a login. This matters because the login endpoint rate-limits (see the refreshFn note below) and a scale-to-zero host makes every start a cold one.

Auth resolution

src/auth.ts prefers a supplied SKYLIGHT_REFRESH_TOKEN and otherwise runs the headless email+password OAuth2 authorization-code flow below; with both set, a stale token falls back to logging in again. (Skylight rejects grant_type=password with unsupported_grant_type; no browser-bridge proxy is needed — no observed bot wall.)

The flow resolveAuth() → login() performs all steps against https://app.ourskylight.com:

1. GET /auth/session/new — scrape the Rails authenticity_token, hold the _skylight_cloud_session cookie.
2. POST /auth/session (form: authenticity_token, email, password; Origin/Referer = app.ourskylight.com) — 302 to /auth/session/success on success. Login must happen before the OAuth authorize step — hitting authorize first poisons the CSRF/session state.
3. GET /oauth/authorize?client_id=skylight-mobile&response_type=code&scope=everything&redirect_uri=https://ourskylight.com/welcome&code_challenge=…&code_challenge_method=S256 — 302 to https://ourskylight.com/welcome?code=…. PKCE is mandatory: without code_challenge the server answers HTTP 400 "Code challenge is required." and issues no code (verified live 2026-08-31).
4. POST /oauth/token (grant_type=authorization_code, client_id=skylight-mobile, scope=everything, code, code_verifier matching step 3's challenge, redirect_uri, skylight_api_client_device_* device params, source=js-mobile) — returns { access_token, refresh_token, expires_in: 86400 (24h, observed 2026-08-31 — it was 604800 when this flow was first captured, so read it from the response, never assume), token_type: Bearer }.