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

package/README.md

@@ -1,159 +1,159 @@
-# @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.10`.
-
-## 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.12`.
+
+## 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

@@ -23,10 +23,13 @@
 //
 // 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';
 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
@@ -98,34 +101,8 @@ function parseLoginFlags(argv) {
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
-// Wire HTTPS_PROXY / HTTP_PROXY env vars into Node's global fetch dispatcher.
-// Node 18-22's undici does NOT auto-honor these vars (Node 24+ does). Without
-// this, the CLI fails with "fetch failed" on corporate networks. Idempotent
-// and a no-op when no proxy var is set.
-let proxyAgentInstalled = false;
-async function ensureProxyAgent() {
-    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 out of the cold-start path when no proxy
-        // is in play. Node ships undici as part of the runtime 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)})`);
-    }
-}
 async function postJson(url, body) {
-    await ensureProxyAgent();
+    await ensureProxyAgent(log);
     const res = await fetch(url, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },

package/dist/cloudClient.js

@@ -16,6 +16,8 @@
 //      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';
 let cached = null;

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;

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/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/package.json

@@ -1,56 +1,58 @@
-{
-  "name": "@heuresis/mcp",
-  "version": "1.0.0-rc.10",
-  "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.12",
+  "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"
+}