[PR #5291] docs(installation): document MCP override for REA source checkouts #6862

Open
opened 2026-11-01 21:43:37 +00:00 by bsakaguchi · 0 comments
Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/5291
Author: @TomManMaz
Created: 10/19/2026
Status: 🔄 Open

Base: main ← Head: claude/relaxed-knuth-5ee86b


📝 Commits (1)

  • b7b9c12 docs(installation): document MCP override for REA source checkouts

📊 Changes

2 files changed (+30 additions, -0 deletions)

View changed files

📝 CONTRIBUTING.md (+5 -0)
📝 docs/installation.md (+25 -0)

📄 Description

Summary

rea setup registers package-runner MCP servers as npx -y rea-agents@<version> mcp (wrapped in cmd.exe /d /c on Windows). That registration cannot start when the client's working directory is a REA source checkout whose root package.json is rea-agents at the same version. Claude Code starts stdio servers in the project directory, so REA is unavailable exactly when a contributor opens the checkout. This PR documents a local-scope override that uses the same published version. Setup is unchanged.

Problem and expected behavior

Observed on Windows 11, Node v24.15.0, npm 11.14.1, checkout of rea-agents@6.7.0 (cwd = checkout root):

  • cmd /d /c npx -y rea-agents@6.7.0 mcp exits 1: 'rea' is not recognized as an internal or external command.
  • The same command from %TEMP% completes an MCP initialize handshake (serverInfo rea 6.7.0).

Source-derived mechanism (npm 11.14.1 libnpmexec/lib/index.js, missingFromTree): for a registry spec of type version, npm queries the local Arborist tree by package name and accepts any node whose pkgid equals the spec. That includes the root project node. npm therefore installs nothing into the npx cache and resolves the bin from ./node_modules/.bin, where a project's own bins are never linked. This path is platform-independent apart from the script shell, so POSIX should fail the same way. POSIX was not executed.

Change and scope

Docs only:

  • docs/installation.md (in the "One project" local-scope section, inside release-please version markers): explains the failure and adds a local-scope Claude Code entry that installs the same exact version under an npm alias (--package=rea-agents-published@npm:rea-agents@<version> rea-agents mcp). Because the alias name differs from the root package name, the local root no longer satisfies the spec.
  • CONTRIBUTING.md: a pointer to that section.

Options considered and not taken:

  • Explicit bin (npm exec --yes --package=rea-agents@X -- rea-agents mcp): observed to fail the same way ('rea-agents' is not recognized), because it uses the same missingFromTree path.
  • Switching setup's registration to the alias form: changes every user's registration and the owned-command identity parser (clientRegistrationPackageReference), alignment, and uninstall ownership, plus a migration of existing entries. This fixes a case that only affects a checkout at the released version. Warm handshakes were similar (alias ~2.3 s vs pinned ~2.1 s, single samples); the first alias handshake took 11.6 s for an unestablished reason. Left as a maintainer scope question.
  • A rea doctor diagnostic: doctor reads only user-level entries, and the affected population is contributors. Not added.
  • Tarball-URL spec: bypasses the user's configured registry. Rejected.

Contract and boundary impact

  • Semantic owner and earliest changed stage: documentation only.

  • Contribution scope fit and linked maintainer decision: not applicable (docs). A setup registration change would need one.

  • CLI and MCP/tool-catalog contract: none.

  • Provider, bridge, target-format, or platform compatibility: none.

  • Evidence, artifact, provenance, or reconstruction contract: none.

  • Target selection, authority, upstream behavior, and cleanup details: not applicable.

  • Generated metadata, package, or installation impact: installation docs only. The new example version is inside x-release-please-start-version markers.

  • Read existing files or captured data.

  • Launch or attach to a process.

  • Inject instrumentation or run scripts/code.

  • Change process memory, registers, files, or configuration.

  • Contact network services.

  • Recover protected code or work around protections.

  • Documentation or usability only; no target interaction.

  • Not sure yet; investigation or maintainer guidance needed.

Evidence and regression coverage

  • Tests added or updated: none (documentation only).
  • Base reproduction (executed, Windows, checkout cwd): see Problem. npm exec --yes --package=rea-agents@6.7.0 -- rea-agents --version also exits 1.
  • Workaround (executed, Windows, checkout cwd): cmd.exe /d /c npx -y --package=rea-agents-published@npm:rea-agents@6.7.0 rea-agents mcp completes the MCP initialize handshake (serverInfo rea 6.7.0).
  • Documented Claude Code workflow (executed in PowerShell with a throwaway CLAUDE_CONFIG_DIR, checkout cwd): the local-scope pinned entry reports Status: × Failed to connect; the documented alias entry reports Status: √ Connected.
  • Remaining proof gaps: POSIX not executed (source-derived only). The bash example was not run. bunx not tested (Bun not installed).

Validation performed

  • npx --no-install oxfmt --check docs/installation.md CONTRIBUTING.md — all files correctly formatted.
  • npm run test:local -- tests/conformance/readmeConsistency.test.ts — 5 passed.
  • npm run test:local -- tests/conformance/releaseConfiguration.test.ts — 5 passed.
  • npm run docs:check — did not run its checks; stopped because the Windows native addon is missing in a source checkout (documented limitation).
  • node scripts/check-doc-facts.mjs — not run to completion; requires a dist/ build, which npm run build:cached could not produce for the same native-addon reason.
  • npx vitepress build docs — failed on 6 pre-existing dead links in other files (experiments/…); none in the touched files.

Compatibility, safety, and release

  • Breaking changes or migration steps: none.
  • Real Hopper/Ghidra, browser, or OS coverage: Windows 11 only.
  • Package or release metadata impact: none beyond release-please updating the new version examples.
  • Security, privacy, process, or containment review: the override uses the public npm registry and the user's own npm configuration, and touches only Claude Code local scope.

Author readiness

Human owner:

  • I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work.
  • I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps.
  • I declare this PR ready for initial maintainer review.

Before merge

  • This PR addresses a concrete problem or an agreed enhancement.
  • Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff.
  • The PR has one focused outcome and the title follows type(scope): outcome.
  • Related issue is linked, or the reason for not linking one is stated above.
  • Tests cover changed observable behavior and meaningful failure paths.
  • Owning docs, contracts, and generated metadata are updated where needed.
  • User-visible CLI/MCP changes include representative output.
  • I checked the final diff for secrets, unrelated cleanup, and unsupported claims.

🤖 Generated with Claude Code


🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/5291 **Author:** [@TomManMaz](https://github.com/TomManMaz) **Created:** 10/19/2026 **Status:** 🔄 Open **Base:** `main` ← **Head:** `claude/relaxed-knuth-5ee86b` --- ### 📝 Commits (1) - [`b7b9c12`](https://github.com/morluto/rea/commit/b7b9c12dec408dba2bb44a777bdfce94424d907d) docs(installation): document MCP override for REA source checkouts ### 📊 Changes **2 files changed** (+30 additions, -0 deletions) <details> <summary>View changed files</summary> 📝 `CONTRIBUTING.md` (+5 -0) 📝 `docs/installation.md` (+25 -0) </details> ### 📄 Description ## Summary `rea setup` registers package-runner MCP servers as `npx -y rea-agents@<version> mcp` (wrapped in `cmd.exe /d /c` on Windows). That registration cannot start when the client's working directory is a REA source checkout whose root `package.json` is `rea-agents` at the same version. Claude Code starts stdio servers in the project directory, so REA is unavailable exactly when a contributor opens the checkout. This PR documents a local-scope override that uses the same published version. Setup is unchanged. ## Problem and expected behavior Observed on Windows 11, Node v24.15.0, npm 11.14.1, checkout of rea-agents@6.7.0 (cwd = checkout root): - `cmd /d /c npx -y rea-agents@6.7.0 mcp` exits 1: `'rea' is not recognized as an internal or external command`. - The same command from `%TEMP%` completes an MCP `initialize` handshake (`serverInfo` rea 6.7.0). Source-derived mechanism (npm 11.14.1 `libnpmexec/lib/index.js`, `missingFromTree`): for a registry spec of type `version`, npm queries the local Arborist tree by package name and accepts any node whose `pkgid` equals the spec. That includes the root project node. npm therefore installs nothing into the npx cache and resolves the bin from `./node_modules/.bin`, where a project's own bins are never linked. This path is platform-independent apart from the script shell, so POSIX should fail the same way. POSIX was not executed. ## Change and scope Docs only: - `docs/installation.md` (in the "One project" local-scope section, inside release-please version markers): explains the failure and adds a local-scope Claude Code entry that installs the same exact version under an npm alias (`--package=rea-agents-published@npm:rea-agents@<version> rea-agents mcp`). Because the alias name differs from the root package name, the local root no longer satisfies the spec. - `CONTRIBUTING.md`: a pointer to that section. Options considered and not taken: - Explicit bin (`npm exec --yes --package=rea-agents@X -- rea-agents mcp`): observed to fail the same way (`'rea-agents' is not recognized`), because it uses the same `missingFromTree` path. - Switching setup's registration to the alias form: changes every user's registration and the owned-command identity parser (`clientRegistrationPackageReference`), alignment, and uninstall ownership, plus a migration of existing entries. This fixes a case that only affects a checkout at the released version. Warm handshakes were similar (alias ~2.3 s vs pinned ~2.1 s, single samples); the first alias handshake took 11.6 s for an unestablished reason. Left as a maintainer scope question. - A `rea doctor` diagnostic: doctor reads only user-level entries, and the affected population is contributors. Not added. - Tarball-URL spec: bypasses the user's configured registry. Rejected. ## Contract and boundary impact - Semantic owner and earliest changed stage: documentation only. - Contribution scope fit and linked maintainer decision: not applicable (docs). A setup registration change would need one. - CLI and MCP/tool-catalog contract: none. - Provider, bridge, target-format, or platform compatibility: none. - Evidence, artifact, provenance, or reconstruction contract: none. - Target selection, authority, upstream behavior, and cleanup details: not applicable. - Generated metadata, package, or installation impact: installation docs only. The new example version is inside `x-release-please-start-version` markers. - [ ] Read existing files or captured data. - [ ] Launch or attach to a process. - [ ] Inject instrumentation or run scripts/code. - [ ] Change process memory, registers, files, or configuration. - [ ] Contact network services. - [ ] Recover protected code or work around protections. - [x] Documentation or usability only; no target interaction. - [ ] Not sure yet; investigation or maintainer guidance needed. ## Evidence and regression coverage - Tests added or updated: none (documentation only). - Base reproduction (executed, Windows, checkout cwd): see Problem. `npm exec --yes --package=rea-agents@6.7.0 -- rea-agents --version` also exits 1. - Workaround (executed, Windows, checkout cwd): `cmd.exe /d /c npx -y --package=rea-agents-published@npm:rea-agents@6.7.0 rea-agents mcp` completes the MCP `initialize` handshake (serverInfo rea 6.7.0). - Documented Claude Code workflow (executed in PowerShell with a throwaway `CLAUDE_CONFIG_DIR`, checkout cwd): the local-scope pinned entry reports `Status: × Failed to connect`; the documented alias entry reports `Status: √ Connected`. - Remaining proof gaps: POSIX not executed (source-derived only). The bash example was not run. `bunx` not tested (Bun not installed). ## Validation performed - `npx --no-install oxfmt --check docs/installation.md CONTRIBUTING.md` — all files correctly formatted. - `npm run test:local -- tests/conformance/readmeConsistency.test.ts` — 5 passed. - `npm run test:local -- tests/conformance/releaseConfiguration.test.ts` — 5 passed. - `npm run docs:check` — did not run its checks; stopped because the Windows native addon is missing in a source checkout (documented limitation). - `node scripts/check-doc-facts.mjs` — not run to completion; requires a `dist/` build, which `npm run build:cached` could not produce for the same native-addon reason. - `npx vitepress build docs` — failed on 6 pre-existing dead links in other files (experiments/…); none in the touched files. ## Compatibility, safety, and release - Breaking changes or migration steps: none. - Real Hopper/Ghidra, browser, or OS coverage: Windows 11 only. - Package or release metadata impact: none beyond release-please updating the new version examples. - Security, privacy, process, or containment review: the override uses the public npm registry and the user's own npm configuration, and touches only Claude Code local scope. ## Author readiness Human owner: <!-- @GitHub-handle --> - [ ] I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work. - [ ] I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps. - [ ] I declare this PR ready for initial maintainer review. ## Before merge - [ ] This PR addresses a concrete problem or an agreed enhancement. - [ ] Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff. - [ ] The PR has one focused outcome and the title follows `type(scope): outcome`. - [ ] Related issue is linked, or the reason for not linking one is stated above. - [ ] Tests cover changed observable behavior and meaningful failure paths. - [ ] Owning docs, contracts, and generated metadata are updated where needed. - [ ] User-visible CLI/MCP changes include representative output. - [ ] I checked the final diff for secrets, unrelated cleanup, and unsupported claims. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
morluto/rea#6862
No description provided.