@algosuite/vo-mcp 0.2.0-beta.8 → 0.2.0-beta.9

package/README.md

@@ -2,10 +2,34 @@
 
 Virtual Office MCP server — the open protocol surface that exposes VO's consensus and ratchet tool family to any MCP-capable LLM client (Claude Code, Claude Desktop, Cursor, Continue, Codex, etc.).
 
-**Status:** Phase 2. Stdio transport. **20 tools registered** (source of truth: `src/server.ts` `buildToolRegistry()`). The static-ratchet tools (`vo_check_assertion_strength`, `vo_check_ratchets`) run locally today; the consensus-routed tools fall back to `{ verdict: "unimplemented", ... }` until engine credentials are present; the heal-family, PR-admin, and session-state tools forward to the vo-control-plane admin proxy in cloud mode. `vo_review_merge` is a **read-only consensus pre-merge review** (the verify-before-act gate for the Command Center — never merges). The shape is stable; the institutional-knowledge content is loaded from closed packages.
+The live AlgoHQ whiteboard is available to every MCP client through
+`hq_whiteboard_post` and `hq_whiteboard_read`. Both use the scoped credential
+created by `vo-mcp login`; tenant/operator ownership is derived by the control
+plane and cannot be widened by tool input. The control plane admits scoped
+credentials only for operator IDs on its internal `HQ_WHITEBOARD_OPERATOR_IDS`
+allowlist; arbitrary self-serve tenants cannot read or write the shared fleet board.
+
+**Status:** Phase 2. Stdio transport. **26 tools registered** (source of truth: `src/server.ts` `buildToolRegistry()`). The static-ratchet tools (`vo_check_assertion_strength`, `vo_check_ratchets`) run locally today; the consensus-routed tools fall back to `{ verdict: "unimplemented", ... }` until engine credentials are present; the heal-family, PR-admin, session-state, and AlgoHQ whiteboard tools forward to the control plane in cloud mode. `vo_review_merge` is a **read-only consensus pre-merge review** (the verify-before-act gate for the Command Center — never merges). The shape is stable; the institutional-knowledge content is loaded from closed packages.
 
 This package is intentionally **shell-only**. Per `docs/handoffs/vo-mcp-server-2026-05-21.md` §C-1: tool *definitions* (schemas, names, descriptions) ship openly. Tool *implementations* that encode institutional knowledge (specific ratchet thresholds, consensus prompt content, architectural-defaults knowledge base) live behind the cloud or in closed companion packages.
 
