feat: add opt-in debug diagnostics

[charliecreates]

Summary

• Add strict HEVY_MCP_DEBUG=1 opt-in structured diagnostics written only to stderr.
• Apply default-deny, bounded redaction to tool arguments.
• Log sanitized API method, endpoint, duration, and status details.
• Document debug configuration in CLI help, README, and the environment sample.

Testing

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

Resolves #557

✨ PR Description

Purpose: Add opt-in privacy-bounded stderr diagnostics for tool invocations and sanitized Hevy API response metadata.

Main changes:

• Created debug module with redaction logic that strips sensitive data while preserving structural information and circular reference detection
• Integrated debugLog calls in telemetry wrapper and Hevy API client to emit sanitized tool invocation and API response events
• Added HEVY_MCP_DEBUG=1 environment variable flag to control diagnostics; safe non-colliding output reserved to stderr

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}

[codecov]

Codecov Report

❌ Patch coverage is 94.73684% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 91.56%. Comparing base (c6f95a1) to head (52120de).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
src/utils/debug.ts	94.00%	1 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #572      +/-   ##
==========================================
+ Coverage   91.25%   91.56%   +0.31%     
==========================================
  Files          30       31       +1     
  Lines        1212     1269      +57     
  Branches      301      317      +16     
==========================================
+ Hits         1106     1162      +56     
- Misses         47       48       +1     
  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.

[mergify]

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

[github-actions]

Unit Test Results

  1 files   28 suites   1s ⏱️
386 tests 386 ✅ 0 💤 0 ❌
390 runs  390 ✅ 0 💤 0 ❌

Results for commit 52120de.

♻️ This comment has been updated with latest results.

[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}

[greptile-apps]

Greptile Summary

This PR adds opt-in debug diagnostics for the MCP server. The main changes are:

• Structured debug records written to stderr only when HEVY_MCP_DEBUG=1.
• Bounded structural redaction for tool arguments.
• Sanitized API response timing and status diagnostics.
• Tests and docs for the new debug configuration.

Confidence Score: 5/5

This looks safe to merge.

No blocking issues found in the changed code.

T-Rex Logs

What T-Rex did

• • Ran the Vitest diagnostics after changes and confirmed 28 test files and 390 tests passed with exit code 0.
• • Verified the PR plan build completed successfully with exit code 0.
• • Confirmed static type checks and changeset checks completed successfully as part of the plan.
• • Reviewed the PR plan check results and found formatting failures limited to non-PR touched files.

_{Ran code and verified through T-Rex}

Important Files Changed

Filename	Overview
src/utils/debug.ts	Adds strict debug opt-in, bounded stderr output, and structural redaction for diagnostic payloads.
src/utils/telemetry-wrapper.ts	Logs redacted tool invocation diagnostics when debug mode is enabled.
src/utils/hevyClientKubb.ts	Logs sanitized API response metadata from the success and error interceptors.
src/utils/debug.test.ts	Adds tests for debug opt-in behavior, redaction, output bounds, and failure handling.

_{Reviews (3): Last reviewed commit: "fix: redact debug parameter keys" | 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 52120decc6fd8547ad63bf7c7c72d6ff47380bdd · squash

This pull request spent 2 minutes 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)"