@heuresis/mcp 1.0.0-rc.15 → 1.0.0-rc.17

package/README.md

@@ -1,189 +1,189 @@
-# @heuresis/mcp
-
-A Model Context Protocol (MCP) server that exposes a Heuresis workspace
-to any MCP-capable client (Claude Desktop, Claude Code, Cursor,
-Windsurf, custom agents). The server logs into the user's Heuresis
-account, talks to the same Supabase project the webapp talks to, and
-respects the same RLS. Webapp and MCP are two front-ends to one cloud
-workspace.
-
-Current version: `1.0.0-rc.13`.
-
-## Install
-
-```bash
-npm install -g @heuresis/mcp
-# or on demand without installing:
-npx -y @heuresis/mcp
-```
-
-> **Package name vs. command name.** The npm package is `@heuresis/mcp`; the
-> command it installs is `heuresis-mcp`. A bare `npx -y @heuresis/mcp` (no
-> subcommand) starts the MCP server fine, but `npx @heuresis/mcp login` can
-> fail with `heuresis-mcp: not found` because npx derives the command name
-> from the scope-stripped package name (`mcp`), which doesn't match. To run a
-> subcommand reliably on every npm/OS, name the binary explicitly with `-p`:
->
-> ```bash
-> npx -y -p @heuresis/mcp heuresis-mcp login
-> ```
-
-## Quickstart
-
-### 1. Link this machine to your Heuresis account
-
-```bash
-npx -y -p @heuresis/mcp heuresis-mcp login
-```
-
-The CLI prints a device code and a one-click URL of the form
-`https://heuresis.app/device?code=XXXX-XXXX`. Open it in your browser,
-sign in if you aren't already, and confirm the device. The CLI polls
-in the background and writes credentials to
-`~/.heuresis/credentials.json` (chmod 600 on POSIX) the moment you
-confirm. Subsequent runs of the MCP are silent.
-
-The login flow rides three Supabase Edge Functions:
-`mcp-device-init`, `mcp-device-grant`, and `mcp-device-poll`.
-
-To unlink a machine: `npx -y -p @heuresis/mcp heuresis-mcp logout`, or open
-Settings ▸ Connected devices in the webapp to revoke remotely.
-
-`npx -y -p @heuresis/mcp heuresis-mcp whoami` confirms which account a machine
-is currently linked to.
-
-### 2. Point your MCP client at it
-
-**Claude Desktop.** Edit
-`~/Library/Application Support/Claude/claude_desktop_config.json` on
-macOS, or `%APPDATA%/Claude/claude_desktop_config.json` on Windows:
-
-```json
-{
-  "mcpServers": {
-    "heuresis": { "command": "npx", "args": ["-y", "@heuresis/mcp"] }
-  }
-}
-```
-
-**Claude Code / Cursor / Windsurf.** Drop a `.mcp.json` in the
-workspace root:
-
-```json
-{
-  "mcpServers": {
-    "heuresis": { "command": "npx", "args": ["-y", "@heuresis/mcp"] }
-  }
-}
-```
-
-Restart the client. The Heuresis tools appear in the tool menu.
-
-### 3. CLI subcommands
-
-```bash
-npx -y -p @heuresis/mcp heuresis-mcp whoami   # show the linked account + device
-npx -y -p @heuresis/mcp heuresis-mcp logout   # delete the credentials file
-npx -y -p @heuresis/mcp heuresis-mcp --help   # all options
-npx -y @heuresis/mcp --no-realtime            # boot the server with live sync off (persisted)
-npx -y @heuresis/mcp --realtime               # re-enable live sync
-```
-
-## Headless mode (CI, cloud agents, disposable containers)
-
-Device pairing writes a **refresh token** to disk. That works great on a
-personal machine, but it does **not** survive disposable/ephemeral
-environments (CI runners, cloud agent containers, "Claude Code on the web"):
-the filesystem is wiped between runs, and a Supabase refresh token is
-**single-use under rotation** — so a token baked into config dies after the
-first session.
-
-For those environments, skip pairing and let the server **sign in fresh on
-every boot** from your account email + password (a password is not consumed on
-use, so it works forever with no re-pairing). Set three env vars:
-
-```bash
-HEURESIS_EMAIL=you@example.com          # your Heuresis account email
-HEURESIS_PASSWORD=your-account-password # secret — store it in a secrets manager
-HEURESIS_ANON_KEY=sb_publishable_...    # project anon/publishable key (public, not a secret)
-# optional: HEURESIS_SUPABASE_URL=...   # defaults to the production project
-```
-
-When `HEURESIS_EMAIL` + `HEURESIS_PASSWORD` are present they take precedence
-over any `credentials.json`, and the MCP server authenticates per boot — no
-device link required. Requirements:
-
-- Email + password sign-in must be enabled for the Supabase project, and the
-  account must have a password set (passwordless / magic-link-only accounts
-  need a password added first).
-- Treat `HEURESIS_PASSWORD` as a secret. Prefer a dedicated account if your
-  environment can only expose env vars that are visible to its users.
-
-## Live sync
-
-When the MCP boots in cloud mode it subscribes to the workspace over
-Supabase Realtime and notifies the client whenever a `nodes`, `edges`,
-`projects`, or `ideas` row changes. Edits made in the webapp show up
-in the agent's view without a manual refresh, and writes from one
-MCP-connected client reach any other connected client the same way.
-Pass `--no-realtime` to disable the subscription (useful if the
-chatter is noisy or the client logs every notification). The
-preference is saved to `~/.heuresis/config.json` so the flag only
-needs to be passed once.
-
-## Tools
-
-34 tools total: 31 data tools against the cloud workspace, plus 3
-operator tools that drive the same ideation operators the webapp uses.
-
-**Reads (10).** `get_workspace_summary`, `list_projects`,
-`get_project_graph`, `list_concepts`, `list_edges`, `get_subtree`,
-`get_concept`, `search_concepts`, `find_concepts`,
-`list_recent_decisions`. Most agent sessions start with
-`get_workspace_summary` or `list_projects`.
-
-**Writes (21).** Concepts: `add_concept`, `update_concept`,
-`bulk_add_concepts`, `set_parent`, `validate_concept`, `set_standing`,
-`archive_concept`, `unarchive_concept`, `star_concept`,
-`remove_concept`. Edges: `link_concepts`, `add_kref`. Ideas:
-`create_idea`, `rename_idea`, `recolor_idea`, `set_idea_members`,
-`add_to_idea`, `delete_idea`. Projects: `create_project`,
-`update_project`, `delete_project`. Every write stamps a row in
-`public.provenance` with `origin='mcp'` so the webapp's session log
-shows which surface made the change.
-
-**Operator runs (3).** `run_operator` (generate candidates with
-Branch / Matrix / ASIT / TRIZ / Combine / Free / Contradiction),
-`run_operator_and_commit` (same, plus commit the result in one
-round-trip), and `expand_concept` (recursive Branch, capped at depth ×
-breadth ≤ 60).
-
-Tool input shapes mirror their counterparts in the webapp's
-`src/agent/tools.ts`, so an agent that uses both surfaces sees a
-uniform contract.
-
-Wave-shipping: `find_in_files` (in-browser embedding search) is in the
-webapp but not yet on the MCP.
-
-## Legacy snapshot mode (deprecated)
-
-The original read-only snapshot reader still works as a fallback while
-users migrate to cloud auth. With no `~/.heuresis/credentials.json`
-and the `HEURESIS_SNAPSHOT` env var set, the server reads a JSON
-export from disk and exposes the original read-only tool set
-(`get_workspace_summary`, `list_projects`, `search_concepts`,
-`get_concept`, `get_subtree`, `get_project_graph`,
-`list_recent_decisions`).
-
-```bash
-export HEURESIS_SNAPSHOT="/absolute/path/to/your-export.json"
-npx @heuresis/mcp
-```
-
-This path is deprecated and will be removed in a later release. It is
-here so existing setups keep working through the migration to cloud
-auth.
-
-## License
-
-AGPL-3.0-or-later.
+# @heuresis/mcp
+
+A Model Context Protocol (MCP) server that exposes a Heuresis workspace
+to any MCP-capable client (Claude Desktop, Claude Code, Cursor,
+Windsurf, custom agents). The server logs into the user's Heuresis
+account, talks to the same Supabase project the webapp talks to, and
+respects the same RLS. Webapp and MCP are two front-ends to one cloud
+workspace.
+
+Current version: `1.0.0-rc.13`.
+
+## Install
+
+```bash
+npm install -g @heuresis/mcp
+# or on demand without installing:
+npx -y @heuresis/mcp
+```
+
+> **Package name vs. command name.** The npm package is `@heuresis/mcp`; the
+> command it installs is `heuresis-mcp`. A bare `npx -y @heuresis/mcp` (no
+> subcommand) starts the MCP server fine, but `npx @heuresis/mcp login` can
+> fail with `heuresis-mcp: not found` because npx derives the command name
+> from the scope-stripped package name (`mcp`), which doesn't match. To run a
+> subcommand reliably on every npm/OS, name the binary explicitly with `-p`:
+>
+> ```bash
+> npx -y -p @heuresis/mcp heuresis-mcp login
+> ```
+
+## Quickstart
+
+### 1. Link this machine to your Heuresis account
+
+```bash
+npx -y -p @heuresis/mcp heuresis-mcp login
+```
+
+The CLI prints a device code and a one-click URL of the form
+`https://heuresis.app/device?code=XXXX-XXXX`. Open it in your browser,
+sign in if you aren't already, and confirm the device. The CLI polls
+in the background and writes credentials to
+`~/.heuresis/credentials.json` (chmod 600 on POSIX) the moment you
+confirm. Subsequent runs of the MCP are silent.
+
+The login flow rides three Supabase Edge Functions:
+`mcp-device-init`, `mcp-device-grant`, and `mcp-device-poll`.
+
+To unlink a machine: `npx -y -p @heuresis/mcp heuresis-mcp logout`, or open
+Settings ▸ Connected devices in the webapp to revoke remotely.
+
+`npx -y -p @heuresis/mcp heuresis-mcp whoami` confirms which account a machine
+is currently linked to.
+
+### 2. Point your MCP client at it
+
+**Claude Desktop.** Edit
+`~/Library/Application Support/Claude/claude_desktop_config.json` on
+macOS, or `%APPDATA%/Claude/claude_desktop_config.json` on Windows:
+
+```json
+{
+  "mcpServers": {
+    "heuresis": { "command": "npx", "args": ["-y", "@heuresis/mcp"] }
+  }
+}
+```
+
+**Claude Code / Cursor / Windsurf.** Drop a `.mcp.json` in the
+workspace root:
+
+```json
+{
+  "mcpServers": {
+    "heuresis": { "command": "npx", "args": ["-y", "@heuresis/mcp"] }
+  }
+}
+```
+
+Restart the client. The Heuresis tools appear in the tool menu.
+
+### 3. CLI subcommands
+
+```bash
+npx -y -p @heuresis/mcp heuresis-mcp whoami   # show the linked account + device
+npx -y -p @heuresis/mcp heuresis-mcp logout   # delete the credentials file
+npx -y -p @heuresis/mcp heuresis-mcp --help   # all options
+npx -y @heuresis/mcp --no-realtime            # boot the server with live sync off (persisted)
+npx -y @heuresis/mcp --realtime               # re-enable live sync
+```
+
+## Headless mode (CI, cloud agents, disposable containers)
+
+Device pairing writes a **refresh token** to disk. That works great on a
+personal machine, but it does **not** survive disposable/ephemeral
+environments (CI runners, cloud agent containers, "Claude Code on the web"):
+the filesystem is wiped between runs, and a Supabase refresh token is
+**single-use under rotation** — so a token baked into config dies after the
+first session.
+
+For those environments, skip pairing and let the server **sign in fresh on
+every boot** from your account email + password (a password is not consumed on
+use, so it works forever with no re-pairing). Set three env vars:
+
+```bash
+HEURESIS_EMAIL=you@example.com          # your Heuresis account email
+HEURESIS_PASSWORD=your-account-password # secret — store it in a secrets manager
+HEURESIS_ANON_KEY=sb_publishable_...    # project anon/publishable key (public, not a secret)
+# optional: HEURESIS_SUPABASE_URL=...   # defaults to the production project
+```
+
+When `HEURESIS_EMAIL` + `HEURESIS_PASSWORD` are present they take precedence
+over any `credentials.json`, and the MCP server authenticates per boot — no
+device link required. Requirements:
+
+- Email + password sign-in must be enabled for the Supabase project, and the
+  account must have a password set (passwordless / magic-link-only accounts
+  need a password added first).
+- Treat `HEURESIS_PASSWORD` as a secret. Prefer a dedicated account if your
+  environment can only expose env vars that are visible to its users.
+
+## Live sync
+
+When the MCP boots in cloud mode it subscribes to the workspace over
+Supabase Realtime and notifies the client whenever a `nodes`, `edges`,
+`projects`, or `ideas` row changes. Edits made in the webapp show up
+in the agent's view without a manual refresh, and writes from one
+MCP-connected client reach any other connected client the same way.
+Pass `--no-realtime` to disable the subscription (useful if the
+chatter is noisy or the client logs every notification). The
+preference is saved to `~/.heuresis/config.json` so the flag only
+needs to be passed once.
+
+## Tools
+
+34 tools total: 31 data tools against the cloud workspace, plus 3
+operator tools that drive the same ideation operators the webapp uses.
+
+**Reads (10).** `get_workspace_summary`, `list_projects`,
+`get_project_graph`, `list_concepts`, `list_edges`, `get_subtree`,
+`get_concept`, `search_concepts`, `find_concepts`,
+`list_recent_decisions`. Most agent sessions start with
+`get_workspace_summary` or `list_projects`.
+
+**Writes (21).** Concepts: `add_concept`, `update_concept`,
+`bulk_add_concepts`, `set_parent`, `validate_concept`, `set_standing`,
+`archive_concept`, `unarchive_concept`, `star_concept`,
+`remove_concept`. Edges: `link_concepts`, `add_kref`. Ideas:
+`create_idea`, `rename_idea`, `recolor_idea`, `set_idea_members`,
+`add_to_idea`, `delete_idea`. Projects: `create_project`,
+`update_project`, `delete_project`. Every write stamps a row in
+`public.provenance` with `origin='mcp'` so the webapp's session log
+shows which surface made the change.
+
+**Operator runs (3).** `run_operator` (generate candidates with
+Branch / Matrix / ASIT / TRIZ / Combine / Free / Contradiction),
+`run_operator_and_commit` (same, plus commit the result in one
+round-trip), and `expand_concept` (recursive Branch, capped at depth ×
+breadth ≤ 60).
+
+Tool input shapes mirror their counterparts in the webapp's
+`src/agent/tools.ts`, so an agent that uses both surfaces sees a
+uniform contract.
+
+Wave-shipping: `find_in_files` (in-browser embedding search) is in the
+webapp but not yet on the MCP.
+
+## Legacy snapshot mode (deprecated)
+
+The original read-only snapshot reader still works as a fallback while
+users migrate to cloud auth. With no `~/.heuresis/credentials.json`
+and the `HEURESIS_SNAPSHOT` env var set, the server reads a JSON
+export from disk and exposes the original read-only tool set
+(`get_workspace_summary`, `list_projects`, `search_concepts`,
+`get_concept`, `get_subtree`, `get_project_graph`,
+`list_recent_decisions`).
+
+```bash
+export HEURESIS_SNAPSHOT="/absolute/path/to/your-export.json"
+npx @heuresis/mcp
+```
+
+This path is deprecated and will be removed in a later release. It is
+here so existing setups keep working through the migration to cloud
+auth.
+
+## License
+
+AGPL-3.0-or-later.

