@heuresis/mcp 1.0.0-rc.1

package/README.md

@@ -0,0 +1,152 @@
+# @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.

package/dist/cli.js

@@ -0,0 +1,276 @@
+// Heuresis MCP — CLI subcommand handlers.
+//
+// `npx @heuresis/mcp` with no subcommand → start the MCP stdio server
+// (run by Claude Desktop / Claude Code / etc.). With a subcommand it's a
+// one-shot CLI:
+//   login    — pair this machine with the user's Heuresis account
+//   logout   — delete ~/.heuresis/credentials.json
+//   whoami   — print the linked email + workspace
+//   --help   — usage
+//
+// AUTH UX (Phase 19.3 — device-code poll flow).
+// ----------------------------------------------------------
+// 1. POST to the `mcp-device-init` Edge Function with the chosen device name.
+//    Receive a short XXXX-XXXX code + an expiry.
+// 2. Tell the user to open https://heuresis.app/device (overridable via
+//    HEURESIS_DEVICE_BASE_URL for staging / self-hosted setups) and enter
+//    the code.
+// 3. Poll `mcp-device-poll` every 5s until status: ok (claim accepted) or
+//    410 (expired / already-used), or 15-minute timeout.
+// 4. On success, write ~/.heuresis/credentials.json with the returned
+//    refresh_token + supabase_url + anon_key + user_id + device_name and
+//    print "Linked to <email>".
+//
+// The webapp `/device` page calls a third Edge Function `mcp-device-grant`
+// 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';
+// 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 POLL_INTERVAL_MS = 5_000;
+const POLL_TIMEOUT_MS = 15 * 60 * 1_000;
+function log(...args) {
+    // Use stderr so we don't confuse MCP-client stdout parsers when this CLI
+    // is misconfigured into the MCP slot. stderr is always safe.
+    console.error(...args);
+}
+function printHelp() {
+    log([
+        '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',
+        '',
+        'Credentials are stored at:',
+        `  ${credentialsPath()}`,
+        '',
+        'Environment overrides:',
+        '  HEURESIS_DEVICE_BASE_URL   Webapp origin (default https://heuresis.app)',
+        '  HEURESIS_SUPABASE_URL      Supabase project URL (default the heuresis.app project)',
+        '',
+        'Legacy snapshot mode (deprecated, removed after 19.7):',
+        '  HEURESIS_SNAPSHOT=/path/to/export.json npx @heuresis/mcp',
+        '  …falls back to read-only behavior against a JSON export.',
+    ].join('\n'));
+}
+async function prompt(question) {
+    const rl = createInterface({ input, output, terminal: true });
+    try {
+        return (await rl.question(question)).trim();
+    }
+    finally {
+        rl.close();
+    }
+}
+/** Parse `npx @heuresis/mcp login [--device-name <name>]`. */
+function parseLoginFlags(argv) {
+    const opts = {};
+    for (let i = 0; i < argv.length; i++) {
+        const flag = argv[i];
+        if (flag === '--device-name' || flag === '--device') {
+            const v = argv[i + 1];
+            if (!v) {
+                log(`Missing value for ${flag}`);
+                process.exit(2);
+            }
+            opts.deviceName = v;
+            i++;
+        }
+        else {
+            log(`Unknown flag: ${flag}`);
+            process.exit(2);
+        }
+    }
+    return opts;
+}
+/** Sleep `ms` milliseconds. Resolves only — no rejection path. */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function postJson(url, body) {
+    const res = await fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+    let data = null;
+    try {
+        data = await res.json();
+    }
+    catch {
+        /* leave null */
+    }
+    return { status: res.status, data };
+}
+export async function loginCommand(argv = []) {
+    const opts = parseLoginFlags(argv);
+    const deviceName = opts.deviceName ?? defaultDeviceName();
+    const deviceBaseUrl = process.env.HEURESIS_DEVICE_BASE_URL ?? DEFAULT_DEVICE_BASE_URL;
+    const supabaseUrl = process.env.HEURESIS_SUPABASE_URL ?? DEFAULT_SUPABASE_URL;
+    log('');
+    log('Heuresis MCP — device link (19.3)');
+    log('─'.repeat(50));
+    // 1. Init — allocate a pairing code.
+    const initUrl = `${supabaseUrl}/functions/v1/mcp-device-init`;
+    let initRes;
+    try {
+        initRes = await postJson(initUrl, { device_name: deviceName });
+    }
+    catch (err) {
+        log('');
+        log(`Could not reach Heuresis at ${initUrl}.`);
+        log(`Error: ${err instanceof Error ? err.message : String(err)}`);
+        log('If you are on a private / staging Supabase project, set HEURESIS_SUPABASE_URL.');
+        process.exit(1);
+    }
+    if (initRes.status !== 200) {
+        log('');
+        log(`Failed to start the pairing flow (HTTP ${initRes.status}).`);
+        const data = initRes.data;
+        if (data?.error)
+            log(`  ${data.error}${data.detail ? ` — ${data.detail}` : ''}`);
+        process.exit(1);
+    }
+    const init = initRes.data;
+    if (!init?.code) {
+        log('Pairing init returned no code. Aborting.');
+        process.exit(1);
+    }
+    // 2. Tell the user where to go.
+    log('');
+    log(`1. Open this page in your browser:`);
+    log(`     ${deviceBaseUrl}/device`);
+    log('');
+    log(`2. Enter this code (case-insensitive):`);
+    log(`     ${init.code}`);
+    log('');
+    log(`3. This window will finish on its own once you confirm. The code`);
+    log(`   expires in 15 minutes.`);
+    log('');
+    log(`Waiting for confirmation…`);
+    // 3. Poll until ok / 410 / timeout.
+    const pollUrl = `${supabaseUrl}/functions/v1/mcp-device-poll`;
+    const deadline = Date.now() + POLL_TIMEOUT_MS;
+    let success = null;
+    while (Date.now() < deadline) {
+        await sleep(POLL_INTERVAL_MS);
+        let pollRes;
+        try {
+            pollRes = await postJson(pollUrl, { code: init.code });
+        }
+        catch (err) {
+            // Transient network errors don't kill the loop — log once and keep polling.
+            log(`  (network blip: ${err instanceof Error ? err.message : String(err)}; retrying)`);
+            continue;
+        }
+        if (pollRes.status === 410) {
+            log('');
+            log('That code expired or was already used. Run `npx @heuresis/mcp login` again to start over.');
+            process.exit(1);
+        }
+        if (pollRes.status === 202) {
+            // Still pending — wait for the next tick.
+            continue;
+        }
+        if (pollRes.status === 200) {
+            const data = pollRes.data;
+            if (data && data.status === 'ok') {
+                success = data;
+                break;
+            }
+            // Unexpected 200 shape — keep trying until timeout rather than fail
+            // catastrophically; the next poll will likely clarify.
+            continue;
+        }
+        // Anything else: log and keep polling. The function may transiently 5xx.
+        log(`  (poll returned HTTP ${pollRes.status}; retrying)`);
+    }
+    if (!success) {
+        log('');
+        log('Timed out waiting for confirmation. Run `npx @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,
+        },
+    });
+    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;
+    }
+    catch (err) {
+        log(`Verification of the new refresh token failed: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+    const creds = {
+        supabase_url: success.supabase_url,
+        anon_key: success.anon_key,
+        refresh_token: success.refresh_token,
+        user_id: success.user_id,
+        device_name: success.device_name || deviceName,
+        created_at: new Date().toISOString(),
+    };
+    const path = await writeCredentials(creds);
+    log('');
+    log(`Linked to ${email} as device "${creds.device_name}".`);
+    log(`Credentials saved to ${path} (chmod 600 on POSIX).`);
+    log('You can now point Claude Desktop / Claude Code at @heuresis/mcp.');
+    log('');
+}
+export async function logoutCommand() {
+    const removed = await deleteCredentials();
+    if (removed) {
+        log('Heuresis credentials removed.');
+    }
+    else {
+        log('No Heuresis credentials were found.');
+    }
+}
+export async function whoamiCommand() {
+    const creds = await readCredentials();
+    if (!creds) {
+        log('Not linked. Run `npx @heuresis/mcp login` to pair this machine.');
+        process.exit(1);
+    }
+    log(`Heuresis MCP — linked`);
+    log(`  device:        ${creds.device_name}`);
+    log(`  user_id:       ${creds.user_id}`);
+    log(`  supabase_url:  ${creds.supabase_url}`);
+    log(`  created_at:    ${creds.created_at}`);
+    log(`  credentials:   ${credentialsPath()}`);
+}
+export function helpCommand() {
+    printHelp();
+}
+// The unused `prompt` helper would only be used if we re-introduced any
+// interactive form; export it so future subcommands can pick it up without
+// re-implementing readline plumbing.
+export { prompt };

package/dist/cloudClient.js

@@ -0,0 +1,71 @@
+// Heuresis MCP — Supabase client wrapper.
+//
+// One SupabaseClient per MCP process. We DON'T let supabase-js persist the
+// 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.
+//   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.
+import { createClient } from '@supabase/supabase-js';
+let cached = null;
+export class CloudAuthError extends Error {
+    constructor(msg) {
+        super(msg);
+        this.name = 'CloudAuthError';
+    }
+}
+/**
+ * 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.
+ */
+export async function getCloudClient(creds) {
+    if (cached)
+        return cached;
+    const client = createClient(creds.supabase_url, creds.anon_key, {
+        auth: {
+            // Headless: no localStorage, no URL detection, no auto-refresh
+            // listeners writing to disk. The library still auto-refreshes the
+            // in-memory access token from the refresh token, which is all we want.
+            persistSession: false,
+            autoRefreshToken: true,
+            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.`);
+    }
+    cached = { client, userId: creds.user_id };
+    return cached;
+}
+/** Clear the cached client. Used after logout. */
+export function resetCloudClient() {
+    cached = null;
+}
+/**
+ * Convenience wrapper that surfaces Postgres / auth errors as a readable
+ * MCP tool error. supabase-js returns `{ data, error }` everywhere; this
+ * unwraps it.
+ */
+export function unwrap(res) {
+    if (res.error)
+        throw new Error(res.error.message);
+    if (res.data === null)
+        throw new Error('Empty result from cloud.');
+    return res.data;
+}