@einlogic/mcp-fitbit 1.0.1

package/build/daily-activity.js

@@ -0,0 +1,21 @@
+import { registerTool, CommonSchemas, handleFitbitApiCall } from './utils.js';
+/**
+ * Registers a daily activity summary tool with the MCP server.
+ * @param server The McpServer instance.
+ * @param getAccessTokenFn Function to retrieve the current access token.
+ */
+export function registerDailyActivityTool(server, getAccessTokenFn) {
+    registerTool(server, {
+        name: 'get_daily_activity_summary',
+        description: "Get the raw JSON response for daily activity summary from Fitbit for a specific date. Includes goals, steps, calories, distances, and heart rate zones. Requires a 'date' parameter in YYYY-MM-DD format.",
+        parametersSchema: {
+            date: CommonSchemas.date,
+        },
+        handler: async ({ date }) => {
+            const endpoint = `activities/date/${date}.json`;
+            return handleFitbitApiCall(endpoint, { date }, getAccessTokenFn, {
+                errorContext: `date '${date}'`
+            });
+        }
+    });
+}

package/build/heart-rate.js

@@ -0,0 +1,106 @@
+import { z } from 'zod';
+import { makeFitbitRequest } from './utils.js';
+const FITBIT_API_BASE = 'https://api.fitbit.com/1';
+// --- Tool Registration ---
+/**
+ * Registers Fitbit heart rate tools with the MCP server.
+ * @param server The McpServer instance.
+ * @param getAccessTokenFn Function to retrieve the current access token.
+ */
+export function registerHeartRateTools(server, getAccessTokenFn) {
+    // --- Heart Rate by Date/Period Tool ---
+    const periodToolName = 'get_heart_rate';
+    const periodDescription = "Get the raw JSON response for heart rate data from Fitbit for a specified period ending today or on a specific date. Requires a 'period' parameter such as '1d', '7d', '30d', '1w', '1m' and optionally accepts 'date' parameter.";
+    const periodParametersSchemaShape = {
+        period: z
+            .enum(['1d', '7d', '30d', '1w', '1m'])
+            .describe('The time period for which to retrieve heart rate data.'),
+        date: z
+            .string()
+            .regex(/^\d{4}-\d{2}-\d{2}$|^today$/, "Date must be in YYYY-MM-DD format or 'today'.")
+            .optional()
+            .describe("The date for which to retrieve heart rate data (YYYY-MM-DD or 'today'). Defaults to 'today'."),
+    };
+    server.tool(periodToolName, periodDescription, periodParametersSchemaShape, async ({ period, date = 'today', }) => {
+        // Construct the endpoint dynamically
+        const endpoint = `activities/heart/date/${date}/${period}.json`;
+        const heartRateData = await makeFitbitRequest(endpoint, getAccessTokenFn, FITBIT_API_BASE);
+        // Handle API call failure
+        if (!heartRateData) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to retrieve heart rate data from Fitbit API for date '${date}' and period '${period}'. Check token and permissions.`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        // Handle no data found for the period
+        const heartRateEntries = heartRateData['activities-heart'] || [];
+        if (heartRateEntries.length === 0) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `No heart rate data found for date '${date}' and period '${period}'.`,
+                    },
+                ],
+            };
+        }
+        // Return successful response with raw JSON
+        const rawJsonResponse = JSON.stringify(heartRateData, null, 2);
+        return {
+            content: [{ type: 'text', text: rawJsonResponse }],
+        };
+    });
+    // --- Heart Rate by Date Range Tool ---
+    const rangeToolName = 'get_heart_rate_by_date_range';
+    const rangeDescription = "Get the raw JSON response for heart rate data from Fitbit for a specific date range. Requires 'startDate' and 'endDate' parameters in 'YYYY-MM-DD' format. Note: The API enforces a maximum range of 1 year.";
+    const rangeParametersSchemaShape = {
+        startDate: z
+            .string()
+            .regex(/^\d{4}-\d{2}-\d{2}$/, 'Start date must be in YYYY-MM-DD format.')
+            .describe('The start date for which to retrieve heart rate data (YYYY-MM-DD).'),
+        endDate: z
+            .string()
+            .regex(/^\d{4}-\d{2}-\d{2}$/, 'End date must be in YYYY-MM-DD format.')
+            .describe('The end date for which to retrieve heart rate data (YYYY-MM-DD).'),
+    };
+    server.tool(rangeToolName, rangeDescription, rangeParametersSchemaShape, async ({ startDate, endDate, }) => {
+        // Construct the endpoint dynamically
+        const endpoint = `activities/heart/date/${startDate}/${endDate}.json`;
+        // Make the request
+        const heartRateData = await makeFitbitRequest(endpoint, getAccessTokenFn, FITBIT_API_BASE);
+        // Handle API call failure
+        if (!heartRateData) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to retrieve heart rate data from Fitbit API for the date range '${startDate}' to '${endDate}'. Check token, permissions, date format, and ensure the range is 1 year or less.`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        // Handle no data found
+        const heartRateEntries = heartRateData['activities-heart'] || [];
+        if (heartRateEntries.length === 0) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `No heart rate data found for the date range '${startDate}' to '${endDate}'.`,
+                    },
+                ],
+            };
+        }
+        // Return successful response
+        const rawJsonResponse = JSON.stringify(heartRateData, null, 2);
+        return {
+            content: [{ type: 'text', text: rawJsonResponse }],
+        };
+    });
+}