package/dist/cloudOperators.js

@@ -28,6 +28,7 @@
 // Cost preview — every run_operator response carries an `estimated_cost:
 // { credits, dollars }` chip from the rate card in `docs/credits.md` §2.
 // Informational only; BYO-key runs don't bill against managed credits.
+import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
 import { unwrap } from './cloudClient.js';
 import { ASIT_OPERATORS } from './operators/asit.js';
@@ -205,6 +206,10 @@ export const runOperatorInput = z
         .record(z.unknown())
         .optional()
         .describe("Family-specific extras: { angle?: string } for free/explore/combine, { improving: number, worsening: number } for contradiction, { combineWithIds: string[] } for combine. Optional { provider: 'anthropic' | 'openai' | 'openrouter' | 'google' } overrides the default provider."),
+    force: z
+        .boolean()
+        .optional()
+        .describe('Bypass idempotent reuse and force a fresh run even if an identical run is already in flight or recently finished.'),
 })
     .strict();
 export async function runOperator(client, args) {
@@ -502,28 +507,175 @@ export async function expandConcept(client, args) {
         },
     };
 }
-// ---------------------------------------------------------------------------
-// OPERATOR_TOOLS export — index.ts splices this onto CLOUD_TOOLS and wires
-// each entry's `handler(client, args)` to the lazy auth handshake.
-// ---------------------------------------------------------------------------
+const FAST_PATH_MS = 8_000; // return inline if the run settles this fast
+const REUSE_MS = 10 * 60_000; // idempotent-reuse window for completed runs
+const MAX_RUNS = 200; // cap the in-memory registry
+const MAX_CONCURRENT_OPS = 2; // heavy LLM bodies allowed in flight at once
+const runsById = new Map();
+const runIdByOpKey = new Map();
+let activeOps = 0;
+const opQueue = [];
+function acquireOpSlot() {
+    if (activeOps < MAX_CONCURRENT_OPS) {
+        activeOps += 1;
+        return Promise.resolve();
+    }
+    return new Promise((resolve) => opQueue.push(resolve));
+}
+function releaseOpSlot() {
+    const next = opQueue.shift();
+    if (next)
+        next();
+    else
+        activeOps -= 1;
+}
+function stableKey(v) {
+    if (Array.isArray(v))
+        return v.map(stableKey);
+    if (v && typeof v === 'object') {
+        const o = v;
+        return Object.keys(o)
+            .sort()
+            .reduce((acc, k) => {
+            if (k !== 'force')
+                acc[k] = stableKey(o[k]); // `force` never affects identity
+            return acc;
+        }, {});
+    }
+    return v;
+}
+function makeOpKey(tool, args) {
+    return JSON.stringify([tool, stableKey(args)]);
+}
+function startOperatorRun(tool, args, work, force = false) {
+    const opKey = makeOpKey(tool, args);
+    if (!force) {
+        const prevId = runIdByOpKey.get(opKey);
+        const prev = prevId ? runsById.get(prevId) : undefined;
+        if (prev &&
+            (prev.status === 'running' ||
+                (prev.status === 'done' &&
+                    prev.finishedAt !== undefined &&
+                    Date.now() - prev.finishedAt < REUSE_MS))) {
+            return prev; // idempotent reuse — no duplicate run/commit
+        }
+    }
+    const run = {
+        runId: randomUUID(),
+        opKey,
+        tool,
+        status: 'running',
+        startedAt: Date.now(),
+    };
+    runsById.set(run.runId, run);
+    runIdByOpKey.set(opKey, run.runId);
+    if (runsById.size > MAX_RUNS) {
+        let oldest;
+        for (const r of runsById.values())
+            if (!oldest || r.startedAt < oldest.startedAt)
+                oldest = r;
+        if (oldest) {
+            runsById.delete(oldest.runId);
+            if (runIdByOpKey.get(oldest.opKey) === oldest.runId)
+                runIdByOpKey.delete(oldest.opKey);
+        }
+    }
+    void (async () => {
+        await acquireOpSlot();
+        try {
+            run.result = await work();
+            run.status = 'done';
+        }
+        catch (err) {
+            run.status = 'error';
+            run.error = err instanceof Error ? err.message : String(err);
+        }
+        finally {
+            run.finishedAt = Date.now();
+            releaseOpSlot();
+        }
+    })();
+    return run;
+}
+async function settleWithin(run, ms) {
+    const deadline = Date.now() + ms;
+    while (run.status === 'running' && Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, 200));
+    }
+}
+function runView(run) {
+    if (run.status === 'done')
+        return { runId: run.runId, status: 'done', result: run.result };
+    if (run.status === 'error')
+        return { runId: run.runId, status: 'error', error: run.error };
+    return {
+        runId: run.runId,
+        status: 'running',
+        hint: `Operator still running (a heavy model can take 1-2 min). Call get_run with runId "${run.runId}" — it returns the result the moment status is "done".`,
+    };
+}
+/**
+ * Run an operator asynchronously: start it (or reuse an identical in-flight /
+ * recent run), return inline if it settles within FAST_PATH_MS, otherwise hand
+ * back a runId for the agent to poll via get_run.
+ */
+async function runAsync(tool, args, work) {
+    const force = Boolean(args?.force);
+    const run = startOperatorRun(tool, args, work, force);
+    await settleWithin(run, FAST_PATH_MS);
+    return runView(run);
+}
+export const getRunInput = z
+    .object({
+    runId: z
+        .string()
+        .min(1)
+        .describe('The runId returned by run_operator / run_operator_and_commit / expand_concept.'),
+})
+    .strict();
 export const OPERATOR_TOOLS = [
     {
         name: 'run_operator',
         description: "Run an ASIT / TRIZ / Contradiction / Free / Combine / Explore operator against one concept (the anchor). Returns CANDIDATE concepts WITHOUT committing them — call `bulk_add_concepts` (or `run_operator_and_commit`) to persist. Use this when you want the agent to vet the candidates before writing. The anchor must already live in a project; the operator pulls in ancestry + validated knowledge in the same project to ground the prompt.",
         inputSchema: runOperatorInput,
-        handler: async (client, raw) => runOperator(client, runOperatorInput.parse(raw)),
+        handler: async (client, raw) => {
+            const args = runOperatorInput.parse(raw);
+            return runAsync('run_operator', args, () => runOperator(client, args));
+        },
     },
     {
         name: 'run_operator_and_commit',
         description: "Same as `run_operator`, but immediately writes every top-level candidate as a child of the anchor with a partition edge and a provenance row stamped origin='mcp'. Use when the agent is confident the candidates should land directly on the canvas (e.g. inside an autonomous expand loop). Children-of-children proposed in `partitions[].children` are NOT auto-committed — request them via a separate run.",
         inputSchema: runOperatorAndCommitInput,
-        handler: async (client, raw) => runOperatorAndCommit(client, runOperatorAndCommitInput.parse(raw)),
+        handler: async (client, raw) => {
+            const args = runOperatorAndCommitInput.parse(raw);
+            return runAsync('run_operator_and_commit', args, () => runOperatorAndCommit(client, args));
+        },
     },
     {
         name: 'expand_concept',
         description: 'Recursive Branch — expand a concept by `breadth` children at each of `depth` levels (depth*breadth ≤ 60). Commits each level immediately so the webapp shows partial results as the run progresses. Optionally takes an `angle` hint that biases the underlying EXPLORE operator. Best when the anchor has few or no children yet; on a dense subtree consider `run_operator(family="explore")` so the operator can read existing children and propose complementary partitions.',
         inputSchema: expandConceptInput,
-        handler: async (client, raw) => expandConcept(client, expandConceptInput.parse(raw)),
+        handler: async (client, raw) => {
+            const args = expandConceptInput.parse(raw);
+            return runAsync('expand_concept', args, () => expandConcept(client, args));
+        },
+    },
+    {
+        name: 'get_run',
+        description: 'Fetch an async operator run by its runId. Returns { status: "running" | "done" | "error" }; when "done", the `result` field holds the operator output (candidates / committedIds). Waits up to ~8s for completion before returning, so a simple poll loop converges fast. run_operator / run_operator_and_commit / expand_concept hand back a runId whenever their work exceeds the ~8s fast-path window.',
+        inputSchema: getRunInput,
+        handler: async (_client, raw) => {
+            const { runId } = getRunInput.parse(raw);
+            const run = runsById.get(runId);
+            if (!run) {
+                return {
+                    error: `No run with id ${runId}. Operator runs are kept in memory for the session; it may have been evicted (200-run cap) or the server restarted.`,
+                };
+            }
+            await settleWithin(run, FAST_PATH_MS);
+            return runView(run);
+        },
     },
 ];
 // Re-exports kept narrow on purpose: index.ts only needs `makeOperatorTools`,

