skylight-mcp

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 management (read+write, incl. preset and custom-photo avatars).

Every API request carries the skylight-api-version: 2026-05-01 header (matching the official mobile app); without it some features 422 with “API version does not support …”.

MCP protocol support

The server uses the official TypeScript SDK v2 and supports the stateless 2026-07-28 protocol revision over stdio. Clients can discover and call tools without an initialization handshake. Existing clients can still use the 2025-11-25 handshake.

The transport remains stdio. A host can expose it over authenticated HTTP. This package does not open a network listener.

Auth

The server uses a headless email+password OAuth2 authorization-code flow — no SSO, no 2FA, no browser extension required. Configure it with SKYLIGHT_REFRESH_TOKEN if you already hold a token, or SKYLIGHT_EMAIL + SKYLIGHT_PASSWORD to log in for one.

On first tool call, the server performs four steps against https://app.ourskylight.com:

1. GET /auth/session/new — fetch the Rails CSRF token and session cookie.
2. POST /auth/session — log in with email + password (must happen before OAuth authorize).
3. GET /oauth/authorize — send an S256 PKCE code_challenge (the server requires it) and receive the one-time authorization code via redirect.
4. POST /oauth/token — exchange the code plus the matching code_verifier for a bearer access_token + refresh_token (currently a 24-hour expiry; the client reads the returned expires_in rather than assuming).

OAuth redirects stay on the authentication origin. Relative redirects resolve against the current URL. The configured callback supplies the authorization code without receiving a request or session cookie. Unexpected destinations fail without including the redirect URL in the error.

The client then refreshes the token proactively (~60 s before expiry) and reactively on any 401. No bot wall has been observed — the headless flow works directly from Node.

No env vars → clean start: if credentials are not set, the server still starts without error. Auth is deferred to the first tool call, so MCP hosts can complete install-time tool listing before credentials are configured.