hevy-mcp-server 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Noah Van Hart
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,135 @@
+# Hevy MCP Server
+
+A Model Context Protocol (MCP) server for integrating with the Hevy workout tracking app API. This server provides tools and resources for managing workouts, routines, and exercise data through the MCP protocol.
+
+## Features
+
+- **Workout Management**: Create, read, and analyze workouts
+- **Routine Management**: Manage workout templates and routines
+- **Exercise Templates**: Access and search exercise databases
+- **Progress Tracking**: Analyze workout trends and progression
+- **Data Resources**: Access workout and fitness data as MCP resources
+
+## Installation
+
+### Global Installation (Recommended)
+
+```bash
+npm install -g hevy-mcp-server
+```
+
+### Local Installation
+
+```bash
+npm install hevy-mcp-server
+```
+
+## Quick Start
+
+1. **Set your Hevy API key**
+   ```bash
+   export HEVY_API_KEY=your_hevy_api_key_here
+   ```
+
+2. **Run the server**
+   ```bash
+   hevy-mcp-server
+   ```
+
+## MCP Configuration
+
+### Claude Desktop App
+
+Add this to your Claude Desktop configuration file:
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "hevy": {
+      "command": "npx",
+      "args": ["hevy-mcp-server"],
+      "env": {
+        "HEVY_API_KEY": "your_hevy_api_key_here"
+      }
+    }
+  }
+}
+```
+
+### Other MCP Clients
+
+For other MCP clients, use:
+
+```bash
+HEVY_API_KEY=your_key hevy-mcp-server
+```
+
+## MCP Tools Available
+
+### Workout Tools
+- `get_workouts` - Get paginated list of workouts
+- `get_workout` - Get specific workout details
+- `get_all_workouts` - Get all workouts automatically
+- `create_workout` - Create a new workout
+- `get_workout_count` - Get total workout count
+- `analyze_workout_trends` - Analyze workout patterns and progress
+
+### Routine Tools
+- `get_routines` - Get paginated list of routines
+- `get_routine` - Get specific routine details
+- `get_all_routines` - Get all routines automatically
+- `create_routine` - Create a new routine
+- `get_routine_folders` - Get routine organization folders
+- `create_routine_folder` - Create new routine folder
+
+### Exercise Tools
+- `get_exercise_templates` - Get all available exercises
+- `search_exercise_templates` - Search exercises by name/muscle group
+- `get_exercise_history` - Get exercise performance history
+
+## MCP Resources Available
+
+- `hevy://workouts` - Complete workout data with statistics
+- `hevy://routines` - All workout routines and templates
+- `hevy://exercise-templates` - Exercise database with muscle groups
+- `hevy://routine-folders` - Routine organization folders
+- `hevy://account-summary` - High-level account statistics
+- `hevy://recent-workouts` - Last 10 workouts with key metrics
+- `hevy://exercise-list` - Simple exercise reference list
+
+## API Documentation
+
+This server interfaces with the Hevy API v1. You'll need a valid Hevy API key to use this server.
+
+## Development
+
+### Setup
+```bash
+npm install
+```
+
+### Build
+```bash
+npm run build
+```
+
+### Test
+```bash
+npm test
+```
+
+### Development Mode
+```bash
+npm run dev
+```
+
+## License
+
+MIT
+
+## Repository
+
+https://github.com/noah-vh/hevy-mcp-server

