withings-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.

General Rules

Always execute tasks in parallel when possible. If multiple independent operations need to be performed (e.g., reading files, running searches, editing unrelated files, running builds), do them simultaneously rather than sequentially. Only run tasks sequentially when there is a dependency between them.

Project Overview

This is an MCP (Model Context Protocol) server that integrates Withings health data with Claude. It implements OAuth 2.0 authentication with PKCE support and uses the Streamable HTTP transport (via the SDK's WebStandardStreamableHTTPServerTransport) for communication between MCP clients and the server.

Development Commands

Running

bun run start        # Run the server (Bun executes TypeScript directly)
bun run dev          # Hot-reload mode for local development
bun run typecheck    # Type-check with tsc (no emit)
bun run build        # Bundle for production (outputs to ./build)

Deployment

Deployed to DigitalOcean App Platform, which detects Bun automatically via its buildpack and runs bun run start.

Architecture

Project Structure

The codebase is organized by context into focused modules:

src/
├── auth/                     # Authentication & Authorization
│   ├── oauth.ts             # OAuth 2.0 endpoints (/authorize, /callback, /token, /register)
│   ├── token-store.ts       # MCP ↔ Withings token mapping
│   └── session-store.ts     # MCP session ↔ owning token (restart survival)
├── db/                       # Database Layer (Supabase)
│   └── supabase.ts          # Supabase client initialization
├── server/                   # Server components
│   ├── app.ts               # Hono app setup, route mounting, MCP_ENDPOINT constant
│   ├── mcp-endpoints.ts     # Unified MCP handler for /mcp endpoint (GET/POST/DELETE)
│   ├── middleware.ts        # Bearer token authentication
│   └── rate-limiter.ts      # Rate limiting middleware using Supabase
├── tools/                    # MCP tools organized by Withings API category
│   ├── index.ts             # Registers all tools on MCP server instances
│   ├── sleep.ts             # Sleep API: get_sleep, get_sleep_summary, get_hrv
│   ├── measure.ts           # Measure API: get_measures, get_workouts, get_activity, get_intraday_activity
│   ├── user.ts              # User API: get_user_devices, get_user_goals
│   ├── heart.ts             # Heart API: list_heart_records, get_heart_signal
│   └── stetho.ts            # Stetho API: list_stetho_records, get_stetho_signal
├── withings/                # Withings API Integration
│   └── api.ts               # Withings API client & request handling
├── types/                    # TypeScript type definitions
│   ├── hono.ts              # Hono app environment types (AppEnv, AppContext)
│   └── withings.ts          # Withings API response interfaces & param types
├── utils/                    # Utilities
│   ├── logger.ts            # Privacy-safe custom logger for Deno Deploy
│   ├── encryption.ts        # AES-256-GCM encryption for sensitive tokens
│   └── timestamp.ts         # Timezone-aware timestamp conversion utilities
└── index.ts                 # Main entry point (initializes Supabase, stores & creates app)

public/
└── styles/                      # External CSS (no unsafe-inline CSP)
    ├── index.css               # Landing page styles
    └── health.css              # Health check page styles

supabase/
└── migrations/
    ├── 001_initial_schema.sql   # Database schema (tables, indexes)
    ├── 004_atomic_rate_limit.sql # Atomic rate limit PostgreSQL function
    ├── 005_pg_cron_cleanup.sql  # pg_cron jobs for expired record cleanup
    ├── 006_mcp_sessions.sql     # Persisted MCP sessions (survive restarts)
    ├── 007_token_rotation_grace.sql # previous_mcp_token grace window
    ├── 008_sliding_window_rate_limit.sql # sliding-window check_rate_limit()
    └── 009_rate_limit_window_clamp.sql   # clamp stale reset_time from a longer window