hevy-mcp-server 1.0.0

package/dist/tools.js

@@ -0,0 +1,610 @@
+/**
+ * MCP Tools for Hevy API interactions
+ * Provides tools for managing workouts, routines, and exercise data
+ */
+// Tool definitions for MCP
+export const toolDefinitions = [
+    {
+        name: 'get_workouts',
+        description: 'Get a paginated list of workouts from Hevy',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                page: {
+                    type: 'number',
+                    description: 'Page number (default: 1)',
+                    minimum: 1,
+                },
+                pageSize: {
+                    type: 'number',
+                    description: 'Number of workouts per page (default: 10, max: 10)',
+                    minimum: 1,
+                    maximum: 10,
+                },
+            },
+        },
+    },
+    {
+        name: 'get_workout',
+        description: 'Get details of a specific workout by ID',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workoutId: {
+                    type: 'string',
+                    description: 'The unique workout ID',
+                },
+            },
+            required: ['workoutId'],
+        },
+    },
+    {
+        name: 'get_all_workouts',
+        description: 'Get all workouts (fetches all pages automatically)',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+    },
+    {
+        name: 'create_workout',
+        description: 'Create a new workout',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                title: {
+                    type: 'string',
+                    description: 'Workout title',
+                },
+                description: {
+                    type: 'string',
+                    description: 'Workout description',
+                },
+                start_time: {
+                    type: 'string',
+                    description: 'Start time in ISO 8601 format (e.g., 2024-08-14T12:00:00Z)',
+                },
+                end_time: {
+                    type: 'string',
+                    description: 'End time in ISO 8601 format (optional)',
+                },
+                is_private: {
+                    type: 'boolean',
+                    description: 'Whether the workout is private',
+                },
+                exercises: {
+                    type: 'array',
+                    description: 'Array of exercises in the workout',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            exercise_template_id: {
+                                type: 'string',
+                                description: 'Exercise template ID',
+                            },
+                            notes: {
+                                type: 'string',
+                                description: 'Notes for the exercise',
+                            },
+                            sets: {
+                                type: 'array',
+                                description: 'Array of sets for the exercise',
+                                items: {
+                                    type: 'object',
+                                    properties: {
+                                        type: {
+                                            type: 'string',
+                                            enum: ['warmup', 'normal', 'failure', 'dropset'],
+                                            description: 'Set type',
+                                        },
+                                        weight_kg: {
+                                            type: 'number',
+                                            description: 'Weight in kilograms',
+                                        },
+                                        reps: {
+                                            type: 'number',
+                                            description: 'Number of repetitions',
+                                        },
+                                        rpe: {
+                                            type: 'number',
+                                            description: 'RPE (Rate of Perceived Exertion)',
+                                        },
+                                    },
+                                    required: ['type'],
+                                },
+                            },
+                        },
+                        required: ['exercise_template_id', 'sets'],
+                    },
+                },
+            },
+            required: ['title', 'start_time', 'exercises'],
+        },
+    },
+    {
+        name: 'get_routines',
+        description: 'Get a paginated list of routines from Hevy',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                page: {
+                    type: 'number',
+                    description: 'Page number (default: 1)',
+                    minimum: 1,
+                },
+                pageSize: {
+                    type: 'number',
+                    description: 'Number of routines per page (default: 10, max: 10)',
+                    minimum: 1,
+                    maximum: 10,
+                },
+            },
+        },
+    },
+    {
+        name: 'get_routine',
+        description: 'Get details of a specific routine by ID',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                routineId: {
+                    type: 'string',
+                    description: 'The unique routine ID',
+                },
+            },
+            required: ['routineId'],
+        },
+    },
+    {
+        name: 'get_all_routines',
+        description: 'Get all routines (fetches all pages automatically)',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+    },
+    {
+        name: 'create_routine',
+        description: 'Create a new routine',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                title: {
+                    type: 'string',
+                    description: 'Routine title',
+                },
+                folder_id: {
+                    type: 'number',
+                    description: 'Folder ID to place the routine in (null for default folder)',
+                },
+                notes: {
+                    type: 'string',
+                    description: 'Notes for the routine',
+                },
+                exercises: {
+                    type: 'array',
+                    description: 'Array of exercises in the routine',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            exercise_template_id: {
+                                type: 'string',
+                                description: 'Exercise template ID',
+                            },
+                            rest_seconds: {
+                                type: 'number',
+                                description: 'Rest time between sets in seconds',
+                            },
+                            notes: {
+                                type: 'string',
+                                description: 'Notes for the exercise',
+                            },
+                            sets: {
+                                type: 'array',
+                                description: 'Array of sets for the exercise',
+                                items: {
+                                    type: 'object',
+                                    properties: {
+                                        type: {
+                                            type: 'string',
+                                            enum: ['warmup', 'normal', 'failure', 'dropset'],
+                                            description: 'Set type',
+                                        },
+                                        weight_kg: {
+                                            type: 'number',
+                                            description: 'Target weight in kilograms',
+                                        },
+                                        reps: {
+                                            type: 'number',
+                                            description: 'Target number of repetitions',
+                                        },
+                                        rep_range: {
+                                            type: 'object',
+                                            properties: {
+                                                start: {
+                                                    type: 'number',
+                                                    description: 'Minimum reps in range',
+                                                },
+                                                end: {
+                                                    type: 'number',
+                                                    description: 'Maximum reps in range',
+                                                },
+                                            },
+                                            description: 'Rep range for the set',
+                                        },
+                                    },
+                                    required: ['type'],
+                                },
+                            },
+                        },
+                        required: ['exercise_template_id', 'sets'],
+                    },
+                },
+            },
+            required: ['title', 'exercises'],
+        },
+    },
+    {
+        name: 'get_routine_folders',
+        description: 'Get all routine folders',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+    },
+    {
+        name: 'create_routine_folder',
+        description: 'Create a new routine folder',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                title: {
+                    type: 'string',
+                    description: 'Folder title',
+                },
+            },
+            required: ['title'],
+        },
+    },
+    {
+        name: 'get_exercise_templates',
+        description: 'Get all exercise templates available in Hevy',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                search: {
+                    type: 'string',
+                    description: 'Optional search term to filter exercises',
+                },
+            },
+        },
+    },
+    {
+        name: 'search_exercise_templates',
+        description: 'Search for exercise templates by name or muscle group',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'Search query (exercise name or muscle group)',
+                },
+                muscle_group: {
+                    type: 'string',
+                    description: 'Filter by specific muscle group',
+                },
+                equipment: {
+                    type: 'string',
+                    description: 'Filter by equipment type',
+                },
+            },
+            required: ['query'],
+        },
+    },
+    {
+        name: 'get_exercise_history',
+        description: 'Get exercise history for a specific exercise template',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                exercise_template_id: {
+                    type: 'string',
+                    description: 'Exercise template ID',
+                },
+                start_date: {
+                    type: 'string',
+                    description: 'Start date filter (ISO 8601 format)',
+                },
+                end_date: {
+                    type: 'string',
+                    description: 'End date filter (ISO 8601 format)',
+                },
+            },
+            required: ['exercise_template_id'],
+        },
+    },
+    {
+        name: 'get_workout_count',
+        description: 'Get the total number of workouts in the account',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+    },
+    {
+        name: 'analyze_workout_trends',
+        description: 'Analyze workout trends and progress over time',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                days: {
+                    type: 'number',
+                    description: 'Number of days to analyze (default: 30)',
+                    minimum: 1,
+                },
+                exercise_template_id: {
+                    type: 'string',
+                    description: 'Focus analysis on specific exercise (optional)',
+                },
+            },
+        },
+    },
+];
+// Tool implementations
+export const tools = {
+    get_workouts: async (client, args) => {
+        const { page = 1, pageSize = 10 } = args;
+        const result = await client.getWorkouts(page, pageSize);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    },
+    get_workout: async (client, args) => {
+        const { workoutId } = args;
+        const result = await client.getWorkout(workoutId);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    },
+    get_all_workouts: async (client) => {
+        const workouts = await client.getAllWorkouts();
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({ workouts, total: workouts.length }, null, 2),
+                },
+            ],
+        };
+    },
+    create_workout: async (client, args) => {
+        const result = await client.createWorkout(args);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    },
+    get_routines: async (client, args) => {
+        const { page = 1, pageSize = 10 } = args;
+        const result = await client.getRoutines(page, pageSize);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    },
+    get_routine: async (client, args) => {
+        const { routineId } = args;
+        const result = await client.getRoutine(routineId);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    },
+    get_all_routines: async (client) => {
+        const routines = await client.getAllRoutines();
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({ routines, total: routines.length }, null, 2),
+                },
+            ],
+        };
+    },
+    create_routine: async (client, args) => {
+        const result = await client.createRoutine(args);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    },
+    get_routine_folders: async (client) => {
+        const folders = await client.getAllRoutineFolders();
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({ routine_folders: folders, total: folders.length }, null, 2),
+                },
+            ],
+        };
+    },
+    create_routine_folder: async (client, args) => {
+        const { title } = args;
+        const result = await client.createRoutineFolder(title);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    },
+    get_exercise_templates: async (client, args) => {
+        const templates = await client.getAllExerciseTemplates();
+        let filteredTemplates = templates;
+        if (args.search) {
+            const searchLower = args.search.toLowerCase();
+            filteredTemplates = templates.filter(template => template.title.toLowerCase().includes(searchLower) ||
+                template.primary_muscle_group.toLowerCase().includes(searchLower) ||
+                template.secondary_muscle_groups.some(muscle => muscle.toLowerCase().includes(searchLower)));
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        exercise_templates: filteredTemplates,
+                        total: filteredTemplates.length,
+                        search: args.search || null,
+                    }, null, 2),
+                },
+            ],
+        };
+    },
+    search_exercise_templates: async (client, args) => {
+        const { query, muscle_group, equipment } = args;
+        const templates = await client.getAllExerciseTemplates();
+        const filtered = templates.filter(template => {
+            const queryMatch = !query || template.title.toLowerCase().includes(query.toLowerCase());
+            const muscleMatch = !muscle_group ||
+                template.primary_muscle_group.toLowerCase().includes(muscle_group.toLowerCase()) ||
+                template.secondary_muscle_groups.some(muscle => muscle.toLowerCase().includes(muscle_group.toLowerCase()));
+            // Note: Equipment filtering would require additional API data that's not in the current schema
+            const equipmentMatch = !equipment || template.title.toLowerCase().includes(equipment.toLowerCase());
+            return queryMatch && muscleMatch && equipmentMatch;
+        });
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        exercise_templates: filtered,
+                        total: filtered.length,
+                        filters: { query, muscle_group, equipment },
+                    }, null, 2),
+                },
+            ],
+        };
+    },
+    get_exercise_history: async (client, args) => {
+        const { exercise_template_id, start_date, end_date } = args;
+        const result = await client.getExerciseHistory(exercise_template_id, start_date, end_date);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    },
+    get_workout_count: async (client) => {
+        const result = await client.getWorkoutCount();
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    },
+    analyze_workout_trends: async (client, args) => {
+        const { days = 30, exercise_template_id } = args;
+        const endDate = new Date();
+        const startDate = new Date();
+        startDate.setDate(endDate.getDate() - days);
+        // Get all workouts and filter by date range
+        const allWorkouts = await client.getAllWorkouts();
+        const recentWorkouts = allWorkouts.filter(workout => {
+            const workoutDate = new Date(workout.start_time);
+            return workoutDate >= startDate && workoutDate <= endDate;
+        });
+        let analysis = {
+            period: `${days} days`,
+            start_date: startDate.toISOString(),
+            end_date: endDate.toISOString(),
+            total_workouts: recentWorkouts.length,
+            workout_frequency: recentWorkouts.length / days,
+        };
+        if (exercise_template_id) {
+            // Analyze specific exercise
+            const exerciseHistory = await client.getExerciseHistory(exercise_template_id, startDate.toISOString(), endDate.toISOString());
+            const history = exerciseHistory.exercise_history;
+            if (history.length > 0) {
+                const weights = history.filter(h => h.weight_kg).map(h => h.weight_kg);
+                const reps = history.filter(h => h.reps).map(h => h.reps);
+                analysis.exercise_analysis = {
+                    exercise_template_id,
+                    total_sets: history.length,
+                    weight_trend: weights.length > 0 ? {
+                        min: Math.min(...weights),
+                        max: Math.max(...weights),
+                        avg: weights.reduce((a, b) => a + b, 0) / weights.length,
+                    } : null,
+                    rep_trend: reps.length > 0 ? {
+                        min: Math.min(...reps),
+                        max: Math.max(...reps),
+                        avg: reps.reduce((a, b) => a + b, 0) / reps.length,
+                    } : null,
+                };
+            }
+        }
+        else {
+            // General analysis
+            const exerciseCount = {};
+            let totalSets = 0;
+            recentWorkouts.forEach(workout => {
+                workout.exercises.forEach(exercise => {
+                    exerciseCount[exercise.exercise_template_id] = (exerciseCount[exercise.exercise_template_id] || 0) + 1;
+                    totalSets += exercise.sets.length;
+                });
+            });
+            analysis.general_analysis = {
+                total_sets: totalSets,
+                avg_sets_per_workout: recentWorkouts.length > 0 ? totalSets / recentWorkouts.length : 0,
+                unique_exercises: Object.keys(exerciseCount).length,
+                most_frequent_exercises: Object.entries(exerciseCount)
+                    .sort(([, a], [, b]) => b - a)
+                    .slice(0, 5)
+                    .map(([exerciseId, count]) => ({ exercise_template_id: exerciseId, frequency: count })),
+            };
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(analysis, null, 2),
+                },
+            ],
+        };
+    },
+};

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "hevy-mcp-server",
+  "version": "1.0.0",
+  "description": "Model Context Protocol (MCP) server for Hevy workout tracking app integration",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": {
+    "hevy-mcp-server": "./dist/index.js"
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "directories": {
+    "doc": "docs",
+    "test": "tests"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "lint": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build && npm test",
+    "postinstall": "echo 'hevy-mcp-server installed! Set HEVY_API_KEY environment variable and run: hevy-mcp-server'"
+  },
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "hevy",
+    "workout",
+    "fitness",
+    "api",
+    "exercise",
+    "training",
+    "gym",
+    "tracking"
+  ],
+  "author": "Noah Van Hart",
+  "license": "MIT",
+  "homepage": "https://github.com/noah-vh/hevy-mcp-server#readme",
+  "bugs": {
+    "url": "https://github.com/noah-vh/hevy-mcp-server/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/noah-vh/hevy-mcp-server.git"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.1",
+    "@types/node": "^25.0.3",
+    "nodemon": "^3.1.11",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "jest": "^30.2.0",
+    "ts-jest": "^29.4.6",
+    "tsx": "^4.21.0"
+  }
+}