package/dist/hevy-api.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Hevy API Client for interacting with the Hevy workout tracking API
+ * Supports workouts, routines, exercise templates, and more
+ */
+export interface HevySet {
+    index: number;
+    type: 'warmup' | 'normal' | 'failure' | 'dropset';
+    weight_kg: number | null;
+    reps: number | null;
+    distance_meters: number | null;
+    duration_seconds: number | null;
+    rpe: number | null;
+    custom_metric: number | null;
+}
+export interface HevyRoutineSet extends HevySet {
+    rep_range?: {
+        start: number;
+        end: number;
+    };
+}
+export interface HevyExercise {
+    index: number;
+    title: string;
+    notes: string;
+    exercise_template_id: string;
+    superset_id: number | null;
+    sets: HevySet[];
+}
+export interface HevyRoutineExercise {
+    index: number;
+    title: string;
+    notes: string;
+    exercise_template_id: string;
+    superset_id: number | null;
+    rest_seconds: number | null;
+    sets: HevyRoutineSet[];
+}
+export interface HevyWorkout {
+    id: string;
+    title: string;
+    routine_id?: string;
+    description: string;
+    start_time: string;
+    end_time: string | null;
+    updated_at: string;
+    created_at: string;
+    exercises: HevyExercise[];
+}
+export interface HevyRoutine {
+    id: string;
+    title: string;
+    folder_id: number | null;
+    updated_at: string;
+    created_at: string;
+    exercises: HevyRoutineExercise[];
+}
+export interface HevyRoutineFolder {
+    id: number;
+    index: number;
+    title: string;
+    updated_at: string;
+    created_at: string;
+}
+export interface HevyExerciseTemplate {
+    id: string;
+    title: string;
+    type: string;
+    primary_muscle_group: string;
+    secondary_muscle_groups: string[];
+    is_custom: boolean;
+}
+export interface HevyExerciseHistoryEntry {
+    workout_id: string;
+    workout_title: string;
+    workout_start_time: string;
+    workout_end_time: string | null;
+    exercise_template_id: string;
+    weight_kg: number | null;
+    reps: number | null;
+    distance_meters: number | null;
+    duration_seconds: number | null;
+    rpe: number | null;
+    custom_metric: number | null;
+    set_type: string;
+}
+export interface HevyAPIResponse<T> {
+    page?: number;
+    page_count?: number;
+    [key: string]: T | any;
+}
+export declare class HevyAPIClient {
+    private apiKey;
+    private baseUrl;
+    constructor(apiKey: string, baseUrl?: string);
+    private makeRequest;
+    getWorkouts(page?: number, pageSize?: number): Promise<HevyAPIResponse<HevyWorkout[]>>;
+    getWorkout(workoutId: string): Promise<{
+        workout: HevyWorkout;
+    }>;
+    createWorkout(workout: Partial<HevyWorkout>): Promise<{
+        workout: HevyWorkout;
+    }>;
+    updateWorkout(workoutId: string, workout: Partial<HevyWorkout>): Promise<{
+        workout: HevyWorkout;
+    }>;
+    getWorkoutCount(): Promise<{
+        workout_count: number;
+    }>;
+    getWorkoutEvents(page?: number, pageSize?: number, since?: string): Promise<HevyAPIResponse<any[]>>;
+    getRoutines(page?: number, pageSize?: number): Promise<HevyAPIResponse<HevyRoutine[]>>;
+    getRoutine(routineId: string): Promise<{
+        routine: HevyRoutine;
+    }>;
+    createRoutine(routine: Partial<HevyRoutine>): Promise<{
+        routine: HevyRoutine;
+    }>;
+    updateRoutine(routineId: string, routine: Partial<HevyRoutine>): Promise<{
+        routine: HevyRoutine;
+    }>;
+    getRoutineFolders(page?: number, pageSize?: number): Promise<HevyAPIResponse<HevyRoutineFolder[]>>;
+    getRoutineFolder(folderId: string): Promise<{
+        routine_folder: HevyRoutineFolder;
+    }>;
+    createRoutineFolder(folderTitle: string): Promise<{
+        routine_folder: HevyRoutineFolder;
+    }>;
+    getExerciseTemplates(page?: number, pageSize?: number): Promise<HevyAPIResponse<HevyExerciseTemplate[]>>;
+    getExerciseTemplate(templateId: string): Promise<{
+        exercise_template: HevyExerciseTemplate;
+    }>;
+    createExerciseTemplate(exercise: {
+        title: string;
+        exercise_type: string;
+        equipment_category: string;
+        muscle_group: string;
+        other_muscles?: string[];
+    }): Promise<{
+        id: string;
+    }>;
+    getExerciseHistory(templateId: string, startDate?: string, endDate?: string): Promise<{
+        exercise_history: HevyExerciseHistoryEntry[];
+    }>;
+    getAllWorkouts(): Promise<HevyWorkout[]>;
+    getAllRoutines(): Promise<HevyRoutine[]>;
+    getAllExerciseTemplates(): Promise<HevyExerciseTemplate[]>;
+    getAllRoutineFolders(): Promise<HevyRoutineFolder[]>;
+}

package/dist/hevy-api.js

