@heuresis/mcp 1.0.0-rc.1

package/dist/tools.js

@@ -0,0 +1,264 @@
+// Read-only tools exposed by the heuresis-mcp v0 server.
+//
+// All tools are designed to be cheap, deterministic, and side-effect free.
+// Agent-write tools (append_concept, set_parent, …) are intentionally
+// deferred — they need a provenance + write-back path through the running
+// app, which is real Phase 12 work.
+import { z } from 'zod';
+const MAX_RESULTS = 50;
+// Bulk tool results are folded into the agent's next API request. Oversized
+// payloads get reset in transit by strict corporate proxies (ECONNRESET), so
+// bulk tools default to a compact view and the agent opts into full text per
+// node via get_concept.
+const detailArg = z
+    .enum(['compact', 'full'])
+    .default('compact')
+    .describe("'compact' drops description/rationale to keep the payload small; 'full' includes them.");
+/** A flat, agent-friendly view of a Node (drops position/embedding). */
+function nodeView(n, detail = 'full') {
+    const base = {
+        id: n.id,
+        label: n.label,
+        status: n.status,
+        starred: n.starred,
+        parentId: n.parentId,
+        operator: n.operator?.family,
+        partitionAttribute: n.partitionAttribute,
+        tags: n.tags,
+        updatedAt: new Date(n.updatedAt).toISOString(),
+    };
+    if (detail === 'compact')
+        return base;
+    return { ...base, description: n.description, rationale: n.rationale };
+}
+// ── get_workspace_summary ───────────────────────────────────────────────────
+export const getWorkspaceSummaryInput = z.object({}).strict();
+export async function getWorkspaceSummary(store) {
+    const [workspaces, nodes, edges, projects, ideas] = await Promise.all([
+        store.workspaces(),
+        store.nodes(),
+        store.edges(),
+        store.projects(),
+        store.ideas(),
+    ]);
+    return {
+        snapshotPath: store.getSnapshotPath(),
+        workspaces: workspaces.map((w) => ({ id: w.id, name: w.name })),
+        counts: {
+            nodes: nodes.length,
+            edges: edges.length,
+            projects: projects.length,
+            ideas: ideas.length,
+        },
+        projects: projects.map((p) => ({
+            id: p.id,
+            name: p.name,
+            brief: p.brief,
+            direction: p.direction,
+            lifecycle: p.lifecycle,
+            nodeCount: p.nodeIds.length,
+            rootNodeId: p.rootNodeId,
+        })),
+        ideas: ideas.map((i) => ({
+            id: i.id,
+            name: i.name,
+            nodeCount: i.nodeIds.length,
+            color: i.color,
+        })),
+    };
+}
+// ── search_concepts ─────────────────────────────────────────────────────────
+export const searchConceptsInput = z
+    .object({
+    query: z.string().describe('Substring matched against label, description, tags, partitionAttribute.'),
+    limit: z.number().int().min(1).max(MAX_RESULTS).default(20),
+    projectId: z.string().optional().describe('Restrict results to nodes belonging to this project.'),
+    status: z.enum(['open', 'validated', 'archived']).optional(),
+    detail: detailArg,
+})
+    .strict();
+export async function searchConcepts(store, args) {
+    const q = args.query.toLowerCase().trim();
+    const allNodes = await store.nodes();
+    const project = args.projectId ? await store.projectById(args.projectId) : null;
+    const allowed = project ? new Set(project.nodeIds) : null;
+    const hits = allNodes
+        .filter((n) => {
+        if (allowed && !allowed.has(n.id))
+            return false;
+        if (args.status && n.status !== args.status)
+            return false;
+        if (!q)
+            return true;
+        const hay = [
+            n.label,
+            n.description,
+            n.partitionAttribute ?? '',
+            n.rationale ?? '',
+            (n.tags ?? []).join(' '),
+        ]
+            .join(' ')
+            .toLowerCase();
+        return hay.includes(q);
+    })
+        .sort((a, b) => b.updatedAt - a.updatedAt)
+        .slice(0, args.limit)
+        .map((n) => nodeView(n, args.detail));
+    return { query: q, total: hits.length, detail: args.detail, results: hits };
+}
+// ── get_concept ─────────────────────────────────────────────────────────────
+export const getConceptInput = z
+    .object({
+    id: z.string(),
+    includeAncestry: z.boolean().default(true),
+    includeChildren: z.boolean().default(true),
+    includeIdeaMemberships: z.boolean().default(true),
+})
+    .strict();
+export async function getConcept(store, args) {
+    const node = await store.nodeById(args.id);
+    if (!node)
+        return { error: `No concept with id ${args.id}` };
+    const out = { node: nodeView(node) };
+    if (args.includeAncestry) {
+        const chain = [];
+        const seen = new Set();
+        let cur = node.parentId;
+        while (cur && !seen.has(cur)) {
+            seen.add(cur);
+            const p = await store.nodeById(cur);
+            if (!p)
+                break;
+            chain.unshift({ id: p.id, label: p.label });
+            cur = p.parentId;
+        }
+        out.ancestry = chain;
+    }
+    if (args.includeChildren) {
+        const kids = await store.childrenOf(node.id);
+        out.children = kids.map((k) => ({ id: k.id, label: k.label, status: k.status }));
+    }
+    if (args.includeIdeaMemberships) {
+        const ideas = await store.ideas();
+        out.ideaMemberships = ideas
+            .filter((i) => i.nodeIds.includes(node.id))
+            .map((i) => ({ id: i.id, name: i.name, color: i.color }));
+    }
+    return out;
+}
+// ── get_subtree ─────────────────────────────────────────────────────────────
+export const getSubtreeInput = z
+    .object({
+    rootId: z.string(),
+    depth: z.number().int().min(0).max(6).default(3).describe('How many generations below the root to include.'),
+    detail: detailArg,
+})
+    .strict();
+export async function getSubtree(store, args) {
+    const root = await store.nodeById(args.rootId);
+    if (!root)
+        return { error: `No concept with id ${args.rootId}` };
+    const nodes = await store.descendantsOf(args.rootId, args.depth);
+    return {
+        rootId: args.rootId,
+        depth: args.depth,
+        detail: args.detail,
+        nodeCount: nodes.length,
+        nodes: nodes.map((n) => nodeView(n, args.detail)),
+    };
+}
+// ── list_projects ───────────────────────────────────────────────────────────
+export const listProjectsInput = z.object({}).strict();
+export async function listProjects(store) {
+    const projects = await store.projects();
+    return {
+        projects: projects.map((p) => ({
+            id: p.id,
+            name: p.name,
+            brief: p.brief,
+            direction: p.direction,
+            lifecycle: p.lifecycle,
+            nodeCount: p.nodeIds.length,
+            rootNodeId: p.rootNodeId,
+        })),
+    };
+}
+// ── get_project_graph ───────────────────────────────────────────────────────
+export const getProjectGraphInput = z
+    .object({
+    projectId: z.string(),
+    includeArchived: z.boolean().default(false),
+    detail: detailArg,
+})
+    .strict();
+export async function getProjectGraph(store, args) {
+    const project = await store.projectById(args.projectId);
+    if (!project)
+        return { error: `No project with id ${args.projectId}` };
+    const memberIds = new Set(project.nodeIds);
+    const [allNodes, allEdges] = await Promise.all([store.nodes(), store.edges()]);
+    const nodes = allNodes
+        .filter((n) => memberIds.has(n.id))
+        .filter((n) => (args.includeArchived ? true : n.status !== 'archived'));
+    const nodeIdSet = new Set(nodes.map((n) => n.id));
+    const edges = allEdges
+        .filter((e) => nodeIdSet.has(e.fromId) && nodeIdSet.has(e.toId))
+        .map((e) => ({ from: e.fromId, to: e.toId, kind: e.kind }));
+    return {
+        project: {
+            id: project.id,
+            name: project.name,
+            brief: project.brief,
+            direction: project.direction,
+            lifecycle: project.lifecycle,
+            rootNodeId: project.rootNodeId,
+        },
+        detail: args.detail,
+        nodeCount: nodes.length,
+        edgeCount: edges.length,
+        nodes: nodes.map((n) => nodeView(n, args.detail)),
+        edges,
+    };
+}
+// ── list_recent_decisions ───────────────────────────────────────────────────
+export const listRecentDecisionsInput = z
+    .object({
+    sinceMs: z
+        .number()
+        .int()
+        .optional()
+        .describe('Unix-ms cutoff; default = last 7 days.'),
+    limit: z.number().int().min(1).max(MAX_RESULTS).default(20),
+})
+    .strict();
+export async function listRecentDecisions(store, args) {
+    const cutoff = args.sinceMs ?? Date.now() - 7 * 24 * 60 * 60 * 1000;
+    const allNodes = await store.nodes();
+    // "Decisions" = validated, starred, or just-archived nodes — the ones
+    // the user has explicitly resolved one way or the other.
+    const decisions = allNodes
+        .filter((n) => n.updatedAt >= cutoff &&
+        (n.starred || n.status === 'validated' || n.status === 'archived'))
+        .sort((a, b) => b.updatedAt - a.updatedAt)
+        .slice(0, args.limit)
+        .map((n) => ({
+        id: n.id,
+        label: n.label,
+        status: n.status,
+        starred: n.starred,
+        updatedAt: new Date(n.updatedAt).toISOString(),
+        decision: n.status === 'validated'
+            ? 'validated'
+            : n.status === 'archived'
+                ? 'archived'
+                : n.starred
+                    ? 'starred'
+                    : 'open',
+    }));
+    return {
+        sinceMs: cutoff,
+        since: new Date(cutoff).toISOString(),
+        count: decisions.length,
+        decisions,
+    };
+}