package/build/hrv.js

@@ -0,0 +1,35 @@
+import { registerTool, CommonSchemas, handleFitbitApiCall, } from './utils.js';
+/**
+ * Registers Heart Rate Variability (HRV) tools with the MCP server.
+ * @param server The McpServer instance.
+ * @param getAccessTokenFn Function to retrieve the current access token.
+ */
+export function registerHrvTools(server, getAccessTokenFn) {
+    registerTool(server, {
+        name: 'get_hrv',
+        description: 'Get the raw JSON response for Heart Rate Variability (HRV) summary data from Fitbit for a single date. Returns daily RMSSD and deep sleep RMSSD values.',
+        parametersSchema: {
+            date: CommonSchemas.date,
+        },
+        handler: async ({ date }) => {
+            const endpoint = `hrv/date/${date}.json`;
+            return handleFitbitApiCall(endpoint, { date }, getAccessTokenFn, {
+                errorContext: `HRV data for ${date}`,
+            });
+        },
+    });
+    registerTool(server, {
+        name: 'get_hrv_by_date_range',
+        description: 'Get the raw JSON response for Heart Rate Variability (HRV) summary data from Fitbit over a date range (max 30 days). Returns daily RMSSD and deep sleep RMSSD values for each day.',
+        parametersSchema: {
+            startDate: CommonSchemas.startDate,
+            endDate: CommonSchemas.endDate,
+        },
+        handler: async ({ startDate, endDate }) => {
+            const endpoint = `hrv/date/${startDate}/${endDate}.json`;
+            return handleFitbitApiCall(endpoint, { startDate, endDate }, getAccessTokenFn, {
+                errorContext: `HRV data from ${startDate} to ${endDate}`,
+            });
+        },
+    });
+}

