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

package/dist/cloudClient.js

@@ -27,6 +27,14 @@ import { makeRetryingFetch } from './httpRetry.js';
 // one-shot-fail a data call (see httpRetry.ts).
 const retryingFetch = makeRetryingFetch();
 let cached = null;
+// The device name from credentials.json, captured at bootstrap so provenance
+// stamps can record WHICH device an MCP write came from (surfaced in the webapp
+// timeline once it syncs cloud provenance). null in headless/password mode,
+// which has no device pairing.
+let activeDeviceName = null;
+export function getActiveDeviceName() {
+    return activeDeviceName;
+}
 export class CloudAuthError extends Error {
     constructor(msg) {
         super(msg);
@@ -96,6 +104,7 @@ async function persistRotatedToken(creds, newToken) {
  * been revoked/rotated away.
  */
 export async function getCloudClient(creds) {
+    activeDeviceName = creds.device_name ?? activeDeviceName;
     if (cached)
         return cached;
     try {
@@ -155,3 +164,15 @@ export function unwrap(res) {
         throw new Error('Empty result from cloud.');
     return res.data;
 }
+/**
+ * Like unwrap(), but a `null` data is RETURNED rather than thrown. Use for
+ * `.maybeSingle()` lookups where "no row" is a meaningful outcome the caller
+ * handles itself (e.g. `if (!node) return { error: 'No concept with id …' }`).
+ * Wrapping those in unwrap() turned a legitimate not-found into the opaque
+ * "Empty result from cloud" — and made get_concept throw on dangling ancestry.
+ */
+export function unwrapMaybe(res) {
+    if (res.error)
+        throw new Error(res.error.message);
+    return res.data;
+}

package/dist/cloudTools.js

@@ -41,7 +41,7 @@
 // the change. The stamp is best-effort: a failed provenance insert never
 // fails the underlying write.
 import { z } from 'zod';
-import { unwrap } from './cloudClient.js';
+import { unwrap, unwrapMaybe, getActiveDeviceName } from './cloudClient.js';
 // ---------------------------------------------------------------------------
 // Shared helpers
 // ---------------------------------------------------------------------------
@@ -294,7 +294,7 @@ export async function getConcept(client, args) {
         let cur = node.parent_id;
         while (cur && !seen.has(cur)) {
             seen.add(cur);
-            const p = unwrap(await client.from('nodes').select('id, label, parent_id').eq('id', cur).maybeSingle());
+            const p = unwrapMaybe(await client.from('nodes').select('id, label, parent_id').eq('id', cur).maybeSingle());
             if (!p)
                 break;
             chain.unshift({ id: p.id, label: p.label });
@@ -431,7 +431,7 @@ export async function addConcept(client, args) {
     // Figure out parent + project.
     let parentNode = null;
     if (typeof args.parentId === 'string') {
-        parentNode = unwrap(await client.from('nodes').select('*').eq('id', args.parentId).maybeSingle());
+        parentNode = unwrapMaybe(await client.from('nodes').select('*').eq('id', args.parentId).maybeSingle());
         if (!parentNode)
             return { error: `Parent ${args.parentId} not found.` };
     }
@@ -618,12 +618,16 @@ export async function linkConcepts(client, args) {
 }
 async function stampProvenance(client, args) {
     try {
+        // Tag the originating device so the webapp timeline can show WHICH MCP
+        // device made the change. Rides in source_refs as `device:<name>` — no
+        // schema migration, and source_refs already syncs/exports.
+        const device = getActiveDeviceName();
         const row = {
             workspace_id: args.workspaceId,
             node_id: args.nodeId,
             origin: args.origin ?? 'mcp',
             operator_key: args.operatorKey ?? null,
-            source_refs: [args.sourceRef],
+            source_refs: device ? [args.sourceRef, `device:${device}`] : [args.sourceRef],
             llm_json: args.llmJson ?? null,
             created_by: 'agent',
             analysis_id: args.analysisId ?? null,
@@ -782,6 +786,12 @@ export const listConceptsInput = z
     includeArchived: z.boolean().default(false),
     detail: detailArg,
     limit: z.number().int().min(1).max(500).default(500),
+    offset: z
+        .number()
+        .int()
+        .min(0)
+        .default(0)
+        .describe('Skip this many results — page through a large workspace with limit + offset.'),
 })
     .strict();
 export async function listConcepts(client, args) {
@@ -792,7 +802,7 @@ export async function listConcepts(client, args) {
         if (!args.projectId) {
             return { error: 'scope=project requires projectId.' };
         }
-        const proj = unwrap(await client
+        const proj = unwrapMaybe(await client
             .from('projects')
             .select('id, name')
             .eq('id', args.projectId)
@@ -817,20 +827,26 @@ export async function listConcepts(client, args) {
     }
     let qb = client
         .from('nodes')
-        .select('*')
+        .select('*', { count: 'exact' })
         .eq('workspace_id', wsId)
         .order('updated_at', { ascending: false })
-        .limit(args.limit);
+        .range(args.offset, args.offset + args.limit - 1);
     if (memberIds)
         qb = qb.in('id', memberIds);
     if (!args.includeArchived)
         qb = qb.neq('status', 'archived');
-    const rows = unwrap(await qb);
+    const res = await qb;
+    if (res.error)
+        throw new Error(res.error.message);
+    const rows = (res.data ?? []);
+    const total = res.count ?? rows.length;
     return {
         scope: args.scope,
         projectName,
-        total: rows.length,
-        truncated: rows.length === args.limit,
+        total,
+        offset: args.offset,
+        returned: rows.length,
+        hasMore: args.offset + rows.length < total,
         concepts: rows.map((n) => nodeView(n, args.detail)),
     };
 }
@@ -926,13 +942,13 @@ export const validateConceptInput = z
 })
     .strict();
 export async function validateConcept(client, args) {
-    const node = unwrap(await client.from('nodes').select('*').eq('id', args.id).maybeSingle());
+    const node = unwrapMaybe(await client.from('nodes').select('*').eq('id', args.id).maybeSingle());
     if (!node)
         return { error: `No concept with id ${args.id}` };
     const patch = { status: 'validated' };
     if (args.rationale !== undefined)
         patch.rationale = args.rationale;
-    const row = unwrap(await client
+    const row = unwrapMaybe(await client
         .from('nodes')
         .update(patch)
         .eq('id', args.id)
@@ -958,7 +974,7 @@ export const setStandingInput = z
 })
     .strict();
 export async function setStanding(client, args) {
-    const node = unwrap(await client
+    const node = unwrapMaybe(await client
         .from('nodes')
         .select('id, workspace_id, label, standing_rationale')
         .eq('id', args.id)
@@ -970,7 +986,7 @@ export async function setStanding(client, args) {
         standing_rationale: args.rationale,
         standing_assessed_at: new Date().toISOString(),
     };
-    const row = unwrap(await client
+    const row = unwrapMaybe(await client
         .from('nodes')
         .update(patch)
         .eq('id', args.id)
@@ -995,7 +1011,7 @@ export async function setStanding(client, args) {
 // ---------------------------------------------------------------------------
 export const archiveConceptInput = z.object({ id: z.string().min(1) }).strict();
 export async function archiveConcept(client, args) {
-    const node = unwrap(await client
+    const node = unwrapMaybe(await client
         .from('nodes')
         .select('id, workspace_id, label, status')
         .eq('id', args.id)
@@ -1005,7 +1021,7 @@ export async function archiveConcept(client, args) {
     if (node.status === 'archived') {
         return { id: node.id, label: node.label, status: node.status, noop: true };
     }
-    const row = unwrap(await client
+    const row = unwrapMaybe(await client
         .from('nodes')
         .update({ status: 'archived' })
         .eq('id', args.id)
@@ -1022,7 +1038,7 @@ export async function archiveConcept(client, args) {
 }
 export const unarchiveConceptInput = z.object({ id: z.string().min(1) }).strict();
 export async function unarchiveConcept(client, args) {
-    const node = unwrap(await client
+    const node = unwrapMaybe(await client
         .from('nodes')
         .select('id, workspace_id, label, status')
         .eq('id', args.id)
@@ -1032,7 +1048,7 @@ export async function unarchiveConcept(client, args) {
     if (node.status !== 'archived') {
         return { id: node.id, label: node.label, status: node.status, noop: true };
     }
-    const row = unwrap(await client
+    const row = unwrapMaybe(await client
         .from('nodes')
         .update({ status: 'open' })
         .eq('id', args.id)
@@ -1049,7 +1065,7 @@ export async function unarchiveConcept(client, args) {
 }
 export const starConceptInput = z.object({ id: z.string().min(1) }).strict();
 export async function starConcept(client, args) {
-    const node = unwrap(await client
+    const node = unwrapMaybe(await client
         .from('nodes')
         .select('id, workspace_id, label, starred')
         .eq('id', args.id)
@@ -1057,7 +1073,7 @@ export async function starConcept(client, args) {
     if (!node)
         return { error: `No concept with id ${args.id}` };
     const next = !node.starred;
-    const row = unwrap(await client
+    const row = unwrapMaybe(await client
         .from('nodes')
         .update({ starred: next })
         .eq('id', args.id)
@@ -1084,7 +1100,7 @@ export async function starConcept(client, args) {
 // in code, collect every descendant, and delete the bottom-up set.
 export const removeConceptInput = z.object({ id: z.string().min(1) }).strict();
 export async function removeConcept(client, args) {
-    const node = unwrap(await client
+    const node = unwrapMaybe(await client
         .from('nodes')
         .select('id, workspace_id, label')
         .eq('id', args.id)
@@ -1100,26 +1116,40 @@ export async function removeConcept(client, args) {
     if (isRoot.length > 0) {
         return { error: 'Cannot delete a project root node.' };
     }
-    // Walk the parent_id subtree in memory (cheaper than depth round-trips).
-    const allNodes = unwrap(await client
-        .from('nodes')
-        .select('id, parent_id')
-        .eq('workspace_id', node.workspace_id));
+    // Walk the subtree via BOTH parent_id AND partition edges. A child can be
+    // attached either way; walking parent_id alone would strand partition-only
+    // children as dangling orphans (the inconsistency surfaced in the rc.17
+    // review — get_subtree counts partition-edge children, so the cascade must
+    // too).
+    const allNodes = unwrap(await client.from('nodes').select('id, parent_id').eq('workspace_id', node.workspace_id));
+    const partEdges = unwrap(await client
+        .from('edges')
+        .select('from_id, to_id')
+        .eq('workspace_id', node.workspace_id)
+        .eq('kind', 'partition'));
     const childrenByParent = new Map();
-    for (const n of allNodes) {
-        if (n.parent_id) {
-            const arr = childrenByParent.get(n.parent_id) ?? [];
-            arr.push(n.id);
-            childrenByParent.set(n.parent_id, arr);
-        }
-    }
+    const addChild = (parent, child) => {
+        const arr = childrenByParent.get(parent) ?? [];
+        arr.push(child);
+        childrenByParent.set(parent, arr);
+    };
+    for (const n of allNodes)
+        if (n.parent_id)
+            addChild(n.parent_id, n.id);
+    for (const e of partEdges)
+        addChild(e.from_id, e.to_id);
     const toDelete = [];
+    const seen = new Set();
     const stack = [args.id];
     while (stack.length > 0) {
         const cur = stack.pop();
+        if (seen.has(cur))
+            continue;
+        seen.add(cur);
         toDelete.push(cur);
-        const kids = childrenByParent.get(cur) ?? [];
-        stack.push(...kids);
+        for (const k of childrenByParent.get(cur) ?? [])
+            if (!seen.has(k))
+                stack.push(k);
     }
     // Delete in one shot — edges/junctions cascade via FK; provenance
     // cascades via FK in 0015's table definition.
@@ -1133,6 +1163,40 @@ export async function removeConcept(client, args) {
     };
 }
 // ---------------------------------------------------------------------------
+// remove_concepts (bulk) — delete many concepts in one call.
+// ---------------------------------------------------------------------------
+// Sequential (not parallel) so a big cleanup can't hammer the backend; each id
+// reuses removeConcept (so each cascades its own subtree). Per-id results are
+// returned so the caller sees exactly what landed — ids already gone (e.g.
+// swept up in another id's cascade) come back ok:false with a not-found error,
+// which is expected, not fatal.
+export const removeConceptsInput = z
+    .object({
+    ids: z
+        .array(z.string().min(1))
+        .min(1)
+        .max(500)
+        .describe('Concept ids to hard-delete. Each cascades its own subtree.'),
+})
+    .strict();
+export async function removeConcepts(client, args) {
+    const results = [];
+    for (const id of args.ids) {
+        const r = (await removeConcept(client, { id }));
+        if (r.error)
+            results.push({ id, ok: false, error: r.error });
+        else
+            results.push({ id, ok: true, cascadeCount: r.cascadeCount });
+    }
+    const ok = results.filter((r) => r.ok).length;
+    return {
+        requested: args.ids.length,
+        deleted: ok,
+        failed: args.ids.length - ok,
+        results,
+    };
+}
+// ---------------------------------------------------------------------------
 // bulk_add_concepts (atomic via fn_bulk_add_concepts RPC)
 // ---------------------------------------------------------------------------
 // Each child resolves its project_id either explicitly (via the item's
@@ -1224,7 +1288,7 @@ export const setParentInput = z
 })
     .strict();
 export async function setParent(client, args) {
-    const node = unwrap(await client
+    const node = unwrapMaybe(await client
         .from('nodes')
         .select('id, workspace_id, parent_id, label')
         .eq('id', args.nodeId)
@@ -1236,7 +1300,7 @@ export async function setParent(client, args) {
     }
     let resolvedParentId = args.newParentId;
     if (resolvedParentId) {
-        const parent = unwrap(await client
+        const parent = unwrapMaybe(await client
             .from('nodes')
             .select('id, workspace_id')
             .eq('id', resolvedParentId)
@@ -1246,6 +1310,22 @@ export async function setParent(client, args) {
         if (parent.workspace_id !== node.workspace_id) {
             return { error: 'Cannot re-parent across workspaces.' };
         }
+        // Cycle guard: the new parent must not sit inside this node's own subtree —
+        // that would detach the subtree from any root and break parent-chain
+        // traversal (get_subtree / get_concept ancestry / remove_concept cascade).
+        const wsNodes = unwrap(await client.from('nodes').select('id, parent_id').eq('workspace_id', node.workspace_id));
+        const parentOf = new Map(wsNodes.map((n) => [n.id, n.parent_id]));
+        let walk = resolvedParentId;
+        const visited = new Set();
+        while (walk && !visited.has(walk)) {
+            if (walk === args.nodeId) {
+                return {
+                    error: "Cannot set parent: the target parent is inside this node's own subtree (would create a cycle).",
+                };
+            }
+            visited.add(walk);
+            walk = parentOf.get(walk) ?? null;
+        }
     }
     // 1) Update parent_id.
     const updRes = await client
@@ -1545,13 +1625,101 @@ export async function updateProject(client, args) {
         lifecycle: row.lifecycle,
     };
 }
-export const deleteProjectInput = z.object({ id: z.string().min(1) }).strict();
+export const deleteProjectInput = z
+    .object({
+    id: z.string().min(1),
+    deleteNodes: z
+        .boolean()
+        .default(false)
+        .describe("Also hard-delete every concept in this project (each cascades its subtree). Default false leaves the nodes behind as orphans — matching prior behavior. Use true to avoid creating orphans."),
+})
+    .strict();
 export async function deleteProject(client, args) {
+    if (args.deleteNodes) {
+        // Capture members BEFORE deleting the project (project_nodes cascades away
+        // with it). Delete the project first so removeConcept's "can't delete a
+        // project root" guard no longer blocks the root node.
+        const members = unwrap(await client.from('project_nodes').select('node_id').eq('project_id', args.id));
+        const del = await client.from('projects').delete().eq('id', args.id);
+        if (del.error)
+            return { error: del.error.message };
+        let nodesDeleted = 0;
+        for (const m of members) {
+            const r = (await removeConcept(client, { id: m.node_id }));
+            // Many members are already gone (swept up in the root's cascade); that
+            // returns a not-found error we simply skip.
+            if (!r.error && typeof r.cascadeCount === 'number')
+                nodesDeleted += r.cascadeCount;
+        }
+        return { id: args.id, deleted: true, nodesDeleted };
+    }
     const del = await client.from('projects').delete().eq('id', args.id);
     if (del.error)
         return { error: del.error.message };
     return { id: args.id, deleted: true };
 }
+// ---------------------------------------------------------------------------
+// find_orphans — surface concepts that no normal traversal reaches.
+// ---------------------------------------------------------------------------
+// Two integrity classes, both confined to the caller's own workspace (RLS):
+//   • projectless  — node in no project (the classic residue of delete_project,
+//                    which leaves nodes behind).
+//   • danglingParent — node whose parent_id points at a row that no longer
+//                    exists (invisible to root traversal, yet still present).
+// Read-only; pair with remove_concepts (to delete) or set_parent (to re-home).
+export const findOrphansInput = z
+    .object({
+    kind: z
+        .enum(['projectless', 'dangling', 'all'])
+        .default('all')
+        .describe("Which orphan class to surface: 'projectless', 'dangling', or 'all'."),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(1000)
+        .default(200)
+        .describe('Max nodes to list per class (counts are always exact).'),
+})
+    .strict();
+export async function findOrphans(client, args) {
+    const wsId = await resolveWorkspaceId(client);
+    const allNodes = unwrap(await client.from('nodes').select('id, label, parent_id, status').eq('workspace_id', wsId));
+    const liveIds = new Set(allNodes.map((n) => n.id));
+    const projects = unwrap(await client.from('projects').select('id').eq('workspace_id', wsId));
+    let memberIds = new Set();
+    if (projects.length > 0) {
+        const pn = unwrap(await client
+            .from('project_nodes')
+            .select('node_id')
+            .in('project_id', projects.map((p) => p.id)));
+        memberIds = new Set(pn.map((r) => r.node_id));
+    }
+    const view = (n) => ({
+        id: n.id,
+        label: n.label,
+        parentId: n.parent_id,
+        status: n.status,
+    });
+    const result = { workspaceId: wsId, totalNodes: allNodes.length };
+    if (args.kind === 'projectless' || args.kind === 'all') {
+        const projectless = allNodes.filter((n) => !memberIds.has(n.id));
+        result.projectless = {
+            count: projectless.length,
+            nodes: projectless.slice(0, args.limit).map(view),
+        };
+    }
+    if (args.kind === 'dangling' || args.kind === 'all') {
+        const dangling = allNodes.filter((n) => n.parent_id && !liveIds.has(n.parent_id));
+        result.danglingParent = {
+            count: dangling.length,
+            nodes: dangling.slice(0, args.limit).map(view),
+        };
+    }
+    result.note =
+        'projectless = in no project (often left by delete_project). danglingParent = parent_id points at a deleted node. To clean up: remove_concepts(ids) to delete, or set_parent to re-home.';
+    return result;
+}
 export const CLOUD_TOOLS = [
     // ── Reads ──────────────────────────────────────────────────────────────
     {
@@ -1673,10 +1841,22 @@ export const CLOUD_TOOLS = [
     },
     {
         name: 'remove_concept',
-        description: 'Hard-delete a concept and its descendants (walks the parent_id subtree). Edges and project/idea memberships cascade via FK. Refuses to delete a project root node.',
+        description: 'Hard-delete a concept and its descendants (walks the subtree via parent_id AND partition edges). Edges and project/idea memberships cascade via FK. Refuses to delete a project root node. For many at once, use remove_concepts.',
         inputSchema: removeConceptInput,
         handler: async (client, args) => removeConcept(client, removeConceptInput.parse(args)),
     },
+    {
+        name: 'remove_concepts',
+        description: "Bulk hard-delete: delete many concepts in one call (each cascades its own subtree). Returns per-id results. Ids already swept up in another id's cascade come back ok:false (not-found) — expected, not fatal. Pair with find_orphans for cleanup.",
+        inputSchema: removeConceptsInput,
+        handler: async (client, args) => removeConcepts(client, removeConceptsInput.parse(args)),
+    },
+    {
+        name: 'find_orphans',
+        description: "Surface concepts no normal traversal reaches, scoped to your workspace: 'projectless' (in no project — typically left behind by delete_project) and 'danglingParent' (parent_id points at a deleted node). Read-only. Clean up with remove_concepts (delete) or set_parent (re-home).",
+        inputSchema: findOrphansInput,
+        handler: async (client, args) => findOrphans(client, findOrphansInput.parse(args)),
+    },
     {
         name: 'bulk_add_concepts',
         description: 'Create many concepts in a single atomic transaction. `items` is an array; each item carries label / description? / parentId? / projectId? / tags?. project_id is resolved per-item (explicit > inherited from parent > workspace solo project). Returns the created ids in input order.',
@@ -1741,7 +1921,7 @@ export const CLOUD_TOOLS = [
     },
     {
         name: 'delete_project',
-        description: "Delete a project. Project_nodes / problem_frames / closed_worlds / lab_matrix_cells cascade via FK. Concepts that belonged to ONLY this project are orphaned (project_id → NULL) — they are NOT auto-deleted.",
+        description: 'Delete a project. By default its concepts are LEFT behind as orphans (find them later with find_orphans). Pass deleteNodes:true to also hard-delete every concept in the project (each cascades its subtree) so no orphans are created.',
         inputSchema: deleteProjectInput,
         handler: async (client, args) => deleteProject(client, deleteProjectInput.parse(args)),
     },

package/package.json

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