From 24fcb8ba12d63e63d8f1a2e438478a98f73085ac Mon Sep 17 00:00:00 2001 From: project7 Date: Sat, 18 Jul 2026 09:03:06 +0900 Subject: [PATCH 1/2] [#1009] docs(operator-mcp): Make the Operator MCP guide backend-neutral and remote-safe MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Backend-neutral: retitle "from a Claude agent" → "from an MCP client"; the operator server is a generic stdio MCP server usable by any MCP-capable client. Add a generic registration framing (every client launches the same `quadwork-mcp-operator --port ` bin) and a verified Codex CLI registration using the `-c mcp_servers.` mechanism — the same one QuadWork uses to attach its chat shim to Codex agents (src/lib/injectMode.js: codex → proxy_flag; server/index.js:576-580). - Remote-safe: keep the loopback-only security model and SSH local-forward remote access intact; genericize the "reaches your laptop's 127.0.0.1" notes from Claude-Desktop-specific to any local client. - No environment-specific identifiers: replace the sample project id `plotlink-ows` with a neutral `myproject`. - Align the start_batch example to the verified default interval (30 min, server/mcp-operator/tools/triggers.js:29). Preserved per ticket: tool-first operating model, @head queue ownership, the read-only (Tier 1) vs state-changing (Tier 2) split, and the local-loopback / no-public-port security warnings. All 14 documented tools match the current mcp-operator surface. Docs-only; no backend/runtime code, packages, tests, legacy migration implementation, other docs, or other repos touched. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/operator-mcp.md | 29 ++++++++++++++++++++--------- 1 file changed, 20 insertions(+), 9 deletions(-) diff --git a/docs/operator-mcp.md b/docs/operator-mcp.md index e78b7d2..57dc0e5 100644 --- a/docs/operator-mcp.md +++ b/docs/operator-mcp.md @@ -1,6 +1,6 @@ -# Drive QuadWork from a Claude agent (Operator MCP) +# Drive QuadWork from an MCP client (Operator MCP) -QuadWork ships an **MCP operator server** — a stdio [Model Context Protocol](https://modelcontextprotocol.io) server that lets a Claude agent (Claude Code or Claude Desktop) **observe and drive** a running QuadWork instance: read team chat and batch progress, define and run overnight batches, and control individual agents. +QuadWork ships an **MCP operator server** — a stdio [Model Context Protocol](https://modelcontextprotocol.io) server that lets any MCP-capable client (Claude Code, Claude Desktop, Codex, or another MCP agent) **observe and drive** a running QuadWork instance: read team chat and batch progress, define and run overnight batches, and control individual agents. It is the same surface a human operator uses from the dashboard, exposed as tools. It talks to the QuadWork backend over `http://127.0.0.1:` (default **8400**) and is launched by the MCP client, **not** by QuadWork itself. @@ -39,7 +39,7 @@ you act as the human operator by talking to them. ## Registration -The package installs a dedicated bin, `quadwork-mcp-operator`. Always register with the bin (never a `/server/...` path — that breaks on global/VPS installs). +The package installs a dedicated bin, `quadwork-mcp-operator`. Always register with the bin (never a `/server/...` path — that breaks on global/VPS installs). Every client launches the **same** command — `quadwork-mcp-operator --port ` — only the registration syntax differs. Examples for common clients follow; any MCP client that can launch a stdio server works the same way. ### Claude Code (local install) @@ -49,6 +49,17 @@ claude mcp add quadwork -- quadwork-mcp-operator --port 8400 Then, in a Claude Code session, the `list_projects`, `batch_status`, `start_batch`, … tools are available. Verify with `list_projects` — it should return your configured projects. +### Codex CLI + +Codex registers MCP servers with `-c mcp_servers.` config flags — the same mechanism QuadWork uses to attach its chat shim to Codex-backed agents: + +```bash +codex -c 'mcp_servers.quadwork.command="quadwork-mcp-operator"' \ + -c 'mcp_servers.quadwork.args=["--port","8400"]' +``` + +The `quadwork` tools are then available in the Codex session; verify with `list_projects`. + ### Claude Desktop Add this to your `claude_desktop_config.json` (Settings → Developer → Edit Config): @@ -68,7 +79,7 @@ Restart Claude Desktop. The QuadWork tools appear under the 🔌 tools menu. ### Remote / VPS registration -The operator server speaks to `127.0.0.1:8400` — the loopback of **whatever machine the MCP client runs on**. If QuadWork runs on a VPS, a Claude Desktop registration on your laptop reaches **your laptop's** `127.0.0.1`, not the VPS. Two ways to register correctly: +The operator server speaks to `127.0.0.1:8400` — the loopback of **whatever machine the MCP client runs on**. If QuadWork runs on a VPS, a local client registration on your laptop reaches **your laptop's** `127.0.0.1`, not the VPS. Two ways to register correctly: 1. **Run Claude Code over SSH on the VPS host** — register there with the same command; it reaches the VPS's local QuadWork directly. ```bash @@ -82,7 +93,7 @@ The operator server speaks to `127.0.0.1:8400` — the loopback of **whatever ma claude mcp add quadwork -- quadwork-mcp-operator --port 8400 ``` -> ⚠️ **A local Claude Desktop registration reaches THIS device's `127.0.0.1`, not the VPS.** Use SSH or a port-forward so the client and QuadWork share a loopback. +> ⚠️ **A local MCP-client registration reaches THIS device's `127.0.0.1`, not the VPS.** Use SSH or a port-forward so the client and QuadWork share a loopback. ### Remote / VPS troubleshooting @@ -171,15 +182,15 @@ not fall back to SSH or HTTP endpoint calls. ### Read status and recent chat -Replace `plotlink-ows` with the `id` returned by `list_projects`. +Replace `myproject` with the `id` returned by `list_projects`. ```bash python3 - <<'PY' import json reqs = [ {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"operator-script","version":"1"}}}, - {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"batch_status","arguments":{"project":"plotlink-ows"}}}, - {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"read_chat","arguments":{"project":"plotlink-ows","limit":20}}}, + {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"batch_status","arguments":{"project":"myproject"}}}, + {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"read_chat","arguments":{"project":"myproject","limit":20}}}, ] open('/tmp/qw-status.jsonl','w').write('\n'.join(json.dumps(r) for r in reqs) + '\n') PY @@ -243,7 +254,7 @@ Each is 1–3 tool calls. Start every session with `list_projects` to get the **Start a code batch** — let HEAD plan and write the queue: 1. `send_message(project, "@head start a batch for : #12 #15 #18")` — HEAD files issues + writes `OVERNIGHT-QUEUE.md`, then asks you to start. -2. Kick it off: `start_batch(project, { interval_min: 15 })` for an overnight cadence (first pulse at T+interval), or `trigger_now(project)` for an immediate first pulse. +2. Kick it off: `start_batch(project, { interval_min: 30 })` for an overnight cadence (30 min is the default; first pulse at T+interval), or `trigger_now(project)` for an immediate first pulse. 3. Monitor (below). **Run a review batch** (review-only — no code, no merges). Just ask HEAD; it stamps the `**Batch type:**` marker — you never touch the queue: From 64ce6b8f2ea297d36ee254a9e8fe6724b270cf82 Mon Sep 17 00:00:00 2001 From: project7 Date: Sat, 18 Jul 2026 09:06:24 +0900 Subject: [PATCH 2/2] [#1009] docs(operator-mcp): Reconcile same-machine note with SSH-forward support Address @re1: the "MCP client must run on the same machine" note (line 7) contradicted the SSH local-forward path documented under Remote / VPS. Restate it as a shared-loopback requirement that explicitly allows either same-host operation or the documented SSH tunnel. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/operator-mcp.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/operator-mcp.md b/docs/operator-mcp.md index 57dc0e5..a1f890b 100644 --- a/docs/operator-mcp.md +++ b/docs/operator-mcp.md @@ -4,7 +4,7 @@ QuadWork ships an **MCP operator server** — a stdio [Model Context Protocol](h It is the same surface a human operator uses from the dashboard, exposed as tools. It talks to the QuadWork backend over `http://127.0.0.1:` (default **8400**) and is launched by the MCP client, **not** by QuadWork itself. -> **The MCP client must run on the same machine as QuadWork.** The server only reaches `127.0.0.1:` — see [Remote / VPS](#remote--vps-registration) below. +> **The client and QuadWork must share a loopback.** The server only reaches `127.0.0.1:`, so either run the MCP client on the same machine as QuadWork, or bridge the two with the SSH local port-forward in [Remote / VPS](#remote--vps-registration) below. ## Operating model — read this first