[#1009] docs(operator-mcp): Make the Operator MCP guide backend-neutral and remote-safe

[realproject7]

Closes #1009

Summary

Docs-only. Makes docs/operator-mcp.md describe a generic tool-first MCP operator surface rather than a Claude-only feature, adds a verified Codex registration, keeps the loopback/SSH-forward security model, and removes an environment-specific project id. Scope: docs/operator-mcp.md only.

Changes

• Backend-neutral: retitled "from a Claude agent" → "from an MCP client"; intro now names Claude Code, Claude Desktop, Codex, or any MCP agent. Added a generic registration note (every client launches the same quadwork-mcp-operator --port <port> bin; only the syntax differs). Genericized the Remote/VPS "reaches your laptop's 127.0.0.1" notes from Claude-Desktop-specific to any local client.
• Codex (verified only): added a Codex CLI registration using -c mcp_servers.<name> config flags — the exact mechanism QuadWork already uses to inject its chat shim into Codex agents (src/lib/injectMode.js codex→proxy_flag; server/index.js:576-580). No unverified/config.toml setup invented.
• Remote-safe: preserved the local-loopback security model, the "backend binds loopback only / do not expose port 8400 publicly" guidance, and the SSH local-forward remote-access flow.
• No environment-specific identifiers: replaced the sample project id plotlink-ows with a neutral myproject. (IPs/hosts elsewhere are placeholders: <vps-ip>, <alias>, 178.x.x.x.)
• Accuracy: aligned the start_batch example to the verified default interval (30 min).

Preserved per ticket

• Tool-first operating model and @Head owns the queue (Operating model section).
• Read-only (Tier 1) vs state-changing (Tier 2) tool split.
• Local-loopback / no-public-port security warnings.

EPIC Alignment

• Batch 24 ticket docs(operator-mcp): Make the Operator MCP guide backend-neutral and remote-safe #1009 (final) owns only docs/operator-mcp.md. This diff touches exactly that file.
• Ticket requirements met: generic MCP surface; @Head queue ownership; current tool surface; secure local-forward remote access; read-only vs state-changing distinguished; no environment-specific hostnames/IPs; Codex mentioned only where verified.
• Out of scope, untouched: backend/runtime code, packages, tests, legacy migration implementation, other docs, and other repositories.

Self-Verification

• Tool surface (all 14 match): list_projects read_chat batch_status read_queue list_agents (server/mcp-operator/tools/{projects,read}.js); send_message start_batch trigger_now stop_batch agent_control interrupt_all set_batch append_batch ensure_batch (.../tools/{chat-send,triggers,agents,batch}.js).
• Codex MCP mechanism: src/lib/injectMode.js:27-29 (codex → proxy_flag); server/index.js:576-580 (-c mcp_servers.chat.command/args). The operator equivalent uses command="quadwork-mcp-operator", args=["--port","8400"].
• start_batch default 30: server/mcp-operator/tools/triggers.js:29,35.
• Loopback bind: server/index.js:2324 (server.listen(PORT, "127.0.0.1")).
• No environment-specific IDs: rg -i plotlink docs/operator-mcp.md → none; no real hostnames/IPs (placeholders only).
• Scope: git diff --stat → docs/operator-mcp.md only.
• CI: pending on push.

Acceptance criteria

• Describes a generic MCP operator surface (not Claude-only)
• Tool-first model, @Head queue ownership, read-only vs state-changing documented
• Remote access via secure local forward; local-loopback security preserved
• No environment-specific hostnames or IP addresses published
• Codex-compatible usage mentioned only where verified
• No backend/runtime changes; no edits outside docs/operator-mcp.md

[project7-interns]

Verdict: REQUEST CHANGES

Epic Alignment: FAIL

The ticket requires a secure local-forward remote-access model, but the guide’s opening contradicts that model.

Checked (evidence)

• Structural gate: filled ## EPIC Alignment and ## Self-Verification; docs-only, non-UI PR.
• Scope and tool surface: docs/operator-mcp.md:220-242 lists all 14 tools, matching server/mcp-operator/tools/{projects,read,chat-send,triggers,agents,batch}.js.
• Codex registration: docs/operator-mcp.md:52-61 matches src/lib/injectMode.js:27-29 and server/index.js:575-580.
• Riskiest part of this diff: remote guidance; its local-forward instructions are correct, but the opening claim makes that supported topology appear forbidden.
• Kill-list: scanned changed docs and supporting source — one accuracy hit listed below.
• CI: gh pr checks 1017 --repo realproject7/quadwork → test pass (55s).

Findings

• [blocking] The guide contradicts its own supported SSH local-forward deployment.
  • File: docs/operator-mcp.md:7
  • Why it fails: “must run on the same machine” is false when a local client reaches the VPS loopback through the documented ssh -L tunnel (docs/operator-mcp.md:82-115). This directly undermines #1009’s remote-safe access requirement.
  • Do instead: say the client must share the backend’s loopback namespace, either by running on the QuadWork host or by using the documented SSH local forward; then retain the link to the Remote/VPS section.

Decision

Correct the opening constraint so it agrees with the secure remote workflow before approval.

[realproject7]

@re2 Independent Review — APPROVE ✅ (head 24fcb8b)

Checked (evidence)

• Backend-neutral — retitled to "from an MCP client"; framing now covers Claude Code / Desktop / Codex / any stdio MCP client, all launching the same quadwork-mcp-operator --port bin. ✓
• Codex registration is verified, not invented — the doc's codex -c 'mcp_servers.quadwork.command=…' -c 'mcp_servers.quadwork.args=[…]' matches the exact mechanism QuadWork uses to inject its chat shim into Codex agents: injectMode === "proxy_flag" → args.push("-c", mcp_servers.chat.command=…, "-c", mcp_servers.chat.args=[…]) (server/index.js:575-580; injectModeForCommand codex→proxy_flag in src/lib/injectMode.js). ✓
• All 14 tools match the live surface — the code exposes exactly 14 operator tools (agent_control, append_batch, batch_status, ensure_batch, interrupt_all, list_agents, list_projects, read_chat, read_queue, send_message, set_batch, start_batch, stop_batch, trigger_now across server/mcp-operator/tools/*.js); every one appears in the doc, and the doc invents none. ✓
• Read-only vs state-changing clearly split — Tier 1 (5 read-only: list_projects/read_chat/batch_status/read_queue/list_agents) vs Tier 2 (9 state-changing incl. agent_control, interrupt_all, set_batch/append_batch/ensure_batch). Classification is accurate against the tool sources. ✓
• Remote-safe / no env-specific identifiers — loopback-only model + SSH local-forward preserved; plotlink-ows → myproject; scan for plotlink|quadwork.xyz|public IPs → none (only generic 127.0.0.1). ✓
• Default interval aligned — start_batch example uses 30 min, matching the verified default (server/index.js:1517, interval || 30). ✓
• Scope — docs/operator-mcp.md only (+20/−9); git diff --name-only origin/main → single file. CI gh pr checks 1017 → test pass (55s). ✓

Verdict: APPROVE on 24fcb8b. (Recorded as a comment; shared bot account cannot self-approve on GitHub.)

[project7-interns]

Verdict: APPROVE

Epic Alignment: PASS

The corrected opening now accurately preserves #1009’s secure local-forward model without expanding scope.

Checked (evidence)

• Re-review delta: 24fcb8ba12d63e63d8f1a2e438478a98f73085ac..64ce6b8f2ea297d36ee254a9e8fe6724b270cf82 changes only docs/operator-mcp.md:7.
• Prior finding resolved: the new shared-loopback wording explicitly permits same-host operation or the documented SSH local forward.
• Riskiest part of this delta: remote topology guidance; it now agrees with the tunnel flow at docs/operator-mcp.md:82-115.
• Kill-list: scanned the new range — clean.
• CI: gh pr checks 1017 --repo realproject7/quadwork → test pass (51s).

Findings

None.

Decision

The targeted correction resolves the contradictory deployment claim and the reviewed delta is accurate.

[realproject7]

@re2 Re-review — APPROVE ✅ (new head 64ce6b8)

Re-confirming after @dev's fix for @re1's REQUEST_CHANGES. The incremental change (git diff 24fcb8b..64ce6b8) is a single one-line intro reword at docs/operator-mcp.md:7:

• Before: "The MCP client must run on the same machine as QuadWork."
• After: "The client and QuadWork must share a loopback… either run the MCP client on the same machine, or bridge the two with the SSH local port-forward in Remote / VPS below."

Checked (evidence)

• @re1's inconsistency is resolved — the old "same machine" absolute contradicted the SSH-forward path; the new wording is consistent with the Remote/VPS section (Option 2: ssh -L 8400:127.0.0.1:8400 you@your-vps, docs/operator-mcp.md:88-97) and the ⚠️ note at :98 ("Use SSH or a port-forward so the client and QuadWork share a loopback"). ✓
• No other changes — diff is that one paragraph only; tool tables, Tier 1/2 split, and security notes are untouched. All prior evidence still holds (14 tools match server/mcp-operator/tools/*.js; Codex proxy_flag injection server/index.js:575-580; no env-specific identifiers; 30-min default server/index.js:1517). ✓
• Scope — docs/operator-mcp.md only; git diff --name-only origin/main → single file. CI gh pr checks 1017 → test pass (51s). ✓

Verdict: APPROVE on 64ce6b8. (Recorded as a comment; shared bot account cannot self-approve on GitHub.)