hevy-mcp 1.14.3 → 1.15.0

package/README.md

@@ -27,7 +27,8 @@ Pick the workflow that fits your setup:
 
 ## Prerequisites
 
-- Node.js (v20 or higher)
+- Node.js (v20 or higher; strongly recommended to use the exact version pinned in
+  `.nvmrc` to match CI)
 - pnpm (via Corepack)
 - A Hevy API key
   - Optional: A Smithery account + API key/login if you plan to deploy via Smithery
@@ -59,11 +60,12 @@ cp .env.sample .env
 
 ### Integration with Cursor
 
-To use this MCP server with Cursor, you need to update your `~/.cursor/mcp.json` file by adding the following configuration:
+To use this MCP server with Cursor, add/merge this server entry under
+`"mcpServers"` in `~/.cursor/mcp.json`:
 
 ```json
 {
-  "hevy-mcp-server": {
+  "hevy-mcp": {
     "command": "npx",
     "args": ["-y", "hevy-mcp"],
     "env": {
@@ -75,6 +77,34 @@ To use this MCP server with Cursor, you need to update your `~/.cursor/mcp.json`
 
 Make sure to replace `your-api-key-here` with your actual Hevy API key.
 
+If your `mcp.json` already contains other servers, do not replace the whole
+file—merge the `"hevy-mcp"` entry into your existing `"mcpServers"` object.
+
+The `"hevy-mcp"` key name is arbitrary. If you already have an existing config
+using a different name (for example `"hevy-mcp-server"`), you can keep it.
+
+If you already have an existing `"mcpServers"` object, merge the `"hevy-mcp"`
+entry into it without removing other servers.
+
+<details>
+<summary><strong>Example full ~/.cursor/mcp.json</strong></summary>
+
+```json
+{
+  "mcpServers": {
+    "hevy-mcp": {
+      "command": "npx",
+      "args": ["-y", "hevy-mcp"],
+      "env": {
+        "HEVY_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+</details>
+
 
 ## Configuration
 
@@ -210,8 +240,13 @@ hevy-mcp/
 │   │   │   ├── schemas/   # Zod schemas
 │   │   │   └── mocks/     # Mock data
 │   └── utils/             # Helper utilities
-│       ├── formatters.ts  # Data formatting helpers
-│       └── validators.ts  # Input validation helpers
+│       ├── config.ts              # Env/CLI config parsing
+│       ├── error-handler.ts       # Tool error wrapper + response builder
+│       ├── formatters.ts          # Domain formatting helpers
+│       ├── hevyClient.ts          # API client factory
+│       ├── httpServer.ts          # Legacy HTTP transport (deprecated; throws explicit error; kept only for backward compatibility - removing may be breaking)
+│       ├── response-formatter.ts  # MCP response utilities
+│       └── tool-helpers.ts        # Zod schema -> TS type inference
 ├── scripts/               # Build and utility scripts
 └── tests/                 # Test suite
     ├── integration/       # Integration tests with real API
@@ -238,7 +273,9 @@ To run all tests (unit and integration), use:
 pnpm test
 ```
 
-> **Note:** If the `HEVY_API_KEY` environment variable is set, integration tests will also run. If not, only unit tests will run.
+> **Note:** `pnpm test` runs **all** tests. Integration tests will fail by design if
+> `HEVY_API_KEY` is missing. If you don’t have an API key locally, use the unit
+> test command below.
 
 #### Run Only Unit Tests
 
@@ -268,8 +305,11 @@ pnpm vitest run tests/integration
 
 For GitHub Actions:
 
-1. Unit tests will always run on every push and pull request
-2. Integration tests will only run if the `HEVY_API_KEY` secret is set in the repository settings
+1. Unit + integration tests are executed as part of the normal `Build and Test` workflow
+2. Integration tests require the `HEVY_API_KEY` secret to be set
+
+The workflow runs `pnpm vitest run --coverage` and provides `HEVY_API_KEY` from
+repository secrets.
 
 To set up the `HEVY_API_KEY` secret:
 
@@ -279,7 +319,23 @@ To set up the `HEVY_API_KEY` secret:
 4. Set the name to `HEVY_API_KEY` and the value to your Hevy API key
 5. Click "Add secret"
 
-If the secret is not set, the integration tests step will be skipped with a message indicating that the API key is missing.
+If the secret is not set, the integration tests will fail (by design).
+
+Note: GitHub does not provide secrets to pull requests from forks by default, so
+fork PRs may fail CI unless a maintainer reruns the checks with `HEVY_API_KEY`
+available.
+
+If CI is failing only because the fork PR is missing `HEVY_API_KEY`, that is
+expected; maintainers may rerun the workflow with secrets enabled.
+
+For contributors from forks: CI failures caused solely by missing `HEVY_API_KEY`
+do not indicate a problem with your changes.
+
+All other CI checks (build, formatting/linting, unit tests, etc.) are still
+expected to pass.
+
+Only failures caused solely by missing `HEVY_API_KEY` on forked PRs are
+considered acceptable.
 
 ### Generating API Client
 

package/dist/cli.js

@@ -11,7 +11,7 @@ import { z as z6 } from "zod";
 
 // package.json
 var name = "hevy-mcp";
-var version = "1.14.2";
+var version = "1.14.4";
 
 // src/tools/folders.ts
 import { z } from "zod";
@@ -351,7 +351,11 @@ function registerRoutineTools(server, hevyClient) {
             distanceMeters: z2.coerce.number().int().optional(),
             duration: z2.coerce.number().int().optional(),
             durationSeconds: z2.coerce.number().int().optional(),
-            customMetric: z2.coerce.number().optional()
+            customMetric: z2.coerce.number().optional(),
+            repRange: z2.object({
+              start: z2.coerce.number().int().optional(),
+              end: z2.coerce.number().int().optional()
+            }).optional()
           })
         )
       })
@@ -386,7 +390,11 @@ function registerRoutineTools(server, hevyClient) {
                   reps: set.reps ?? null,
                   distance_meters: set.distance ?? set.distanceMeters ?? null,
                   duration_seconds: set.duration ?? set.durationSeconds ?? null,
-                  custom_metric: set.customMetric ?? null
+                  custom_metric: set.customMetric ?? null,
+                  rep_range: set.repRange ? {
+                    start: set.repRange.start ?? null,
+                    end: set.repRange.end ?? null
+                  } : null
                 })
               )
             })
@@ -425,7 +433,11 @@ function registerRoutineTools(server, hevyClient) {
             distanceMeters: z2.coerce.number().int().optional(),
             duration: z2.coerce.number().int().optional(),
             durationSeconds: z2.coerce.number().int().optional(),
-            customMetric: z2.coerce.number().optional()
+            customMetric: z2.coerce.number().optional(),
+            repRange: z2.object({
+              start: z2.coerce.number().int().optional(),
+              end: z2.coerce.number().int().optional()
+            }).optional()
           })
         )
       })
@@ -459,7 +471,11 @@ function registerRoutineTools(server, hevyClient) {
                   reps: set.reps ?? null,
                   distance_meters: set.distance ?? set.distanceMeters ?? null,
                   duration_seconds: set.duration ?? set.durationSeconds ?? null,
-                  custom_metric: set.customMetric ?? null
+                  custom_metric: set.customMetric ?? null,
+                  rep_range: set.repRange ? {
+                    start: set.repRange.start ?? null,
+                    end: set.repRange.end ?? null
+                  } : null
                 })
               )
             })