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

package/README.md

@@ -1,152 +1,159 @@
-# @heuresis/mcp
-
-A Model Context Protocol (MCP) server that turns the user's Heuresis
-workspace into a thinking substrate any MCP-capable agent (Claude
-Desktop, Claude Code, Cursor, Windsurf, custom agents) can read and
-write — the webapp and the MCP become two front-ends to one cloud
-workspace. The MCP logs into the user's Heuresis account, talks to the
-same Supabase project the webapp talks to, and respects the same RLS.
-
-## Install
-
-```bash
-npm install -g @heuresis/mcp
-# or run on demand without installing:
-npx -y @heuresis/mcp@latest
-```
-
-> Not yet published. While in alpha you can run it locally:
->
-> ```bash
-> cd mcp-server
-> npm install
-> npm run build
-> node dist/index.js --help
-> ```
-
-## Quickstart
-
-### 1. Link this machine to your Heuresis account
-
-```bash
-npx @heuresis/mcp login
-```
-
-The CLI prints a short device code (`XXXX-XXXX`) and a URL. Open the URL in your browser, sign into Heuresis if you aren't already, paste the code, and confirm the device. The CLI polls in the background and writes your credentials to `~/.heuresis/credentials.json` (chmod 600 on POSIX) the moment you confirm. Subsequent runs of the MCP are silent.
-
-To unlink a machine, run `npx @heuresis/mcp logout` locally, or open Settings ▸ Connected devices in the webapp to revoke remotely.
-
-`npx @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. Optional CLI subcommands
-
-```bash
-npx @heuresis/mcp whoami         # show the linked account + device
-npx @heuresis/mcp logout         # delete the credentials file
-npx @heuresis/mcp --help         # all options
-npx @heuresis/mcp --no-realtime  # boot once with live sync turned off (persisted)
-npx @heuresis/mcp --realtime     # re-enable live sync
-```
-
-## Live sync
-
-When the MCP boots in cloud mode it subscribes to your workspace over
-Supabase Realtime and notifies the client whenever a `nodes`, `edges`,
-`projects`, or `ideas` row changes. Edits you make in the webapp show
-up in your 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 your client logs every notification). The preference is
-saved to `~/.heuresis/config.json` so you only have to pass the flag
-once.
-
-## Tools
-
-This is the **Phase 19.1** tool surface. The remaining tools from
-`docs/mcp-cloud.md` §4 ship in rolling waves under Phase 19.4.
-
-### Reads
-
-| Tool                | Input                                                                                                                       |
-| ------------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `list_projects`     | `{}` — every project in the workspace with brief, direction, lifecycle, and node count.                                     |
-| `get_project_graph` | `{ projectId, includeArchived?, detail? }` — every node + edge inside one project.                                          |
-| `get_subtree`       | `{ rootId, depth?, detail? }` — a node and its descendants up to `depth` generations.                                       |
-| `get_concept`       | `{ id, includeAncestry?, includeChildren?, includeIdeaMemberships? }` — one concept with full detail.                       |
-| `search_concepts`   | `{ query, limit?, projectId?, status?, detail? }` — substring search across label / description / partition / tags. Text-only; semantic search lands in 19.4. |
-
-### Writes
-
-| Tool             | Input                                                                                                                |
-| ---------------- | -------------------------------------------------------------------------------------------------------------------- |
-| `add_concept`    | `{ label, description?, parentId?, projectId?, tags? }` — create a node; partition edge auto-created if parented.    |
-| `update_concept` | `{ id, label?, description?, tags?, partitionAttribute?, rationale?, status? }` — patch a node.                      |
-| `link_concepts`  | `{ fromId, toId, kind }` where `kind ∈ { 'k-ref', 'derived-from', 'semantic-adjacency' }` — create a non-partition edge. |
-
-Each tool's input shape mirrors its counterpart in the webapp's
-`src/agent/tools.ts`, so an agent that uses both surfaces sees a
-uniform contract.
-
-## Status
-
-**Cloud-authenticated alpha (v0.2.0-alpha, Phase 19.1).**
-
-- The 8 tools above hit Supabase live, against the same workspace your
-  webapp sees, under the same RLS.
-- Full tool parity (the other 19 tools — operators, k-ref bulk ops,
-  validation, standing, ideas, projects-as-targets) ships in waves
-  under Phase 19.4 and is **not** included in this build.
-- The `mcp-device-poll` / `mcp-device-grant` Edge Functions that make
-  `login` automatic ship in Phase 19.3. Until then the `login`
-  subcommand uses the manual paste workaround described above.
-- The Settings ▸ Account ▸ Connected devices UI (where you'd revoke
-  this device) ships in Phase 19.6. Until then, revoke at the database
-  level.
-
-## Legacy snapshot mode (deprecated)
-
-The v0 read-only snapshot reader still works as a fallback while users
-migrate. With no `~/.heuresis/credentials.json` and the
-`HEURESIS_SNAPSHOT` env var set, the server reads a JSON export from
-disk and exposes the v0 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 after Phase 19.7
-(cloud-auth mandatory). It's here so the current install path keeps
-working through the migration.
-
-## 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.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.

package/dist/cli.js

@@ -25,14 +25,15 @@
 // to attach the user's identity to the pending grant row.
 import { createInterface } from 'node:readline/promises';
 import { stdin as input, stdout as output } from 'node:process';
-import { createClient } from '@supabase/supabase-js';
 import { credentialsPath, defaultDeviceName, deleteCredentials, readCredentials, writeCredentials, } from './credentials.js';
+import { exchangeRefreshToken, RefreshTokenError } from './gotrue.js';
+import { ensureProxyAgent } from './proxy.js';
 // Where the device pairing UI lives. Production default; can be overridden
 // for staging / self-hosted deploys via HEURESIS_DEVICE_BASE_URL. We also
 // 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://heuresis.supabase.co';
+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) {
@@ -45,12 +46,12 @@ function printHelp() {
         'heuresis-mcp — Heuresis MCP server (cloud-authenticated, alpha)',
         '',
         'Usage:',
-        '  npx @heuresis/mcp              Start the MCP stdio server (run by Claude Desktop, Cursor, etc.)',
-        '  npx @heuresis/mcp login        Link this machine to your Heuresis account',
-        '    --device-name <name>           Override the default device name (hostname-shortRand).',
-        '  npx @heuresis/mcp logout       Remove the saved credentials',
-        '  npx @heuresis/mcp whoami       Show the linked account',
-        '  npx @heuresis/mcp --help       Show this message',
+        '  npx -y @heuresis/mcp                              Start the MCP stdio server (run by Claude Desktop, Cursor, etc.)',
+        '  npx -y -p @heuresis/mcp heuresis-mcp login        Link this machine to your Heuresis account',
+        '    --device-name <name>                             Override the default device name (hostname-shortRand).',
+        '  npx -y -p @heuresis/mcp heuresis-mcp logout       Remove the saved credentials',
+        '  npx -y -p @heuresis/mcp heuresis-mcp whoami       Show the linked account',
+        '  npx -y -p @heuresis/mcp heuresis-mcp --help       Show this message',
         '',
         'Credentials are stored at:',
         `  ${credentialsPath()}`,
@@ -99,6 +100,7 @@ function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
 async function postJson(url, body) {
+    await ensureProxyAgent(log);
     const res = await fetch(url, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
@@ -147,16 +149,15 @@ export async function loginCommand(argv = []) {
         log('Pairing init returned no code. Aborting.');
         process.exit(1);
     }
-    // 2. Tell the user where to go.
+    // 2. Tell the user where to go. The URL has the code baked in as a query
+    // param so the device page can pre-fill it; the user just clicks Confirm.
+    const confirmUrl = `${deviceBaseUrl}/device?code=${encodeURIComponent(init.code)}`;
     log('');
-    log(`1. Open this page in your browser:`);
-    log(`     ${deviceBaseUrl}/device`);
+    log(`Open this URL to link this machine to your Heuresis account:`);
     log('');
-    log(`2. Enter this code (case-insensitive):`);
-    log(`     ${init.code}`);
+    log(`  ${confirmUrl}`);
     log('');
-    log(`3. This window will finish on its own once you confirm. The code`);
-    log(`   expires in 15 minutes.`);
+    log(`(Code: ${init.code}, in case the page needs it manually. Expires in 15 min.)`);
     log('');
     log(`Waiting for confirmation…`);
     // 3. Poll until ok / 410 / timeout.
@@ -176,7 +177,7 @@ export async function loginCommand(argv = []) {
         }
         if (pollRes.status === 410) {
             log('');
-            log('That code expired or was already used. Run `npx @heuresis/mcp login` again to start over.');
+            log('That code expired or was already used. Run `npx -y -p @heuresis/mcp heuresis-mcp login` again to start over.');
             process.exit(1);
         }
         if (pollRes.status === 202) {
@@ -198,36 +199,31 @@ export async function loginCommand(argv = []) {
     }
     if (!success) {
         log('');
-        log('Timed out waiting for confirmation. Run `npx @heuresis/mcp login` again.');
+        log('Timed out waiting for confirmation. Run `npx -y -p @heuresis/mcp heuresis-mcp login` again.');
         process.exit(1);
     }
     // 4. Verify the refresh token works + fetch the user's email to print.
-    const client = createClient(success.supabase_url, success.anon_key, {
-        auth: {
-            persistSession: false,
-            autoRefreshToken: false,
-            detectSessionInUrl: false,
-        },
-    });
+    // We exchange the refresh token straight against the GoTrue token endpoint
+    // rather than going through supabase-js's stored-session machinery (which
+    // throws "Auth session missing!" headlessly — see gotrue.ts for why).
     let email = '(no email on record)';
     try {
-        const { data, error } = await client.auth.setSession({
-            access_token: '',
-            refresh_token: success.refresh_token,
-        });
-        if (error || !data.session || !data.user) {
-            log('');
-            log(`Pairing returned a token, but it failed to refresh: ${error?.message ?? 'no session'}`);
-            log('Run `npx @heuresis/mcp login` again to retry.');
-            process.exit(1);
-        }
-        email = data.user.email ?? email;
-        // Use whatever supabase-js handed us back — it may have already rotated
-        // the refresh token at the first refresh.
-        success.refresh_token = data.session.refresh_token ?? success.refresh_token;
+        const session = await exchangeRefreshToken(success.supabase_url, success.anon_key, success.refresh_token);
+        email = session.user?.email ?? email;
+        // GoTrue rotates the refresh token on every exchange — persist the NEW
+        // one so the credentials we write are immediately usable. The token we
+        // got from the poll is now spent.
+        success.refresh_token = session.refresh_token;
     }
     catch (err) {
-        log(`Verification of the new refresh token failed: ${err instanceof Error ? err.message : String(err)}`);
+        log('');
+        if (err instanceof RefreshTokenError) {
+            log(`Pairing returned a token, but it failed to refresh: ${err.message}`);
+        }
+        else {
+            log(`Verification of the new refresh token failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        log('Run `npx -y -p @heuresis/mcp heuresis-mcp login` again to retry.');
         process.exit(1);
     }
     const creds = {
@@ -257,7 +253,7 @@ export async function logoutCommand() {
 export async function whoamiCommand() {
     const creds = await readCredentials();
     if (!creds) {
-        log('Not linked. Run `npx @heuresis/mcp login` to pair this machine.');
+        log('Not linked. Run `npx -y -p @heuresis/mcp heuresis-mcp login` to pair this machine.');
         process.exit(1);
     }
     log(`Heuresis MCP — linked`);

package/dist/cloudClient.js

@@ -4,18 +4,20 @@
 // session to localStorage (no such thing in Node) — instead we manage the
 // session manually:
 //
-//   1. At process start: read ~/.heuresis/credentials.json → call
-//      `client.auth.setSession({ access_token: '', refresh_token })`.
-//      supabase-js immediately refreshes the access token from the refresh
-//      token and stores both in memory.
+//   1. At process start: read ~/.heuresis/credentials.json → exchange the
+//      refresh token for a fresh session by hitting the GoTrue token endpoint
+//      directly (see gotrue.ts), then hand the resulting access_token +
+//      refresh_token to `client.auth.setSession(...)`. We deliberately do NOT
+//      use the old `setSession({ access_token: '', refresh_token })` trick:
+//      auth-js 2.x rejects an empty access_token with "Auth session missing!"
+//      before it ever refreshes. With a real access_token the guard passes
+//      and supabase-js stores both tokens in memory.
 //   2. supabase-js handles silent re-refresh in the background while the
 //      process runs. We don't have to do anything per-tool-call.
-//   3. If the refresh fails (revoked, expired), tool calls 401 — the wrapper
-//      catches that and surfaces a "re-run `npx @heuresis/mcp login`" message.
-//
-// Phase 19.3 will swap the refresh-token issuance to come from the
-// `mcp-device-poll` Edge Function, but the client-side shape doesn't change.
+//   3. If the refresh fails (revoked, expired), the bootstrap throws — the
+//      wrapper surfaces a "re-run login" message.
 import { createClient } from '@supabase/supabase-js';
+import { exchangeRefreshToken } from './gotrue.js';
 let cached = null;
 export class CloudAuthError extends Error {
     constructor(msg) {
@@ -41,14 +43,25 @@ export async function getCloudClient(creds) {
             detectSessionInUrl: false,
         },
     });
-    // Bootstrap the session from the refresh token. setSession with an empty
-    // access_token forces an immediate refresh against the refresh_token.
-    const { data, error } = await client.auth.setSession({
-        access_token: '',
-        refresh_token: creds.refresh_token,
-    });
-    if (error || !data.session) {
-        throw new CloudAuthError(`Failed to refresh Heuresis session: ${error?.message ?? 'no session returned'}. Run \`npx @heuresis/mcp login\` to re-authenticate.`);
+    // 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.
+    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.');
+        }
+    }
+    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;

package/dist/cloudOperators.js

@@ -37,6 +37,7 @@ import { COMBINE_OPERATOR } from './operators/combine.js';
 import { EXPLORE_OPERATOR } from './operators/explore.js';
 import { TRIZ_PARAMETERS, TRIZ_PRINCIPLES, lookupPrinciples, } from './operators/triz-matrix.js';
 import { composePrompt } from './prompt/compose.js';
+import { composeOperatorSystemPrefix } from './llm/operatorFraming.js';
 import { parseLlmResponse } from './prompt/parse.js';
 import { defaultModelFor, runLlm, } from './llm/client.js';
 import { estimateCost } from './llm/cost.js';
@@ -293,7 +294,14 @@ export async function runOperator(client, args) {
         model: config.model,
         promptChars: prompt.length,
     });
-    const llmResult = await runLlm(config, { prompt });
+    // Prompt-caching Step 2 mirror — pass a stable operator-framing system
+    // prefix so the Anthropic prompt cache catches every repeat operator
+    // call within the 5-minute TTL. The MCP `runLlm` already wraps
+    // systemPrefix with `cache_control: ephemeral` for the Anthropic path.
+    const llmResult = await runLlm(config, {
+        prompt,
+        systemPrefix: composeOperatorSystemPrefix(),
+    });
     const parsed = parseLlmResponse(llmResult.text);
     if (!parsed.ok) {
         throw new Error(`Operator run produced output the parser rejected: ${parsed.error}`);

package/dist/cloudTools.js

@@ -853,17 +853,14 @@ export async function listEdges(client, args) {
 // ---------------------------------------------------------------------------
 // find_concepts
 // ---------------------------------------------------------------------------
-// Mirrors the webapp `find_concepts` tool. Webapp version supports
-// by='meaning' (in-browser embeddings) and by='label'. The MCP runs server-
-// side without a local embedding model, so by='meaning' transparently falls
-// back to the same substring search as by='label' and the response carries a
-// `note` explaining the degradation. Phase 19.5 swaps in pgvector when the
-// schema picks it up.
+// Mirrors the webapp `find_concepts` tool, label/substring path only. The
+// webapp's by='meaning' variant relies on in-browser embeddings; that path is
+// not wired on the MCP side, so this tool accepts by='label' only.
 export const findConceptsInput = z
     .object({
     query: z.string().min(1),
     k: z.number().int().positive().max(20).default(10),
-    by: z.enum(['meaning', 'label']).default('meaning'),
+    by: z.enum(['label']).default('label'),
     projectId: z.string().optional(),
 })
     .strict();
@@ -885,13 +882,6 @@ export async function findConcepts(client, args) {
         status: r.status,
         score: 1,
     }));
-    if (args.by === 'meaning') {
-        return {
-            hits,
-            mode: 'label',
-            note: 'Semantic search not yet wired in MCP (no in-browser embedding model); fell back to label/substring match.',
-        };
-    }
     return { hits, mode: 'label' };
 }
 // ===========================================================================
