docs: create MCP_USAGE.md and add config snippets for Cline, Claude, and Opencode #6#38
Conversation
![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 adds documentation for configuring Model Context Protocol (MCP) clients with the React Debugger MCP server, along with several symlinks and a local pointer guide for the project harness. The review feedback suggests adding the -y flag to npx commands in the MCP configuration snippets to prevent interactive prompts from corrupting the JSON-RPC stream, and replacing a hardcoded local user path in the harness documentation with a generic placeholder.
| "command": "npx", | ||
| "args": [ | ||
| "@nhonh/react-debugger@latest", | ||
| "mcp" | ||
| ] |
There was a problem hiding this comment.
When running npx in a non-interactive environment (like an MCP server host), it can prompt the user to install the package if it is not cached or if a newer version is found. This prompt or installation progress output on stdout will corrupt the MCP JSON-RPC stream. Adding the -y (or --yes) flag ensures npx runs non-interactively without prompting.
| "command": "npx", | |
| "args": [ | |
| "@nhonh/react-debugger@latest", | |
| "mcp" | |
| ] | |
| "command": "npx", | |
| "args": [ | |
| "-y", | |
| "@nhonh/react-debugger@latest", | |
| "mcp" | |
| ] |
| "command": "npx", | ||
| "args": [ | ||
| "@nhonh/react-debugger@latest", | ||
| "mcp" | ||
| ] |
There was a problem hiding this comment.
When running npx in a non-interactive environment (like an MCP server host), it can prompt the user to install the package if it is not cached or if a newer version is found. This prompt or installation progress output on stdout will corrupt the MCP JSON-RPC stream. Adding the -y (or --yes) flag ensures npx runs non-interactively without prompting.
| "command": "npx", | |
| "args": [ | |
| "@nhonh/react-debugger@latest", | |
| "mcp" | |
| ] | |
| "command": "npx", | |
| "args": [ | |
| "-y", | |
| "@nhonh/react-debugger@latest", | |
| "mcp" | |
| ] |
| "command": "npx", | ||
| "args": [ | ||
| "@nhonh/react-debugger@latest", | ||
| "mcp" | ||
| ] |
There was a problem hiding this comment.
When running npx in a non-interactive environment (like an MCP server host), it can prompt the user to install the package if it is not cached or if a newer version is found. This prompt or installation progress output on stdout will corrupt the MCP JSON-RPC stream. Adding the -y (or --yes) flag ensures npx runs non-interactively without prompting.
| "command": "npx", | |
| "args": [ | |
| "@nhonh/react-debugger@latest", | |
| "mcp" | |
| ] | |
| "command": "npx", | |
| "args": [ | |
| "-y", | |
| "@nhonh/react-debugger@latest", | |
| "mcp" | |
| ] |
| The authoritative harness lives at the workspace root, **not in this repo**. | ||
|
|
||
| - **In-workspace path:** `../../docs/HARNESS.md` (resolved by the symlinks at `docs/HARNESS.md`, `docs/FEATURE_INTAKE.md`, `docs/HARNESS_BACKLOG.md`, `docs/templates/story.md`, `docs/evidence/README.md`) | ||
| - **Workspace canonical:** `/Users/nhonh/Documents/personal/docs/HARNESS.md` |
There was a problem hiding this comment.
This line contains a hardcoded absolute path specific to a local user directory (/Users/nhonh/...). To make this documentation generic and useful for other contributors, please use a placeholder or a relative path.
| - **Workspace canonical:** `/Users/nhonh/Documents/personal/docs/HARNESS.md` | |
| - **Workspace canonical:** ~/Documents/personal/docs/HARNESS.md (or your local workspace path) |
|
@AsifpMulla123 Thanks for contributing, please review comment and fix them if any first |
hoainho
left a comment
hoainho
left a comment
There was a problem hiding this comment.
Thanks for the documentation work @AsifpMulla123. The core file cli/docs/MCP_USAGE.md is well-structured and matches the project's brand voice. There are however a few items that block merging — the most important being that this PR documents a CLI subcommand that does not yet exist.
⛔ Critical — must fix before merge
1. The mcp subcommand is not yet implemented
cli/docs/MCP_USAGE.md lines 9, 23, and 38 all instruct users to run:
npx @nhonh/react-debugger@latest mcpBut the mcp subcommand does not exist yet. The current CLI (cli/bin/cli.js) only supports the install flow. The MCP server is in spec phase at openspec/changes/mcp-server-v1/ (Momus-approved proposal, M1-M5 milestones, not yet implemented). Publishing this doc on main will cause every user who follows it to hit a "command not found" error.
Two options:
- (a) Hold this PR until
mcp-server-v1ships M3 (~end of July 2026). I'll coordinate the merge then. - (b) Add a prominent preview banner at the top of the file:
> ⚠️ **Preview / unreleased.** The `mcp` subcommand documented here is part of the [MCP Server v1 design](https://github.com/hoainho/react-debugger-extension/tree/main/openspec/changes/mcp-server-v1) and not yet shipped on npm. Track progress at [milestones M1–M5](https://github.com/hoainho/react-debugger-extension/milestones).I'd prefer option (a) but option (b) is acceptable if you want this to land soon.
2. Six unrelated symlink/local files committed
The PR includes 6 files that are workspace-local symlinks pointing OUTSIDE the repo:
docs/FEATURE_INTAKE.md→../../docs/FEATURE_INTAKE.mddocs/HARNESS.md→../../docs/HARNESS.mddocs/HARNESS_BACKLOG.md→../../docs/HARNESS_BACKLOG.mddocs/evidence/README.md→../../../docs/evidence/README.mddocs/templates/story.md→../../docs/templates/story.mddocs/HARNESS.local.md(regular file — see #3 below)
These are broken in any standalone clone of the repo (the ../../docs/ targets resolve to the maintainer's ~/Documents/personal/ workspace, not anywhere a contributor would have). You confirmed this yourself in docs/HARNESS.local.md:
"the symlinks will be broken. To restore the harness: 1. Re-clone inside
~/Documents/personal/"
These files appear because your fork was created before some recent commits and git add docs/ captured the existing workspace symlinks. They have zero relevance to public consumers of this repo.
Fix: rebase your branch on current main and drop these files. Approximate steps:
git fetch upstream main
git rebase upstream/main
git rm docs/FEATURE_INTAKE.md docs/HARNESS.md docs/HARNESS.local.md \
docs/HARNESS_BACKLOG.md docs/evidence/README.md docs/templates/story.md
git commit -m "drop workspace-local harness symlinks"
git push --force-with-lease3. Absolute private path leaked
docs/HARNESS.local.md:9 contains the line:
**Workspace canonical:** `/Users/nhonh/Documents/personal/docs/HARNESS.md`
This is the maintainer's private filesystem path. It will be wrong for every other contributor. Should be dropped when #2 above lands (the file itself shouldn't be in this PR).
🔍 Major — should fix before merge
4. Cline config path is inaccurate
cli/docs/MCP_USAGE.md:51 says:
To use this React Debugger MCP server with Cline (VS Code extension), add the following configuration to your Cline settings (
.cline/mcp.jsonor your global VS Codesettings.json):
Per the official Cline MCP docs and Cline config reference, the actual paths are:
| Surface | Path |
|---|---|
| Cline VS Code extension (global storage) | ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json (macOS/Linux) |
| Cline CLI (unified config) | ~/.cline/data/settings/cline_mcp_settings.json |
| Windows VS Code extension | %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json |
.cline/mcp.json is not where Cline reads from. Also, Cline ignores settings.json for MCP config — that's a different file entirely.
Fix: update the Cline section with the correct paths above.
5. Issue #6 scope: 1 section vs 3
Issue #6 asked for "Add a ## Cline section" to an existing cli/docs/MCP_USAGE.md that was supposed to contain Claude + Opencode sections (assumed prerequisite from openspec/changes/mcp-server-v1/tasks.md task 5.2). The PR creates the file from scratch with all 3 sections.
This is overdelivery, which is generous, but it overlaps with mcp-server-v1 work that's still in flight. Coordinating with that branch is necessary to avoid file conflict at merge time.
I'll handle the coordination — but please be aware that some sections of your file may be rewritten by the mcp-server-v1 author before this lands.
✅ Minor
- Trailing blank line inside code fences — lines 28, 47, 66 each have an empty line before the closing
```of the JSON snippet. Cosmetic but some markdown linters flag it. - Section ordering — Claude → Opencode → Cline. Issue #6 was Cline-first; if you want to match the issue ordering, move Cline to the top. Optional.
- README link missing —
cli/README.mdcould link to this new doc from a "Using as an MCP server" section once themcpsubcommand is real. Punt to a follow-up.
✅ Security
- No secrets, tokens, or example API keys in any snippet. Clean on that axis.
- All URLs verified as legitimate (
github.com/sponsors/hoainhomatchespackage.json:28).
✅ What's good
- Documentation tone matches the project's voice (terse, technical, accurate-when-the-feature-exists).
- JSON snippets are syntactically valid.
- Per-OS config paths included for Claude Desktop (
~/Library/Application Support/Claude/claude_desktop_config.jsonon macOS,%APPDATA%\Claude\claude_desktop_config.jsonon Windows). These are correct per the Anthropic Claude Desktop docs. - File placement at
cli/docs/MCP_USAGE.mdmatches the issue request and themcp-server-v1task list.
Suggested path forward
The minimum-viable shape for this PR to merge:
- Add the
⚠️ Preview / unreleasedbanner (option (b) above) OR hold the PR until M3 of mcp-server-v1 ships (option (a)) - Rebase on
mainand drop the 6 docs/ harness files - Fix the Cline config path
If you take option (a) (hold until M3), I'll comment back here when it's time to rebase + merge. If you take option (b), I'd re-review immediately after the 3 fixes above.
Thanks again for the writeup — once the misalignment with the actual CLI surface is sorted, this is a quality contribution.
|
@hoainho Thank you for the incredibly thorough review and structural guidance! I have taken Option (b) and updated the PR:
The PR is now completely streamlined, clean, and ready for your re-review! |
hoainho
added
the
pre-star-rule
…w) (#48) Promotes the 'star the repo' rule from soft enforcement to a CI-blocking gate on PR merges. PRs from contributors who haven't starred the repo cannot merge until they do (single click + Re-run job). Mechanism: - New workflow .github/workflows/star-check.yml runs on every PR (opened, reopened, synchronize, ready_for_review, labeled, unlabeled). - Uses the public GitHub REST API 'GET /users/{login}/starred/{owner}/{repo}' via github-script. Returns 204 if starred, 404 if not. - No extra auth scope required beyond the default GITHUB_TOKEN. - Single job, 2 steps: the check + a summary write to the Actions UI. Auto-exemptions (no human action needed): - Maintainer PRs (@hoainho): hard-coded in the workflow's MAINTAINERS list. - Bot PRs: matches *[bot] suffix + an allowlist (dependabot, gemini-code-assist, google-cla, github-actions, renovate). - PRs labeled 'tracked-plan': for maintainer-driven milestone work (M-A, M-B, future Self-Roadmap milestones). - PRs labeled 'pre-star-rule': grandfathered PRs that were open before this policy landed (2026-06-01). Grandfathering (applied before this commit, separately via gh CLI): - 4 in-flight contributor PRs (#17, #36, #37, #38) labeled 'pre-star-rule' so the new check skips them. - 2 in-flight maintainer PRs (#39 M-A, #41 M-B) labeled 'tracked-plan' so the new check skips them. Failure UX: - When star check fails, the workflow writes a clear error message with: 'star the repo', 'click Re-run failed jobs', and a link to CONTRIBUTING.md. No re-push required to re-run after starring. Doc surface updated: - CONTRIBUTING.md: 'How to claim' section now flags the hard gate with a clear⚠️ notice; new 'Exemptions' subsection documents the 4 bypass categories. - PULL_REQUEST_TEMPLATE.md: 'Claim confirmation' section updated to note the CI enforcement. - CHANGELOG.md: new Unreleased entries under Added (workflow) + Changed (policy hardening) + Migration (grandfathering). Privacy + safety notes: - The API endpoint is public + read-only (no PII beyond GitHub's own public star list). - Workflow permissions are minimal: 'contents: read' + 'pull-requests: read'. No write access requested. - The check is idempotent and safe to re-run. Self-referential note: this PR itself will trigger the new workflow once merged. Author is @hoainho (in MAINTAINERS), so it auto-passes.
hoainho
left a comment
hoainho
left a comment
There was a problem hiding this comment.
@AsifpMulla123 All 3 critical items from the earlier review are addressed:
1. Preview banner ✅ — Line 3: > ⚠️ **Preview / unreleased.** The \mcp` subcommand documented here is part of the MCP Server v1 design and not yet shipped on npm. Track progress at milestones M1–M5.` — Sets expectations correctly, links to roadmap.
2. Cline configuration path corrected ✅ — Replaced the inaccurate .cline/mcp.json with the actual VS Code globalStorage path:
- Windows:
%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json - macOS/Linux:
~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
This matches the Cline official docs.
3. Workspace symlinks dropped ✅ — 6 docs/*.md symlinks removed. These were personal-workspace shortcuts (../../docs/...) — they're useless to anyone cloning the repo, so removing them is the right call.
Single-line args formatting is also cleaner. Bonus.
Approving and merging — this becomes the canonical MCP configuration reference for the project. Thanks for the patient revisions @AsifpMulla123. 🎉
Reminder: star + claim policy applies to future contributions. You're already starred — appreciated.
2 participants
Linked issue
Closes #6
Type of change
What changed
Created the missing
cli/docs/MCP_USAGE.mdfile to house Model Context Protocol (MCP) server integration documentation. Added valid, streamlined JSON configuration snippets for Claude Desktop, Opencode, and Cline referencing@nhonh/react-debugger@latestrunning themcpsubcommand.Testing notes
Tested configuration injection inside Cline's global settings framework to verify standard terminal communication behavior.
Checklist
npm run test:runpasses locally (or pre-existing failures are unrelated to this change)npm run buildsucceeds locally## [Unreleased](skip for docs-only or test-only PRs)fix(panel): ...)Screenshots / GIFs
Per maintainer confirmation on the issue thread, this PR is submitted without a sidebar screenshot due to local Windows environment stdio parsing constraints.
Additional notes
Testing the suggested
NO_COLOR=1environment block bypassed the initial ANSI terminal color escapes but confirmed that the CLI bootstrap continues to leak standard initialization text logs directly intostdout, corrupting the strict MCP JSON stream. A separate, dedicated bug report issue has been opened for this Windows bootstrap logging compatibility behavior as requested.