skylight-mcp CLAUDE.md

CLAUDE.md

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

Overview

MCP server enabling AI assistants to interact with the Skylight family calendar API (calendar, chores, lists, tasks, rewards, meals, photos).

Base API URL: https://app.ourskylight.com

Commands

npm install
npm run build          # Compile TypeScript
npm run dev            # Development with hot reload (tsx watch)
npm test               # Run vitest tests
npm test -- dates      # Run single test file (matches filename)
npm run test:coverage  # Tests with coverage
npm run lint           # ESLint
npm run typecheck      # tsc --noEmit
npm run generate:types # Generate TypeScript types from OpenAPI spec

Architecture

Two-tier tool system:

1. api/endpoints/*.ts (11 modules) - Low-level HTTP wrappers for each API resource
2. tools/*.ts (9 modules) - MCP tool definitions with Zod parameter validation

Tool Registration: Each domain exports registerXxxTools(server) called from server.ts. Plus-only tools are conditionally registered based on subscription status.

Key files:

• config.ts - Zod-validated env config supporting two auth methods
• api/client.ts - HTTP client with Bearer/Basic auth, auto-login, subscription status tracking
• api/auth.ts - Login endpoint for email/password authentication
• api/generated-types.ts - Auto-generated types from OpenAPI spec
• utils/dates.ts - Parses "today", "tomorrow", day names, YYYY-MM-DD

Authentication

Two methods supported (validated via Zod refinement in config.ts):

1. Email/Password (recommended): Set SKYLIGHT_EMAIL and SKYLIGHT_PASSWORD. Server auto-logs in via POST /api/sessions and uses Basic base64(userId:token) format for subsequent requests.
2. Manual Token: Set SKYLIGHT_TOKEN and optionally SKYLIGHT_AUTH_TYPE (bearer/basic).

Both require SKYLIGHT_FRAME_ID (household identifier from API URLs like /api/frames/{frameId}/chores).