@@ -1591,7 +1581,7 @@ export const CLOUD_TOOLS = [
     },
     {
         name: 'find_concepts',
-        description: "Find concepts by label/substring match. (Webapp parity: by='meaning' is accepted but currently falls back to label match on the MCP — semantic search ships in Phase 19.5.) Returns up to k hits, each with id, label, status.",
+        description: 'Find concepts by label/substring match. Returns up to k hits, each with id, label, status.',
         inputSchema: findConceptsInput,
         handler: async (client, args) => findConcepts(client, findConceptsInput.parse(args)),
     },

package/dist/gotrue.js

@@ -0,0 +1,84 @@
+// Heuresis MCP — direct GoTrue refresh-token exchange.
+//
+// Why not `supabase-js` setSession/refreshSession?
+// ------------------------------------------------
+// We run headless in Node — there is no localStorage and no persisted
+// session for supabase-js to read. The previous code tried to bootstrap a
+// session with `client.auth.setSession({ access_token: '', refresh_token })`,
+// relying on the old behavior where an empty access_token forced an immediate
+// refresh from the refresh token. That trick is dead as of @supabase/auth-js
+// 2.x: `_setSession` now guards at the very top —
+//
+//     if (!currentSession.access_token || !currentSession.refresh_token) {
+//       throw new AuthSessionMissingError();   // → "Auth session missing!"
+//     }
+//
+// so an empty `access_token` throws `AuthSessionMissingError` ("Auth session
+// missing!") BEFORE it ever attempts the refresh. `refreshSession()` has the
+// same problem in a different shape — it leans on a stored session that does
+// not exist here.
+//
+// The robust path is to hit the GoTrue token endpoint directly. It exchanges
+// a bare refresh token for a fresh session with zero stored-state
+// assumptions, and it is exactly what supabase-js does internally once it has
+// a session — including refresh-token rotation.
+export class RefreshTokenError extends Error {
+    constructor(msg) {
+        super(msg);
+        this.name = 'RefreshTokenError';
+    }
+}
+/**
+ * Exchange a refresh token for a fresh session via the GoTrue token endpoint:
+ *
+ *   POST `${supabaseUrl}/auth/v1/token?grant_type=refresh_token`
+ *   headers: { apikey, Authorization: Bearer <anon>, Content-Type: application/json }
+ *   body:    { refresh_token }
+ *
+ * Returns the full session (access_token + the rotated refresh_token + the
+ * user). Throws `RefreshTokenError` with an actionable message — including the
+ * response's keys when the expected token fields are missing — on any failure.
+ */
+export async function exchangeRefreshToken(supabaseUrl, anonKey, refreshToken) {
+    if (!refreshToken) {
+        throw new RefreshTokenError('No refresh token to exchange (the value was empty/undefined). ' +
+            'The pairing response did not carry a usable token.');
+    }
+    const url = `${supabaseUrl.replace(/\/$/, '')}/auth/v1/token?grant_type=refresh_token`;
+    let res;
+    try {
+        res = await fetch(url, {
+            method: 'POST',
+            headers: {
+                apikey: anonKey,
+                Authorization: `Bearer ${anonKey}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({ refresh_token: refreshToken }),
+        });
+    }
+    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(`Token refresh failed (HTTP ${res.status}): ${detail}`);
+    }
+    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(`Token refresh succeeded (HTTP ${res.status}) but the response is missing ` +
+            `access_token/refresh_token. Response keys: [${keys}].`);
+    }
+    return session;
+}

package/dist/index.js

@@ -24,6 +24,7 @@ import { getConcept as legacyGetConcept, getConceptInput as legacyGetConceptInpu
 import { CLOUD_TOOLS } from './cloudTools.js';
 import { readCredentials } from './credentials.js';
 import { CloudAuthError, getCloudClient } from './cloudClient.js';
+import { ensureProxyAgent } from './proxy.js';
 import { helpCommand, loginCommand, logoutCommand, whoamiCommand, } from './cli.js';
 import { readRealtimeFlag, resolveSubscriptionWorkspaceId, startRealtimeSubscription, stripRealtimeFlags, } from './realtime.js';
 const VERSION = '0.2.0-alpha';
@@ -93,6 +94,9 @@ function makeLegacySnapshotTools(store) {
     ];
 }
 async function runServer() {
+    // Route outbound fetch (GoTrue refresh + PostgREST queries) through
+    // HTTPS_PROXY / HTTP_PROXY before any cloud call. No-op when unset.
+    await ensureProxyAgent(console.error);
     const creds = await readCredentials();
     const snapshotEnv = process.env.HEURESIS_SNAPSHOT;
     let tools;
@@ -141,7 +145,7 @@ async function runServer() {
             '[heuresis-mcp] Not configured.',
             '',
             'To use cloud mode (recommended):',
-            '  npx @heuresis/mcp login',
+            '  npx -y -p @heuresis/mcp heuresis-mcp login',
             '',
             'To use legacy snapshot mode (deprecated, removed after 19.7):',
             '  HEURESIS_SNAPSHOT=/path/to/export.json npx @heuresis/mcp',

package/dist/llm/operatorFraming.js

@@ -0,0 +1,53 @@
+// VENDORED MIRROR of src/llm/operatorFraming.ts — keep in sync with the
+// webapp. The mcp-server is independently buildable (its own tsconfig,
+// its own deps), so we vendor the framing block here rather than reaching
+// across the repo boundary.
+//
+// Heuresis's smaller operator doctrines (ASIT ~500-800 tok, Branch ~600-1200
+// tok) sit right around or below Sonnet's 1,024-token minimum-cacheable-size
+// threshold. Below that floor the Anthropic API silently does NOT cache the
+// prefix — `cache_creation_input_tokens` comes back as 0 and the next call
+// re-tokenizes everything at full price.
+//
+// IMPORTANT: this block is the cache prefix for the ENTIRE MCP operator
+// path. Editing it invalidates every operator's cache. Keep BYTE-IDENTICAL
+// with the webapp copy at src/llm/operatorFraming.ts.
+export const OPERATOR_FRAMING_PREAMBLE = [
+    'You are Heuresis\'s operator engine — a stateless transform that takes a parent CONCEPT plus structured context, applies one named OPERATOR (an ASIT tool, a TRIZ inventive principle, a C-K partition rule, a free-form lab prompt, etc.), and emits a JSON object proposing 1–8 child concepts.',
+    '',
+    'CONTRACT.',
+    '  • You receive: the project brief, the concept-path from root to target, the target concept, a pool of validated knowledge (K), an operator definition (family / key / name / doctrine / prompt fragment), an optional graph-awareness <context> block (ancestry, sibling axes, existing labels), and optionally COMBINE inputs, an EXPLORE <branch>, or a free-form <angle>.',
+    '  • You return: ONE JSON object matching the requested schema. NEVER prose before or after, NEVER markdown fences, NEVER trailing commas, NEVER comments inside the JSON. The caller parses with strict-mode zod and rejects anything that does not match.',
+    '  • If the schema asks for partitions[], emit between 3 and 5 top-level partitions unless the operator explicitly says otherwise (EXPLORE allows 4–8). Each partition is a STANDALONE concept title (2–5 words, ≤60 chars, no parent-prefix, no trailing period), a 1–2 sentence description, a ≤5-word partitionAttribute naming the distinguishing AXIS, a 1–3 sentence rationale citing the operator and any K used, and a kReferences[] of K-ids you actually used.',
+    '',
+    'DOCTRINE.',
+    '  • Stay faithful to the operator. ASIT operators MUST stay inside the closed world — never introduce alien components. TRIZ operators MUST honor the named inventive principle. C-K operators MUST treat C-nodes as undecidable noun-phrases (never solutions in disguise — verbs like "build", "add", "use", "implement", "create" at the start of a label belong in the parking lot, not in the C-tree).',
+    '  • Be additive, not redundant. The <context> block (when present) lists existing canvas labels and sibling axes — do not propose paraphrases of either. Where possible, partition on an axis NOT yet present in <sibling_axes>.',
+    '  • Be honest. Use the optional selfCritique field to surface the strongest assumption or risk in each partition. Do not flatter.',
+    '  • Cite K. If a knowledge item informed a partition, list its id in kReferences. If you needed a fact you do not have, propose it via newKnowledgeProposed (1–3 items, framed as questions, never invented numbers).',
+    '',
+    'VOICE.',
+    '  • Plain, sharp, conversational. Active voice, short sentences. No sales hype, no poetry, no exclamation points. Never use an em dash ("—"); use a period, comma, colon, or parentheses instead.',
+    '  • Labels are concept titles, not sentences. Put long-form prose in description / rationale, never in label.',
+    '',
+    'FAILURE MODES TO AVOID.',
+    '  • Restating the parent concept as a child.',
+    '  • Two partitions that decompose the same axis (collapse them or pick the stronger).',
+    '  • Children whose label contains the immediate parent partition\'s label.',
+    '  • Nesting children deeper than one level — a child MUST NOT carry its own children[].',
+    '  • Markdown / code fences around the JSON.',
+].join('\n');
+/**
+ * Stable system prefix shared by every operator run on the MCP side.
+ * Composed of the framing preamble plus a short prologue paragraph so the
+ * cached prefix carries both the framing and the per-call lead-in.
+ */
+export function composeOperatorSystemPrefix() {
+    return (OPERATOR_FRAMING_PREAMBLE +
+        '\n\n' +
+        'You are assisting an inventive design session structured by C-K theory. ' +
+        'The user grows a graph of concepts (C) drawing on a pool of validated ' +
+        'knowledge (K). When asked to apply an operator from ASIT, TRIZ, or a ' +
+        'free-form lab prompt, propose between 3 and 5 partitions of the TARGET ' +
+        'concept (3–8 for EXPLORE) unless the operator instructions say otherwise.');
+}

package/dist/proxy.js

@@ -0,0 +1,43 @@
+// Heuresis MCP — proxy wiring for Node's global fetch dispatcher.
+//
+// Node 18-22's undici does NOT auto-honor HTTPS_PROXY / HTTP_PROXY (Node 24+
+// does). Without this, every outbound fetch fails with "fetch failed" on
+// networks that require an egress proxy — both the device-pairing + GoTrue
+// refresh calls in the CLI and the SupabaseClient's PostgREST queries in the
+// running MCP server. We install an undici ProxyAgent as the global
+// dispatcher once, at process start.
+//
+// Idempotent across the whole process (module-level flag) and a no-op when no
+// proxy var is set, so it is safe to call from every entry point.
+//
+// NOTE: this only covers `fetch` (PostgREST + auth). The Realtime websocket
+// uses a separate transport that the global dispatcher does not touch; live
+// sync behind a strict proxy is a known follow-up, but it is best-effort and
+// fire-and-forget, so it never blocks tool calls.
+let proxyAgentInstalled = false;
+/**
+ * Route Node's global `fetch` through HTTPS_PROXY / HTTP_PROXY when set.
+ * Pass a logger to surface the routing decision (the CLI logs to stderr; the
+ * server passes console.error). Resolves once the dispatcher is in place.
+ */
+export async function ensureProxyAgent(log = () => { }) {
+    if (proxyAgentInstalled)
+        return;
+    proxyAgentInstalled = true;
+    const proxyUrl = process.env.HTTPS_PROXY ||
+        process.env.https_proxy ||
+        process.env.HTTP_PROXY ||
+        process.env.http_proxy;
+    if (!proxyUrl)
+        return;
+    try {
+        // Dynamic import keeps undici off the cold-start path when no proxy is in
+        // play. It's a direct dependency, so this resolves.
+        const { ProxyAgent, setGlobalDispatcher } = await import('undici');
+        setGlobalDispatcher(new ProxyAgent(proxyUrl));
+        log(`(routing through proxy ${proxyUrl})`);
+    }
+    catch (err) {
+        log(`(could not configure proxy ${proxyUrl}: ${err instanceof Error ? err.message : String(err)})`);
+    }
+}

package/package.json

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