package/dist/cloudTools.js

@@ -188,11 +188,25 @@ function shapeProject(p) {
 // ---------------------------------------------------------------------------
 export const getSubtreeInput = z
     .object({
-    rootId: z.string(),
+    rootId: z.string().min(1).optional(),
+    id: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Alias for rootId — the concept to root the subtree at (use either).'),
     depth: z.number().int().min(0).max(6).default(3),
     detail: detailArg,
 })
-    .strict();
+    .strict()
+    .refine((a) => Boolean(a.rootId ?? a.id), {
+    message: 'Provide `id` (or `rootId`) — the concept to get the subtree for.',
+    path: ['id'],
+})
+    .transform((a) => ({
+    rootId: (a.rootId ?? a.id),
+    depth: a.depth,
+    detail: a.detail,
+}));
 export async function getSubtree(client, args) {
     const rootRes = await client.from('nodes').select('*').eq('id', args.rootId).maybeSingle();
     if (rootRes.error)
@@ -1554,7 +1568,9 @@ export const CLOUD_TOOLS = [
     },
     {
         name: 'get_subtree',
-        description: 'A node and its descendants up to a given depth. Use when the user asks "tell me about everything under X".',
+        description: 'A node and its descendants up to a given depth. Pass the concept as `id` (or `rootId`). Use when the user asks "tell me about everything under X".',
+        // ZodEffects (refine+transform for the id/rootId alias) — cast like the
+        // operator tools; zodToJsonSchema unwraps it for the served schema.
         inputSchema: getSubtreeInput,
         handler: async (client, args) => getSubtree(client, getSubtreeInput.parse(args)),
     },

package/dist/index.js

@@ -14,7 +14,7 @@
 //
 // Subcommands (one-shot, never start the MCP server):
 //   login | logout | whoami | --help
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
@@ -27,8 +27,87 @@ import { CloudAuthError, getCloudClient, getCloudClientFromPassword } from './cl
 import { ensureProxyAgent } from './proxy.js';
 import { DEFAULT_SUPABASE_URL, helpCommand, loginCommand, logoutCommand, whoamiCommand, } from './cli.js';
 import { readRealtimeFlag, resolveSubscriptionWorkspaceId, startRealtimeSubscription, stripRealtimeFlags, } from './realtime.js';
-const VERSION = '0.2.0-alpha';
+// Report the real published version (dist/index.js → ../package.json) so
+// `heuresis-mcp --version` and the startup banner never lie about what's loaded.
+const VERSION = (() => {
+    try {
+        const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+        return pkg.version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+})();
 const MAX_RESULT_CHARS = 50_000;
+// Fields worth preserving when a node/edge-bearing result is degraded to fit
+// the size cap (everything else — descriptions, rationale, tags — is dropped).
+const SKELETON_KEYS = [
+    'id',
+    'label',
+    'name',
+    'parentId',
+    'parent_id',
+    'kind',
+    'from',
+    'to',
+    'status',
+    'standing',
+    'starred',
+    'projectId',
+    'rootNodeId',
+];
+function skeletonize(item) {
+    if (item && typeof item === 'object' && !Array.isArray(item)) {
+        const o = item;
+        const keep = {};
+        for (const k of SKELETON_KEYS)
+            if (k in o)
+                keep[k] = o[k];
+        return Object.keys(keep).length > 0 ? keep : item;
+    }
+    return item;
+}
+// Never hard-fail a read on size. If a result blows the cap, first drop verbose
+// fields from its array elements (keep id/label/parent/kind…), then, if still
+// too big, slice the largest array — always tagging `_truncated` + `_note` so
+// the agent knows to narrow (limit/depth/scope) or fetch detail via get_concept.
+function fitResultToCap(result, cap) {
+    if (JSON.stringify(result, null, 2).length <= cap)
+        return result;
+    if (!result || typeof result !== 'object' || Array.isArray(result)) {
+        const s = JSON.stringify(result, null, 2);
+        return {
+            _truncated: true,
+            _note: `Result exceeded ${cap} chars and could not be structurally reduced; showing a prefix. Narrow the query.`,
+            preview: s.slice(0, Math.max(0, cap - 200)),
+        };
+    }
+    const obj = { ...result };
+    const arrayKeys = Object.keys(obj).filter((k) => Array.isArray(obj[k]) && obj[k].some((x) => x && typeof x === 'object'));
+    for (const k of arrayKeys)
+        obj[k] = obj[k].map(skeletonize);
+    obj._truncated = true;
+    obj._note =
+        'Result exceeded the size cap; verbose fields were dropped (id/label/parent/kind kept). Use get_concept(id) for full detail, or narrow with limit/depth/scope.';
+    let guard = 0;
+    while (JSON.stringify(obj, null, 2).length > cap && guard++ < 100) {
+        let biggestKey;
+        let biggestLen = 0;
+        for (const k of arrayKeys) {
+            const len = obj[k].length;
+            if (len > biggestLen) {
+                biggestLen = len;
+                biggestKey = k;
+            }
+        }
+        if (!biggestKey || biggestLen <= 1)
+            break;
+        const arr = obj[biggestKey];
+        obj[biggestKey] = arr.slice(0, Math.max(1, Math.floor(arr.length * 0.8)));
+        obj._note = `Result exceeded the size cap; showing a truncated, skeletonized view (some "${biggestKey}" omitted). Narrow with limit/depth/scope, or fetch specifics with get_concept.`;
+    }
+    return obj;
+}
 function makeCloudTools(getClient, operatorTools) {
     // Lazy: defer the actual auth handshake until the first tool call so the
     // MCP server boots fast.
@@ -209,21 +288,6 @@ async function runServer() {
             inputSchema: zodToJsonSchema(t.inputSchema),
         })),
     }));