+## Install and refresh client configuration
+
+`vo-mcp install` safely registers the same required `algohq` MCP server in
+Claude Desktop, Claude Code, and Codex (`~/.codex/config.toml`), then offers
+pairing and runner auto-start. Existing client settings and comments are
+preserved, and every changed config is backed up first.
+
+To refresh client configuration on an already-paired runner without touching
+its keychain credential or auto-start service, use the noninteractive form:
+
+```sh
+vo-mcp install --config-only
+```
+
+Restart the MCP clients and runner after updating, then use
+[AlgoHQ](https://algosuite.ai/algohq) to dispatch work.
+
 ## Tools
 
 | Name | Phase 1 status | Description |
@@ -44,7 +68,7 @@ pnpm test            # vitest run
 
 The integration test (`test/integration/stdio-roundtrip.test.ts`) spawns the built CLI, exchanges JSON-RPC over stdio, and asserts:
 
-- `initialize` + `tools/list` returns the 20 expected tools.
+- `initialize` + `tools/list` returns the 26 expected tools.
 - `vo_check_assertion_strength` runs end-to-end and writes a JSONL event line.
 - A repeat call with identical input hits the cache (`cache.hit = true`).
 - `vo_consensus_judgment` returns `unimplemented` and still writes its event line.

package/bin/vo-mcp

@@ -5,6 +5,7 @@
  * Usage:
  *   vo-mcp                                  # MCP stdio server (default)
  *   vo-mcp install                          # one-command installer
+ *   vo-mcp install --config-only            # refresh Claude + Codex MCP config only
  *   vo-mcp update                           # update MCP + runner package
  *   vo-mcp login                            # credential login (browser loopback)
  *   vo-mcp pair                             # device-code pairing (enter a code in the web)

package/dist/cli.js

@@ -5592,6 +5592,149 @@ async function handlePrivateKnowledgeContext(_deps, rawInput, _signal, fetchFn =
   return jsonContent({ tool: CONTEXT_TOOL_NAME, schema_version: 1, payload });
 }
 
+// src/tools/hq/whiteboard.ts
+init_auth_token_source();
+init_credential_store();
+init_common();
+var POST_TOOL_NAME = "hq_whiteboard_post";
+var READ_TOOL_NAME = "hq_whiteboard_read";
+var postDescription = "Post an append-only coordination note to the live AlgoHQ whiteboard. Uses the scoped credential from vo-mcp login; operator and tenant ownership are derived by the server.";
+var readDescription = "Read recent coordination notes from the caller's live AlgoHQ whiteboard. Uses the scoped credential from vo-mcp login and cannot widen tenant scope.";
+var postInputSchema = {
+  type: "object",
+  properties: {
+    from: { type: "string", minLength: 1, maxLength: 100, description: "Agent/session display name." },
+    type: { type: "string", minLength: 1, maxLength: 64, description: "Message kind, such as intent, worklog, blocker, or completion." },
+    content: { type: "string", minLength: 1, maxLength: 500, description: "Short coordination note." },
+    targetAgent: { type: "string", maxLength: 100 },
+    tester: { type: "string", maxLength: 100 },
+    tier: { type: "string", maxLength: 32 }
+  },
+  required: ["from", "type", "content"],
+  additionalProperties: false
+};
+var readInputSchema = {
+  type: "object",
+  properties: {
+    limit: { type: "integer", minimum: 1, maximum: 100, default: 25 },
+    since: { type: "string", description: "Optional ISO-8601 lower bound." },
+    type: { type: "string", minLength: 1, maxLength: 64 }
+  },
+  additionalProperties: false
+};
+function resolveTimeoutMs() {
+  const parsed = Number(process.env["HQ_WHITEBOARD_TIMEOUT_MS"]);
+  return Number.isFinite(parsed) && parsed >= 10 && parsed <= 12e4 ? parsed : 1e4;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function onlyKeys(value, allowed) {
+  return Object.keys(value).every((key) => allowed.includes(key));
+}
+function isBoundedString(value, min, max) {
+  return typeof value === "string" && value.trim().length >= min && value.trim().length <= max;
+}
+function parsePostInput(value) {
+  if (!isRecord(value) || !onlyKeys(value, ["from", "type", "content", "targetAgent", "tester", "tier"])) return null;
+  if (!isBoundedString(value["from"], 1, 100)) return null;
+  if (!isBoundedString(value["type"], 1, 64) || !/^[a-zA-Z0-9_-]+$/.test(value["type"].trim())) return null;
+  if (!isBoundedString(value["content"], 1, 500)) return null;
+  for (const [key, max] of [["targetAgent", 100], ["tester", 100], ["tier", 32]]) {
+    if (value[key] !== void 0 && !isBoundedString(value[key], 0, max)) return null;
+  }
+  return {
+    from: value["from"].trim(),
+    type: value["type"].trim(),
+    content: value["content"].trim(),
+    ...typeof value["targetAgent"] === "string" ? { targetAgent: value["targetAgent"].trim() } : {},
+    ...typeof value["tester"] === "string" ? { tester: value["tester"].trim() } : {},
+    ...typeof value["tier"] === "string" ? { tier: value["tier"].trim() } : {}
+  };
+}
+function parseReadInput(value) {
+  if (!isRecord(value) || !onlyKeys(value, ["limit", "since", "type"])) return null;
+  if (value["limit"] !== void 0 && (!Number.isInteger(value["limit"]) || Number(value["limit"]) < 1 || Number(value["limit"]) > 100)) return null;
+  if (value["since"] !== void 0 && (typeof value["since"] !== "string" || Number.isNaN(Date.parse(value["since"])))) return null;
+  if (value["type"] !== void 0 && !isBoundedString(value["type"], 1, 64)) return null;
+  return {
+    ...typeof value["limit"] === "number" ? { limit: value["limit"] } : {},
+    ...typeof value["since"] === "string" ? { since: value["since"] } : {},
+    ...typeof value["type"] === "string" ? { type: value["type"].trim() } : {}
+  };
+}
+async function resolveCloud(fetchFn) {
+  const url = process.env["VO_CONTROL_PLANE_URL"]?.trim().replace(/\/$/, "");
+  if (!url) return null;
+  try {
+    const source = createAuthTokenSourceFromEnv(process.env, fetchFn, () => readStoredCredential(process.env));
+    const token = await source?.getToken();
+    return token ? { url, token } : null;
+  } catch {
+    return null;
+  }
+}
+async function callWhiteboard(method, bodyOrQuery, signal, fetchFn = fetch) {
+  const cloud = await resolveCloud(fetchFn);
+  if (!cloud) {
+    return {
+      ok: false,
+      error: "hq_whiteboard_not_configured",
+      message: "Set VO_CONTROL_PLANE_URL and run vo-mcp login to install a scoped HQ credential."
+    };
+  }
+  const timeoutSignal = AbortSignal.timeout(resolveTimeoutMs());
+  const requestSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+  const query = new URLSearchParams();
+  if (method === "GET") {
+    const input = bodyOrQuery;
+    query.set("limit", String(input.limit ?? 25));
+    if (input.since) query.set("since", input.since);
+    if (input.type) query.set("type", input.type);
+  }
+  try {
+    const response = await fetchFn(
+      `${cloud.url}/api/v1/hq/whiteboard/messages${query.size ? `?${query}` : ""}`,
+      {
+        method,
+        headers: {
+          Authorization: `Bearer ${cloud.token}`,
+          ...method === "POST" ? { "Content-Type": "application/json" } : {}
+        },
+        ...method === "POST" ? { body: JSON.stringify(bodyOrQuery) } : {},
+        signal: requestSignal
+      }
+    );
+    const text = await response.text();
+    let payload;
+    try {
+      payload = JSON.parse(text);
+    } catch {
+      payload = { ok: false, error: "invalid_response", message: text.slice(0, 200) };
+    }
+    if (!response.ok) {
+      return { ok: false, error: "hq_whiteboard_http_error", status: response.status, response: payload };
+    }
+    return payload;
+  } catch (error) {
+    return {
+      ok: false,
+      error: signal?.aborted ? "cancelled" : timeoutSignal.aborted ? "hq_whiteboard_timeout" : "hq_whiteboard_unreachable",
+      message: error instanceof Error ? error.message.slice(0, 200) : String(error).slice(0, 200)
+    };
+  }
+}
+async function handleHqWhiteboardPost(_deps, rawInput, signal) {
+  const input = parsePostInput(rawInput);
+  if (!input) throw invalidParams(POST_TOOL_NAME, "requires from, type, and 1-500 character content; unknown fields are rejected");
+  return jsonContent(await callWhiteboard("POST", input, signal));
+}
+async function handleHqWhiteboardRead(_deps, rawInput, signal) {
+  const input = parseReadInput(rawInput);
+  if (!input) throw invalidParams(READ_TOOL_NAME, "limit must be 1-100, since must be ISO-8601, and unknown fields are rejected");
+  return jsonContent(await callWhiteboard("GET", input, signal));
+}
+
 // src/server.ts
 function buildToolRegistry() {
   return {
@@ -5786,6 +5929,22 @@ function buildToolRegistry() {
         inputSchema: contextInputSchema
       },
       handler: handlePrivateKnowledgeContext
+    },
+    [POST_TOOL_NAME]: {
+      definition: {
+        name: POST_TOOL_NAME,
+        description: postDescription,
+        inputSchema: postInputSchema
+      },
+      handler: handleHqWhiteboardPost
+    },
+    [READ_TOOL_NAME]: {
+      definition: {
+        name: READ_TOOL_NAME,
+        description: readDescription,
+        inputSchema: readInputSchema
+      },
+      handler: handleHqWhiteboardRead
     }
   };
 }