@daveremy/hevy-mcp 0.1.2

package/.claude-plugin/marketplace.json

@@ -0,0 +1,17 @@
+{
+	"name": "daveremy-plugins",
+	"owner": {
+		"name": "daveremy"
+	},
+	"plugins": [
+		{
+			"name": "hevy-mcp",
+			"source": {
+				"source": "npm",
+				"package": "@daveremy/hevy-mcp"
+			},
+			"description": "MCP server for the Hevy fitness tracking API",
+			"version": "0.1.2"
+		}
+	]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+	"name": "hevy-mcp",
+	"description": "MCP server for the Hevy fitness tracking API — workouts, routines, exercises, and more",
+	"version": "0.1.2",
+	"author": {
+		"name": "daveremy"
+	},
+	"homepage": "https://github.com/daveremy/hevy-mcp",
+	"repository": "https://github.com/daveremy/hevy-mcp",
+	"mcpServers": {
+		"hevy-mcp": {
+			"command": "npx",
+			"args": [
+				"-y",
+				"@daveremy/hevy-mcp"
+			]
+		}
+	}
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Christoph Kieslich
+
+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,448 @@
+# hevy-mcp: Model Context Protocol Server for Hevy Fitness API
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+> **Attribution:** This project is a fork of [chrisdoc/hevy-mcp](https://github.com/chrisdoc/hevy-mcp), originally created by **Christoph Kieslich**. Published as `@daveremy/hevy-mcp` with Claude Code plugin packaging.
+
+A Model Context Protocol (MCP) server implementation that interfaces with the [Hevy fitness tracking app](https://www.hevyapp.com/) and its [API](https://api.hevyapp.com/docs/). This server enables AI assistants to access and manage workout data, routines, exercise templates, and more through the Hevy API (requires PRO subscription).
+
+## Features
+
+- **Workout Management**: Fetch, create, and update workouts
+- **Routine Management**: Access and manage workout routines
+- **Exercise Templates**: Browse available exercise templates
+- **Folder Organization**: Manage routine folders
+- **Webhook Subscriptions**: Create, view, and delete webhook subscriptions for workout events
+
+> **Note:** HTTP transport and Docker images are deprecated. The server runs via stdio transport (e.g., `npx hevy-mcp`). Legacy GHCR images remain available but are no longer maintained.
+
+## Claude Code Plugin Install
+
+Install as a Claude Code plugin:
+
+```bash
+claude plugin add @daveremy/hevy-mcp
+```
+
+Then set your Hevy API key when prompted. The `/hevy` skill becomes available for interacting with your fitness data.
+
+## Quick start
+
+Pick the workflow that fits your setup:
+
+| Scenario | Command | Requirements |
+| --- | --- | --- |
+| One-off stdio run | `HEVY_API_KEY=sk_live... npx -y @daveremy/hevy-mcp` | Node.js ≥ 20, Hevy API key |
+| Local development | `pnpm install && pnpm run dev` | `.env` with `HEVY_API_KEY`, pnpm via Corepack |
+
+## Prerequisites
+
+- 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
+
+## Installation
+
+### Run via npx (recommended)
+
+You can launch the server directly without cloning:
+
+```bash
+HEVY_API_KEY=your_hevy_api_key_here npx -y @daveremy/hevy-mcp
+```
+
+### Manual Installation
+```bash
+# Clone the repository
+git clone https://github.com/daveremy/hevy-mcp.git
+cd hevy-mcp
+
+# Install dependencies
+corepack use pnpm@10.22.0
+pnpm install
+
+# Create .env and add your keys (never commit real keys)
+cp .env.sample .env
+# Edit .env and add your HEVY_API_KEY.
+```
+
+### Integration with Cursor
+
+To use this MCP server with Cursor, add/merge this server entry under
+`"mcpServers"` in `~/.cursor/mcp.json`:
+
+```json
+{
+  "hevy-mcp": {
+    "command": "npx",
+    "args": ["-y", "@daveremy/hevy-mcp"],
+    "env": {
+      "HEVY_API_KEY": "your-api-key-here"
+    }
+  }
+}
+```
+
+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", "@daveremy/hevy-mcp"],
+      "env": {
+        "HEVY_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+
+## Configuration
+
+You can supply your Hevy API key in two ways:
+
+1. Environment variable (`HEVY_API_KEY`)
+2. Command-line argument (`--hevy-api-key=your_key` or `hevy-api-key=your_key` after `--` when using pnpm scripts)
+
+Create a `.env` file in the project root (you can copy from [.env.sample](.env.sample)) with the following content if using the environment variable approach:
+
+```env
+HEVY_API_KEY=your_hevy_api_key_here
+```
+
+Replace `your_hevy_api_key_here` with your actual Hevy API key. If you prefer the command argument approach you can skip setting the environment variable and start the server with for example:
+
+```bash
+pnpm start -- --hevy-api-key=your_hevy_api_key_here
+```
+
+### Sentry monitoring
+
+`hevy-mcp` ships with Sentry monitoring baked into the built MCP server so
+that usage and errors from published builds can be observed.
+
+The server initializes `@sentry/node` with a fixed DSN, release name derived
+from the package version, and tracing settings
+directly in the code (see `src/index.ts`), and wraps the underlying
+`McpServer` with `Sentry.wrapMcpServerWithSentry` so requests and tool calls
+are captured by Sentry automatically. The configuration uses
+`sendDefaultPii: false` to keep Sentry's default PII collection disabled.
+
+There is currently no built-in toggle to disable Sentry for the published
+package. If you need a build without Sentry telemetry, you can fork the
+repository and remove the Sentry initialization in `src/index.ts`.
+
+## Transport
+
+
+### Stdio Only (Current)
+
+**As of version 1.18.0, hevy-mcp only supports stdio transport.** HTTP/SSE
+transport has been completely removed.
+
+hevy-mcp runs exclusively over stdio, which works seamlessly with MCP-aware clients like Claude Desktop and Cursor. The server communicates via standard input/output streams using JSON-RPC messages.
+
+### Migration from HTTP/SSE Transport
+
+**If you were using HTTP or SSE transport in an older version (< 1.18.0), you must migrate to stdio.**
+
+The HTTP/SSE transport was removed in v1.18.0 to simplify the codebase and focus
+on the stdio-native MCP experience. If you're encountering errors like:
+
+- `"stream is not readable"` when making HTTP requests
+- `"HTTP transport mode has been removed from hevy-mcp"`
+- Server messages about SSE mode on `http://localhost:3001`
+
+You are likely running an outdated build or trying to connect with an HTTP-based client. Here's how to fix it:
+
+#### Steps to Migrate:
+
+1. **Update to the latest version:**
+   ```bash
+   npx -y @daveremy/hevy-mcp@latest
+   # or if installed locally:
+   pnpm install @daveremy/hevy-mcp@latest
+   ```
+
+2. **Update your client configuration** to use stdio transport instead of HTTP. For example, in Cursor's `~/.cursor/mcp.json`:
+   
+   **Old HTTP-based config (no longer supported):**
+   ```json
+   {
+     "hevy-mcp": {
+       "url": "http://localhost:3001/sse"
+     }
+   }
+   ```
+   
+   **New stdio-based config (current):**
+   ```json
+   {
+     "hevy-mcp": {
+       "command": "npx",
+       "args": ["-y", "@daveremy/hevy-mcp"],
+       "env": {
+         "HEVY_API_KEY": "your-api-key-here"
+       }
+     }
+   }
+   ```
+
+3. **Clear any cached builds:**
+   ```bash
+   # If you have a local clone, rebuild
+   pnpm run build
+   
+   # Or remove node_modules and reinstall
+   rm -rf node_modules dist
+   pnpm install
+   pnpm run build
+   ```
+
+4. **Ensure you're not running a custom HTTP server.** If you have custom code that imports `createHttpServer()`, it will now throw an error. Remove those imports and use stdio transport instead.
+
+If you absolutely need HTTP/SSE transport, you can use version `1.17.x` or earlier, but those versions are no longer maintained and contain known bugs (including the "stream is not readable" issue caused by middleware conflicts).
+
+## Usage
+
+### Development
+
+```bash
+pnpm run dev
+```
+
+This starts the MCP server in development mode with hot reloading.
+
+### Production
+
+```bash
+pnpm run build
+pnpm start
+```
+
+### Docker (deprecated)
+
+Docker-based workflows have been retired so we can focus on the stdio-native experience. The bundled `Dockerfile` now exits with a clear message to prevent accidental builds, and `.dockerignore` simply documents the deprecation. Previously published images remain available on GHCR (for example `ghcr.io/chrisdoc/hevy-mcp:latest`), but they are **no longer updated**. For the best experience, run the server locally via `npx @daveremy/hevy-mcp` or your own Node.js runtime.
+
+## Available MCP Tools
+
+The server implements the following MCP tools for interacting with the Hevy API:
+
+### Workout Tools
+- `get-workouts`: Fetch and format workout data
+- `get-workout`: Get a single workout by ID
+- `create-workout`: Create a new workout
+- `update-workout`: Update an existing workout
+- `get-workout-count`: Get the total count of workouts
+- `get-workout-events`: Get workout update/delete events
+
+### Routine Tools
+- `get-routines`: Fetch and format routine data
+- `create-routine`: Create a new routine
+- `update-routine`: Update an existing routine
+- `get-routine-by-id`: Get a single routine by ID using direct endpoint
+
+### Exercise Template Tools
+- `get-exercise-templates`: Fetch exercise templates
+- `get-exercise-template`: Get a template by ID
+
+### Routine Folder Tools
+- `get-routine-folders`: Fetch routine folders
+- `create-routine-folder`: Create a new folder
+- `get-routine-folder`: Get a folder by ID
+
+### Webhook Tools
+- `get-webhook-subscription`: Get the current webhook subscription
+- `create-webhook-subscription`: Create a new webhook subscription
+- `delete-webhook-subscription`: Delete the current webhook subscription
+
+## Project Structure
+
+```plaintext
+hevy-mcp/
+├── .env                   # Environment variables (API keys)
+├── src/
+│   ├── index.ts           # Main entry point
+│   ├── tools/             # Directory for MCP tool implementations
+│   │   ├── workouts.ts    # Workout-related tools
+│   │   ├── routines.ts    # Routine-related tools
+│   │   ├── templates.ts   # Exercise template tools
+│   │   ├── folders.ts     # Routine folder tools
+│   │   └── webhooks.ts    # Webhook subscription tools
+│   ├── generated/         # API client (generated code)
+│   │   ├── client/        # Kubb-generated client
+│   │   │   ├── api/       # API client methods
+│   │   │   ├── types/     # TypeScript types
+│   │   │   ├── schemas/   # Zod schemas
+│   │   │   └── mocks/     # Mock data
+│   └── utils/             # Helper utilities
+│       ├── 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
+    │   └── hevy-mcp.integration.test.ts  # MCP server integration tests
+```
+
+## Development Guide
+
+### Code Style
+
+This project uses Biome for code formatting and linting:
+
+```bash
+pnpm run check
+```
+
+### Testing
+
+#### Run All Tests
+
+To run all tests (unit and integration), use:
+
+```bash
+pnpm test
+```
+
+> **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
+
+To run only unit tests (excluding integration tests):
+
+```bash
+pnpm vitest run --exclude tests/integration/**
+```
+
+Or with coverage:
+
+```bash
+pnpm vitest run --coverage --exclude tests/integration/**
+```
+
+#### Run Only Integration Tests
+
+To run only the integration tests (requires a valid `HEVY_API_KEY`):
+
+```bash
+pnpm vitest run tests/integration
+```
+
+**Note:** The integration tests will fail if the `HEVY_API_KEY` environment variable is not set. This is by design to ensure that the tests are always run with a valid API key.
+
+##### GitHub Actions Configuration
+
+For GitHub Actions:
+
+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:
+
+1. Go to your GitHub repository
+2. Click on "Settings" > "Secrets and variables" > "Actions"
+3. Click on "New repository 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 will fail (by design).
+
+To set up Sentry secrets for source map uploads during builds:
+
+The build process uses Sentry's Rollup plugin to upload source maps. You need to configure three secrets:
+
+1. Go to your GitHub repository
+2. Click on "Settings" > "Secrets and variables" > "Actions"
+3. Add the following secrets:
+   - `SENTRY_ORG`: Your Sentry organization slug
+   - `SENTRY_PROJECT`: Your Sentry project slug
+   - `SENTRY_AUTH_TOKEN`: A Sentry auth token with `project:releases` scope
+
+   You can create a Sentry auth token at: https://sentry.io/settings/account/api/auth-tokens/
+
+If these secrets are not set, the build will still succeed, but source maps will not be uploaded to Sentry.
+
+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
+
+The API client is generated from the OpenAPI specification using [Kubb](https://kubb.dev/):
+
+```bash
+pnpm run export-specs
+pnpm run build:client
+```
+
+Kubb generates TypeScript types, API clients, Zod schemas, and mock data from the OpenAPI specification.
+
+### Troubleshooting
+
+- **Rollup optional dependency missing**: If you see an error similar to `Cannot find module @rollup/rollup-linux-x64-gnu`, set the environment variable `ROLLUP_SKIP_NODEJS_NATIVE_BUILD=true` before running `pnpm run build`. This forces Rollup to use the pure JavaScript fallback and avoids the npm optional dependency bug on some Linux runners.
+
+## Skills
+
+When installed as a Claude Code plugin, the `/hevy` skill is available with the following subcommands:
+
+| Command | Description |
+|---------|-------------|
+| `/hevy` or `/hevy status` | Quick dashboard of recent activity |
+| `/hevy log` | Log a new workout interactively |
+| `/hevy history` | View recent workout history |
+| `/hevy routines` | Browse and manage routines |
+| `/hevy exercises` | Search exercise templates |
+| `/hevy help` | Show available commands |
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
+
+## Acknowledgements
+
+- [Model Context Protocol](https://github.com/modelcontextprotocol) for the MCP SDK
+- [Hevy](https://www.hevyapp.com/) for their fitness tracking platform and API

package/dist/cli.d.mts

@@ -0,0 +1,2 @@
+
+export { };

package/dist/cli.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+// Generated with tsdown
+// https://tsdown.dev
+(function() {
+	try {
+		var e = "undefined" != typeof window ? window : "undefined" != typeof global ? global : "undefined" != typeof globalThis ? globalThis : "undefined" != typeof self ? self : {};
+		e.SENTRY_RELEASE = { id: "0.1.2" };
+		var n = new e.Error().stack;
+		n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "03cf150f-6466-4ca3-9cf1-e423cc0e3cd2", e._sentryDebugIdIdentifier = "sentry-dbid-03cf150f-6466-4ca3-9cf1-e423cc0e3cd2");
+	} catch (e) {}
+})();
+import { r as runServer } from "./src-CCpNxeP3.mjs";
+//#region src/cli.ts
+runServer().catch((error) => {
+	console.error("Fatal error in main():", error);
+	process.exit(1);
+});
+//#endregion
+export {};
+
+//# sourceMappingURL=cli.mjs.map

package/dist/cli.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.mjs","names":[],"sources":["../src/cli.ts"],"sourcesContent":["import { runServer } from \"./index.js\";\n\nvoid runServer().catch((error) => {\n\tconsole.error(\"Fatal error in main():\", error);\n\tprocess.exit(1);\n});\n"],"mappings":";;;;;;;;;;;;;AAEK,WAAW,CAAC,OAAO,UAAU;AACjC,SAAQ,MAAM,0BAA0B,MAAM;AAC9C,SAAQ,KAAK,EAAE;EACd"}

package/dist/index.d.mts

@@ -0,0 +1,21 @@
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+//#region src/index.d.ts
+declare const serverConfigSchema: z.ZodObject<{
+  apiKey: z.ZodString;
+}, z.core.$strip>;
+declare const configSchema: z.ZodObject<{
+  apiKey: z.ZodString;
+}, z.core.$strip>;
+type ServerConfig = z.infer<typeof serverConfigSchema>;
+declare function createServer({
+  config
+}: {
+  config: ServerConfig;
+}): McpServer;
+declare function runServer(): Promise<void>;
+//#endregion
+export { configSchema, createServer as default, runServer };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// Generated with tsdown
+// https://tsdown.dev
+(function() {
+	try {
+		var e = "undefined" != typeof window ? window : "undefined" != typeof global ? global : "undefined" != typeof globalThis ? globalThis : "undefined" != typeof self ? self : {};
+		e.SENTRY_RELEASE = { id: "0.1.2" };
+		var n = new e.Error().stack;
+		n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "a23492d3-dc93-45b6-9c01-6c2fef1c843d", e._sentryDebugIdIdentifier = "sentry-dbid-a23492d3-dc93-45b6-9c01-6c2fef1c843d");
+	} catch (e) {}
+})();
+import { n as createServer, r as runServer, t as configSchema } from "./src-CCpNxeP3.mjs";
+export { configSchema, createServer as default, runServer };