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

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/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.7",
+  "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": {