thryve-mcp-server 0.0.1

package/src/schemas.ts

@@ -0,0 +1,372 @@
+import { z } from "zod";
+
+// Zod schemas for tool inputs
+
+// CATEGORY-BASED TOOLS (Primary LLM-friendly interface)
+export const GetDailyDataSchema = z.object({
+  categories: z
+    .array(
+      z.enum([
+        "Activity",
+        "Heart Rate",
+        "Sleep",
+        "Workouts",
+        "Stress & HRV",
+        "Respiratory",
+        "Blood Glucose",
+        "Body Composition",
+        "Womens Health",
+        "Nutrition",
+        "Cardiovascular",
+        "Wellness",
+        "Audio & Hearing",
+        "Microbiome",
+        "Location",
+        "Movement Analysis",
+      ])
+    )
+    .describe(
+      "Health data categories to retrieve. Choose from: Activity (steps, distance, calories), Heart Rate, Sleep, Workouts, Stress & HRV, Respiratory, Blood Glucose, Body Composition, Womens Health, Nutrition, Cardiovascular, Wellness, Audio & Hearing, Microbiome, Location, Movement Analysis"
+    ),
+  startTimestamp: z
+    .string()
+    .optional()
+    .describe(
+      "Start time in ISO 8601 format (e.g., '2025-10-28T00:00:00Z'). Defaults to 7 days ago"
+    ),
+  endTimestamp: z
+    .string()
+    .optional()
+    .describe(
+      "End time in ISO 8601 format (e.g., '2025-10-28T23:59:59Z'). Defaults to now"
+    ),
+  dataSources: z
+    .array(z.number())
+    .optional()
+    .describe(
+      "Filter by specific data source IDs (e.g., [1, 2] for Fitbit and Garmin). Leave empty for all sources"
+    ),
+  limit: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe(
+      "Maximum number of records to return per category (default: no limit)"
+    ),
+});
+
+export const GetEpochDataSchema = z.object({
+  categories: z
+    .array(
+      z.enum([
+        "Activity",
+        "Heart Rate",
+        "Sleep",
+        "Workouts",
+        "Stress & HRV",
+        "Respiratory",
+        "Blood Glucose",
+        "Body Composition",
+        "Womens Health",
+        "Nutrition",
+        "Cardiovascular",
+        "Wellness",
+        "Audio & Hearing",
+        "Microbiome",
+        "Location",
+        "Movement Analysis",
+      ])
+    )
+    .describe(
+      "Health data categories to retrieve. Choose from: Activity (steps, distance, calories), Heart Rate, Sleep, Workouts, Stress & HRV, Respiratory, Blood Glucose, Body Composition, Womens Health, Nutrition, Cardiovascular, Wellness, Audio & Hearing, Microbiome, Location, Movement Analysis"
+    ),
+  startTimestamp: z
+    .string()
+    .optional()
+    .describe(
+      "Start time in ISO 8601 format (e.g., '2025-10-28T00:00:00Z'). Defaults to 7 days ago"
+    ),
+  endTimestamp: z
+    .string()
+    .optional()
+    .describe(
+      "End time in ISO 8601 format (e.g., '2025-10-28T23:59:59Z'). Defaults to now"
+    ),
+  dataSources: z
+    .array(z.number())
+    .optional()
+    .describe(
+      "Filter by specific data source IDs (e.g., [1, 2] for Fitbit and Garmin). Leave empty for all sources"
+    ),
+  limit: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe(
+      "Maximum number of records to return per category (default: no limit)"
+    ),
+});
+
+export const SearchKeywordSchema = z.object({
+  query: z
+    .string()
+    .describe("Property name to search for (e.g., 'SleepBinary', 'Steps', 'HeartRate'). Searches for exact or partial matches in data type property names"),
+  startDate: z
+    .string()
+    .optional()
+    .describe("Filter by start date in YYYY-MM-DD format"),
+  endDate: z
+    .string()
+    .optional()
+    .describe("Filter by end date in YYYY-MM-DD format"),
+  dataType: z
+    .string()
+    .optional()
+    .describe("Filter by data type category (e.g., 'Activity', 'Sleep', 'Heart Rate')"),
+  dataSource: z
+    .string()
+    .optional()
+    .describe("Filter by data source ID (e.g., '1' for Fitbit, '2' for Garmin)"),
+  page: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .default(1)
+    .describe("Page number for pagination (default: 1)"),
+  pageSize: z
+    .number()
+    .int()
+    .positive()
+    .max(200)
+    .optional()
+    .default(50)
+    .describe("Number of results per page (default: 50, max: 200)"),
+  sortBy: z
+    .enum(["timestamp", "day", "value", "dataType", "dataSource"])
+    .optional()
+    .default("timestamp")
+    .describe("Field to sort by (default: 'timestamp')"),
+  sortOrder: z
+    .enum(["asc", "desc"])
+    .optional()
+    .default("desc")
+    .describe("Sort order (default: 'desc')"),
+});
+
+export const SearchFiltersSchema = z.object({
+  resolution: z
+    .enum(["daily", "epoch", "both"])
+    .optional()
+    .default("both")
+    .describe("Data resolution: 'daily' for daily aggregated data, 'epoch' for intraday time-series data, 'both' for combined (default: 'both')"),
+  dataTypes: z
+    .array(z.number())
+    .optional()
+    .describe("Filter by specific data type IDs (e.g., [1000, 3000] for Steps and HeartRate)"),
+  dataSources: z
+    .array(z.number())
+    .optional()
+    .describe("Filter by data source IDs (e.g., [1, 2] for Fitbit and Garmin)"),
+  categories: z
+    .array(z.enum([
+      "Activity",
+      "Heart Rate",
+      "Sleep",
+      "Workouts",
+      "Stress & HRV",
+      "Respiratory",
+      "Blood Glucose",
+      "Body Composition",
+      "Womens Health",
+      "Nutrition",
+      "Cardiovascular",
+      "Wellness",
+      "Audio & Hearing",
+      "Microbiome",
+      "Location",
+      "Movement Analysis",
+    ]))
+    .optional()
+    .describe("Filter by high-level health categories. When specified, results can be grouped by category using groupByCategory parameter"),
+  groupByCategory: z
+    .boolean()
+    .optional()
+    .default(false)
+    .describe("Group results by category (only applies when categories are specified). Returns { results: { Category: [...] }, metadata: {...} } format instead of flat paginated list"),
+  limit: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe("Maximum number of records to return (applied before pagination when groupByCategory is false)"),
+  startDate: z
+    .string()
+    .optional()
+    .describe("Filter by start date in YYYY-MM-DD format"),
+  endDate: z
+    .string()
+    .optional()
+    .describe("Filter by end date in YYYY-MM-DD format"),
+  startTimestamp: z
+    .string()
+    .optional()
+    .describe("Filter by start timestamp in ISO 8601 format (e.g., '2025-10-28T00:00:00Z')"),
+  endTimestamp: z
+    .string()
+    .optional()
+    .describe("Filter by end timestamp in ISO 8601 format (e.g., '2025-10-29T00:00:00Z')"),
+  valueMin: z
+    .number()
+    .optional()
+    .describe("Minimum value threshold for filtering"),
+  valueMax: z
+    .number()
+    .optional()
+    .describe("Maximum value threshold for filtering"),
+  page: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .default(1)
+    .describe("Page number for pagination (default: 1)"),
+  pageSize: z
+    .number()
+    .int()
+    .positive()
+    .max(200)
+    .optional()
+    .default(50)
+    .describe("Number of results per page (default: 50, max: 200)"),
+  sortBy: z
+    .enum(["timestamp", "day", "value", "dataType", "dataSource"])
+    .optional()
+    .default("timestamp")
+    .describe("Field to sort by (default: 'timestamp')"),
+  sortOrder: z
+    .enum(["asc", "desc"])
+    .optional()
+    .default("desc")
+    .describe("Sort order (default: 'desc')"),
+});
+
+export const GetSchema = z.object({
+  dataType: z
+    .number()
+    .int()
+    .positive()
+    .describe("Data type ID (e.g., 1000 for Steps, 3000 for HeartRate)"),
+  dataSource: z
+    .number()
+    .int()
+    .positive()
+    .describe("Data source ID (e.g., 1 for Fitbit, 2 for Garmin)"),
+  day: z
+    .string()
+    .optional()
+    .describe("Specific day in YYYY-MM-DD format for daily data. Provide either 'day' or 'timestamp', not both"),
+  timestamp: z
+    .string()
+    .optional()
+    .describe("Specific timestamp in ISO 8601 format for epoch data (e.g., '2025-10-28T14:30:00Z'). Provide either 'day' or 'timestamp', not both"),
+  includeMetadata: z
+    .boolean()
+    .optional()
+    .default(true)
+    .describe("Include additional metadata about the record (default: true)"),
+});
+
+// INTERNAL/ADVANCED TOOLS
+export const GetAvailableDataTypesSchema = z.object({
+  category: z
+    .enum([
+      "Activity",
+      "Heart Rate",
+      "Sleep",
+      "Workouts",
+      "Stress & HRV",
+      "Respiratory",
+      "Blood Glucose",
+      "Body Composition",
+      "Womens Health",
+      "Nutrition",
+      "Cardiovascular",
+      "Wellness",
+      "Audio & Hearing",
+      "Microbiome",
+      "Location",
+      "Movement Analysis",
+    ])
+    .optional()
+    .describe("Filter by high-level health category to see available data types in that category"),
+  search: z
+    .string()
+    .optional()
+    .describe("Search keyword to find specific data types (e.g., 'calories', 'steps', 'heart')"),
+  dataSource: z
+    .string()
+    .optional()
+    .describe("Filter by wearable brand (e.g., 'Fitbit', 'Garmin', 'Whoop', 'Oura')"),
+});
+
+// END USER INFORMATION TOOLS
+export const ListConnectedSourcesSchema = z.object({});
+
+export const ListDevicesSchema = z.object({});
+
+// CATEGORY-SPECIFIC TOOLS (16 specialized tools)
+// Base schema factory for category-specific tools
+const createCategorySchema = () => z.object({
+  resolution: z
+    .enum(["daily", "epoch"])
+    .optional()
+    .default("daily")
+    .describe("Data resolution: 'daily' for daily aggregated data, 'epoch' for intraday time-series data (default: 'daily')"),
+  startTimestamp: z
+    .string()
+    .optional()
+    .describe("Start time in ISO 8601 format (e.g., '2025-10-28T00:00:00Z'). Defaults to 7 days ago"),
+  endTimestamp: z
+    .string()
+    .optional()
+    .describe("End time in ISO 8601 format (e.g., '2025-10-28T23:59:59Z'). Defaults to now"),
+  dataSources: z
+    .array(z.number())
+    .optional()
+    .describe("Filter by specific data source IDs (e.g., [1, 2] for Fitbit and Garmin). Leave empty for all sources"),
+  limit: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe("Maximum number of records to return (default: no limit)"),
+  includeFields: z
+    .array(z.string())
+    .optional()
+    .describe("Sub-categories to include (e.g., ['Cardiovascular Health', 'Advanced Cardiac Analysis']). Leave empty for all sub-categories in this category"),
+  excludeFields: z
+    .array(z.string())
+    .optional()
+    .describe("Sub-categories to exclude (e.g., ['Advanced Cardiac Analysis']). Leave empty to exclude none"),
+});
+
+// Individual schemas for each category
+export const GetActivitySchema = createCategorySchema();
+export const GetHeartRateSchema = createCategorySchema();
+export const GetSleepSchema = createCategorySchema();
+export const GetWorkoutsSchema = createCategorySchema();
+export const GetStressAndHRVSchema = createCategorySchema();
+export const GetRespiratorySchema = createCategorySchema();
+export const GetBloodGlucoseSchema = createCategorySchema();
+export const GetBodyCompositionSchema = createCategorySchema();
+export const GetWomensHealthSchema = createCategorySchema();
+export const GetNutritionSchema = createCategorySchema();
+export const GetCardiovascularSchema = createCategorySchema();
+export const GetWellnessSchema = createCategorySchema();
+export const GetAudioAndHearingSchema = createCategorySchema();
+export const GetMicrobiomeSchema = createCategorySchema();
+export const GetLocationSchema = createCategorySchema();
+export const GetMovementAnalysisSchema = createCategorySchema();