@@ -0,0 +1,165 @@
+/**
+ * Hevy API Client for interacting with the Hevy workout tracking API
+ * Supports workouts, routines, exercise templates, and more
+ */
+const HEVY_API_BASE = 'https://api.hevyapp.com/v1';
+export class HevyAPIClient {
+    apiKey;
+    baseUrl;
+    constructor(apiKey, baseUrl = HEVY_API_BASE) {
+        this.apiKey = apiKey;
+        this.baseUrl = baseUrl;
+    }
+    async makeRequest(endpoint, options = {}) {
+        const url = `${this.baseUrl}${endpoint}`;
+        const response = await fetch(url, {
+            ...options,
+            headers: {
+                'api-key': this.apiKey,
+                'Content-Type': 'application/json',
+                ...options.headers,
+            },
+        });
+        if (response.status === 429) {
+            throw new Error('Rate limit exceeded. Please try again later.');
+        }
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Hevy API error (${response.status}): ${errorText}`);
+        }
+        return response.json();
+    }
+    // Workouts
+    async getWorkouts(page = 1, pageSize = 10) {
+        return this.makeRequest(`/workouts?page=${page}&pageSize=${pageSize}`);
+    }
+    async getWorkout(workoutId) {
+        return this.makeRequest(`/workouts/${workoutId}`);
+    }
+    async createWorkout(workout) {
+        return this.makeRequest('/workouts', {
+            method: 'POST',
+            body: JSON.stringify({ workout }),
+        });
+    }
+    async updateWorkout(workoutId, workout) {
+        return this.makeRequest(`/workouts/${workoutId}`, {
+            method: 'PUT',
+            body: JSON.stringify({ workout }),
+        });
+    }
+    async getWorkoutCount() {
+        return this.makeRequest('/workouts/count');
+    }
+    async getWorkoutEvents(page = 1, pageSize = 10, since = '1970-01-01T00:00:00Z') {
+        return this.makeRequest(`/workouts/events?page=${page}&pageSize=${pageSize}&since=${encodeURIComponent(since)}`);
+    }
+    // Routines
+    async getRoutines(page = 1, pageSize = 10) {
+        return this.makeRequest(`/routines?page=${page}&pageSize=${pageSize}`);
+    }
+    async getRoutine(routineId) {
+        return this.makeRequest(`/routines/${routineId}`);
+    }
+    async createRoutine(routine) {
+        return this.makeRequest('/routines', {
+            method: 'POST',
+            body: JSON.stringify({ routine }),
+        });
+    }
+    async updateRoutine(routineId, routine) {
+        return this.makeRequest(`/routines/${routineId}`, {
+            method: 'PUT',
+            body: JSON.stringify({ routine }),
+        });
+    }
+    // Routine Folders
+    async getRoutineFolders(page = 1, pageSize = 10) {
+        return this.makeRequest(`/routine_folders?page=${page}&pageSize=${pageSize}`);
+    }
+    async getRoutineFolder(folderId) {
+        return this.makeRequest(`/routine_folders/${folderId}`);
+    }
+    async createRoutineFolder(folderTitle) {
+        return this.makeRequest('/routine_folders', {
+            method: 'POST',
+            body: JSON.stringify({ routine_folder: { title: folderTitle } }),
+        });
+    }
+    // Exercise Templates
+    async getExerciseTemplates(page = 1, pageSize = 100) {
+        return this.makeRequest(`/exercise_templates?page=${page}&pageSize=${pageSize}`);
+    }
+    async getExerciseTemplate(templateId) {
+        return this.makeRequest(`/exercise_templates/${templateId}`);
+    }
+    async createExerciseTemplate(exercise) {
+        return this.makeRequest('/exercise_templates', {
+            method: 'POST',
+            body: JSON.stringify({ exercise }),
+        });
+    }
+    // Exercise History
+    async getExerciseHistory(templateId, startDate, endDate) {
+        let url = `/exercise_history/${templateId}`;
+        const params = new URLSearchParams();
+        if (startDate)
+            params.append('start_date', startDate);
+        if (endDate)
+            params.append('end_date', endDate);
+        if (params.toString()) {
+            url += `?${params.toString()}`;
+        }
+        return this.makeRequest(url);
+    }
+    // Utility methods
+    async getAllWorkouts() {
+        const firstPage = await this.getWorkouts(1, 10);
+        const allWorkouts = [...(firstPage.workouts || [])];
+        if (firstPage.page_count && firstPage.page_count > 1) {
+            for (let page = 2; page <= firstPage.page_count; page++) {
+                const pageData = await this.getWorkouts(page, 10);
+                allWorkouts.push(...(pageData.workouts || []));
+                // Add delay to respect rate limits
+                await new Promise(resolve => setTimeout(resolve, 100));
+            }
+        }
+        return allWorkouts;
+    }
+    async getAllRoutines() {
+        const firstPage = await this.getRoutines(1, 10);
+        const allRoutines = [...(firstPage.routines || [])];
+        if (firstPage.page_count && firstPage.page_count > 1) {
+            for (let page = 2; page <= firstPage.page_count; page++) {
+                const pageData = await this.getRoutines(page, 10);
+                allRoutines.push(...(pageData.routines || []));
+                await new Promise(resolve => setTimeout(resolve, 100));
+            }
+        }
+        return allRoutines;
+    }
+    async getAllExerciseTemplates() {
+        const firstPage = await this.getExerciseTemplates(1, 100);
+        const allTemplates = [...(firstPage.exercise_templates || [])];
+        if (firstPage.page_count && firstPage.page_count > 1) {
+            for (let page = 2; page <= firstPage.page_count; page++) {
+                const pageData = await this.getExerciseTemplates(page, 100);
+                allTemplates.push(...(pageData.exercise_templates || []));
+                await new Promise(resolve => setTimeout(resolve, 100));
+            }
+        }
+        return allTemplates;
+    }
+    async getAllRoutineFolders() {
+        const firstPage = await this.getRoutineFolders(1, 10);
+        const allFolders = [...(firstPage.routine_folders || [])];
+        if (firstPage.page_count && firstPage.page_count > 1) {
+            for (let page = 2; page <= firstPage.page_count; page++) {
+                const pageData = await this.getRoutineFolders(page, 10);
+                allFolders.push(...(pageData.routine_folders || []));
+                await new Promise(resolve => setTimeout(resolve, 100));
+            }
+        }
+        return allFolders;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ErrorCode, ListResourcesRequestSchema, ListToolsRequestSchema, McpError, ReadResourceRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { HevyAPIClient } from './hevy-api.js';
+import { tools, toolDefinitions } from './tools.js';
+import { resources, resourceDefinitions } from './resources.js';
+const API_KEY = process.env.HEVY_API_KEY;
+if (!API_KEY) {
+    console.error('Error: HEVY_API_KEY environment variable is required');
+    process.exit(1);
+}
+const hevyClient = new HevyAPIClient(API_KEY);
+const server = new Server({
+    name: 'hevy-mcp-server',
+    version: '1.0.0',
+}, {
+    capabilities: {
+        tools: {},
+        resources: {},
+    },
+});
+// List available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: toolDefinitions,
+    };
+});
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    if (!tools[name]) {
+        throw new McpError(ErrorCode.MethodNotFound, `Tool ${name} not found`);
+    }
+    try {
+        return await tools[name](hevyClient, args);
+    }
+    catch (error) {
+        console.error(`Error executing tool ${name}:`, error);
+        throw new McpError(ErrorCode.InternalError, `Error executing tool: ${error instanceof Error ? error.message : String(error)}`);
+    }
+});
+// List available resources
+server.setRequestHandler(ListResourcesRequestSchema, async () => {
+    return {
+        resources: resourceDefinitions,
+    };
+});
+// Handle resource reads
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    const { uri } = request.params;
+    if (!resources[uri]) {
+        throw new McpError(ErrorCode.InvalidRequest, `Resource ${uri} not found`);
+    }
+    try {
+        return await resources[uri](hevyClient);
+    }
+    catch (error) {
+        console.error(`Error reading resource ${uri}:`, error);
+        throw new McpError(ErrorCode.InternalError, `Error reading resource: ${error instanceof Error ? error.message : String(error)}`);
+    }
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('Hevy MCP server running on stdio');
+}
+main().catch((error) => {
+    console.error('Server error:', error);
+    process.exit(1);
+});

package/dist/resources.d.ts

@@ -0,0 +1,8 @@
+/**
+ * MCP Resources for Hevy API data
+ * Provides read-only access to workout and fitness data as resources
+ */
+import { Resource } from '@modelcontextprotocol/sdk/types.js';
+import { HevyAPIClient } from './hevy-api.js';
+export declare const resourceDefinitions: Resource[];
+export declare const resources: Record<string, (client: HevyAPIClient) => Promise<any>>;