@einlogic/mcp-fitbit 2.2.0 → 2.3.0

package/README.md

@@ -1,184 +1,196 @@
-# Google Health (Fitbit) MCP Connector for AI
-
-[![CI](https://github.com/TheDigitalNinja/mcp-fitbit/actions/workflows/ci.yml/badge.svg)](https://github.com/TheDigitalNinja/mcp-fitbit/actions/workflows/ci.yml)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-> Connect AI assistants to your Fitbit / Pixel Watch health data through the **Google Health API**
-
-The legacy Fitbit Web API was shut down on **2 November 2026**. Google replaced it with the
-[Google Health API](https://developers.google.com/health), which uses Google OAuth 2.0. This server now talks to
-the Google Health API and returns its raw JSON.
-
-## What it does
-
-🏃 **Exercise & Activities** - Workout sessions and daily activity roll-ups
-😴 **Sleep Analysis** - Sleep sessions
-⚖️ **Weight Tracking** - Weight data points
-❤️ **Heart Rate Data** - Samples, daily roll-ups and HRV
-🍎 **Nutrition Logs** - Food log, calories, macros and water
-👤 **Profile & Devices** - Profile, settings, identity and paired trackers
-
-*Ask your AI things like: "Show me my sleep patterns this week" or "What's my step count trend this month?"*
-
-## ⚠️ Breaking changes from the Fitbit version
-
-- You must create a **Google Cloud** OAuth client (see below) and re-authorize. Old Fitbit tokens cannot be reused.
-- Credentials are now `GOOGLE_HEALTH_CLIENT_ID` / `GOOGLE_HEALTH_CLIENT_SECRET`.- The token file is now `.google-health-token.json` (the old `.fitbit-token.json` is ignored and can be deleted).
-- Responses are the Google Health API's JSON, not Fitbit's. Fitbit-style `period` (`1d`, `7d`, ...) parameters are gone: tools take explicit start/end times, as the API does.
-- `get_activity_goals` was removed: the Google Health API has no goals endpoint.
-- New tools: `get_identity`, `get_settings`, `list_paired_devices`, `list_data_points`, `reconcile_data_points`.
-
-## Setup
-
-### 1. Link your account to Google Health
-
-In the **Google Health mobile app**, tap **Sign in with Google** and choose the Google Account to use (this creates a
-Google Health profile or migrates your existing Fitbit account). Without this, the API returns `ACCOUNT_NOT_LINKED`.
-
-### 2. Create Google OAuth credentials
-
-1. In the [Google Cloud Console](https://console.cloud.google.com/), create (or pick) a project.
-2. [Enable the Google Health API](https://console.developers.google.com/apis/library/health.googleapis.com).
-3. Create an **OAuth client ID** of type **Web application** and add the authorized redirect URI
-   `http://localhost:3000/callback`. Note the **Client ID** and **Client secret**.
-4. On the [OAuth consent screen / Audience](https://console.developers.google.com/auth/audience) page, keep the user
-   type **External** and add your Google Account under **Test users**.
-5. On the [Data Access](https://console.developers.google.com/auth/scopes) page, add these scopes (all read-only):
-   - `https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly`
-   - `https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements.readonly`
-   - `https://www.googleapis.com/auth/googlehealth.sleep.readonly`
-   - `https://www.googleapis.com/auth/googlehealth.nutrition.readonly`
-   - `https://www.googleapis.com/auth/googlehealth.profile.readonly`
-   - `https://www.googleapis.com/auth/googlehealth.settings.readonly`
-
-> **Refresh tokens in Testing mode expire after 7 days.** For a personal tool, set the app's publishing status to
-> **In production** (an unverified app is limited to 100 users and shows a warning screen at consent, which is fine
-> for your own account). Verification is only required beyond that.
-
-### 3. Install and configure
-
-**From npm:**
-```bash
-npm install -g mcp-fitbit
-```
-
-**From source:**
-```bash
-git clone https://github.com/TheDigitalNinja/mcp-fitbit
-cd mcp-fitbit
-npm install
-npm run build
-```
-
-Create a `.env` file in the package directory (the server prints the expected path if it is missing):
-```bash
-GOOGLE_HEALTH_CLIENT_ID=your_client_id_here
-GOOGLE_HEALTH_CLIENT_SECRET=your_client_secret_here
-```
-
-### 4. Claude Desktop
-
-Add to `claude_desktop_config.json`:
-```json
-{
-  "mcpServers": {
-    "google-health": {
-      "command": "mcp-fitbit",
-      "args": [],
-      "env": {
-        "GOOGLE_HEALTH_CLIENT_ID": "your_client_id_here",
-        "GOOGLE_HEALTH_CLIENT_SECRET": "your_client_secret_here"
-      }
-    }
-  }
-}
-```
-For a local build use `"command": "node", "args": ["C:\\path\\to\\mcp-fitbit\\build\\index.js"]`.
-
-Config file locations:
-- Windows: `%AppData%\Claude\claude_desktop_config.json`
-- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
-- Linux: `~/.config/Claude/claude_desktop_config.json`
-
-### First Run Authorization
-
-1. The server opens your browser to `http://localhost:3000/auth`
-2. Sign in to Google and grant the requested Google Health permissions
-3. The server verifies your Google Health link (`/v4/users/me/identity`) and saves the token
-4. Your AI can now access your data. Access tokens refresh automatically.
-
-## Available Tools
-
-Time parameters follow the API: ranges are **start inclusive, end exclusive**. Samples (`get_weight`, `get_heart_rate`)
-use RFC 3339 timestamps (e.g. `2026-03-04T00:00:00Z`); sessions use civil time (`YYYY-MM-DD` or `YYYY-MM-DDTHH:MM:SS`).
-List tools accept `pageSize` and `pageToken` (use `nextPageToken` from the response).
-
-| Tool | Google Health API | Parameters |
-|------|-------------------|------------|
-| `get_weight` | `weight` data points | `startTime`, optional `endTime` (RFC 3339) |
-| `get_sleep_by_date_range` | `sleep` data points (max 25/page) | `startTime`, optional `endTime` (civil) |
-| `get_exercises` | `exercise` data points (max 25/page) | `startTime`, optional `endTime` (civil) |
-| `get_daily_activity_summary` | daily roll-ups of steps, distance, total calories, active zone minutes, floors | `date` |
-| `get_activity_timeseries` | `dailyRollUp` (max 90 days; 14 for calories/active minutes) | `dataType`, `startDate`, `endDate` |
-| `get_azm_timeseries` | `dailyRollUp` of `active-zone-minutes` | `startDate`, `endDate` |
-| `get_heart_rate` | `heart-rate` samples | `startTime`, optional `endTime` (RFC 3339) |
-| `get_heart_rate_by_date_range` | `dailyRollUp` of `heart-rate` (max 14 days) | `startDate`, `endDate` |
-| `get_hrv` / `get_hrv_by_date_range` | `daily-heart-rate-variability` | `date` / `startDate`, `endDate` |
-| `get_food_log` | `nutrition-log` data points | `startTime`, optional `endTime` (civil) |
-| `get_nutrition` / `get_nutrition_by_date_range` | `dailyRollUp` of `nutrition-log` / `hydration-log` | `dataType`, `date` / `startDate`, `endDate` |
-| `get_profile` | `users/me/profile` | none |
-| `get_identity` | `users/me/identity` | none |
-| `get_settings` | `users/me/settings` | none |
-| `list_paired_devices` | `users/me/pairedDevices` | none |
-| `reauthenticate` | not an API call: deletes the local tokens (memory + `.google-health-token.json`) and opens a new Google sign-in; new tokens are saved on approval, no restart needed. Cancels a pending sign-in. Confirm with `get_identity` | none |
-| `list_data_points` | any of the 38 data types | `dataType`, optional raw `filter` |
-| `reconcile_data_points` | `dataPoints:reconcile` for any data type | `dataType`, optional `filter`, `dataSourceFamily` |
-
-**Activity data types:** `steps`, `distance`, `total-calories`, `active-energy-burned`, `floors`, `active-minutes`
-
-See the [data types reference](https://developers.google.com/health/data-types) for everything `list_data_points` can query.
-
-## Fitbit-compatible output mode
-
-Set `GOOGLE_HEALTH_OUTPUT_MODE=fitbit` (in the Claude Desktop `env` block or `.env`) to make the overlapping tools behave
-like the old Fitbit Web API server, so prompts and projects written against it keep working. The default (`google`) mode
-is unchanged. In `fitbit` mode these tools are replaced by Fitbit-shaped versions (same names, `period` parameters and
-**inclusive** end dates); everything else (`get_profile`, `get_exercises`, `get_identity`, `get_settings`,
-`list_paired_devices`, `list_data_points`, `reconcile_data_points`) stays a Google proxy.
-
-| Tool | Fitbit-style response | Notes |
-|------|----------------------|-------|
-| `get_weight` (`period`, `date?`) | `{ weight: [{ date, time, logId, weight }] }` | Pounds (follows the account unit). Duplicate weigh-ins from several sources are collapsed to one. No `bmi`/`fat`. |
-| `get_sleep_by_date_range` | `{ sleep: [{ dateOfSleep, minutesAsleep, timeInBed, levels.summary.{deep,light,rem,wake} }] }` | Max 100 days. No sleep score or efficiency (the Fitbit API had neither). |
-| `get_daily_activity_summary` | `{ activities: [], goals: {}, summary: { caloriesOut, steps, distances, floors, *ActiveMinutes, restingHeartRate, heartRateZones } }` | Miles. Exercise sessions and goals are not included. |
-| `get_heart_rate` (`period`) / `get_heart_rate_by_date_range` | `{ 'activities-heart': [{ dateTime, value: { restingHeartRate, heartRateZones } }] }` | Zones: Out of Range / Fat Burn / Cardio / Peak with `min`, `max`, `minutes`, `caloriesOut`. |
-| `get_hrv` / `get_hrv_by_date_range` | `{ hrv: [{ dateTime, value: { dailyRmssd, deepRmssd } }] }` | Milliseconds; max 30 days. |
-| `get_activity_timeseries` | `{ 'activities-<resource>': [{ dateTime, value: '<string>' }] }` | `steps`, `distance`, `calories`, `activityCalories` (+ `tracker/` variants). `caloriesBMR` is not available. |
-| `get_azm_timeseries` | `{ 'activities-active-zone-minutes': [...] }` | Total + fat burn / cardio / peak. |
-| `get_food_log` / `get_nutrition` / `get_nutrition_by_date_range` | Fitbit food-log summary / `foods-log-caloriesIn`, `foods-log-water` | No individual food entries or goals. |
-
-How the numbers are mapped (verified against a real day of Fitbit-era data):
-
-- **Heart-rate zones:** Fitbit's Out of Range / Fat Burn / Cardio / Peak are Google's Light / Moderate / Vigorous / Peak.
-  Fat Burn minutes equal Active Zone Minutes fat burn (1x); Cardio and Peak minutes are Active Zone Minutes divided by 2
-  (they count double). Out of Range comes from time-in-zone. Calories per zone come from `calories-in-heart-rate-zone`
-  and the bpm bounds from the account's own `daily-heart-rate-zones`.
-- **Sleep:** stage minutes come straight from Google's stage summary, which matched Fitbit's deep/REM numbers exactly.
-  The wake date (`dateOfSleep`) is derived from the sleep end time and its UTC offset.
-- **Units and time zone:** weight, distance and water follow the account's Google Health unit settings; days are
-  interpreted in the account time zone (override with `COMPAT_TIME_ZONE`).
-- **Known small differences:** Google re-derives some values, so a historical day can differ slightly from what Fitbit
-  returned at the time (e.g. a few steps or 1 bpm of resting heart rate). Fields that could not be provided are listed in a
-  top-level `_compat.notes` array when relevant.
-
-## Development
-
-```bash
-npm run build         # Compile TypeScript
-npm test              # Run tests
-npm run lint          # Check code quality
-npm run format        # Fix formatting
-npm run dev           # Run with MCP inspector
-```
-
-**Architecture:** See [CLAUDE.md](CLAUDE.md) and [MIGRATION_PLAN.md](MIGRATION_PLAN.md).
+# Google Health (Fitbit) MCP Connector for AI
+
+[![CI](https://github.com/TheDigitalNinja/mcp-fitbit/actions/workflows/ci.yml/badge.svg)](https://github.com/TheDigitalNinja/mcp-fitbit/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+> Connect AI assistants to your Fitbit / Pixel Watch health data through the **Google Health API**
+
+The legacy Fitbit Web API was shut down on **2 November 2026**. Google replaced it with the
+[Google Health API](https://developers.google.com/health), which uses Google OAuth 2.0. This server now talks to
+the Google Health API and returns its raw JSON.
+
+## What it does
+
+🏃 **Exercise & Activities** - Workout sessions and daily activity roll-ups
+😴 **Sleep Analysis** - Sleep sessions
+⚖️ **Weight Tracking** - Weight data points
+❤️ **Heart Rate Data** - Samples, daily roll-ups and HRV
+🍎 **Nutrition Logs** - Food log, calories, macros and water
+👤 **Profile & Devices** - Profile, settings, identity and paired trackers
+
+*Ask your AI things like: "Show me my sleep patterns this week" or "What's my step count trend this month?"*
+
+## ⚠️ Breaking changes from the Fitbit version
+
+- You must create a **Google Cloud** OAuth client (see below) and re-authorize. Old Fitbit tokens cannot be reused.
+- Credentials are now `GOOGLE_HEALTH_CLIENT_ID` / `GOOGLE_HEALTH_CLIENT_SECRET`.
+- The token is now stored per user at `~/.google-health-mcp/token.json` (see [Token storage](#token-storage)). The old `.fitbit-token.json` and any `.google-health-token.json` inside the package folder are ignored and can be deleted; you will sign in once after upgrading.
+- Responses are the Google Health API's JSON, not Fitbit's. Fitbit-style `period` (`1d`, `7d`, ...) parameters are gone: tools take explicit start/end times, as the API does.
+- `get_activity_goals` was removed: the Google Health API has no goals endpoint.
+- New tools: `get_identity`, `get_settings`, `list_paired_devices`, `list_data_points`, `reconcile_data_points`.
+
+## Setup
+
+### 1. Link your account to Google Health
+
+In the **Google Health mobile app**, tap **Sign in with Google** and choose the Google Account to use (this creates a
+Google Health profile or migrates your existing Fitbit account). Without this, the API returns `ACCOUNT_NOT_LINKED`.
+
+### 2. Create Google OAuth credentials
+
+1. In the [Google Cloud Console](https://console.cloud.google.com/), create (or pick) a project.
+2. [Enable the Google Health API](https://console.developers.google.com/apis/library/health.googleapis.com).
+3. Create an **OAuth client ID** of type **Web application** and add the authorized redirect URI
+   `http://localhost:3000/callback`. Note the **Client ID** and **Client secret**.
+4. On the [OAuth consent screen / Audience](https://console.developers.google.com/auth/audience) page, keep the user
+   type **External** and add your Google Account under **Test users**.
+5. On the [Data Access](https://console.developers.google.com/auth/scopes) page, add these scopes (all read-only):
+   - `https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly`
+   - `https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements.readonly`
+   - `https://www.googleapis.com/auth/googlehealth.sleep.readonly`
+   - `https://www.googleapis.com/auth/googlehealth.nutrition.readonly`
+   - `https://www.googleapis.com/auth/googlehealth.profile.readonly`
+   - `https://www.googleapis.com/auth/googlehealth.settings.readonly`
+
+> **Refresh tokens in Testing mode expire after 7 days.** For a personal tool, set the app's publishing status to
+> **In production** (an unverified app is limited to 100 users and shows a warning screen at consent, which is fine
+> for your own account). Verification is only required beyond that.
+
+### 3. Install and configure
+
+**From npm:**
+```bash
+npm install -g mcp-fitbit
+```
+
+**From source:**
+```bash
+git clone https://github.com/TheDigitalNinja/mcp-fitbit
+cd mcp-fitbit
+npm install
+npm run build
+```
+
+Create a `.env` file in the package directory (the server prints the expected path if it is missing):
+```bash
+GOOGLE_HEALTH_CLIENT_ID=your_client_id_here
+GOOGLE_HEALTH_CLIENT_SECRET=your_client_secret_here
+```
+
+### 4. Claude Desktop
+
+Add to `claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "google-health": {
+      "command": "mcp-fitbit",
+      "args": [],
+      "env": {
+        "GOOGLE_HEALTH_CLIENT_ID": "your_client_id_here",
+        "GOOGLE_HEALTH_CLIENT_SECRET": "your_client_secret_here"
+      }
+    }
+  }
+}
+```
+For a local build use `"command": "node", "args": ["C:\\path\\to\\mcp-fitbit\\build\\index.js"]`.
+
+Config file locations:
+- Windows: `%AppData%\Claude\claude_desktop_config.json`
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Linux: `~/.config/Claude/claude_desktop_config.json`
+
+### First Run Authorization
+
+1. The server opens your browser to `http://localhost:3000/auth`
+2. Sign in to Google and grant the requested Google Health permissions
+3. The server verifies your Google Health link (`/v4/users/me/identity`) and saves the token
+4. Your AI can now access your data. Access tokens refresh automatically.
+
+### Token storage
+
+The token is saved to `~/.google-health-mcp/token.json` (on Windows `C:\Users\<you>\.google-health-mcp\token.json`),
+outside the install folder, so it survives upgrades and works when the global npm folder is read-only. New chat
+sessions reuse it and refresh the access token silently; you only sign in again if Google rejects the refresh token
+(for example after the 7-day Testing-mode limit, or if you revoke access).
+
+Set `GOOGLE_HEALTH_TOKEN_PATH` (in the `env` block or `.env`) to store it elsewhere. If the token cannot be saved, the
+browser page after sign-in says so, and the server log (stderr) shows the path and the reason. A temporary failure to
+refresh (for example no network) keeps the saved token and does not open a sign-in window.
+
+## Available Tools
+
+Time parameters follow the API: ranges are **start inclusive, end exclusive**. Samples (`get_weight`, `get_heart_rate`)
+use RFC 3339 timestamps (e.g. `2026-03-04T00:00:00Z`); sessions use civil time (`YYYY-MM-DD` or `YYYY-MM-DDTHH:MM:SS`).
+List tools accept `pageSize` and `pageToken` (use `nextPageToken` from the response).
+
+| Tool | Google Health API | Parameters |
+|------|-------------------|------------|
+| `get_weight` | `weight` data points | `startTime`, optional `endTime` (RFC 3339) |
+| `get_sleep_by_date_range` | `sleep` data points (max 25/page) | `startTime`, optional `endTime` (civil) |
+| `get_exercises` | `exercise` data points (max 25/page) | `startTime`, optional `endTime` (civil) |
+| `get_daily_activity_summary` | daily roll-ups of steps, distance, total calories, active zone minutes, floors | `date` |
+| `get_activity_timeseries` | `dailyRollUp` (max 90 days; 14 for calories/active minutes) | `dataType`, `startDate`, `endDate` |
+| `get_azm_timeseries` | `dailyRollUp` of `active-zone-minutes` | `startDate`, `endDate` |
+| `get_heart_rate` | `heart-rate` samples | `startTime`, optional `endTime` (RFC 3339) |
+| `get_heart_rate_by_date_range` | `dailyRollUp` of `heart-rate` (max 14 days) | `startDate`, `endDate` |
+| `get_hrv` / `get_hrv_by_date_range` | `daily-heart-rate-variability` | `date` / `startDate`, `endDate` |
+| `get_food_log` | `nutrition-log` data points | `startTime`, optional `endTime` (civil) |
+| `get_nutrition` / `get_nutrition_by_date_range` | `dailyRollUp` of `nutrition-log` / `hydration-log` | `dataType`, `date` / `startDate`, `endDate` |
+| `get_profile` | `users/me/profile` | none |
+| `get_identity` | `users/me/identity` | none |
+| `get_settings` | `users/me/settings` | none |
+| `list_paired_devices` | `users/me/pairedDevices` | none |
+| `reauthenticate` | not an API call: deletes the local tokens (memory + the token file, see [Token storage](#token-storage)) and opens a new Google sign-in; new tokens are saved on approval, no restart needed. Cancels a pending sign-in. Confirm with `get_identity` | none |
+| `list_data_points` | any of the 38 data types | `dataType`, optional raw `filter` |
+| `reconcile_data_points` | `dataPoints:reconcile` for any data type | `dataType`, optional `filter`, `dataSourceFamily` |
+
+**Activity data types:** `steps`, `distance`, `total-calories`, `active-energy-burned`, `floors`, `active-minutes`
+
+See the [data types reference](https://developers.google.com/health/data-types) for everything `list_data_points` can query.
+
+## Fitbit-compatible output mode
+
+Set `GOOGLE_HEALTH_OUTPUT_MODE=fitbit` (in the Claude Desktop `env` block or `.env`) to make the overlapping tools behave
+like the old Fitbit Web API server, so prompts and projects written against it keep working. The default (`google`) mode
+is unchanged. In `fitbit` mode these tools are replaced by Fitbit-shaped versions (same names, `period` parameters and
+**inclusive** end dates); everything else (`get_profile`, `get_exercises`, `get_identity`, `get_settings`,
+`list_paired_devices`, `list_data_points`, `reconcile_data_points`) stays a Google proxy.
+
+| Tool | Fitbit-style response | Notes |
+|------|----------------------|-------|
+| `get_weight` (`period`, `date?`) | `{ weight: [{ date, time, logId, weight }] }` | Pounds (follows the account unit). Duplicate weigh-ins from several sources are collapsed to one. No `bmi`/`fat`. |
+| `get_sleep_by_date_range` | `{ sleep: [{ dateOfSleep, minutesAsleep, timeInBed, levels.summary.{deep,light,rem,wake} }] }` | Max 100 days. No sleep score or efficiency (the Fitbit API had neither). |
+| `get_daily_activity_summary` | `{ activities: [], goals: {}, summary: { caloriesOut, steps, distances, floors, *ActiveMinutes, restingHeartRate, heartRateZones } }` | Miles. Exercise sessions and goals are not included. |
+| `get_heart_rate` (`period`) / `get_heart_rate_by_date_range` | `{ 'activities-heart': [{ dateTime, value: { restingHeartRate, heartRateZones } }] }` | Zones: Out of Range / Fat Burn / Cardio / Peak with `min`, `max`, `minutes`, `caloriesOut`. |
+| `get_hrv` / `get_hrv_by_date_range` | `{ hrv: [{ dateTime, value: { dailyRmssd, deepRmssd } }] }` | Milliseconds; max 30 days. |
+| `get_activity_timeseries` | `{ 'activities-<resource>': [{ dateTime, value: '<string>' }] }` | `steps`, `distance`, `calories`, `activityCalories` (+ `tracker/` variants). `caloriesBMR` is not available. |
+| `get_azm_timeseries` | `{ 'activities-active-zone-minutes': [...] }` | Total + fat burn / cardio / peak. |
+| `get_food_log` / `get_nutrition` / `get_nutrition_by_date_range` | Fitbit food-log summary / `foods-log-caloriesIn`, `foods-log-water` | No individual food entries or goals. |
+
+How the numbers are mapped (verified against a real day of Fitbit-era data):
+
+- **Heart-rate zones:** Fitbit's Out of Range / Fat Burn / Cardio / Peak are Google's Light / Moderate / Vigorous / Peak.
+  Fat Burn minutes equal Active Zone Minutes fat burn (1x); Cardio and Peak minutes are Active Zone Minutes divided by 2
+  (they count double). Out of Range comes from time-in-zone. Calories per zone come from `calories-in-heart-rate-zone`
+  and the bpm bounds from the account's own `daily-heart-rate-zones`.
+- **Sleep:** stage minutes come straight from Google's stage summary, which matched Fitbit's deep/REM numbers exactly.
+  The wake date (`dateOfSleep`) is derived from the sleep end time and its UTC offset.
+- **Units and time zone:** weight, distance and water follow the account's Google Health unit settings; days are
+  interpreted in the account time zone (override with `COMPAT_TIME_ZONE`).
+- **Known small differences:** Google re-derives some values, so a historical day can differ slightly from what Fitbit
+  returned at the time (e.g. a few steps or 1 bpm of resting heart rate). Fields that could not be provided are listed in a
+  top-level `_compat.notes` array when relevant.
+
+## Development
+
+```bash
+npm run build         # Compile TypeScript
+npm test              # Run tests
+npm run lint          # Check code quality
+npm run format        # Fix formatting
+npm run dev           # Run with MCP inspector
+```
+
+**Architecture:** See [CLAUDE.md](CLAUDE.md) and [MIGRATION_PLAN.md](MIGRATION_PLAN.md).

package/build/auth-tools.js

@@ -7,7 +7,7 @@ import { registerTool, createSuccessResponse, createErrorResponse, } from './uti
 export function registerAuthTools(server, reauthenticate) {
     registerTool(server, {
         name: 'reauthenticate',
-        description: "Clear this MCP server's locally stored Google Health tokens (memory and .google-health-token.json) and start a new Google sign-in. A browser window opens for consent; once approved, new tokens are saved and the other tools work again without restarting the server. Use when the token has expired (testing-mode refresh tokens last 7 days), was revoked, or the wrong Google account is connected. Cancels any sign-in that is still pending. Verify afterwards with get_identity.",
+        description: "Clear this MCP server's locally stored Google Health tokens (memory and the token file) and start a new Google sign-in. A browser window opens for consent; once approved, new tokens are saved and the other tools work again without restarting the server. Use when the token has expired (testing-mode refresh tokens last 7 days), was revoked, or the wrong Google account is connected. Cancels any sign-in that is still pending. Verify afterwards with get_identity.",
         parametersSchema: {},
         handler: async () => {
             try {

package/build/auth.js

@@ -7,7 +7,7 @@ import { AuthorizationCode } from 'simple-oauth2';
 import { fileURLToPath } from 'url';
 import fs from 'fs/promises';
 import { existsSync } from 'fs';
-import { GOOGLE_OAUTH_CONFIG, GOOGLE_HEALTH_API_BASE, FILE_PATHS, ERROR_MESSAGES, HTTP_CONFIG, resolveClientCredentials, } from './config.js';
+import { GOOGLE_OAUTH_CONFIG, GOOGLE_HEALTH_API_BASE, FILE_PATHS, ERROR_MESSAGES, HTTP_CONFIG, resolveClientCredentials, resolveTokenPath, } from './config.js';
 // Determine the directory of the current module (build/auth.js)
 const currentFilename = fileURLToPath(import.meta.url);
 const currentDirname = path.dirname(currentFilename);
@@ -41,20 +41,42 @@ let accessToken = null;
 let tokenData = null;
 // Holds the temporary HTTP server instance used for the OAuth callback
 let oauthServer = null;
-// --- File paths for token persistence ---
-const TOKEN_FILE_PATH = path.resolve(currentDirname, '..', FILE_PATHS.TOKEN_STORAGE);
+// A refresh already running, so parallel callers share one Google request
+let refreshInFlight = null;
+// Refresh token Google rejected with invalid_grant. A copy of it found on disk
+// is ignored, so an unauthenticated session doesn't retry it on every call.
+let rejectedRefreshToken = null;
+// How many times a refresh is tried before giving up for now
+const REFRESH_MAX_ATTEMPTS = 3;
+// --- File path for token persistence (per-user, outside the install dir) ---
+const TOKEN_FILE_PATH = resolveTokenPath();
 // --- OAuth Client Initialization ---
 const oauthClient = new AuthorizationCode(googleConfig);
 /**
- * Saves the token data to a file for persistence
+ * Saves the token data to a file for persistence. The write is atomic (temp
+ * file + rename) so a session starting at the same moment never reads a
+ * half-written file.
+ * @returns null on success, otherwise a description of why the save failed.
  */
 async function saveTokenToFile(data) {
+    const tempPath = `${TOKEN_FILE_PATH}.${process.pid}.tmp`;
     try {
-        await fs.writeFile(TOKEN_FILE_PATH, JSON.stringify(data, null, 2), 'utf8');
+        await fs.mkdir(path.dirname(TOKEN_FILE_PATH), { recursive: true });
+        await fs.writeFile(tempPath, JSON.stringify(data, null, 2), {
+            encoding: 'utf8',
+            mode: 0o600,
+        });
+        await fs.rename(tempPath, TOKEN_FILE_PATH);
         console.error(`Token saved to ${TOKEN_FILE_PATH}`);
+        return null;
     }
     catch (error) {
-        console.error(`Error saving token to file: ${error}`);
+        await fs.unlink(tempPath).catch(() => undefined);
+        const reason = error instanceof Error ? error.message : String(error);
+        console.error(`Error saving token to ${TOKEN_FILE_PATH}: ${reason}. ` +
+            `You will have to sign in again next session. ` +
+            `Set ${FILE_PATHS.TOKEN_PATH_ENV} to a writable file path.`);
+        return reason;
     }
 }
 /**
@@ -108,45 +130,115 @@ async function verifyAccountLinked(token) {
         return true;
     }
 }
-function isExpired(data) {
+function isExpired(data, marginMs = 60_000) {
     if (!data.expires_at)
         return false;
-    // Refresh a minute early to avoid racing the expiry
-    return new Date(data.expires_at).getTime() - 60_000 < Date.now();
+    // By default refresh a minute early to avoid racing the expiry
+    return new Date(data.expires_at).getTime() - marginMs < Date.now();
 }
-/**
- * Refreshes the access token if it has expired. Google does not return a new
- * refresh token on refresh, so the existing one is carried over.
- */
-async function refreshTokenIfNeeded() {
-    if (!tokenData || !isExpired(tokenData)) {
+function forgetTokenInMemory() {
+    accessToken = null;
+    tokenData = null;
+}
+/** The error text plus Google's response body (e.g. {"error":"invalid_grant"}). */
+function describeRefreshError(error) {
+    const e = error;
+    const payload = e?.data?.payload;
+    const body = payload === undefined
+        ? ''
+        : ` ${typeof payload === 'string' ? payload : JSON.stringify(payload)}`;
+    return `${e?.message ?? String(error)}${body}`;
+}
+/** invalid_grant: the refresh token is expired, revoked or otherwise dead. */
+function isInvalidGrant(error) {
+    return describeRefreshError(error).includes('invalid_grant');
+}
+/** A client error (4xx, except timeout/rate limit): retrying cannot help. */
+function isNonRetryable(error) {
+    const e = error;
+    const status = e?.output?.statusCode ?? e?.data?.res?.statusCode;
+    return (typeof status === 'number' &&
+        status >= 400 &&
+        status < 500 &&
+        status !== 408 &&
+        status !== 429);
+}
+async function refreshAccessToken() {
+    const current = tokenData;
+    if (!current)
         return;
-    }
-    const refreshToken = tokenData.refresh_token;
+    const refreshToken = current.refresh_token;
     if (!refreshToken) {
         console.error('Token is expired and no refresh token is available.');
-        accessToken = null;
-        tokenData = null;
+        forgetTokenInMemory();
         return;
     }
-    console.error('Token is expired. Attempting to refresh...');
-    try {
-        const accessTokenObj = oauthClient.createToken(tokenData);
-        const refreshed = await accessTokenObj.refresh();
-        const refreshedData = refreshed.token;
-        if (!refreshedData.refresh_token) {
-            refreshedData.refresh_token = refreshToken;
+    for (let attempt = 1; attempt <= REFRESH_MAX_ATTEMPTS; attempt++) {
+        console.error(`Token is expired. Attempting to refresh (attempt ${attempt}/${REFRESH_MAX_ATTEMPTS})...`);
+        try {
+            const refreshed = await oauthClient.createToken(current).refresh();
+            const refreshedData = refreshed.token;
+            // Google does not return a refresh token on refresh: keep the existing one
+            if (!refreshedData.refresh_token) {
+                refreshedData.refresh_token = refreshToken;
+            }
+            tokenData = refreshedData;
+            accessToken = refreshedData.access_token;
+            await saveTokenToFile(refreshedData);
+            console.error('Token refreshed successfully.');
+            return;
+        }
+        catch (error) {
+            const detail = describeRefreshError(error);
+            if (isInvalidGrant(error)) {
+                // Only this means the refresh token itself is dead and sign-in is needed
+                console.error(`Google rejected the refresh token (invalid_grant): ${detail}. Sign-in is required.`);
+                rejectedRefreshToken = refreshToken;
+                forgetTokenInMemory();
+                return;
+            }
+            console.error(`Token refresh attempt ${attempt} failed: ${detail}`);
+            if (isNonRetryable(error)) {
+                console.error('Google refused the refresh request. Check GOOGLE_HEALTH_CLIENT_ID / GOOGLE_HEALTH_CLIENT_SECRET match the client that issued the token.');
+                break;
+            }
+            if (attempt < REFRESH_MAX_ATTEMPTS) {
+                const delayMs = HTTP_CONFIG.RETRY_BASE_DELAY_MS * 2 ** (attempt - 1);
+                await new Promise((resolve) => setTimeout(resolve, delayMs));
+            }
         }
-        tokenData = refreshedData;
-        accessToken = refreshedData.access_token;
-        await saveTokenToFile(refreshedData);
-        console.error('Token refreshed and saved successfully.');
     }
-    catch (refreshError) {
-        console.error('Failed to refresh token:', refreshError);
-        accessToken = null;
-        tokenData = null;
+    // The stored token is kept: a network blip must not force a new sign-in
+    console.error('Could not refresh the token right now. Keeping it and retrying on the next request.');
+}
+/**
+ * Refreshes the access token if it has expired. Parallel callers share a single
+ * refresh. Only an invalid_grant response discards the token; any other
+ * failure keeps it so a later call can try again.
+ */
+function refreshTokenIfNeeded() {
+    if (!tokenData || !isExpired(tokenData)) {
+        return Promise.resolve();
+    }
+    refreshInFlight ??= refreshAccessToken().finally(() => {
+        refreshInFlight = null;
+    });
+    return refreshInFlight;
+}
+/**
+ * Loads the stored token into memory. Also called when a session has no token,
+ * to pick up one that another session has saved since startup.
+ */
+async function loadPersistedToken() {
+    const stored = await loadTokenFromFile();
+    // A refresh may have set a newer token while we were reading the file
+    if (tokenData || !stored || !stored.access_token)
+        return;
+    if (rejectedRefreshToken && stored.refresh_token === rejectedRefreshToken) {
+        return;
     }
+    tokenData = stored;
+    accessToken = stored.access_token;
 }
 // --- Google Authorization Flow ---
 /**
@@ -229,9 +321,11 @@ export function startAuthorizationFlow() {
             }
             accessToken = newToken.access_token;
             tokenData = newToken;
-            await saveTokenToFile(newToken);
-            console.error('Token data has been persisted to file');
-            res.send('Authorization successful! You can close this window. The MCP Server is now authenticated.');
+            rejectedRefreshToken = null;
+            const saveError = await saveTokenToFile(newToken);
+            res.send(saveError
+                ? `Authorization successful for this session, but the token could not be saved (${saveError}). You will have to sign in again next session. Set ${FILE_PATHS.TOKEN_PATH_ENV} to a writable file path.`
+                : 'Authorization successful! You can close this window. The MCP Server is now authenticated.');
         }
         catch (error) {
             // Handle errors during token exchange
@@ -300,8 +394,8 @@ async function stopAuthorizationServer() {
  * @returns true when a token file was deleted, false when there was none.
  */
 export async function clearStoredToken() {
-    accessToken = null;
-    tokenData = null;
+    forgetTokenInMemory();
+    rejectedRefreshToken = null;
     try {
         await fs.unlink(TOKEN_FILE_PATH);
         console.error(`Token file deleted: ${TOKEN_FILE_PATH}`);
@@ -335,29 +429,46 @@ export async function reauthenticate() {
  * @returns The access token string or null if not available.
  */
 export async function getAccessToken() {
+    if (!tokenData) {
+        // Another session may have signed in and saved a token since we started
+        await loadPersistedToken();
+    }
     if (!tokenData || !accessToken) {
         console.error('No valid access token found.');
         return null;
     }
     await refreshTokenIfNeeded();
+    if (!tokenData || !accessToken) {
+        return null;
+    }
+    // A temporary refresh failure keeps the token but leaves it expired
+    if (isExpired(tokenData, 0)) {
+        return null;
+    }
     return accessToken;
 }
+/**
+ * Whether the user has to sign in: there is no stored token, or Google rejected
+ * the refresh token. False while a stored token exists but could not be
+ * refreshed yet (e.g. offline), which a later request can still recover.
+ */
+export function isAuthorizationRequired() {
+    return !tokenData;
+}
 /**
  * Initializes the authentication module.
  * Loads persisted token from file storage if available.
  */
 export async function initializeAuth() {
-    console.error('Auth initialized. Checking for persisted token...');
+    console.error(`Auth initialized. Token file: ${TOKEN_FILE_PATH}`);
     try {
-        tokenData = await loadTokenFromFile();
-        if (tokenData && tokenData.access_token) {
-            accessToken = tokenData.access_token;
+        await loadPersistedToken();
+        if (tokenData) {
             console.error('Persisted access token loaded successfully.');
             await refreshTokenIfNeeded();
         }
         else {
             console.error('No valid access token found.');
-            tokenData = null;
         }
     }
     catch (error) {

package/build/config.js

@@ -2,6 +2,8 @@
  * Centralized configuration for the Google Health MCP server
  * Contains all constants, API URLs, and shared configurations
  */
+import os from 'os';
+import path from 'path';
 // === API Configuration ===
 export const GOOGLE_HEALTH_API_BASE = 'https://health.googleapis.com/v4';
 const SCOPE_PREFIX = 'https://www.googleapis.com/auth/googlehealth';
@@ -108,8 +110,25 @@ export const HTTP_CONFIG = {
 };
 // === File Paths ===
 export const FILE_PATHS = {
-    TOKEN_STORAGE: '.google-health-token.json',
+    /** Per-user directory (under the home directory) that holds the token file. */
+    TOKEN_DIR: '.google-health-mcp',
+    TOKEN_FILE: 'token.json',
+    /** Env var that overrides the full token file path. */
+    TOKEN_PATH_ENV: 'GOOGLE_HEALTH_TOKEN_PATH',
 };
+/**
+ * Where the OAuth token is persisted. Deliberately NOT inside the package/install
+ * directory: that is often read-only (global npm installs) and is wiped on
+ * upgrade, which would force a new sign-in every session.
+ * Override with GOOGLE_HEALTH_TOKEN_PATH.
+ */
+export function resolveTokenPath() {
+    const override = process.env[FILE_PATHS.TOKEN_PATH_ENV];
+    if (override && override.trim()) {
+        return path.resolve(override.trim());
+    }
+    return path.join(os.homedir(), FILE_PATHS.TOKEN_DIR, FILE_PATHS.TOKEN_FILE);
+}
 // === Error Messages ===
 export const ERROR_MESSAGES = {
     NO_ACCESS_TOKEN: 'No Google Health access token available. Please authorize first.',

package/build/index.js

@@ -5,7 +5,7 @@ import dotenv from 'dotenv';
 import path from 'path';
 import { fileURLToPath } from 'url';
 // Import authentication functions
-import { initializeAuth, startAuthorizationFlow, getAccessToken, reauthenticate, } from './auth.js';
+import { initializeAuth, startAuthorizationFlow, getAccessToken, isAuthorizationRequired, reauthenticate, } from './auth.js';
 // Import tool registration function(s)
 import { registerWeightTool } from './weight.js';
 import { registerSleepTool } from './sleep.js';
@@ -58,7 +58,7 @@ console.error('✅ Environment variables loaded successfully');
 // Create the main MCP server instance
 const server = new McpServer({
     name: 'google-health',
-    version: '2.2.0',
+    version: '2.3.0',
     capabilities: {
         resources: {},
         tools: {}, // Tools are registered dynamically below
@@ -99,12 +99,17 @@ async function main() {
         // Check if an access token is available after connection
         // If not, initiate the OAuth2 authorization flow
         const token = await getAccessToken();
-        if (!token) {
+        if (token) {
+            console.error('Using existing/loaded access token.');
+        }
+        else if (isAuthorizationRequired()) {
             console.error('No access token found. Starting Google Health authorization flow...');
             startAuthorizationFlow(); // Start flow in background, do not await
         }
         else {
-            console.error('Using existing/loaded access token.');
+            // A stored token exists but refreshing failed for a temporary reason
+            // (e.g. offline). Do not force a new sign-in; the next request retries.
+            console.error('A stored token exists but could not be refreshed right now. Not starting sign-in; it will be retried on the next request.');
         }
     }
     catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@einlogic/mcp-fitbit",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "type": "module",
   "main": "./build/index.js",
   "bin": {