Fitbit MCP Server

# Claude Development Guide ## Project Overview MCP server for Fitbit API integration providing health data access (weight, sleep, activities, profile). **Design Philosophy:** This MCP server acts as a 1:1 JSON proxy to the Fitbit API. Tools should match the underlying API parameters and limitations exactly, without adding abstraction layers or client-side data manipulation. Return raw JSON responses from Fitbit API calls. ## Development Commands - `npm run build` - Compile TypeScript to build/ directory - `npm run start` - Run the built MCP server - `npm run dev` - Build and run with MCP inspector for testing/debugging - `npm run lint` - Check code quality and style issues - `npm run format` - Auto-fix code formatting - `npm test` - Run tests with Vitest - `npm run test:coverage` - Run tests with coverage report ## CI/CD - GitHub Actions workflow runs tests, lint checks, and build on push/PR to main branch - Located at `.github/workflows/ci.yml` ## Project Structure - `src/index.ts` - Main MCP server entry point, registers all tools - `src/auth.ts` - OAuth2 flow with token persistence - `src/utils.ts` - Shared Fitbit API request utilities - `src/weight.ts` - Weight data tool (time series) - `src/sleep.ts` - Sleep data tool (date range) - `src/activities.ts` - Exercise/activity data tool (date range) - `src/profile.ts` - User profile tool - `src/heart-rate.ts` - Heart rate data tools (time series and date range) - `src/nutrition.ts` - Nutrition data tools (comprehensive food log with macros, plus time series for individual nutrients) - `src/daily-activity.ts` - Daily activity summary tool (steps, calories, goals, heart rate zones) - `src/activity-goals.ts` - Activity goals tool (daily/weekly goals) - `src/activity-timeseries.ts` - Activity time series tool (steps, distance, calories over time) - `src/azm-timeseries.ts` - Active Zone Minutes time series tool - `build/` - Compiled JavaScript output - `.env` - Environment variables (FITBIT_CLIENT_ID, FITBIT_CLIENT_SECRET) ## Code Conventions - TypeScript with ES modules - Zod for parameter validation - All tools return raw JSON from Fitbit API - Error handling with console.error for debugging - Use makeFitbitRequest utility for API calls - **API Fidelity:** Tool parameters must exactly match Fitbit API requirements - no client-side workarounds or data filtering - **No Abstraction:** If Fitbit API only supports `afterDate`, the tool should only accept `afterDate` (not `startDate`/`endDate`) - **Documentation First:** Always check the official Fitbit API documentation at https://dev.fitbit.com/build/reference/ when adding new endpoints to ensure proper parameters, authentication scopes, and response formats - **CRITICAL: Endpoint URL Construction:** The `makeFitbitRequest` utility automatically adds `/user/-/` to all endpoint paths. When constructing endpoints, DO NOT include `user/-/` in the path - start directly with the resource path (e.g., `foods/log/caloriesIn/date/today/1d.json` NOT `user/-/foods/log/caloriesIn/date/today/1d.json`) ## Testing the Server **Development mode (with inspector):** 1. `npm run dev` - Builds and opens MCP inspector web UI 2. Test tools interactively at http://localhost:5173 3. OAuth flow - server opens browser for authorization **Production mode:** 1. `npm run build` - Compile TypeScript 2. `npm run start` - Run server directly 3. Tools available after auth: get_weight, get_sleep_by_date_range, get_exercises, get_daily_activity_summary, get_activity_goals, get_activity_timeseries, get_azm_timeseries, get_profile, get_heart_rate, get_heart_rate_by_date_range, get_food_log, get_nutrition, get_nutrition_by_date_range ## Environment Setup Requires `.env` file with: ``` FITBIT_CLIENT_ID=your_client_id FITBIT_CLIENT_SECRET=your_client_secret ``` ## API Notes - Fitbit API uses different base URLs per endpoint (v1, v1.2) - Activities tool has custom request handler due to different URL structure - All dates in YYYY-MM-DD format - Token persisted to `.fitbit-token.json` - OAuth scopes: weight, sleep, profile, activity, heartrate, nutrition ## Contributing & Improvements When working on this codebase: 1. Follow the existing code style and patterns 2. Update relevant documentation 3. Test changes thoroughly with the MCP inspector 4. Ensure backward compatibility with existing tools 5. **VERY IMPORTANT:** When you have completed a task, you MUST run both build, test, and lint commands (`npm run build` then `npm run test:coverage` then `npm run lint`) to ensure your code is correct 6. Update documentation when making changes **For identified improvement opportunities, see [TASKS.md](TASKS.md)** - this file contains a comprehensive analysis of refactoring opportunities, code quality improvements, and architectural enhancements prioritized by impact and effort.