package/src/tools/baseCategoryHandler.ts

@@ -0,0 +1,243 @@
+import type { Request } from "express";
+import type { HealthCategory } from "../category-mappings.js";
+import type { HealthDataRecord } from "../types.js";
+import {
+  extractThryveHeaders,
+  buildUrlEncodedBody,
+  getDefaultTimestampRange,
+  THRYVE_API_BASE_URL,
+} from "../helpers.js";
+import { getDataTypeIdsForCategories, CATEGORY_MAPPINGS } from "../category-mappings.js";
+import { flattenThryveResponse, enrichWithDataTypes } from "../data-enrichment.js";
+import { ALL_DATA_TYPES } from "../data-types-generated.js";
+
+export interface BaseCategoryParams {
+  resolution?: "daily" | "epoch";
+  startTimestamp?: string;
+  endTimestamp?: string;
+  dataSources?: number[];
+  limit?: number;
+  includeFields?: string[];
+  excludeFields?: string[];
+}
+
+/**
+ * Base handler for category-specific tools
+ * Fetches health data for a single category with configurable resolution
+ */
+export async function baseCategoryHandler(
+  req: Request,
+  category: HealthCategory,
+  params: BaseCategoryParams
+) {
+  const { headers, authToken } = extractThryveHeaders(req);
+
+  // Apply defaults
+  const resolution = params.resolution || "daily";
+  const defaults = getDefaultTimestampRange();
+  const startTimestamp = params.startTimestamp || defaults.startTimestamp;
+  const endTimestamp = params.endTimestamp || defaults.endTimestamp;
+
+  // Get data type IDs for this category
+  const allDataTypeIds = getDataTypeIdsForCategories([category]);
+
+  if (allDataTypeIds.length === 0) {
+    return {
+      category,
+      resolution,
+      data: [],
+      metadata: {
+        timeRange: { start: startTimestamp, end: endTimestamp },
+        totalRecords: 0,
+        message: "No data types found for this category",
+      },
+    };
+  }
+
+  // Filter data types by includeFields/excludeFields (which are actually sub-category names)
+  let filteredDataTypeIds = allDataTypeIds;
+
+  if (params.includeFields && params.includeFields.length > 0) {
+    const includeSet = new Set(params.includeFields);
+    filteredDataTypeIds = allDataTypeIds.filter((id) => {
+      const dataType = ALL_DATA_TYPES.find((dt) => dt.id === id);
+      if (!dataType) return false;
+      // Check if any of the data type's categories match the include list
+      const dataTypeCategories = dataType.category.split(",").map((c) => c.trim());
+      return dataTypeCategories.some((cat) => includeSet.has(cat));
+    });
+  }
+
+  if (params.excludeFields && params.excludeFields.length > 0) {
+    const excludeSet = new Set(params.excludeFields);
+    filteredDataTypeIds = filteredDataTypeIds.filter((id) => {
+      const dataType = ALL_DATA_TYPES.find((dt) => dt.id === id);
+      if (!dataType) return false;
+      // Check if any of the data type's categories match the exclude list
+      const dataTypeCategories = dataType.category.split(",").map((c) => c.trim());
+      return !dataTypeCategories.some((cat) => excludeSet.has(cat));
+    });
+  }
+
+  if (filteredDataTypeIds.length === 0) {
+    return {
+      category,
+      resolution,
+      data: [],
+      metadata: {
+        timeRange: { start: startTimestamp, end: endTimestamp },
+        totalRecords: 0,
+        message: "No data types match the field filters",
+        appliedFilters: {
+          includeFields: params.includeFields,
+          excludeFields: params.excludeFields,
+        },
+      },
+    };
+  }
+
+  // Fetch data based on resolution
+  let rawData: any;
+  if (resolution === "daily") {
+    rawData = await fetchDailyData(headers, authToken, startTimestamp, endTimestamp, params.dataSources);
+  } else {
+    rawData = await fetchEpochData(headers, authToken, startTimestamp, endTimestamp, params.dataSources);
+  }
+
+  // Flatten and enrich data
+  const flattenedData = flattenThryveResponse(rawData);
+  enrichWithDataTypes(flattenedData);
+
+  // Filter by category's data type IDs
+  const dataTypeIdSet = new Set(filteredDataTypeIds);
+  const categoryData = flattenedData.filter((record) => {
+    const typeId = record.dataType || record.dailyDynamicValueType || record.dynamicEpochValueType;
+    return typeId && dataTypeIdSet.has(typeId);
+  });
+
+  // Apply limit if specified
+  const limitedData = params.limit ? categoryData.slice(0, params.limit) : categoryData;
+
+  // Build metadata
+  const dataTypesFound = new Set<string>();
+  const fieldsFound = new Set<string>();
+  limitedData.forEach((record) => {
+    const typeName = record.dailyDynamicValueTypeName || record.dynamicEpochValueTypeName;
+    if (typeName) {
+      dataTypesFound.add(typeName);
+      fieldsFound.add(typeName);
+    }
+  });
+
+  const metadata: any = {
+    category,
+    resolution,
+    timeRange: {
+      start: startTimestamp,
+      end: endTimestamp,
+    },
+    totalRecords: limitedData.length,
+    fieldsFound: Array.from(fieldsFound).sort(),
+    dataSources: params.dataSources,
+  };
+
+  if (params.limit) {
+    metadata.limitApplied = params.limit;
+  }
+
+  if (params.includeFields || params.excludeFields) {
+    metadata.appliedFilters = {
+      includeFields: params.includeFields,
+      excludeFields: params.excludeFields,
+    };
+  }
+
+  return {
+    category,
+    resolution,
+    data: limitedData,
+    metadata,
+  };
+}
+
+/**
+ * Fetch daily data from Thryve API
+ */
+async function fetchDailyData(
+  headers: Record<string, string>,
+  authToken: string,
+  startTimestamp: string,
+  endTimestamp: string,
+  dataSources?: number[]
+) {
+  // Extract dates from timestamps for daily API
+  const startDay = startTimestamp.split('T')[0];
+  const endDay = endTimestamp.split('T')[0];
+
+  const dataSourcesParam = dataSources?.join(',');
+
+  const body = buildUrlEncodedBody({
+    authenticationToken: authToken,
+    startDay,
+    endDay,
+    dataSources: dataSourcesParam,
+    displayTypeName: "true",
+  });
+
+  const response = await fetch(`${THRYVE_API_BASE_URL}/v5/dailyDynamicValues`, {
+    method: "POST",
+    headers,
+    body,
+  });
+
+  if (!response.ok) {
+    throw new Error(`Thryve API error: ${response.status} ${response.statusText}`);
+  }
+
+  return await response.json();
+}
+
+/**
+ * Fetch epoch data from Thryve API
+ */
+async function fetchEpochData(
+  headers: Record<string, string>,
+  authToken: string,
+  startTimestamp: string,
+  endTimestamp: string,
+  dataSources?: number[]
+) {
+  const dataSourcesParam = dataSources?.join(',');
+
+  const body = buildUrlEncodedBody({
+    authenticationToken: authToken,
+    startTimestamp,
+    endTimestamp,
+    dataSources: dataSourcesParam,
+    displayTypeName: "true",
+  });
+
+  const response = await fetch(`${THRYVE_API_BASE_URL}/v5/dynamicEpochValues`, {
+    method: "POST",
+    headers,
+    body,
+  });
+
+  if (!response.ok) {
+    throw new Error(`Thryve API error: ${response.status} ${response.statusText}`);
+  }
+
+  return await response.json();
+}
+
+/**
+ * Get available sub-categories for a category
+ * Returns the list of Thryve sub-category names that can be used with includeFields/excludeFields
+ */
+export function getAvailableFieldsForCategory(category: HealthCategory): string[] {
+  const mapping = CATEGORY_MAPPINGS[category];
+  if (!mapping) return [];
+
+  // Return the Thryve sub-categories that this high-level category aggregates
+  return mapping.thryveCategories;
+}