feat: add server tool-selection instructions

[charliecreates]

Summary

• add concise server-level MCP instructions for Hevy purpose and authentication
• document tool safety, recommended workflows, pagination, and retry behavior
• verify high-signal guidance and guard the handshake payload size in tests
• add a patch changeset for the runtime-visible behavior

Testing

• npm install
• npm run build
• npx vitest run --exclude tests/integration/**
• npm run check
• npm run check:types
• npm run check:changeset

Resolves #556

✨ PR Description

Purpose: Add comprehensive server-level instructions to MCP server advertising safe tool usage, workflows, and API guidelines to clients.

Main changes:

• Define SERVER_INSTRUCTIONS constant with five guidance sections covering API setup, safety constraints, workflows, pagination, and retry handling
• Extend McpServer initialization with instructions parameter alongside existing logging capability
• Expand test coverage to validate instruction content completeness, format, and token constraints

Generated by LinearB AI and added by gitStream.
_{AI-generated content may contain inaccuracies. Please verify before using.
💡 Tip: You can customize your AI Description using Guidelines Learn how}

[gitstream-cm]

✨ PR Review

LGTM

Generated by LinearB AI and added by gitStream.
_{AI-generated content may contain inaccuracies. Please verify before using.
💡 Tip: You can customize your AI Review using Guidelines Learn how}

[github-actions]

Unit Test Results

  1 files   27 suites   1s ⏱️
370 tests 370 ✅ 0 💤 0 ❌
374 runs  374 ✅ 0 💤 0 ❌

Results for commit 8e727a1.

[mergify]

Queued — the merge queue status continues in this comment ↓.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.26%. Comparing base (c6f95a1) to head (8e727a1).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #563   +/-   ##
=======================================
  Coverage   91.25%   91.26%           
=======================================
  Files          30       30           
  Lines        1212     1213    +1     
  Branches      301      301           
=======================================
+ Hits         1106     1107    +1     
  Misses         47       47           
  Partials       59       59           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[greptile-apps]

Greptile Summary

This PR adds server-level guidance for MCP clients using the Hevy server. The main changes are:

• Runtime instructions for authentication, tool safety, workflows, pagination, and retries.
• Server initialization now advertises those instructions with logging support.
• Tests check the instruction content and payload size.
• A patch changeset records the runtime-visible behavior.

Confidence Score: 5/5

This looks safe to merge.

No blocking issues found in the changed code.

No files need attention.

T-Rex Logs

What T-Rex did

• The build completed successfully with exit code 0 in 1601ms, and the log shows the expected no-auth-token warning.
• The Vitest test run finished with exit code 0, reporting 27 test files passed and 374 tests in total.
• The code health check ran and exited with code 1 due to formatting failures reported in two files.
• The TypeScript type check completed with exit code 0 (tsc --noEmit) and reported no type errors.
• The changeset validation completed with exit code 0, and it notes that packages to be bumped at patch include hevy-mcp.

_{Ran code and verified through T-Rex}

Important Files Changed

Filename	Overview
src/index.ts	Adds the server instruction text and includes it in McpServer options.
src/index.test.ts	Extends server-entry coverage for the advertised instruction payload.
.changeset/bright-otters-guide.md	Adds a patch changeset for the new runtime guidance.

_{Reviews (2): Last reviewed commit: "feat: add server tool-selection instruct..." | Re-trigger Greptile}

[chrisdoc]

@Mergifyio refresh

[mergify]

refresh

✅ Pull request refreshed

[mergify]

Merge Queue Status

• ✅ Entered queue — 2026-07-10 17:58 UTC · Rule: default · triggered by rule Queue pull requests labeled 'queue'
• ✅ Checks passed · on draft merge queue: checking main (92379c8) and [#569 + #563 + #572] together #580
• ✅ Merged — 2026-07-10 18:00 UTC · at 8e727a115e077020cd6d1fcc2028e37e542aab37 · squash

This pull request spent 2 minutes 2 seconds in the queue, including 1 minute 19 seconds running CI.

Required conditions to merge

• check-success = "Build and test (Node 24.x)"
• check-success = "Build and test (Node 26.x)"

[charliecreates]

No Charlie action needed here—Mergify has already refreshed the PR.