@heuresis/mcp 1.0.0-rc.11 → 1.0.0-rc.13

package/README.md

@@ -1,159 +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.11`.
-
-## 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
-```
-
-## 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/cli.js

@@ -23,6 +23,8 @@
 //
 // The webapp `/device` page calls a third Edge Function `mcp-device-grant`
 // to attach the user's identity to the pending grant row.
+// Polyfill global WebSocket on Node < 22 before any Supabase client is built.
+import './wsPolyfill.js';
 import { createInterface } from 'node:readline/promises';
 import { stdin as input, stdout as output } from 'node:process';
 import { credentialsPath, defaultDeviceName, deleteCredentials, readCredentials, writeCredentials, } from './credentials.js';
@@ -33,7 +35,7 @@ import { ensureProxyAgent } from './proxy.js';
 // allow HEURESIS_SUPABASE_URL to override which Supabase project the CLI
 // talks to (e.g. a staging instance). Both default to production.
 const DEFAULT_DEVICE_BASE_URL = 'https://heuresis.app';
-const DEFAULT_SUPABASE_URL = 'https://wpgniquyuppljeqkedqh.supabase.co';
+export const DEFAULT_SUPABASE_URL = 'https://wpgniquyuppljeqkedqh.supabase.co';
 const POLL_INTERVAL_MS = 5_000;
 const POLL_TIMEOUT_MS = 15 * 60 * 1_000;
 function log(...args) {

package/dist/cloudClient.js

@@ -16,8 +16,10 @@
 //      process runs. We don't have to do anything per-tool-call.
 //   3. If the refresh fails (revoked, expired), the bootstrap throws — the
 //      wrapper surfaces a "re-run login" message.
+// Polyfill global WebSocket on Node < 22 before any Supabase client is built.
+import './wsPolyfill.js';
 import { createClient } from '@supabase/supabase-js';
-import { exchangeRefreshToken } from './gotrue.js';
+import { exchangeRefreshToken, signInWithPassword } from './gotrue.js';
 let cached = null;
 export class CloudAuthError extends Error {
     constructor(msg) {
@@ -26,14 +28,12 @@ export class CloudAuthError extends Error {
     }
 }
 /**
- * Build (or return cached) a Supabase client bound to the credentials on
- * disk. Throws CloudAuthError if no credentials exist or if the refresh
- * token has been revoked.
+ * Create a headless Supabase client and seed it with an already-obtained
+ * GoTrue session, so every subsequent PostgREST call carries the user's JWT
+ * and supabase-js keeps the in-memory access token alive. Caches the result.
  */
-export async function getCloudClient(creds) {
-    if (cached)
-        return cached;
-    const client = createClient(creds.supabase_url, creds.anon_key, {
+async function seedClient(supabaseUrl, anonKey, session, userId) {
+    const client = createClient(supabaseUrl, anonKey, {
         auth: {
             // Headless: no localStorage, no URL detection, no auto-refresh
             // listeners writing to disk. The library still auto-refreshes the
@@ -43,28 +43,58 @@ export async function getCloudClient(creds) {
             detectSessionInUrl: false,
         },
     });
-    // Bootstrap the session: exchange the stored refresh token for a fresh
-    // session directly against GoTrue, then seed supabase-js with the REAL
-    // tokens so every subsequent PostgREST call carries the user's JWT and
-    // auto-refresh keeps it alive.
+    const { error } = await client.auth.setSession({
+        access_token: session.access_token,
+        refresh_token: session.refresh_token,
+    });
+    if (error) {
+        throw new CloudAuthError(`Failed to seed Heuresis session: ${error.message}.`);
+    }
+    cached = { client, userId };
+    return cached;
+}
+/**
+ * Build (or return cached) a Supabase client bound to the credentials on
+ * disk. Bootstraps by exchanging the stored (rotating) refresh token. Throws
+ * CloudAuthError if the refresh token has been revoked/rotated away.
+ *
+ * NOTE: a stored refresh token is single-use under Supabase rotation, so this
+ * path is unsuitable for ephemeral environments that reuse the same persisted
+ * credential across boots — use getCloudClientFromPassword() for those.
+ */
+export async function getCloudClient(creds) {
+    if (cached)
+        return cached;
     try {
         const session = await exchangeRefreshToken(creds.supabase_url, creds.anon_key, creds.refresh_token);
-        const { error } = await client.auth.setSession({
-            access_token: session.access_token,
-            refresh_token: session.refresh_token,
-        });
-        if (error) {
-            throw new CloudAuthError(`Failed to seed Heuresis session: ${error.message}. ` +
-                'Run `npx -y -p @heuresis/mcp heuresis-mcp login` to re-authenticate.');
-        }
+        return await seedClient(creds.supabase_url, creds.anon_key, session, creds.user_id);
     }
     catch (err) {
         if (err instanceof CloudAuthError)
             throw err;
         throw new CloudAuthError(`Failed to refresh Heuresis session: ${err instanceof Error ? err.message : String(err)}. Run \`npx -y -p @heuresis/mcp heuresis-mcp login\` to re-authenticate.`);
     }
-    cached = { client, userId: creds.user_id };
-    return cached;
+}
+/**
+ * Build (or return cached) a Supabase client by signing in fresh with an
+ * email + password. Because a password is not consumed on use, this works
+ * durably across disposable/ephemeral sessions that re-authenticate on every
+ * boot — no persisted, rotating refresh token required. Throws CloudAuthError
+ * on bad credentials or if password sign-in is disabled for the project.
+ */
+export async function getCloudClientFromPassword(supabaseUrl, anonKey, email, password) {
+    if (cached)
+        return cached;
+    try {
+        const session = await signInWithPassword(supabaseUrl, anonKey, email, password);
+        const userId = session.user?.id ?? '(unknown)';
+        return await seedClient(supabaseUrl, anonKey, session, userId);
+    }
+    catch (err) {
+        if (err instanceof CloudAuthError)
+            throw err;
+        throw new CloudAuthError(`Headless email/password sign-in failed: ${err instanceof Error ? err.message : String(err)}. Check HEURESIS_EMAIL / HEURESIS_PASSWORD / HEURESIS_ANON_KEY.`);
+    }
 }
 /** Clear the cached client. Used after logout. */
 export function resetCloudClient() {

package/dist/gotrue.js

@@ -82,3 +82,60 @@ export async function exchangeRefreshToken(supabaseUrl, anonKey, refreshToken) {
     }
     return session;
 }
+/**
+ * Sign in with an email + password directly against the GoTrue token endpoint:
+ *
+ *   POST `${supabaseUrl}/auth/v1/token?grant_type=password`
+ *   headers: { apikey, Authorization: Bearer <anon>, Content-Type: application/json }
+ *   body:    { email, password }
+ *
+ * Unlike a refresh token, a password is NOT consumed on use, so this is the
+ * right primitive for headless, ephemeral environments (e.g. cloud agent
+ * containers) that re-authenticate from scratch on every boot. Returns the
+ * full session (access_token + refresh_token + user). Throws
+ * `RefreshTokenError` with an actionable message on any failure.
+ */
+export async function signInWithPassword(supabaseUrl, anonKey, email, password) {
+    if (!email || !password) {
+        throw new RefreshTokenError('Headless sign-in needs both an email and a password (HEURESIS_EMAIL / HEURESIS_PASSWORD).');
+    }
+    const url = `${supabaseUrl.replace(/\/$/, '')}/auth/v1/token?grant_type=password`;
+    let res;
+    try {
+        res = await fetch(url, {
+            method: 'POST',
+            headers: {
+                apikey: anonKey,
+                Authorization: `Bearer ${anonKey}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({ email, password }),
+        });
+    }
+    catch (err) {
+        throw new RefreshTokenError(`Could not reach the auth endpoint at ${url}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    let payload = null;
+    try {
+        payload = await res.json();
+    }
+    catch {
+        /* leave null — handled below */
+    }
+    if (!res.ok) {
+        const err = payload;
+        const detail = err?.error_description ?? err?.msg ?? err?.error ?? err?.message ?? `HTTP ${res.status}`;
+        throw new RefreshTokenError(`Email/password sign-in failed (HTTP ${res.status}): ${detail}. ` +
+            'Check HEURESIS_EMAIL / HEURESIS_PASSWORD, and that email+password sign-in is ' +
+            'enabled for the Supabase project.');
+    }
+    const session = payload;
+    if (!session || !session.access_token || !session.refresh_token) {
+        const keys = session && typeof session === 'object'
+            ? Object.keys(session).join(', ') || '(empty object)'
+            : '(no JSON body)';
+        throw new RefreshTokenError(`Sign-in succeeded (HTTP ${res.status}) but the response is missing ` +
+            `access_token/refresh_token. Response keys: [${keys}].`);
+    }
+    return session;
+}

package/dist/index.js

@@ -23,9 +23,9 @@ import { HeuresisStore } from './store.js';
 import { getConcept as legacyGetConcept, getConceptInput as legacyGetConceptInput, getProjectGraph as legacyGetProjectGraph, getProjectGraphInput as legacyGetProjectGraphInput, getSubtree as legacyGetSubtree, getSubtreeInput as legacyGetSubtreeInput, getWorkspaceSummary as legacyGetWorkspaceSummary, getWorkspaceSummaryInput as legacyGetWorkspaceSummaryInput, listProjects as legacyListProjects, listProjectsInput as legacyListProjectsInput, listRecentDecisions as legacyListRecentDecisions, listRecentDecisionsInput as legacyListRecentDecisionsInput, searchConcepts as legacySearchConcepts, searchConceptsInput as legacySearchConceptsInput, } from './tools.js';
 import { CLOUD_TOOLS } from './cloudTools.js';
 import { readCredentials } from './credentials.js';
-import { CloudAuthError, getCloudClient } from './cloudClient.js';
+import { CloudAuthError, getCloudClient, getCloudClientFromPassword } from './cloudClient.js';
 import { ensureProxyAgent } from './proxy.js';
-import { helpCommand, loginCommand, logoutCommand, whoamiCommand, } from './cli.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';
 const MAX_RESULT_CHARS = 50_000;
@@ -46,6 +46,21 @@ function makeCloudTools(getClient, operatorTools) {
         handler: async (args) => t.handler(await getClient(), args),
     }));
 }
+// Phase 19.5 — try to load LLM-backed Operator tools. The module may be absent
+// or export nothing; in that case we fall back to just the Phase 19.4 parity
+// set. Wrapping the dynamic import in try/catch keeps the server starting
+// cleanly either way.
+async function loadOperatorTools() {
+    try {
+        const mod = (await import('./cloudOperators.js').catch(() => null));
+        if (mod && Array.isArray(mod.OPERATOR_TOOLS))
+            return mod.OPERATOR_TOOLS;
+    }
+    catch {
+        /* fall through to empty */
+    }
+    return [];
+}
 function makeLegacySnapshotTools(store) {
     // LEGACY FALLBACK — removed after 19.7. Read-only, no auth, snapshot file.
     return [
@@ -99,38 +114,59 @@ async function runServer() {
     await ensureProxyAgent(console.error);
     const creds = await readCredentials();
     const snapshotEnv = process.env.HEURESIS_SNAPSHOT;
+    // Headless credential (durable across ephemeral/disposable sessions): when
+    // HEURESIS_EMAIL + HEURESIS_PASSWORD are set, the server signs in fresh on
+    // every boot. Unlike a persisted refresh token — which is single-use under
+    // Supabase rotation and dies after one session — a password is not consumed,
+    // so this survives container resets with zero re-pairing. It takes
+    // precedence over a (possibly stale) credentials.json.
+    const headlessEmail = process.env.HEURESIS_EMAIL?.trim();
+    const headlessPassword = process.env.HEURESIS_PASSWORD;
     let tools;
     let modeBanner;
-    if (creds) {
-        // CLOUD mode.
-        const getClient = async () => {
+    // Single cloud client getter, shared by the tool handlers and the realtime
+    // subscription. null in legacy snapshot / unconfigured modes.
+    let cloudGetClient = null;
+    if (headlessEmail && headlessPassword) {
+        // CLOUD mode — headless email/password sign-in (recommended for cloud /
+        // disposable containers).
+        const supabaseUrl = process.env.HEURESIS_SUPABASE_URL?.trim() || DEFAULT_SUPABASE_URL;
+        const anonKey = process.env.HEURESIS_ANON_KEY?.trim();
+        if (!anonKey) {
+            console.error([
+                '[heuresis-mcp] HEURESIS_EMAIL/HEURESIS_PASSWORD are set but HEURESIS_ANON_KEY is missing.',
+                'Set HEURESIS_ANON_KEY to your project anon/publishable key (it is public, not a secret).',
+            ].join('\n'));
+            process.exit(1);
+        }
+        cloudGetClient = async () => {
             try {
-                const { client } = await getCloudClient(creds);
+                const { client } = await getCloudClientFromPassword(supabaseUrl, anonKey, headlessEmail, headlessPassword);
                 return client;
             }
             catch (err) {
-                if (err instanceof CloudAuthError) {
+                if (err instanceof CloudAuthError)
                     throw new Error(err.message);
-                }
                 throw err;
             }
         };
-        // Phase 19.5 — try to load Operator tools. The module may not exist
-        // yet at build time (Agent A ships it in a parallel pass); if it's
-        // missing OR exports nothing, we fall back to just the Phase 19.4
-        // parity set. Wrapping the dynamic import in try/catch keeps the
-        // server starting cleanly in either case.
-        let operatorTools = [];
-        try {
-            const mod = (await import('./cloudOperators.js').catch(() => null));
-            if (mod && Array.isArray(mod.OPERATOR_TOOLS)) {
-                operatorTools = mod.OPERATOR_TOOLS;
+        tools = makeCloudTools(cloudGetClient, await loadOperatorTools());
+        modeBanner = `cloud-authenticated (headless ${headlessEmail}; ${tools.length} tools)`;
+    }
+    else if (creds) {
+        // CLOUD mode — persisted device credential (refresh-token bootstrap).
+        cloudGetClient = async () => {
+            try {
+                const { client } = await getCloudClient(creds);
+                return client;
             }
-        }
-        catch {
-            operatorTools = [];
-        }
-        tools = makeCloudTools(getClient, operatorTools);
+            catch (err) {
+                if (err instanceof CloudAuthError)
+                    throw new Error(err.message);
+                throw err;
+            }
+        };
+        tools = makeCloudTools(cloudGetClient, await loadOperatorTools());
         modeBanner = `cloud-authenticated (user_id ${creds.user_id}, device ${creds.device_name}; ${tools.length} tools)`;
     }
     else if (snapshotEnv || hasDefaultSnapshot()) {
@@ -144,9 +180,15 @@ async function runServer() {
         console.error([
             '[heuresis-mcp] Not configured.',
             '',
-            'To use cloud mode (recommended):',
+            'To use cloud mode on a personal machine (device pairing):',
             '  npx -y -p @heuresis/mcp heuresis-mcp login',
             '',
+            'To use cloud mode headlessly (CI / cloud agents / disposable containers),',
+            'set these env vars so the server signs in fresh on every boot:',
+            '  HEURESIS_EMAIL      your Heuresis account email',
+            '  HEURESIS_PASSWORD   your Heuresis account password',
+            '  HEURESIS_ANON_KEY   your project anon/publishable key (public, not a secret)',
+            '',
             'To use legacy snapshot mode (deprecated, removed after 19.7):',
             '  HEURESIS_SNAPSHOT=/path/to/export.json npx @heuresis/mcp',
             '',
@@ -210,7 +252,7 @@ async function runServer() {
     console.error(`[heuresis-mcp ${VERSION}] ready - ${modeBanner}`);
     // Phase 19.8 - Supabase Realtime CDC subscription. Cloud mode only; legacy
     // snapshot mode has no live source to subscribe to.
-    if (creds) {
+    if (cloudGetClient) {
         const realtimeOn = await readRealtimeFlag();
         if (!realtimeOn) {
             console.error('[heuresis-mcp] realtime: disabled (--no-realtime or config).');
@@ -220,7 +262,7 @@ async function runServer() {
             // client (Supabase) is not reachable, the error surfaces on stderr.
             void (async () => {
                 try {
-                    const { client } = await getCloudClient(creds);
+                    const client = await cloudGetClient();
                     const wsId = await resolveSubscriptionWorkspaceId(client);
                     if (!wsId) {
                         console.error('[heuresis-mcp] realtime: no workspace visible; skipping subscription.');

package/dist/wsPolyfill.js

@@ -0,0 +1,12 @@
+// Node < 22 ships no global `WebSocket`, but @supabase/realtime-js requires
+// one: a Supabase client builds a RealtimeClient in its constructor (even when
+// realtime is never used), which throws "Node.js 20 detected without native
+// WebSocket support" when no global WebSocket exists. Install the `ws`
+// implementation as the global so createClient works on Node 18/20. No-op on
+// Node 22+, where WebSocket is native. Imported for its side effect by every
+// module that builds a Supabase client, before the first createClient call.
+import WebSocket from 'ws';
+const g = globalThis;
+if (typeof g.WebSocket === 'undefined') {
+    g.WebSocket = WebSocket;
+}

package/dist/zod-to-json-schema.js

@@ -69,7 +69,32 @@ function leafSchema(schema) {
     return out;
 }
 export function zodToJsonSchema(schema) {
-    const shape = schema.shape;
+    // Peel wrappers to reach the underlying object whose `.shape` we can
+    // introspect: `.refine()`/`.transform()`/`.superRefine()` produce a
+    // ZodEffects (no `.shape`), and optional/default/nullable wrap the root too.
+    // Without this, a tool whose inputSchema is a ZodEffects (e.g. expand_concept)
+    // makes `Object.entries(undefined)` throw — which previously took down the
+    // ENTIRE tools/list response and caused MCP clients to drop the server.
+    let root = schema;
+    while (root && root._def) {
+        if (root instanceof z.ZodEffects) {
+            root = root._def.schema;
+            continue;
+        }
+        if (root instanceof z.ZodOptional ||
+            root instanceof z.ZodDefault ||
+            root instanceof z.ZodNullable) {
+            root = root._def.innerType;
+            continue;
+        }
+        break;
+    }
+    const shape = root?.shape;
+    if (!shape || typeof shape !== 'object') {
+        // Not an object schema we can introspect — expose a permissive object so
+        // the tool still lists and still accepts its arguments.
+        return { type: 'object', additionalProperties: true };
+    }
     const properties = {};
     const required = [];
     for (const [key, value] of Object.entries(shape)) {

package/package.json

@@ -1,56 +1,58 @@
-{
-  "name": "@heuresis/mcp",
-  "version": "1.0.0-rc.11",
-  "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",
-    "zod": "^3.23.0"
-  },
-  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "typescript": "^5.6.0"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "license": "AGPL-3.0-or-later"
-}
+{
+  "name": "@heuresis/mcp",
+  "version": "1.0.0-rc.13",
+  "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"
+}