docs: improve README onboarding and add demo - #679
Conversation
|
Caution Review failedThe pull request is closed. ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: ⛔ Files ignored due to path filters (2)
📒 Files selected for processing (2)
📝 WalkthroughWalkthroughThe README is substantially rewritten around onboarding, MCP capabilities, transport configuration, security, troubleshooting, and contribution guidance. A Changesets entry records a patch release for the documentation update. ChangesREADME documentation update
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related PRs
Suggested labels: Poem
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
MCP tool token costMeasured with
Change from baseline
Per-tool changes
Per-tool breakdown
Per-tool counts encode each complete tool object independently. The total encodes the complete |
Unit Test Results 1 files 48 suites 4s ⏱️ Results for commit d232da2. ♻️ This comment has been updated with latest results. |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request significantly updates the README.md file to improve documentation, adding a demo section, detailed quick start instructions for Codex, Claude Desktop, and Cursor, an exhaustive list of the 25 registered tools, and a new troubleshooting section. The feedback suggests replacing absolute asset URLs pointing to the main branch with relative paths to ensure they remain functional across forks and branches.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
| to the [Hevy](https://www.hevyapp.com/) fitness API. Ask about workout history, | ||
| analyze progress, browse routines and exercises, or create and update Hevy data | ||
| without leaving your assistant. | ||
| [Watch the 18-second demo](https://raw.githubusercontent.com/chrisdoc/hevy-mcp/main/docs/assets/hevy-mcp-demo.mp4) · [Quick start](#quick-start) · [Explore all 25 tools](#tools) |
There was a problem hiding this comment.
Using absolute URLs pointing to the main branch of the repository for assets can break when the repository is forked or when working on a different branch. It is highly recommended to use relative paths for files located within the same repository. This ensures the links remain functional and correct across all forks and branches.
| [Watch the 18-second demo](https://raw.githubusercontent.com/chrisdoc/hevy-mcp/main/docs/assets/hevy-mcp-demo.mp4) · [Quick start](#quick-start) · [Explore all 25 tools](#tools) | |
| [Watch the 18-second demo](./docs/assets/hevy-mcp-demo.mp4) · [Quick start](#quick-start) · [Explore all 25 tools](#tools) |
| The npm package and official container are **stdio-only** MCP executables. Your | ||
| client starts the process and communicates through standard input/output; this | ||
| is not an interactive terminal command or an HTTP service. | ||
| [](https://raw.githubusercontent.com/chrisdoc/hevy-mcp/main/docs/assets/hevy-mcp-demo.mp4) |
There was a problem hiding this comment.
Using absolute URLs pointing to the main branch of the repository for assets can break when the repository is forked or when working on a different branch. It is highly recommended to use relative paths for files located within the same repository. This ensures the links remain functional and correct across all forks and branches.
| [](https://raw.githubusercontent.com/chrisdoc/hevy-mcp/main/docs/assets/hevy-mcp-demo.mp4) | |
| [](./docs/assets/hevy-mcp-demo.mp4) |
![charliecreates[bot]](https://avatars.githubusercontent.com/in/1140780?s=60&v=4){kind=small}
There was a problem hiding this comment.
Blocking
- Please add an empty Changesets file for this documentation/assets PR (for example, via
npx changeset --empty).CONTRIBUTING.md:242-257requires a Changesets file for every pull request that changes documentation, and the requiredCheck for changesetstep in.github/workflows/build-and-test.yml:70-81is currently failing on5174cc127668c58b84dbfeb8df649866865fa5afwith “Some packages have been changed but no changesets were found.” Until this is added, the PR cannot pass the required CI baseline.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #679 +/- ##
=======================================
Coverage 96.13% 96.13%
=======================================
Files 46 46
Lines 1942 1942
Branches 535 535
=======================================
Hits 1867 1867
Misses 24 24
Partials 51 51 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
Code Review by QodoNew Review StartedThis review has been superseded by a new analysis |
|
Tick the box to add this pull request to the merge queue (same as
|
PR Summary by Qododocs: improve README onboarding and add demo assets
AI Description
Diagram
High-Level Assessment
Files changed (2)
|
|
PR #679 merged while I was reviewing the current head, so I didn’t submit a stale post-merge formal review. I checked the README claims against the tool, prompt, resource, runtime, and release configuration and found no blocking issue. The absolute raw GitHub demo links are less fork/branch-portable than relative links, but that’s non-blocking. |
Code Review by Qodo
Context used✅ Compliance rules (platform):
65 rules 1. README passes HEVY_API_KEY via CLI
|
![qodo-code-review[bot]](https://avatars.githubusercontent.com/in/484649?s=60&v=4){kind=small}
| codex mcp add hevy \ | ||
| --env HEVY_API_KEY=your-hevy-api-key \ | ||
| -- npx -y hevy-mcp | ||
| ``` |
There was a problem hiding this comment.
1. Readme passes hevy_api_key via cli 📘 Rule violation ⛨ Security
The updated README instructs users to provide the Hevy API key in command-line arguments (via `--env HEVY_API_KEY=...`), which violates the requirement to never pass API keys via CLI arguments. CLI history/process listings can expose secrets, so the docs should require HEVY_API_KEY to come from the environment only.
Agent Prompt
## Issue description
The README shows commands that place `HEVY_API_KEY` on the command line (e.g., `--env HEVY_API_KEY=...`). The compliance requirement forbids providing API keys via CLI arguments and requires reading the key exclusively from the `HEVY_API_KEY` environment variable.
## Issue Context
This impacts onboarding snippets for Codex (and similar snippets elsewhere in the README). Command-line arguments can be captured in shell history and visible via process inspection.
## Fix Focus Areas
- README.md[75-89]
- README.md[187-193]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
| --- | ||
| "hevy-mcp": patch | ||
| --- | ||
|
|
||
| update readme |
There was a problem hiding this comment.
3. Vague changeset summary 🐞 Bug ⚙ Maintainability
The changeset message is only "update readme", which will generate an unhelpful changelog/release note entry. This reduces release-note quality and makes it harder to understand what shipped in the patch.
Agent Prompt
## Issue description
The changeset summary is too generic ("update readme"), which will surface in generated release notes and provide little value.
## Issue Context
This PR’s README change is substantial (onboarding rewrite + demo + setup examples). The changeset should reflect that.
## Fix Focus Areas
- .changeset/tasty-cameras-sip.md[1-5]
## Suggested fix
Replace the body text with something descriptive, e.g. "Improve README onboarding and add demo media + setup examples" (or similar phrasing that matches the actual user-facing changes).
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
1 participant
What changed
Why
Make the repository easier to discover and help new users reach a successful first MCP call quickly.
Validation
npm run buildpassed.npm run check:typespassed.npm run checkpassed.The full pre-commit test hook was attempted but cannot pass in this sandbox because listener creation, live Hevy API access, and the local 1Password signing socket are unavailable.
Summary by CodeRabbit