@heuresis/mcp 1.0.0-rc.6 → 1.0.0-rc.8

package/README.md

@@ -1,152 +1,148 @@
-# @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.7`.
+
+## Install
+
+```bash
+npm install -g @heuresis/mcp
+# or on demand without installing:
+npx -y @heuresis/mcp
+```
+
+## Quickstart
+
+### 1. Link this machine to your Heuresis account
+
+```bash
+npx -y @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-start`, `mcp-device-grant`, and `mcp-device-poll`.
+
+To unlink a machine: `npx @heuresis/mcp logout`, 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. 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 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/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/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/package.json

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