@heuresis/mcp 1.0.0-rc.16 → 1.0.0-rc.17

package/dist/cloudTools.js

@@ -188,11 +188,25 @@ function shapeProject(p) {
 // ---------------------------------------------------------------------------
 export const getSubtreeInput = z
     .object({
-    rootId: z.string(),
+    rootId: z.string().min(1).optional(),
+    id: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Alias for rootId — the concept to root the subtree at (use either).'),
     depth: z.number().int().min(0).max(6).default(3),
     detail: detailArg,
 })
-    .strict();
+    .strict()
+    .refine((a) => Boolean(a.rootId ?? a.id), {
+    message: 'Provide `id` (or `rootId`) — the concept to get the subtree for.',
+    path: ['id'],
+})
+    .transform((a) => ({
+    rootId: (a.rootId ?? a.id),
+    depth: a.depth,
+    detail: a.detail,
+}));
 export async function getSubtree(client, args) {
     const rootRes = await client.from('nodes').select('*').eq('id', args.rootId).maybeSingle();
     if (rootRes.error)
@@ -1554,7 +1568,9 @@ export const CLOUD_TOOLS = [
     },
     {
         name: 'get_subtree',
-        description: 'A node and its descendants up to a given depth. Use when the user asks "tell me about everything under X".',
+        description: 'A node and its descendants up to a given depth. Pass the concept as `id` (or `rootId`). Use when the user asks "tell me about everything under X".',
+        // ZodEffects (refine+transform for the id/rootId alias) — cast like the
+        // operator tools; zodToJsonSchema unwraps it for the served schema.
         inputSchema: getSubtreeInput,
         handler: async (client, args) => getSubtree(client, getSubtreeInput.parse(args)),
     },

package/dist/index.js

@@ -14,7 +14,7 @@
 //
 // Subcommands (one-shot, never start the MCP server):
 //   login | logout | whoami | --help
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
@@ -27,8 +27,87 @@ import { CloudAuthError, getCloudClient, getCloudClientFromPassword } from './cl
 import { ensureProxyAgent } from './proxy.js';
 import { DEFAULT_SUPABASE_URL, helpCommand, loginCommand, logoutCommand, whoamiCommand, } from './cli.js';
 import { readRealtimeFlag, resolveSubscriptionWorkspaceId, startRealtimeSubscription, stripRealtimeFlags, } from './realtime.js';
-const VERSION = '0.2.0-alpha';
+// Report the real published version (dist/index.js → ../package.json) so
+// `heuresis-mcp --version` and the startup banner never lie about what's loaded.
+const VERSION = (() => {
+    try {
+        const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+        return pkg.version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+})();
 const MAX_RESULT_CHARS = 50_000;
+// Fields worth preserving when a node/edge-bearing result is degraded to fit
+// the size cap (everything else — descriptions, rationale, tags — is dropped).
+const SKELETON_KEYS = [
+    'id',
+    'label',
+    'name',
+    'parentId',
+    'parent_id',
+    'kind',
+    'from',
+    'to',
+    'status',
+    'standing',
+    'starred',
+    'projectId',
+    'rootNodeId',
+];
+function skeletonize(item) {
+    if (item && typeof item === 'object' && !Array.isArray(item)) {
+        const o = item;
+        const keep = {};
+        for (const k of SKELETON_KEYS)
+            if (k in o)
+                keep[k] = o[k];
+        return Object.keys(keep).length > 0 ? keep : item;
+    }
+    return item;
+}
+// Never hard-fail a read on size. If a result blows the cap, first drop verbose
+// fields from its array elements (keep id/label/parent/kind…), then, if still
+// too big, slice the largest array — always tagging `_truncated` + `_note` so
+// the agent knows to narrow (limit/depth/scope) or fetch detail via get_concept.
+function fitResultToCap(result, cap) {
+    if (JSON.stringify(result, null, 2).length <= cap)
+        return result;
+    if (!result || typeof result !== 'object' || Array.isArray(result)) {
+        const s = JSON.stringify(result, null, 2);
+        return {
+            _truncated: true,
+            _note: `Result exceeded ${cap} chars and could not be structurally reduced; showing a prefix. Narrow the query.`,
+            preview: s.slice(0, Math.max(0, cap - 200)),
+        };
+    }
+    const obj = { ...result };
+    const arrayKeys = Object.keys(obj).filter((k) => Array.isArray(obj[k]) && obj[k].some((x) => x && typeof x === 'object'));
+    for (const k of arrayKeys)
+        obj[k] = obj[k].map(skeletonize);
+    obj._truncated = true;
+    obj._note =
+        'Result exceeded the size cap; verbose fields were dropped (id/label/parent/kind kept). Use get_concept(id) for full detail, or narrow with limit/depth/scope.';
+    let guard = 0;
+    while (JSON.stringify(obj, null, 2).length > cap && guard++ < 100) {
+        let biggestKey;
+        let biggestLen = 0;
+        for (const k of arrayKeys) {
+            const len = obj[k].length;
+            if (len > biggestLen) {
+                biggestLen = len;
+                biggestKey = k;
+            }
+        }
+        if (!biggestKey || biggestLen <= 1)
+            break;
+        const arr = obj[biggestKey];
+        obj[biggestKey] = arr.slice(0, Math.max(1, Math.floor(arr.length * 0.8)));
+        obj._note = `Result exceeded the size cap; showing a truncated, skeletonized view (some "${biggestKey}" omitted). Narrow with limit/depth/scope, or fetch specifics with get_concept.`;
+    }
+    return obj;
+}
 function makeCloudTools(getClient, operatorTools) {
     // Lazy: defer the actual auth handshake until the first tool call so the
     // MCP server boots fast.
@@ -252,20 +331,10 @@ async function runServer() {
             // background with their own concurrency control (cloudOperators.ts), so no
             // per-call serialization is needed here.
             const result = await tool.handler(req.params.arguments ?? {});
-            const text = JSON.stringify(result, null, 2);
-            if (text.length > MAX_RESULT_CHARS) {
-                return {
-                    isError: true,
-                    content: [
-                        {
-                            type: 'text',
-                            text: `Result too large (${text.length} chars, limit ${MAX_RESULT_CHARS}). ` +
-                                `Narrow the query: lower 'limit'/'depth', keep detail='compact', ` +
-                                `or fetch individual nodes with get_concept.`,
-                        },
-                    ],
-                };
-            }
+            // Never hard-fail on size: auto-degrade node/edge-bearing results
+            // (skeletonize → slice) so the agent always gets actionable structure
+            // back instead of an error it has to recover from.
+            const text = JSON.stringify(fitResultToCap(result, MAX_RESULT_CHARS), null, 2);
             return {
                 content: [{ type: 'text', text }],
             };
@@ -358,6 +427,11 @@ async function main() {
         case 'whoami':
             await whoamiCommand();
             return;
+        case '-v':
+        case '--version':
+        case 'version':
+            console.log(VERSION);
+            return;
         case '-h':
         case '--help':
         case 'help':

package/package.json

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