package/build/index.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import dotenv from 'dotenv';
+import path from 'path';
+import { fileURLToPath } from 'url';
+// Import authentication functions
+import { initializeAuth, startAuthorizationFlow, getAccessToken, } from './auth.js';
+// Import tool registration function(s)
+import { registerWeightTool } from './weight.js';
+import { registerSleepTool } from './sleep.js';
+import { registerProfileTool } from './profile.js';
+import { registerActivitiesTool } from './activities.js';
+import { registerHeartRateTools } from './heart-rate.js';
+import { registerNutritionTools } from './nutrition.js';
+import { registerDailyActivityTool } from './daily-activity.js';
+import { registerActivityGoalsTool } from './activity-goals.js';
+import { registerActivityTimeSeriesTool } from './activity-timeseries.js';
+import { registerAzmTimeSeriesTool } from './azm-timeseries.js';
+import { registerHrvTools } from './hrv.js';
+// Import utilities
+import './utils.js';
+// Calculate the directory name of the current module (build/index.js)
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+// Construct the absolute path to the .env file (one level up from build/)
+// Load environment variables early in the application lifecycle
+const envPath = path.resolve(__dirname, '..', '.env');
+dotenv.config({ path: envPath });
+// Validate required environment variables
+function validateEnvironment() {
+    const requiredVars = {
+        FITBIT_CLIENT_ID: process.env.FITBIT_CLIENT_ID,
+        FITBIT_CLIENT_SECRET: process.env.FITBIT_CLIENT_SECRET,
+    };
+    const missingVars = Object.entries(requiredVars)
+        .filter(([, value]) => !value)
+        .map(([key]) => key);
+    if (missingVars.length > 0) {
+        console.error('Missing required environment variables:');
+        missingVars.forEach(varName => {
+            console.error(`   - ${varName}`);
+        });
+        console.error(`Please create a .env file at: ${envPath}`);
+        console.error('See README.md for details on getting Fitbit API credentials.');
+        process.exit(1);
+    }
+}
+// Validate environment before proceeding
+validateEnvironment();
+// Log successful environment loading
+console.error('✅ Environment variables loaded successfully');
+// Create the main MCP server instance
+const server = new McpServer({
+    name: 'fitbit',
+    version: '1.0.0',
+    capabilities: {
+        resources: {},
+        tools: {}, // Tools are registered dynamically below
+    },
+});
+// Register available tools with the MCP server
+registerWeightTool(server, getAccessToken);
+registerSleepTool(server, getAccessToken);
+registerProfileTool(server, getAccessToken);
+registerActivitiesTool(server, getAccessToken);
+registerHeartRateTools(server, getAccessToken);
+registerNutritionTools(server, getAccessToken);
+registerDailyActivityTool(server, getAccessToken);
+registerActivityGoalsTool(server, getAccessToken);
+registerActivityTimeSeriesTool(server, getAccessToken);
+registerAzmTimeSeriesTool(server, getAccessToken);
+registerHrvTools(server, getAccessToken);
+// --- Main Application Entry Point ---
+async function main() {
+    // Initialize the authentication module (e.g., load persisted token)
+    await initializeAuth();
+    // Set up the transport layer for communication (stdio in this case)
+    const transport = new StdioServerTransport();
+    try {
+        // Connect the MCP server to the transport
+        await server.connect(transport);
+        console.error('Fitbit MCP Server connected via stdio.');
+        // Check if an access token is available after connection
+        // If not, initiate the OAuth2 authorization flow
+        const token = await getAccessToken();
+        if (!token) {
+            console.error('No access token found. Starting Fitbit authorization flow...');
+            startAuthorizationFlow(); // Start flow in background, do not await
+        }
+        else {
+            console.error('Using existing/loaded access token.');
+        }
+    }
+    catch (error) {
+        console.error('Failed to connect MCP server:', error);
+        process.exit(1); // Exit if connection fails
+    }
+    console.error('MCP Server setup complete. Waiting for requests...');
+    // The server connection via StdioServerTransport keeps the process alive.
+}
+// Execute the main function and handle any top-level errors
+main().catch((error) => {
+    console.error('Fatal error during MCP server startup:', error.message || error);
+    process.exit(1);
+});

package/build/nutrition.js

