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

package/README.md

@@ -7,7 +7,7 @@ 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.12`.
+Current version: `1.0.0-rc.13`.
 
 ## Install
 
@@ -89,6 +89,36 @@ npx -y @heuresis/mcp --no-realtime            # boot the server with live sync o
 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

package/dist/cli.js

@@ -35,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

@@ -19,7 +19,7 @@
 // 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) {
@@ -28,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
@@ -45,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/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,6 +1,6 @@
 {
   "name": "@heuresis/mcp",
-  "version": "1.0.0-rc.12",
+  "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",