package/dist/types.js

@@ -0,0 +1,5 @@
+// Mirror of the relevant subset of src/types/domain.ts from the main app.
+// Kept inline rather than imported across packages so this server is a
+// standalone npm package — drop into any agent setup without the rest of
+// the Heuresis monorepo.
+export {};

package/dist/zod-to-json-schema.js

@@ -0,0 +1,89 @@
+// Minimal zod → JSON-Schema converter. We only support the shapes our
+// tool inputs use (object roots with string/number/boolean/enum/optional/
+// default leaves + a description). This avoids pulling in the heavy
+// `zod-to-json-schema` npm package for a couple-hundred-byte job.
+import { z } from 'zod';
+function leafSchema(schema) {
+    // Peel optional/default/describe wrappers, recording metadata as we go.
+    let cur = schema;
+    let description;
+    let defaultValue;
+    // Capture `.describe(...)` text from any wrapper level.
+    if (cur.description) {
+        description = cur.description;
+    }
+    while (cur instanceof z.ZodOptional ||
+        cur instanceof z.ZodDefault ||
+        cur instanceof z.ZodNullable) {
+        if (cur instanceof z.ZodDefault) {
+            defaultValue = cur._def.defaultValue();
+        }
+        cur = cur._def.innerType ?? cur;
+        if (!description &&
+            cur.description) {
+            description = cur.description;
+        }
+    }
+    const out = {};
+    if (cur instanceof z.ZodString)
+        out.type = 'string';
+    else if (cur instanceof z.ZodNumber) {
+        out.type = 'number';
+        // z.number().int() — there's no clean API, but checks live on _def.checks.
+        const checks = cur._def
+            .checks;
+        if (checks) {
+            for (const c of checks) {
+                if (c.kind === 'int')
+                    out.type = 'integer';
+                if (c.kind === 'min' && typeof c.value === 'number')
+                    out.minimum = c.value;
+                if (c.kind === 'max' && typeof c.value === 'number')
+                    out.maximum = c.value;
+            }
+        }
+    }
+    else if (cur instanceof z.ZodBoolean)
+        out.type = 'boolean';
+    else if (cur instanceof z.ZodEnum) {
+        out.type = 'string';
+        out.enum = [...cur.options];
+    }
+    else if (cur instanceof z.ZodLiteral) {
+        out.enum = [cur.value];
+    }
+    else if (cur instanceof z.ZodArray) {
+        out.type = 'array';
+    }
+    else if (cur instanceof z.ZodObject) {
+        // Nested object — recurse via the public path.
+        return zodToJsonSchema(cur);
+    }
+    else {
+        // Unknown / unsupported — fall back to "any".
+    }
+    if (description)
+        out.description = description;
+    if (defaultValue !== undefined)
+        out.default = defaultValue;
+    return out;
+}
+export function zodToJsonSchema(schema) {
+    const shape = schema.shape;
+    const properties = {};
+    const required = [];
+    for (const [key, value] of Object.entries(shape)) {
+        properties[key] = leafSchema(value);
+        const isOptional = value instanceof z.ZodOptional || value instanceof z.ZodDefault;
+        if (!isOptional)
+            required.push(key);
+    }
+    const out = {
+        type: 'object',
+        properties,
+        additionalProperties: false,
+    };
+    if (required.length > 0)
+        out.required = required;
+    return out;
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@heuresis/mcp",
+  "version": "1.0.0-rc.1",
+  "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": {
+    "heuresis-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://heuresis.app/mcp",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ToremLabs/Heuresis.git",
+    "directory": "mcp-server"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "heuresis",
+    "ideation",
+    "knowledge-graph",
+    "claude-code",
+    "claude-desktop",
+    "cursor"
+  ],
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.40.0",
+    "@google/generative-ai": "^0.21.0",
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@supabase/supabase-js": "^2.45.0",
+    "openai": "^4.71.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "@types/node": "^22.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "AGPL-3.0-or-later"
+}