Fitbit MCP Server

Instructions

Implementation Reference

• src/activities.ts:83-96 (handler)

  The inline handler function for the 'get_exercises' tool. It constructs the specific Fitbit API endpoint for listing activities after a given date and invokes the shared handleFitbitApiCall helper with appropriate data extraction and error handling.

  handler: async ({ afterDate, limit = 20 }: ActivitiesParams) => {
    const endpoint = `activities/list.json?afterDate=${afterDate}&sort=asc&offset=0&limit=${limit}`;
    
    return handleFitbitApiCall<ActivitiesListResponse, ActivitiesParams>(
      endpoint,
      { afterDate, limit },
      getAccessTokenFn,
      {
        successDataExtractor: (data) => data.activities || [],
        noDataMessage: `after date '${afterDate}'`,
        errorContext: `after date '${afterDate}'`
      }
    );
  }

• src/activities.ts:79-82 (schema)

  The input parameters schema for the 'get_exercises' tool, defining 'afterDate' (required YYYY-MM-DD) and optional 'limit' (1-100).

  parametersSchema: {
    afterDate: CommonSchemas.afterDate,
    limit: CommonSchemas.limit,
  },

• src/activities.ts:76-97 (registration)

  The registration of the 'get_exercises' tool using the registerTool utility, specifying name, description, input schema, and handler function.

  registerTool(server, {
    name: 'get_exercises',
    description: "Get the raw JSON response for exercise and activity logs from Fitbit after a specific date. Requires 'afterDate' parameter in 'YYYY-MM-DD' format. Retrieves a detailed list of logged exercises and activities.",
    parametersSchema: {
      afterDate: CommonSchemas.afterDate,
      limit: CommonSchemas.limit,
    },
    handler: async ({ afterDate, limit = 20 }: ActivitiesParams) => {
      const endpoint = `activities/list.json?afterDate=${afterDate}&sort=asc&offset=0&limit=${limit}`;
      
      return handleFitbitApiCall<ActivitiesListResponse, ActivitiesParams>(
        endpoint,
        { afterDate, limit },
        getAccessTokenFn,
        {
          successDataExtractor: (data) => data.activities || [],
          noDataMessage: `after date '${afterDate}'`,
          errorContext: `after date '${afterDate}'`
        }
      );
    }
  });

• src/utils.ts:183-222 (helper)

  Shared helper function used by 'get_exercises' (and other tools) to make Fitbit API requests, handle authentication, errors, empty data checks via extractor, and format responses as MCP ToolResponseStructure.

  export async function handleFitbitApiCall<TResponse, TParams>(
    endpoint: string,
    params: TParams,
    getAccessTokenFn: () => Promise<string | null>,
    options: {
      apiBase?: string;
      successDataExtractor?: (data: TResponse) => unknown[] | null;
      noDataMessage?: string;
      errorContext?: string;
    } = {}
  ): Promise<ToolResponseStructure> {
    const {
      apiBase = FITBIT_API_VERSIONS.V1,
      successDataExtractor,
      noDataMessage,
      errorContext = JSON.stringify(params)
    } = options;
  
    const responseData = await makeFitbitRequest<TResponse>(
      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);
  }