-    // The heavy operator/LLM tools are serialized: several fired in parallel
-    // overwhelm the backend and trip the 60s timeout (observed: parallel
-    // expand_concept runs timing out). Read/write tools still run concurrently.
-    const OPERATOR_TOOLS = new Set([
-        'run_operator',
-        'run_operator_and_commit',
-        'expand_concept',
-    ]);
-    let operatorChain = Promise.resolve();
-    const runExclusive = (fn) => {
-        const result = operatorChain.then(fn, fn);
-        // Keep the chain alive regardless of this call's outcome.
-        operatorChain = result.then(() => undefined, () => undefined);
-        return result;
-    };
     server.setRequestHandler(CallToolRequestSchema, async (req, extra) => {
         const tool = tools.find((t) => t.name === req.params.name);
         if (!tool) {
@@ -263,24 +327,14 @@ async function runServer() {
             }, 15_000);
         }
         try {
-            const invoke = () => tool.handler(req.params.arguments ?? {});
-            const result = OPERATOR_TOOLS.has(tool.name)
-                ? await runExclusive(invoke)
-                : await invoke();
-            const text = JSON.stringify(result, null, 2);
-            if (text.length > MAX_RESULT_CHARS) {
-                return {
-                    isError: true,
-                    content: [
-                        {
-                            type: 'text',
-                            text: `Result too large (${text.length} chars, limit ${MAX_RESULT_CHARS}). ` +
-                                `Narrow the query: lower 'limit'/'depth', keep detail='compact', ` +
-                                `or fetch individual nodes with get_concept.`,
-                        },
-                    ],
-                };
-            }
+            // Operator tools are async now: they return a runId fast and run in the
+            // background with their own concurrency control (cloudOperators.ts), so no
+            // per-call serialization is needed here.
+            const result = await tool.handler(req.params.arguments ?? {});
+            // Never hard-fail on size: auto-degrade node/edge-bearing results
+            // (skeletonize → slice) so the agent always gets actionable structure
+            // back instead of an error it has to recover from.
+            const text = JSON.stringify(fitResultToCap(result, MAX_RESULT_CHARS), null, 2);
             return {
                 content: [{ type: 'text', text }],
             };
@@ -373,6 +427,11 @@ async function main() {
         case 'whoami':
             await whoamiCommand();
             return;
+        case '-v':
+        case '--version':
+        case 'version':
+            console.log(VERSION);
+            return;
         case '-h':
         case '--help':
         case 'help':

package/dist/prompt/compose.js

@@ -8,31 +8,31 @@
 // target, knowledge pool, operator, plus the operator-specific inputs block.
 // File-context retrieval is a separate tool (find_in_files) that ships in
 // Agent B's tool-parity wave; not folded in here.
-const RESPONSE_TEMPLATE = `{
-  "partitions": [
-    {
-      "label": "STANDALONE concept title — 2–5 words, ≤ 60 chars, NO parent prefix, no trailing period",
-      "description": "1–2 sentences, ≤ 280 chars",
-      "partitionAttribute": "≤ 5 words for the distinguishing attribute",
-      "rationale": "1–3 sentences citing the operator and any K used",
-      "kReferences": ["k_id_or_empty"],
-      "selfCritique": "main weakness or assumption",
-      "children": [
-        {
-          "label": "STANDALONE sub-concept title — same rules; do NOT prefix with this partition's label either",
-          "description": "1–2 sentences, ≤ 280 chars",
-          "partitionAttribute": "≤ 5 words",
-          "rationale": "1–3 sentences",
-          "kReferences": [],
-          "selfCritique": "main weakness or assumption"
-        }
-      ]
-    }
-  ],
-  "newKnowledgeProposed": [
-    { "title": "fact title", "body": "1–2 sentences", "tags": ["tag1"] }
-  ],
-  "operatorNotes": "one line on how the operator fit (optional)"
+const RESPONSE_TEMPLATE = `{
+  "partitions": [
+    {
+      "label": "STANDALONE concept title — 2–5 words, ≤ 60 chars, NO parent prefix, no trailing period",
+      "description": "1–2 sentences, ≤ 280 chars",
+      "partitionAttribute": "≤ 5 words for the distinguishing attribute",
+      "rationale": "1–3 sentences citing the operator and any K used",
+      "kReferences": ["k_id_or_empty"],
+      "selfCritique": "main weakness or assumption",
+      "children": [
+        {
+          "label": "STANDALONE sub-concept title — same rules; do NOT prefix with this partition's label either",
+          "description": "1–2 sentences, ≤ 280 chars",
+          "partitionAttribute": "≤ 5 words",
+          "rationale": "1–3 sentences",
+          "kReferences": [],
+          "selfCritique": "main weakness or assumption"
+        }
+      ]
+    }
+  ],
+  "newKnowledgeProposed": [
+    { "title": "fact title", "body": "1–2 sentences", "tags": ["tag1"] }
+  ],
+  "operatorNotes": "one line on how the operator fit (optional)"
 }`;
 function pathBlock(path) {
     return path
@@ -70,11 +70,11 @@ function contradictionBlock(c) {
     const principles = c.principles
         .map((p) => `  - #${p.num} ${p.name}: ${p.doctrine}`)
         .join('\n');
-    return `<contradiction>
-  improving: ${c.improvingName}
-  worsening: ${c.worseningName}
-  matrix_principles:
-${principles}
+    return `<contradiction>
+  improving: ${c.improvingName}
+  worsening: ${c.worseningName}
+  matrix_principles:
+${principles}
 </contradiction>`;
 }
 export function composePrompt(input) {
@@ -92,50 +92,50 @@ export function composePrompt(input) {
     const contradictionXml = operator.family === 'CONTRADICTION' && contradiction
         ? `\n${contradictionBlock(contradiction)}\n`
         : '';
-    return `You are assisting an inventive design session structured by C-K theory. The user is growing a graph of concepts (C) drawing on a pool of validated knowledge (K). You will generate a set of new partitions of the TARGET concept by applying the requested operator from ASIT/TRIZ.
-
-<brief>
-${project.brief}
-</brief>
-
-<concept_path_root_to_target>
-${pathBlock(ancestry)}
-</concept_path_root_to_target>
-
-<target_concept>
-id: ${target.id}
-label: ${target.label}
-description: ${target.description || '(no description)'}
-notes: ${target.notes || '(none)'}
-</target_concept>
-
-<knowledge_pool>
-${knowledgeBlock(knowledge)}
-</knowledge_pool>
-
-<operator>
-family: ${operator.family}
-key: ${operator.key}
-name: ${operator.name}
-doctrine: ${operator.doctrine}
-</operator>
-${inputsXml}${branchXml}${contradictionXml}${angleBlock}
-<instructions>
-${operator.promptFragment}
-
-Rules:
-- Produce 3–5 partitions at the top level, each genuinely distinct, each adding a clear new attribute to the TARGET concept. (The optional \`children\` array below adds depth-2 nodes; it does NOT count toward the 3–5 top-level requirement.)
-- Labels MUST be STANDALONE concept titles. Do NOT prefix labels with the parent concept's label. For example, if the parent is "Test", do NOT write labels like "Test by destruction" or "Test for X" — just write "Destruction" or "X". The label should make sense on its own; the parent context is implicit from the graph structure. This rule applies to EVERY label in the response, including children (a child's label must not contain its immediate parent partition's label either).
-- Labels MUST be short: 2–5 words, ≤ 60 characters, no trailing punctuation. The label is a concept title, not a sentence. Put long-form prose in description/rationale, not in label.
-- Each partition MAY optionally include a \`children\` array of 1–4 sub-partitions, when the partition naturally decomposes further into a clearly distinct sub-axis. Children follow the same shape (label, description, partitionAttribute, rationale, kReferences, selfCritique). Do NOT nest beyond one level — a child must NEVER have its own \`children\` array. Omit \`children\` entirely when no useful sub-decomposition exists; do not pad.
-- Stay faithful to the operator's doctrine. If the operator forbids alien components (ASIT closed-world), do not introduce them.
-- For each partition, cite by id any knowledge item from <knowledge_pool> you actually used in kReferences. Empty array if none.
-- Use selfCritique to surface the strongest assumption or risk in that partition (do not flatter the idea).
-- If you needed a fact you did not have, propose it via newKnowledgeProposed (1–3 items max). Do NOT invent specific numbers as facts; phrase as questions to verify.
-- Output ONLY a single JSON object, matching this shape exactly. No prose before or after, no markdown fences.
-</instructions>
-
-<response_shape>
-${RESPONSE_TEMPLATE}
+    return `You are assisting an inventive design session structured by C-K theory. The user is growing a graph of concepts (C) drawing on a pool of validated knowledge (K). You will generate a set of new partitions of the TARGET concept by applying the requested operator from ASIT/TRIZ.
+
+<brief>
+${project.brief}
+</brief>
+
+<concept_path_root_to_target>
+${pathBlock(ancestry)}
+</concept_path_root_to_target>
+
+<target_concept>
+id: ${target.id}
+label: ${target.label}
+description: ${target.description || '(no description)'}
+notes: ${target.notes || '(none)'}
+</target_concept>
+
+<knowledge_pool>
+${knowledgeBlock(knowledge)}
+</knowledge_pool>
+
+<operator>
+family: ${operator.family}
+key: ${operator.key}
+name: ${operator.name}
+doctrine: ${operator.doctrine}
+</operator>
+${inputsXml}${branchXml}${contradictionXml}${angleBlock}
+<instructions>
+${operator.promptFragment}
+
+Rules:
+- Produce 3–5 partitions at the top level, each genuinely distinct, each adding a clear new attribute to the TARGET concept. (The optional \`children\` array below adds depth-2 nodes; it does NOT count toward the 3–5 top-level requirement.)
+- Labels MUST be STANDALONE concept titles. Do NOT prefix labels with the parent concept's label. For example, if the parent is "Test", do NOT write labels like "Test by destruction" or "Test for X" — just write "Destruction" or "X". The label should make sense on its own; the parent context is implicit from the graph structure. This rule applies to EVERY label in the response, including children (a child's label must not contain its immediate parent partition's label either).
+- Labels MUST be short: 2–5 words, ≤ 60 characters, no trailing punctuation. The label is a concept title, not a sentence. Put long-form prose in description/rationale, not in label.
+- Each partition MAY optionally include a \`children\` array of 1–4 sub-partitions, when the partition naturally decomposes further into a clearly distinct sub-axis. Children follow the same shape (label, description, partitionAttribute, rationale, kReferences, selfCritique). Do NOT nest beyond one level — a child must NEVER have its own \`children\` array. Omit \`children\` entirely when no useful sub-decomposition exists; do not pad.
+- Stay faithful to the operator's doctrine. If the operator forbids alien components (ASIT closed-world), do not introduce them.
+- For each partition, cite by id any knowledge item from <knowledge_pool> you actually used in kReferences. Empty array if none.
+- Use selfCritique to surface the strongest assumption or risk in that partition (do not flatter the idea).
+- If you needed a fact you did not have, propose it via newKnowledgeProposed (1–3 items max). Do NOT invent specific numbers as facts; phrase as questions to verify.
+- Output ONLY a single JSON object, matching this shape exactly. No prose before or after, no markdown fences.
+</instructions>
+
+<response_shape>
+${RESPONSE_TEMPLATE}
 </response_shape>`;
 }

package/package.json

@@ -1,58 +1,58 @@
-{
-  "name": "@heuresis/mcp",
-  "version": "1.0.0-rc.15",
-  "mcpName": "io.github.ToremLabs/heuresis",
-  "description": "Cloud-authenticated Model Context Protocol server for a Heuresis workspace. Logs into the user's Heuresis account and lets any MCP client (Claude Desktop, Claude Code, Cursor, custom agents) read and write the same workspace the webapp uses. 31 data tools, 3 operator tools (Branch/Matrix/C-K/ASIT/TRIZ/Free/Combine/Explore), and live Realtime change subscriptions.",
-  "type": "module",
-  "bin": {
-    "heuresis-mcp": "dist/index.js"
-  },
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "start": "node dist/index.js",
-    "dev": "tsc --watch",
-    "prepublishOnly": "npm run build"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "homepage": "https://heuresis.app/mcp",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/ToremLabs/Heuresis.git",
-    "directory": "mcp-server"
-  },
-  "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "heuresis",
-    "ideation",
-    "knowledge-graph",
-    "claude-code",
-    "claude-desktop",
-    "cursor"
-  ],
-  "dependencies": {
-    "@anthropic-ai/sdk": "^0.40.0",
-    "@google/generative-ai": "^0.21.0",
-    "@modelcontextprotocol/sdk": "^1.0.0",
-    "@supabase/supabase-js": "^2.45.0",
-    "openai": "^4.71.0",
-    "undici": "^6.25.0",
-    "ws": "^8.18.0",
-    "zod": "^3.23.0"
-  },
-  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "@types/ws": "^8.5.13",
-    "typescript": "^5.6.0"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "license": "AGPL-3.0-or-later"
-}
+{
+  "name": "@heuresis/mcp",
+  "version": "1.0.0-rc.17",
+  "mcpName": "io.github.ToremLabs/heuresis",
+  "description": "Cloud-authenticated Model Context Protocol server for a Heuresis workspace. Logs into the user's Heuresis account and lets any MCP client (Claude Desktop, Claude Code, Cursor, custom agents) read and write the same workspace the webapp uses. 31 data tools, 3 operator tools (Branch/Matrix/C-K/ASIT/TRIZ/Free/Combine/Explore), and live Realtime change subscriptions.",
+  "type": "module",
+  "bin": {
+    "heuresis-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://heuresis.app/mcp",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ToremLabs/Heuresis.git",
+    "directory": "mcp-server"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "heuresis",
+    "ideation",
+    "knowledge-graph",
+    "claude-code",
+    "claude-desktop",
+    "cursor"
+  ],
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.40.0",
+    "@google/generative-ai": "^0.21.0",
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@supabase/supabase-js": "^2.45.0",
+    "openai": "^4.71.0",
+    "undici": "^6.25.0",
+    "ws": "^8.18.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.5.13",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "AGPL-3.0-or-later"
+}