@@ -0,0 +1,162 @@
+import { z } from 'zod';
+import { makeFitbitRequest } from './utils.js';
+const FITBIT_API_BASE = 'https://api.fitbit.com/1';
+// --- Tool Registration ---
+/**
+ * Registers Fitbit nutrition tools with the MCP server.
+ * @param server The McpServer instance.
+ * @param getAccessTokenFn Function to retrieve the current access token.
+ */
+export function registerNutritionTools(server, getAccessTokenFn) {
+    // --- Food Log Tool (comprehensive nutrition data) ---
+    const foodLogToolName = 'get_food_log';
+    const foodLogDescription = 'Get comprehensive nutrition data (calories, protein, carbs, fat, fiber, sodium) from Fitbit food log for a specific date. Returns daily summary totals and individual food entries with nutritional values.';
+    const foodLogParametersSchemaShape = {
+        date: z
+            .string()
+            .regex(/^\d{4}-\d{2}-\d{2}$|^today$/, "Date must be in YYYY-MM-DD format or 'today'.")
+            .optional()
+            .describe("The date for which to retrieve food log data (YYYY-MM-DD or 'today'). Defaults to 'today'."),
+    };
+    server.tool(foodLogToolName, foodLogDescription, foodLogParametersSchemaShape, async ({ date = 'today', }) => {
+        // Construct the endpoint
+        const endpoint = `foods/log/date/${date}.json`;
+        const foodLogData = await makeFitbitRequest(endpoint, getAccessTokenFn, FITBIT_API_BASE);
+        // Handle API call failure
+        if (!foodLogData) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to retrieve food log data from Fitbit API for date '${date}'. Check token and permissions.`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        // Return successful response with raw JSON
+        const rawJsonResponse = JSON.stringify(foodLogData, null, 2);
+        return {
+            content: [{ type: 'text', text: rawJsonResponse }],
+        };
+    });
+    // --- Nutrition by Date/Period Tool ---
+    const periodToolName = 'get_nutrition';
+    const periodDescription = "Get the raw JSON response for nutrition data from Fitbit for a specified resource and period ending today or on a specific date. Requires 'resource' parameter (caloriesIn, water) and 'period' parameter such as '1d', '7d', '30d', '1w', '1m', '3m', '6m', '1y' and optionally accepts 'date' parameter.";
+    const periodParametersSchemaShape = {
+        resource: z
+            .enum([
+            'caloriesIn',
+            'water',
+            'protein',
+            'carbs',
+            'fat',
+            'fiber',
+            'sodium',
+        ])
+            .describe('The nutrition resource to retrieve data for.'),
+        period: z
+            .enum(['1d', '7d', '30d', '1w', '1m', '3m', '6m', '1y'])
+            .describe('The time period for which to retrieve nutrition data.'),
+        date: z
+            .string()
+            .regex(/^\d{4}-\d{2}-\d{2}$|^today$/, "Date must be in YYYY-MM-DD format or 'today'.")
+            .optional()
+            .describe("The date for which to retrieve nutrition data (YYYY-MM-DD or 'today'). Defaults to 'today'."),
+    };
+    server.tool(periodToolName, periodDescription, periodParametersSchemaShape, async ({ resource, period, date = 'today', }) => {
+        // Construct the endpoint dynamically
+        const endpoint = `foods/log/${resource}/date/${date}/${period}.json`;
+        const nutritionData = await makeFitbitRequest(endpoint, getAccessTokenFn, FITBIT_API_BASE);
+        // Handle API call failure
+        if (!nutritionData) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to retrieve nutrition data from Fitbit API for resource '${resource}', date '${date}' and period '${period}'. Check token and permissions.`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        // Handle no data found for the period
+        const resourceKey = `foods-log-${resource}`;
+        const nutritionEntries = nutritionData[resourceKey] || [];
+        if (nutritionEntries.length === 0) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `No nutrition data found for resource '${resource}', date '${date}' and period '${period}'.`,
+                    },
+                ],
+            };
+        }
+        // Return successful response with raw JSON
+        const rawJsonResponse = JSON.stringify(nutritionData, null, 2);
+        return {
+            content: [{ type: 'text', text: rawJsonResponse }],
+        };
+    });
+    // --- Nutrition by Date Range Tool ---
+    const rangeToolName = 'get_nutrition_by_date_range';
+    const rangeDescription = "Get the raw JSON response for nutrition data from Fitbit for a specific resource and date range. Requires 'resource' parameter (caloriesIn, water), 'startDate' and 'endDate' parameters in 'YYYY-MM-DD' format. Note: The API enforces a maximum range of 1,095 days.";
+    const rangeParametersSchemaShape = {
+        resource: z
+            .enum([
+            'caloriesIn',
+            'water',
+            'protein',
+            'carbs',
+            'fat',
+            'fiber',
+            'sodium',
+        ])
+            .describe('The nutrition resource to retrieve data for.'),
+        startDate: z
+            .string()
+            .regex(/^\d{4}-\d{2}-\d{2}$/, 'Start date must be in YYYY-MM-DD format.')
+            .describe('The start date for which to retrieve nutrition data (YYYY-MM-DD).'),
+        endDate: z
+            .string()
+            .regex(/^\d{4}-\d{2}-\d{2}$/, 'End date must be in YYYY-MM-DD format.')
+            .describe('The end date for which to retrieve nutrition data (YYYY-MM-DD).'),
+    };
+    server.tool(rangeToolName, rangeDescription, rangeParametersSchemaShape, async ({ resource, startDate, endDate, }) => {
+        // Construct the endpoint dynamically
+        const endpoint = `foods/log/${resource}/date/${startDate}/${endDate}.json`;
+        // Make the request
+        const nutritionData = await makeFitbitRequest(endpoint, getAccessTokenFn, FITBIT_API_BASE);
+        // Handle API call failure
+        if (!nutritionData) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to retrieve nutrition data from Fitbit API for resource '${resource}' and the date range '${startDate}' to '${endDate}'. Check token, permissions, date format, and ensure the range is 1,095 days or less.`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        // Handle no data found
+        const resourceKey = `foods-log-${resource}`;
+        const nutritionEntries = nutritionData[resourceKey] || [];
+        if (nutritionEntries.length === 0) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `No nutrition data found for resource '${resource}' and the date range '${startDate}' to '${endDate}'.`,
+                    },
+                ],
+            };
+        }
+        // Return successful response
+        const rawJsonResponse = JSON.stringify(nutritionData, null, 2);
+        return {
+            content: [{ type: 'text', text: rawJsonResponse }],
+        };
+    });
+}

package/build/profile.js

@@ -0,0 +1,19 @@
+import { registerTool, handleFitbitApiCall } from './utils.js';
+/**
+ * Registers a single, parameterized Fitbit profile tool with the MCP server.
+ * @param server The McpServer instance.
+ * @param getAccessTokenFn Function to retrieve the current access token.
+ */
+export function registerProfileTool(server, getAccessTokenFn) {
+    registerTool(server, {
+        name: 'get_profile',
+        description: "Get the raw JSON response for the user's Fitbit profile.",
+        parametersSchema: {},
+        handler: async () => {
+            const endpoint = 'profile.json';
+            return handleFitbitApiCall(endpoint, {}, getAccessTokenFn, {
+                errorContext: 'profile data'
+            });
+        }
+    });
+}

package/build/sleep.js

@@ -0,0 +1,27 @@
+import { registerTool, CommonSchemas, handleFitbitApiCall } from './utils.js';
+import { FITBIT_API_VERSIONS, VALIDATION_MESSAGES } from './config.js';
+// --- Tool Registration ---
+/**
+ * Registers a single, parameterized Fitbit sleep tool with the MCP server for a date range.
+ * @param server The McpServer instance.
+ * @param getAccessTokenFn Function to retrieve the current access token.
+ */
+export function registerSleepTool(server, getAccessTokenFn) {
+    registerTool(server, {
+        name: 'get_sleep_by_date_range',
+        description: `Get the raw JSON response for sleep logs from Fitbit for a specific date range. Requires 'startDate' and 'endDate' parameters in 'YYYY-MM-DD' format. ${VALIDATION_MESSAGES.MAX_RANGE_100_DAYS}.`,
+        parametersSchema: {
+            startDate: CommonSchemas.startDate,
+            endDate: CommonSchemas.endDate,
+        },
+        handler: async ({ startDate, endDate }) => {
+            const endpoint = `/sleep/date/${startDate}/${endDate}.json`;
+            return handleFitbitApiCall(endpoint, { startDate, endDate }, getAccessTokenFn, {
+                apiBase: FITBIT_API_VERSIONS.V1_2,
+                successDataExtractor: (data) => data.sleep || [],
+                noDataMessage: `the date range '${startDate}' to '${endDate}'`,
+                errorContext: `date range '${startDate}' to '${endDate}'`
+            });
+        }
+    });
+}

package/build/utils.js

@@ -0,0 +1,120 @@
+/**
+ * Shared utility functions for Fitbit API integration
+ */
+import { z } from 'zod';
+import { HTTP_CONFIG, ERROR_MESSAGES, FITBIT_API_VERSIONS, DATE_REGEX, VALIDATION_MESSAGES, TIME_PERIODS, HEART_RATE_DETAIL_LEVELS } from './config.js';
+/**
+ * Makes a generic request to the Fitbit API.
+ * Handles adding the base URL, authorization header, and basic error handling.
+ * @param endpoint The specific API endpoint path (e.g., '/body/weight/date/today/30d.json').
+ * @param getAccessTokenFn A function that returns the current valid access token or null.
+ * @param apiBase The base URL for the API (defaults to v1, can be overridden for different API versions)
+ * @returns A promise resolving to the parsed JSON response (type T) or null if the request fails.
+ */
+export async function makeFitbitRequest(endpoint, getAccessTokenFn, apiBase = FITBIT_API_VERSIONS.V1) {
+    const currentAccessToken = await getAccessTokenFn();
+    if (!currentAccessToken) {
+        console.error(`Error: ${ERROR_MESSAGES.NO_ACCESS_TOKEN}`);
+        return null;
+    }
+    // Ensure endpoint starts correctly relative to the user path
+    const cleanEndpoint = endpoint.startsWith('/')
+        ? endpoint.substring(1)
+        : endpoint;
+    // Construct the full URL including the user scope '-'.
+    const url = `${apiBase}/user/-/${cleanEndpoint}`;
+    console.error(`Attempting Fitbit API request to: ${url}`);
+    const headers = {
+        'User-Agent': HTTP_CONFIG.USER_AGENT,
+        Authorization: `Bearer ${currentAccessToken}`,
+        Accept: 'application/json',
+    };
+    try {
+        const response = await fetch(url, { headers });
+        if (!response.ok) {
+            const errorBody = await response.text();
+            console.error(`Fitbit API Error! Status: ${response.status}, URL: ${url}, Body: ${errorBody}`);
+            if (response.status === 401) {
+                console.error(ERROR_MESSAGES.TOKEN_EXPIRED);
+            }
+            return null;
+        }
+        // Handle potential empty response body for certain success statuses (e.g., 204 No Content)
+        if (response.status === 204) {
+            return {}; // Return an empty object or appropriate type for no content
+        }
+        return (await response.json());
+    }
+    catch (error) {
+        console.error(`Error making Fitbit request to ${url}:`, error);
+        return null;
+    }
+}
+// === Parameter Validation Schemas ===
+export const CommonSchemas = {
+    period: z
+        .enum(TIME_PERIODS)
+        .describe(VALIDATION_MESSAGES.PERIOD_REQUIRED),
+    startDate: z
+        .string()
+        .regex(DATE_REGEX, VALIDATION_MESSAGES.DATE_FORMAT)
+        .describe(VALIDATION_MESSAGES.START_DATE_REQUIRED),
+    endDate: z
+        .string()
+        .regex(DATE_REGEX, VALIDATION_MESSAGES.DATE_FORMAT)
+        .describe(VALIDATION_MESSAGES.END_DATE_REQUIRED),
+    detailLevel: z
+        .enum(HEART_RATE_DETAIL_LEVELS)
+        .describe(VALIDATION_MESSAGES.DETAIL_LEVEL_REQUIRED),
+    date: z
+        .string()
+        .regex(DATE_REGEX, VALIDATION_MESSAGES.DATE_FORMAT)
+        .describe('The date for which to retrieve data (YYYY-MM-DD)'),
+    afterDate: z
+        .string()
+        .regex(DATE_REGEX, VALIDATION_MESSAGES.DATE_FORMAT)
+        .describe('Retrieve activities after this date (YYYY-MM-DD)'),
+    limit: z
+        .number()
+        .min(1)
+        .max(100)
+        .optional()
+        .describe('Maximum number of items to return (1-100, default: 20)')
+};
+// === Tool Response Helpers ===
+export function createErrorResponse(message) {
+    return {
+        content: [{ type: 'text', text: message }],
+        isError: true,
+    };
+}
+export function createSuccessResponse(data) {
+    const rawJsonResponse = JSON.stringify(data, null, 2);
+    return {
+        content: [{ type: 'text', text: rawJsonResponse }],
+    };
+}
+export function createNoDataResponse(context) {
+    return {
+        content: [{ type: 'text', text: `${ERROR_MESSAGES.NO_DATA_FOUND} ${context}.` }],
+    };
+}
+export function registerTool(server, config) {
+    server.tool(config.name, config.description, config.parametersSchema, config.handler);
+}
+// === Fitbit-Specific Tool Helpers ===
+export async function handleFitbitApiCall(endpoint, params, getAccessTokenFn, options = {}) {
+    const { apiBase = FITBIT_API_VERSIONS.V1, successDataExtractor, noDataMessage, errorContext = JSON.stringify(params) } = options;
+    const responseData = await makeFitbitRequest(endpoint, getAccessTokenFn, apiBase);
+    if (!responseData) {
+        return createErrorResponse(`${ERROR_MESSAGES.API_REQUEST_FAILED} for ${errorContext}. ${ERROR_MESSAGES.CHECK_TOKEN_PERMISSIONS}.`);
+    }
+    // Check for empty data if extractor provided
+    if (successDataExtractor) {
+        const extractedData = successDataExtractor(responseData);
+        if (!extractedData || extractedData.length === 0) {
+            return createNoDataResponse(noDataMessage || errorContext);
+        }
+    }
+    return createSuccessResponse(responseData);
+}

package/build/weight.js

@@ -0,0 +1,24 @@
+import { registerTool, CommonSchemas, handleFitbitApiCall } from './utils.js';
+// --- Tool Registration ---
+/**
+ * Registers a single, parameterized Fitbit weight tool with the MCP server.
+ * @param server The McpServer instance.
+ * @param getAccessTokenFn Function to retrieve the current access token.
+ */
+export function registerWeightTool(server, getAccessTokenFn) {
+    registerTool(server, {
+        name: 'get_weight',
+        description: "Get the raw JSON response for weight entries from Fitbit for a specified period ending today. Requires a 'period' parameter such as '1d', '7d', '30d', '3m', '6m', '1y'",
+        parametersSchema: {
+            period: CommonSchemas.period,
+        },
+        handler: async ({ period }) => {
+            const endpoint = `/body/weight/date/today/${period}.json`;
+            return handleFitbitApiCall(endpoint, { period }, getAccessTokenFn, {
+                successDataExtractor: (data) => data['body-weight'] || [],
+                noDataMessage: `the period '${period}'`,
+                errorContext: `period '${period}'`
+            });
+        }
+    });
+}