@creator-notes/cnotes 0.16.11

package/dist/mcp-server.js

@@ -0,0 +1,782 @@
+#!/usr/bin/env node
+//
+// CN MCP Server — exposes CreatorNotes CLI operations as MCP tools.
+//
+// Claude Desktop config (macOS):
+//   ~/Library/Application Support/Claude/claude_desktop_config.json
+//   {
+//     "mcpServers": {
+//       "cnotes": {
+//         "command": "node",
+//         "args": ["/path/to/pm-notes/cli/dist/mcp-server.js"],
+//         "env": {
+//           "CN_SERVER": "https://your-codespace.app.github.dev",
+//           "CN_TOKEN": "your-token",
+//           "CN_WORKSPACE": "your-workspace-id"
+//         }
+//       }
+//     }
+//   }
+//
+import { readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { ApiClient } from "./lib/api-client.js";
+import { resolveNoteId } from "./lib/resolve-note.js";
+import { readCanvasMarkdown } from "./lib/canvas-read.js";
+import { buildSchema } from "./lib/build-schema.js";
+// ---------------------------------------------------------------------------
+// Environment
+// ---------------------------------------------------------------------------
+const CN_SERVER = process.env.CN_SERVER;
+const CN_TOKEN = process.env.CN_TOKEN;
+const CN_WORKSPACE = process.env.CN_WORKSPACE;
+if (!CN_SERVER || !CN_TOKEN || !CN_WORKSPACE) {
+    const missing = [
+        !CN_SERVER && "CN_SERVER",
+        !CN_TOKEN && "CN_TOKEN",
+        !CN_WORKSPACE && "CN_WORKSPACE",
+    ].filter(Boolean);
+    process.stderr.write(`cnotes-mcp: missing required env vars: ${missing.join(", ")}\n` +
+        "Set them in your Claude Desktop config or shell environment.\n");
+    process.exit(1);
+}
+const api = new ApiClient(CN_SERVER, CN_TOKEN);
+const workspaceId = CN_WORKSPACE;
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function ok(data) {
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}
+function arrowToMarkers(arrow) {
+    switch (arrow) {
+        case "end":
+            return { arrowStart: false, arrowEnd: true };
+        case "start":
+            return { arrowStart: true, arrowEnd: false };
+        case "both":
+            return { arrowStart: true, arrowEnd: true };
+        case "none":
+            return { arrowStart: false, arrowEnd: false };
+        default:
+            return {};
+    }
+}
+function err(message) {
+    return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
+}
+async function withErrorHandling(fn) {
+    try {
+        return ok(await fn());
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        return err(msg);
+    }
+}
+// ---------------------------------------------------------------------------
+// Server
+// ---------------------------------------------------------------------------
+const server = new McpServer({
+    name: "cnotes-mcp",
+    version: "0.3.0",
+});
+// ---------------------------------------------------------------------------
+// Resources
+// ---------------------------------------------------------------------------
+server.resource("workspace-current", "cnotes://workspace/current", async () => ({
+    contents: [
+        {
+            uri: "cnotes://workspace/current",
+            mimeType: "application/json",
+            text: JSON.stringify(await api.get(`/api/workspaces/${workspaceId}`), null, 2),
+        },
+    ],
+}));
+server.resource("types", "cnotes://types", async () => ({
+    contents: [
+        {
+            uri: "cnotes://types",
+            mimeType: "application/json",
+            text: JSON.stringify(await api.get("/api/supertags", { workspaceId }), null, 2),
+        },
+    ],
+}));
+// ---------------------------------------------------------------------------
+// Notes tools
+// ---------------------------------------------------------------------------
+server.tool("cn_notes_list", "List notes in the workspace. Returns metadata by default. Set includeContent=true to include full note content (useful to avoid multiple cn_notes_get calls).", {
+    search: z.string().optional().describe("Full-text search query"),
+    type: z.string().optional().describe("Filter by note type (e.g. Meeting, PRD)"),
+    tags: z.string().optional().describe("Filter by tags (comma-separated)"),
+    pinned: z.boolean().optional().describe("Only show pinned notes"),
+    limit: z.number().optional().default(20).describe("Max results"),
+    includeContent: z.boolean().optional().default(false).describe("Include full note content in results"),
+}, async ({ search, type, tags, pinned, limit, includeContent }) => withErrorHandling(() => api.get("/api/notes", {
+    workspaceId,
+    search,
+    types: type,
+    tags,
+    onlyPinned: pinned ? "true" : undefined,
+    excludeDrafts: "true",
+    excludeContent: includeContent ? undefined : "true",
+    format: includeContent ? "markdown" : undefined,
+    limit: String(limit ?? 20),
+})));
+server.tool("cn_notes_get", "Get one or more notes by display ID (e.g. MEETING-12, PRD-3). Always returns an array, in input order, in a single round-trip. Pass one ID for one note, or many IDs to batch-fetch — never call this tool multiple times in parallel for different IDs.", {
+    ids: z
+        .array(z.string())
+        .min(1)
+        .describe("Display IDs (e.g. ['MEETING-12','PRD-3','IDEA-7']). Pass an array even for a single ID."),
+}, async ({ ids }) => withErrorHandling(async () => {
+    const notesList = await api.get("/api/notes", {
+        workspaceId,
+        exact_ids: ids.join(","),
+        excludeDrafts: "true",
+        format: "markdown",
+    });
+    const found = Array.isArray(notesList) ? notesList : [];
+    const byDisplayId = new Map();
+    for (const n of found) {
+        if (typeof n.displayId === "string")
+            byDisplayId.set(n.displayId, n);
+    }
+    const missing = ids.filter((id) => !byDisplayId.has(id));
+    if (missing.length > 0) {
+        throw new Error(`Notes not found: ${missing.join(", ")}`);
+    }
+    // Preserve input order.
+    return ids.map((id) => byDisplayId.get(id));
+}));
+server.tool("cn_notes_delete", "Delete (archive) a note.", {
+    id: z.string().describe("Note display ID or Convex ID"),
+}, async ({ id }) => withErrorHandling(async () => {
+    const noteId = await resolveNoteId(api, workspaceId, id);
+    return api.delete(`/api/notes/${noteId}`);
+}));
+server.tool("cn_notes_bulk_archive", "Archive or unarchive multiple notes in one operation. More efficient than calling cn_notes_delete multiple times.", {
+    ids: z.array(z.string()).describe("Array of note display IDs or Convex IDs"),
+    unarchive: z.boolean().optional().default(false).describe("Set true to unarchive instead of archive"),
+}, async ({ ids, unarchive }) => withErrorHandling(async () => {
+    const noteIds = await Promise.all(ids.map((id) => resolveNoteId(api, workspaceId, id)));
+    return api.post("/api/notes/bulk", {
+        action: "bulkArchive",
+        noteIds,
+        isArchived: !unarchive,
+    });
+}));
+server.tool("cn_notes_bulk_retype", "Retype multiple notes to a new type in one operation. Each note is atomically retyped (new note created, old archived, cross-linked).", {
+    ids: z.array(z.string()).describe("Array of note display IDs or Convex IDs to retype"),
+    targetType: z.string().describe("Target type name (must be an existing supertag, e.g. 'Insight')"),
+}, async ({ ids, targetType }) => withErrorHandling(async () => {
+    return api.post("/api/notes/bulk", {
+        action: "bulkRetype",
+        workspaceId,
+        noteIds: ids,
+        targetType,
+    });
+}));
+server.tool("cn_notes_update", "Update note metadata (type, tags, pin/archive status). Does NOT change content — use cn_versions_create for that. Title is read-only (derived from # h1 heading in content).", {
+    id: z.string().describe("Note display ID or Convex ID"),
+    type: z.string().optional().describe("New note type (must be an existing supertag, e.g. 'Insight')"),
+    tags: z.string().optional().describe("Replace tags (comma-separated). Use empty string to clear."),
+    pin: z.boolean().optional().describe("Pin the note"),
+    unpin: z.boolean().optional().describe("Unpin the note"),
+    archive: z.boolean().optional().describe("Archive the note"),
+    unarchive: z.boolean().optional().describe("Unarchive the note"),
+}, async ({ id, type, tags, pin, unpin, archive, unarchive }) => withErrorHandling(async () => {
+    const body = {};
+    if (type !== undefined)
+        body.type = type;
+    if (tags !== undefined) {
+        body.tags = tags === "" ? [] : tags.split(",").map((t) => t.trim()).filter(Boolean);
+    }
+    if (pin)
+        body.isPinned = true;
+    if (unpin)
+        body.isPinned = false;
+    if (archive)
+        body.isArchived = true;
+    if (unarchive)
+        body.isArchived = false;
+    if (Object.keys(body).length === 0) {
+        throw new Error("At least one of type, tags, pin, unpin, archive, or unarchive is required");
+    }
+    const noteId = await resolveNoteId(api, workspaceId, id);
+    return api.patch(`/api/notes/${noteId}`, body);
+}));
+const NoteCreateItem = z.object({
+    key: z.string().describe("Unique key for this item, used in @key placeholder cross-references"),
+    type: z.string().describe("Note type (must be an existing supertag, e.g. 'Insight', 'Meeting')"),
+    markdown: z.string().describe("Note content as markdown (the first # h1 heading becomes the title)"),
+    tags: z.array(z.string()).optional().describe("Tags for this note"),
+});
+server.tool("cn_notes_create", "Create one or more interlinked notes in a single atomic transaction. Pass `notes` as a single item object or an array of items. Title is derived from the # h1 heading in each note's markdown. Relationship link syntax inside markdown: use [@key: Title](relationship:references) to cross-reference another note in the same batch (the @key is replaced with the new note's display ID after creation), or [NOTE-12: Title](relationship:references) to reference an existing note. ALWAYS include the `: Title` part — the title-less form `[NOTE-12](relationship:references)` saves a chip with `title: null` that renders as \"Untitled\" in the UI. The relationship name is free-form (e.g. references, supports, triggers); use `references` if unsure. If validation fails, the response includes a structured `details.items` array pinpointing which item (by index + key) is malformed and why.", {
+    notes: z
+        .union([NoteCreateItem, z.array(NoteCreateItem).min(1)])
+        .describe("Either a single item object or a non-empty array of items."),
+}, async ({ notes }) => withErrorHandling(() => api.post("/api/notes/bulk", {
+    action: "bulkCreate",
+    workspaceId,
+    notes: Array.isArray(notes) ? notes : [notes],
+})));
+server.tool("cn_notes_retype", "Change a single note's type. Atomic operation: creates a new note with the target type, archives the old one, and cross-links both.", {
+    noteId: z.string().describe("Display ID of the note to retype (e.g. NOTE-1)"),
+    targetType: z.string().describe("Target type name (must be an existing supertag)"),
+}, async ({ noteId, targetType }) => withErrorHandling(() => api.post("/api/notes/retype", {
+    workspaceId,
+    noteId,
+    targetType,
+})));
+// ---------------------------------------------------------------------------
+// Search tools
+// ---------------------------------------------------------------------------
+server.tool("cn_search_semantic", "Semantic (vector) search across notes. Better for meaning-based queries.", {
+    query: z.string().describe("Search query"),
+    limit: z.number().optional().default(10).describe("Max results"),
+    canvasId: z.string().optional().describe("Scope search to notes on a canvas"),
+}, async ({ query, limit, canvasId }) => withErrorHandling(() => api.post("/api/semantic-search", {
+    query,
+    workspaceId,
+    limit: limit ?? 10,
+    ...(canvasId ? { canvasId } : {}),
+})));
+// ---------------------------------------------------------------------------
+// Canvas tools
+// ---------------------------------------------------------------------------
+server.tool("cn_canvas_list", "List canvases in the workspace. Archived canvases are excluded by default.", {
+    includeArchived: z.boolean().optional().default(false).describe("Include archived canvases"),
+}, async ({ includeArchived }) => withErrorHandling(() => api.get("/api/canvas", {
+    workspaceId,
+    ...(includeArchived ? { includeArchived: "true" } : {}),
+})));
+server.tool("cn_canvas_get", "Get canvas details including nodes, edges, and canvas links. Richtext node content is returned as markdown.", {
+    canvasId: z.string().describe("Canvas ID"),
+}, async ({ canvasId }) => withErrorHandling(() => api.get(`/api/canvas/${encodeURIComponent(canvasId)}`, { workspaceId, format: "markdown" })));
+server.tool("cn_canvas_read", "Read every note on a canvas as one concatenated markdown document, in display order (top-to-bottom, then left-to-right). Use this to think across a canvas in a single round-trip — preferred over canvas_get + N notes_get calls.", {
+    canvasId: z.string().describe("Canvas ID"),
+}, async ({ canvasId }) => withErrorHandling(async () => readCanvasMarkdown(api, workspaceId, canvasId)));
+server.tool("cn_canvas_create", "Create a new canvas. Goal and target audience are required — every canvas must declare its purpose and who it serves.", {
+    name: z.string().describe("Canvas name"),
+    goal: z.string().describe("Canvas goal — the purpose, desired outcome, and what it should communicate (markdown). Required."),
+    targetAudience: z.string().describe("Target audience — who this canvas is meant to serve or inform. Required."),
+}, async ({ name, goal, targetAudience }) => {
+    return withErrorHandling(() => api.post("/api/canvas", { workspaceId, title: name, goal, targetAudience }));
+});
+server.tool("cn_canvas_update", "Update canvas metadata: title, goal (purpose/outcome), and/or target audience. Use this to set or change the intent metadata that guides agents working on this canvas.", {
+    canvasId: z.string().describe("Canvas ID"),
+    title: z.string().optional().describe("New canvas title"),
+    goal: z.string().optional().describe("Canvas goal — the purpose, desired outcome, and what it should communicate (markdown)"),
+    targetAudience: z.string().optional().describe("Target audience — who this canvas is meant to serve or inform"),
+}, async ({ canvasId, title, goal, targetAudience }) => {
+    if (!title && !goal && !targetAudience) {
+        return { content: [{ type: "text", text: "Error: at least one of title, goal, or targetAudience is required" }] };
+    }
+    const body = {};
+    if (title !== undefined)
+        body.title = title;
+    if (goal !== undefined)
+        body.goal = goal;
+    if (targetAudience !== undefined)
+        body.targetAudience = targetAudience;
+    return withErrorHandling(() => api.patch(`/api/canvas/${encodeURIComponent(canvasId)}`, body, { workspaceId }));
+});
+server.tool("cn_canvas_delete", "Delete a canvas.", {
+    canvasId: z.string().describe("Canvas ID"),
+}, async ({ canvasId }) => withErrorHandling(() => api.delete(`/api/canvas/${canvasId}`)));
+server.tool("cn_canvas_archive", "Archive or unarchive a canvas. Archiving is a soft delete (sets archivedAt timestamp). Use unarchive=true to restore.", {
+    canvasId: z.string().describe("Canvas ID"),
+    unarchive: z.boolean().optional().default(false).describe("Set true to unarchive/restore instead of archive"),
+}, async ({ canvasId, unarchive }) => withErrorHandling(() => api.post(`/api/canvas/${canvasId}`, {
+    action: unarchive ? "unarchive" : "archive",
+})));
+server.tool("cn_canvas_set_home", "Set a canvas as the workspace home/default canvas. Clears any previous home canvas.", {
+    canvasId: z.string().describe("Canvas ID to set as home"),
+}, async ({ canvasId }) => withErrorHandling(() => api.post(`/api/canvas/${canvasId}`, { action: "setAsHome" })));
+// --- Deprecated single-item wrappers (delegate to bulk_add) ---
+// Kept for backward compatibility with existing MCP clients.
+server.tool("cn_canvas_add_node", "[Deprecated: use cn_canvas_bulk_add] Add a note to a canvas as a node.", {
+    canvasId: z.string().describe("Canvas ID"),
+    noteId: z.string().describe("Note display ID or Convex ID"),
+    x: z.number().optional().default(100).describe("X position"),
+    y: z.number().optional().default(100).describe("Y position"),
+}, async ({ canvasId, noteId, x, y }) => withErrorHandling(() => api.post(`/api/canvas/${canvasId}`, {
+    action: "bulkAddNodes",
+    items: [{ type: "note", noteId, positionX: x, positionY: y }],
+})));
+server.tool("cn_canvas_add_text", "[Deprecated: use cn_canvas_bulk_add] Add a text annotation node to a canvas.", {
+    canvasId: z.string().describe("Canvas ID"),
+    text: z.string().describe("Text content"),
+    size: z.enum(["heading", "paragraph"]).optional().default("heading").describe("Text size"),
+    color: z.enum(["normal", "muted", "highlighted"]).optional().describe("Color variant"),
+    x: z.number().optional().default(100).describe("X position"),
+    y: z.number().optional().default(100).describe("Y position"),
+}, async ({ canvasId, text, size, color, x, y }) => withErrorHandling(() => api.post(`/api/canvas/${canvasId}`, {
+    action: "bulkAddNodes",
+    items: [{ type: "text", content: text, fontSize: size === "paragraph" ? 18 : 32, colorVariant: color, positionX: x, positionY: y }],
+})));
+server.tool("cn_canvas_add_richtext", "[Deprecated: use cn_canvas_bulk_add] Add a richtext annotation node to a canvas.", {
+    canvasId: z.string().describe("Canvas ID"),
+    content: z.string().describe("Richtext content as markdown. To link to notes, use [NOTE-123: Title](relationship:references)."),
+    size: z.enum(["small", "medium", "large"]).optional().default("small").describe("Display size"),
+    color: z.string().optional().describe("Background color hex"),
+    x: z.number().optional().default(100).describe("X position"),
+    y: z.number().optional().default(100).describe("Y position"),
+}, async ({ canvasId, content, size, color, x, y }) => withErrorHandling(() => api.post(`/api/canvas/${canvasId}`, {
+    action: "bulkAddNodes",
+    items: [{ type: "richtext", content, size, colorHex: color, positionX: x, positionY: y }],
+})));
+server.tool("cn_canvas_add_list", "[Deprecated: use cn_canvas_bulk_add] Add a list/grid node grouping notes on a canvas. The description is the only label; its first paragraph derives the searchable title.", {
+    canvasId: z.string().describe("Canvas ID"),
+    description: z.string().min(1).describe("Rich-text description (markdown). Required. First paragraph derives the searchable title."),
+    noteIds: z.string().optional().describe("Comma-separated note IDs"),
+    viewMode: z.enum(["list", "grid"]).optional().default("list").describe("View mode"),
+    x: z.number().optional().default(100).describe("X position"),
+    y: z.number().optional().default(100).describe("Y position"),
+}, async ({ canvasId, description, noteIds, viewMode, x, y }) => withErrorHandling(() => api.post(`/api/canvas/${canvasId}`, {
+    action: "bulkAddNodes",
+    items: [{
+            type: "list",
+            description,
+            viewMode,
+            noteIds: noteIds ? noteIds.split(",").map((id) => id.trim()) : undefined,
+            positionX: x,
+            positionY: y,
+        }],
+})));
+server.tool("cn_canvas_add_link", "[Deprecated: use cn_canvas_bulk_add] Add a link to another canvas.", {
+    canvasId: z.string().describe("Canvas ID"),
+    targetCanvasId: z.string().describe("Target canvas ID to link to"),
+    x: z.number().optional().default(100).describe("X position"),
+    y: z.number().optional().default(100).describe("Y position"),
+}, async ({ canvasId, targetCanvasId, x, y }) => withErrorHandling(() => api.post(`/api/canvas/${canvasId}`, {
+    action: "bulkAddNodes",
+    items: [{ type: "canvas", linkedCanvasId: targetCanvasId, positionX: x, positionY: y }],
+})));
+// --- Primary bulk tool ---
+server.tool("cn_canvas_bulk_add", "Add one or more items to a canvas. Use this for ALL canvas additions — single or multiple. Supports all node types: note, text, richtext, list, canvas (link to another canvas), and edge. ALWAYS prefer this over repeated single-item calls. Items are processed in order so edges can reference nodes created earlier in the same batch via sourceItemIndex/targetItemIndex.", {
+    canvasId: z.string().describe("Canvas ID"),
+    notes: z.array(z.object({
+        noteId: z.string().describe("Note display ID or Convex ID"),
+        x: z.number().describe("X position"),
+        y: z.number().describe("Y position"),
+    })).optional().describe("Legacy: array of note nodes (backward compat). Use 'items' for mixed types."),
+    items: z.array(z.discriminatedUnion("type", [
+        z.object({
+            type: z.literal("note"),
+            noteId: z.string().describe("Note display ID or Convex ID"),
+            x: z.number().describe("X position"),
+            y: z.number().describe("Y position"),
+        }),
+        z.object({
+            type: z.literal("text"),
+            content: z.string().describe("Text content"),
+            x: z.number().describe("X position"),
+            y: z.number().describe("Y position"),
+            fontSize: z.number().optional().describe("Font size (default 18, h1=32, h2=24)"),
+            colorVariant: z.enum(["normal", "muted", "highlighted"]).optional(),
+        }),
+        z.object({
+            type: z.literal("richtext"),
+            content: z.string().describe("Markdown content. To link to notes, use [NOTE-123: Title](relationship:references)."),
+            x: z.number().describe("X position"),
+            y: z.number().describe("Y position"),
+            size: z.enum(["small", "medium", "large"]).optional().describe("Node size"),
+            colorHex: z.string().optional().describe("Background color hex"),
+        }),
+        z.object({
+            type: z.literal("list"),
+            description: z.string().min(1).describe("Rich-text description (markdown). Required. First paragraph derives the searchable title — this is the only label for list nodes."),
+            x: z.number().describe("X position"),
+            y: z.number().describe("Y position"),
+            viewMode: z.enum(["list", "grid"]).optional(),
+            noteIds: z.array(z.string()).optional().describe("Note IDs to add as list items"),
+        }),
+        z.object({
+            type: z.literal("canvas"),
+            linkedCanvasId: z.string().describe("Canvas ID to link to"),
+            x: z.number().describe("X position"),
+            y: z.number().describe("Y position"),
+        }),
+        z.object({
+            type: z.literal("edge"),
+            sourceNodeId: z.string().optional().describe("Existing source node ID"),
+            targetNodeId: z.string().optional().describe("Existing target node ID"),
+            sourceItemIndex: z.number().optional().describe("Index of source item in this batch (0-based)"),
+            targetItemIndex: z.number().optional().describe("Index of target item in this batch (0-based)"),
+            label: z.string().optional().describe("Edge label"),
+        }),
+    ])).optional().describe("Array of items to add (supports all node types and edges). Item indices for edges are relative to this array, not the merged result."),
+}, async ({ canvasId, notes, items }) => withErrorHandling(() => {
+    // Normalize: convert legacy notes to items format, merge with items
+    const noteItems = (notes ?? []).map((n) => ({
+        type: "note",
+        noteId: n.noteId,
+        positionX: n.x,
+        positionY: n.y,
+    }));
+    const noteOffset = noteItems.length;
+    const allItems = [
+        ...noteItems,
+        ...(items ?? []).map((item) => {
+            if (item.type === 'edge') {
+                // Shift sourceItemIndex/targetItemIndex to account for prepended legacy notes
+                return {
+                    ...item,
+                    sourceItemIndex: item.sourceItemIndex != null ? item.sourceItemIndex + noteOffset : undefined,
+                    targetItemIndex: item.targetItemIndex != null ? item.targetItemIndex + noteOffset : undefined,
+                };
+            }
+            const { x, y, ...rest } = item;
+            return { ...rest, positionX: x, positionY: y };
+        }),
+    ];
+    return api.post(`/api/canvas/${canvasId}`, {
+        action: "bulkAddNodes",
+        items: allItems,
+    });
+}));
+server.tool("cn_canvas_place", "Place items on a canvas using a DECLARATIVE LAYOUT (no x/y math). The server measures every item, packs them with no overlaps, and inserts them in a single batch. PREFER THIS over cn_canvas_bulk_add whenever you can express the layout as stacks/grids/anchors — which is almost always. The agent should describe STRUCTURE (rows, columns, what's near what), not pixel coordinates.\n\nThe call is best-effort, NOT atomic: per-item failures are reported in the response (HTTP 207) but the items that succeeded stay on the canvas. Always inspect `items[].error` and `edges[].error` in the response.\n\nThe `doc` argument is a layout document:\n  { root: <LayoutNode>, edges?: [{from, to, label?}], origin?: {x, y} }\n\n<LayoutNode> is one of:\n  • { kind: 'stack',  axis: 'vertical'|'horizontal', gap?: 'tight'|'medium'|'spacious'|<px>, align?: 'start'|'center'|'end', items: [<LayoutNode>...] }\n  • { kind: 'grid',   columns: <n>, gap?: ..., items: [<LayoutNode>...] }\n  • { kind: 'anchor', to: '<displayId or canvas node id>', direction: 'right'|'left'|'above'|'below', gap?: ..., child: <LayoutNode> }\n  • { kind: 'item',   type: 'note'|'text'|'richtext'|'list'|'canvas', key?: '<name>', ...item-specific fields }\n\nLeaf item shapes (no x/y!):\n  note:     { kind:'item', type:'note', noteId:'NOTE-3', key?:'a' }\n  text:     { kind:'item', type:'text', content:'Hello', fontSize?:32, colorVariant?:'normal'|'muted'|'highlighted' }\n  richtext: { kind:'item', type:'richtext', content:'# Markdown OK', size?:'small'|'medium'|'large', colorHex?:'#3B82F6' }\n  list:     { kind:'item', type:'list', name:'My list', noteIds?:['NOTE-1','NOTE-2'], viewMode?:'list'|'grid' }\n  canvas:   { kind:'item', type:'canvas', linkedCanvasId:'<id>' }\n\nEdges reference endpoints by, in priority order: `@<key>` (any item with a `key` placed in the same call), the original noteId/displayId of a note placed in this call (e.g. 'NOTE-7'), or the displayId / convex id of a node already on the canvas.\n\nExample (a SWOT-like quadrant):\n  {\n    root: {\n      kind:'stack', axis:'vertical', gap:'spacious',\n      items:[\n        { kind:'stack', axis:'horizontal', gap:'spacious', items:[\n          { kind:'grid', columns:2, items:[\n            { kind:'item', type:'note', noteId:'STR-1' },\n            { kind:'item', type:'note', noteId:'STR-2' },\n          ]},\n          { kind:'grid', columns:2, items:[\n            { kind:'item', type:'note', noteId:'WEAK-1' },\n          ]},\n        ]},\n        { kind:'stack', axis:'horizontal', gap:'spacious', items:[ /* opportunities + threats */ ]},\n      ],\n    },\n  }", {
+    canvasId: z.string().describe("Canvas ID"),
+    doc: z.any().describe("Layout document. See tool description for shape."),
+}, async ({ canvasId, doc }) => withErrorHandling(() => api.post(`/api/canvas/${encodeURIComponent(canvasId)}?workspaceId=${encodeURIComponent(workspaceId)}`, {
+    action: "placeLayout",
+    doc,
+})));
+server.tool("cn_canvas_bulk_move", "Move multiple nodes to new positions in one operation. More efficient than calling cn_canvas_move_node multiple times.", {
+    canvasId: z.string().describe("Canvas ID"),
+    moves: z.array(z.object({
+        nodeId: z.string().describe("Canvas node ID"),
+        nodeType: z.enum(["note", "text", "list", "canvas", "richtext"]).optional().default("note").describe("Node type"),
+        x: z.number().describe("New X position"),
+        y: z.number().describe("New Y position"),
+    })).describe("Array of node moves"),
+}, async ({ canvasId, moves }) => withErrorHandling(() => api.post(`/api/canvas/${canvasId}`, {
+    action: "bulkMoveNodes",
+    moves: moves.map((m) => ({
+        nodeId: m.nodeId,
+        nodeType: m.nodeType || "note",
+        positionX: m.x,
+        positionY: m.y,
+    })),
+})));
+server.tool("cn_canvas_bulk_remove", "Remove multiple nodes from a canvas in one operation. More efficient than calling cn_canvas_remove_node multiple times.", {
+    canvasId: z.string().describe("Canvas ID"),
+    nodeIds: z.array(z.string()).describe("Array of node IDs to remove"),
+}, async ({ canvasId, nodeIds }) => withErrorHandling(() => api.post(`/api/canvas/${canvasId}`, {
+    action: "bulkRemoveNodes",
+    nodeIds,
+})));
+server.tool("cn_canvas_add_edge", "Connect two nodes on a canvas with an edge. Defaults to an arrow at the target end and a solid line.", {
+    canvasId: z.string().describe("Canvas ID"),
+    sourceNodeId: z.string().describe("Source node ID"),
+    targetNodeId: z.string().describe("Target node ID"),
+    label: z.string().optional().describe("Edge label"),
+    arrow: z
+        .enum(["end", "start", "both", "none"])
+        .optional()
+        .describe("Arrow direction (default: end)"),
+    lineStyle: z
+        .enum(["solid", "dashed"])
+        .optional()
+        .describe("Line style (default: solid)"),
+}, async ({ canvasId, sourceNodeId, targetNodeId, label, arrow, lineStyle }) => withErrorHandling(() => {
+    const markers = arrowToMarkers(arrow);
+    return api.post(`/api/canvas/${canvasId}`, {
+        action: "addEdge",
+        sourceNodeId,
+        targetNodeId,
+        label,
+        ...markers,
+        lineStyle,
+    });
+}));
+server.tool("cn_canvas_update_edge", "Update an edge: change its label, toggle arrowheads, switch line style, or reverse direction. Only the fields you pass are changed.", {
+    canvasId: z.string().describe("Canvas ID"),
+    edgeId: z.string().describe("Canvas edge ID"),
+    label: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("Set label text, or pass null to clear it"),
+    arrow: z
+        .enum(["end", "start", "both", "none"])
+        .optional()
+        .describe("Arrow direction"),
+    lineStyle: z.enum(["solid", "dashed"]).optional().describe("Line style"),
+    reverse: z.boolean().optional().describe("Swap source and target nodes"),
+}, async ({ canvasId, edgeId, label, arrow, lineStyle, reverse }) => withErrorHandling(() => {
+    const body = {
+        action: "updateEdge",
+        edgeId,
+    };
+    if (label !== undefined)
+        body.label = label;
+    if (arrow !== undefined)
+        Object.assign(body, arrowToMarkers(arrow));
+    if (lineStyle !== undefined)
+        body.lineStyle = lineStyle;
+    if (reverse !== undefined)
+        body.reverse = reverse;
+    return api.post(`/api/canvas/${canvasId}`, body);
+}));
+server.tool("cn_canvas_move_node", "Move a node to a new position on a canvas.", {
+    canvasId: z.string().describe("Canvas ID"),
+    nodeId: z.string().describe("Canvas node ID"),
+    nodeType: z.enum(["note", "text", "list", "canvas", "richtext"]).optional().default("note").describe("Node type"),
+    x: z.number().describe("New X position"),
+    y: z.number().describe("New Y position"),
+}, async ({ canvasId, nodeId, nodeType, x, y }) => withErrorHandling(() => api.post(`/api/canvas/${canvasId}`, {
+    action: "moveNode",
+    nodeId,
+    nodeType,
+    positionX: x,
+    positionY: y,
+})));
+server.tool("cn_canvas_remove_node", "Remove a node from a canvas.", {
+    canvasId: z.string().describe("Canvas ID"),
+    nodeId: z.string().describe("Canvas node ID"),
+}, async ({ canvasId, nodeId }) => withErrorHandling(() => api.post(`/api/canvas/${canvasId}`, {
+    action: "removeNode",
+    nodeId,
+})));
+server.tool("cn_canvas_remove_edge", "Remove an edge from a canvas.", {
+    canvasId: z.string().describe("Canvas ID"),
+    edgeId: z.string().describe("Canvas edge ID"),
+}, async ({ canvasId, edgeId }) => withErrorHandling(() => api.post(`/api/canvas/${canvasId}`, {
+    action: "removeEdge",
+    edgeId,
+})));
+server.tool("cn_canvas_digest", "Get the AI-generated digest of a canvas: narrative summary, key themes, and a per-note summary list covering every note on the canvas. Run this first when starting work on any canvas — it gives you full orientation in a single call, so you don't need to read each note individually. Each note entry has shape { displayId, title, type, summary }; when summary is null the AI summary hasn't generated yet. The notes list is always populated, even when digest status is 'none' or 'stale'.", {
+    canvasId: z.string().describe("Canvas ID"),
+}, async ({ canvasId }) => withErrorHandling(() => api.get(`/api/canvas/${encodeURIComponent(canvasId)}/digest`, { workspaceId })));
+server.tool("cn_canvas_digest_generate", "Request digest (re)generation for a canvas. Use when digest status is 'none' or you want a fresh summary. The digest is generated async — poll cn_canvas_digest after ~60s.", {
+    canvasId: z.string().describe("Canvas ID"),
+}, async ({ canvasId }) => withErrorHandling(() => api.post(`/api/canvas/${encodeURIComponent(canvasId)}/digest?workspaceId=${encodeURIComponent(workspaceId)}`, {})));
+server.tool("cn_canvas_activity", "Show recent activity on a canvas — edits, agent runs, gestures, restores — newest first. Use this to find out what changed and who changed it before making further edits, or to confirm a previous agent run actually applied. Returns { canvasName, operations: Array<{ _id, operationType, actorName, actorSource ('human'|'agent'|'import'|'api'), agentRunId, userPrompt, status ('in_progress'|'applied'|'reverted'|'failed'), eventCount, affectedEntityIds, summary, structuredSummary: { headline, summary, byCategory[], themes[] }, startedAt, completedAt }>}.", {
+    canvasId: z.string().describe("Canvas ID"),
+    limit: z.number().int().min(1).max(200).optional().describe("Max entries (default 50, max 200)"),
+}, async ({ canvasId, limit }) => {
+    const params = { workspaceId };
+    if (limit !== undefined)
+        params.limit = String(limit);
+    return withErrorHandling(() => api.get(`/api/canvas/${encodeURIComponent(canvasId)}/activity`, params));
+});
+server.tool("cn_canvas_templates", "List available canvas templates.", {}, async () => withErrorHandling(() => api.get("/api/canvas/template")));
+server.tool("cn_canvas_from_template", "Create a canvas from a predefined template.", {
+    templateId: z.string().describe("Template ID"),
+    title: z.string().optional().describe("Custom canvas title"),
+}, async ({ templateId, title }) => withErrorHandling(() => api.post("/api/canvas/template", {
+    workspaceId,
+    templateId,
+    title,
+})));
+// ---------------------------------------------------------------------------
+// Timeline
+// ---------------------------------------------------------------------------
+server.tool("cn_timeline", "Show recent changes across notes. Supports relative time (7d, 2w) or ISO dates.", {
+    since: z.string().optional().default("7d").describe("Start of range (e.g. 7d, 2w, 2026-03-21)"),
+    until: z.string().optional().describe("End of range (default: now)"),
+    type: z.string().optional().describe("Filter by note type (comma-separated)"),
+    noteFilter: z.string().optional().describe("Filter by note ID or title substring"),
+    limit: z.number().optional().default(50).describe("Max results (1-100)"),
+}, async ({ since, until, type, noteFilter, limit }) => withErrorHandling(() => {
+    const sinceMs = parseDuration(since ?? "7d");
+    const untilMs = until ? parseDuration(until) : undefined;
+    return api.get("/api/timeline", {
+        workspaceId,
+        afterTimestamp: String(sinceMs),
+        beforeTimestamp: untilMs ? String(untilMs) : undefined,
+        limit: String(Math.max(1, Math.min(100, limit ?? 50))),
+        noteTypes: type,
+        noteFilter,
+    });
+}));
+const DURATION_UNITS = {
+    m: 60_000,
+    h: 3_600_000,
+    d: 86_400_000,
+    w: 604_800_000,
+};
+function parseDuration(input) {
+    const rel = input.match(/^(\d+)([mhdw])$/);
+    if (rel) {
+        return Date.now() - parseInt(rel[1], 10) * DURATION_UNITS[rel[2]];
+    }
+    if (/^\d{10,13}$/.test(input)) {
+        const n = parseInt(input, 10);
+        return input.length <= 10 ? n * 1000 : n;
+    }
+    const ms = new Date(input).getTime();
+    if (isNaN(ms))
+        throw new Error(`Invalid date: "${input}"`);
+    return ms;
+}
+// ---------------------------------------------------------------------------
+// Types (supertags)
+// ---------------------------------------------------------------------------
+server.tool("cn_types_list", "List note types (supertags) in the workspace.", {}, async () => withErrorHandling(() => api.get("/api/supertags", { workspaceId })));
+server.tool("cn_types_create", "Create a new note type (supertag).", {
+    name: z.string().describe("Type name, PascalCase, no spaces (e.g. PainPoint, UserStory)"),
+    displayName: z.string().optional().describe("Display name (can have spaces)"),
+    prefix: z.string().optional().describe("ID prefix, uppercase (e.g. PAINPOINT, USERSTORY)"),
+    description: z.string().optional().describe("Description"),
+    color: z.string().optional().describe("Color hex code (e.g. #FF5733)"),
+}, async ({ name, displayName, prefix, description, color }) => withErrorHandling(() => api.post("/api/supertags", {
+    workspaceId,
+    name,
+    displayName,
+    prefix,
+    description,
+    color,
+})));
+server.tool("cn_types_update", "Update a note type (supertag).", {
+    name: z.string().describe("Type name to update"),
+    displayName: z.string().optional().describe("New display name"),
+    prefix: z.string().optional().describe("New ID prefix (uppercase)"),
+    description: z.string().optional().describe("New description"),
+    color: z.string().optional().describe("Color hex code"),
+}, async ({ name, displayName, prefix, description, color }) => withErrorHandling(() => {
+    const body = { workspaceId, name };
+    if (displayName !== undefined)
+        body.displayName = displayName;
+    if (prefix !== undefined)
+        body.prefix = prefix;
+    if (description !== undefined)
+        body.description = description;
+    if (color !== undefined)
+        body.color = color;
+    return api.patch("/api/supertags", body);
+}));
+// ---------------------------------------------------------------------------
+// Relationships
+// ---------------------------------------------------------------------------
+server.tool("cn_relationships_list", "List note relationships in the workspace.", {
+    noteDisplayId: z.string().optional().describe("Filter by note display ID"),
+}, async ({ noteDisplayId }) => withErrorHandling(() => api.get("/api/relationships", {
+    workspaceId,
+    displayId: noteDisplayId,
+})));
+// ---------------------------------------------------------------------------
+// Memory (Zep)
+// ---------------------------------------------------------------------------
+server.tool("cn_memory_query", "Search facts and entities in the knowledge graph by relevance.", {
+    query: z.string().describe("Search query"),
+    limit: z.number().optional().default(10).describe("Max results per category"),
+}, async ({ query, limit }) => withErrorHandling(() => api.post("/api/zep/query", {
+    workspaceId,
+    query,
+    limit: limit ?? 10,
+})));
+server.tool("cn_memory_facts", "List all workspace facts from the knowledge graph.", {}, async () => withErrorHandling(async () => {
+    const data = await api.post("/api/zep/query", {
+        workspaceId,
+        query: "all facts",
+        limit: 1,
+    });
+    return data.allFacts;
+}));
+server.tool("cn_memory_entities", "List all workspace entities (people, topics, orgs) from the knowledge graph.", {}, async () => withErrorHandling(async () => {
+    const data = await api.post("/api/zep/query", {
+        workspaceId,
+        query: "all entities",
+        limit: 1,
+    });
+    return data.allEntities;
+}));
+// ---------------------------------------------------------------------------
+// Versions
+// ---------------------------------------------------------------------------
+server.tool("cn_versions_list", "List versions of a note.", {
+    noteId: z.string().describe("Note display ID or Convex ID"),
+}, async ({ noteId }) => withErrorHandling(async () => {
+    const notesList = await api.get("/api/notes", {
+        workspaceId,
+        exact_id: noteId,
+        includeVersions: "true",
+    });
+    const note = Array.isArray(notesList) ? notesList[0] : null;
+    if (!note)
+        throw new Error(`Note not found: ${noteId}`);
+    return note.versions || [];
+}));
+server.tool("cn_versions_create", "Create a new version of a note. Content is markdown. To link to other notes, use [NOTE-123: Title](relationship:references) inside the markdown — always include the title (the part after the colon) or the chip renders as 'Untitled'. The relationship name is free-form (e.g. references, triggers, caused-by); use 'references' if unsure.", {
+    noteId: z.string().describe("Note display ID or Convex ID"),
+    markdown: z.string().describe("New content as markdown"),
+    description: z.string().describe("Change description (required)"),
+}, async ({ noteId, markdown, description }) => withErrorHandling(async () => {
+    const resolvedId = await resolveNoteId(api, workspaceId, noteId);
+    return api.post(`/api/notes/${resolvedId}/versions`, {
+        content: markdown,
+        description,
+    });
+}));
+// ---------------------------------------------------------------------------
+// Workspace
+// ---------------------------------------------------------------------------
+server.tool("cn_workspace_list", "List all workspaces the authenticated user belongs to.", {}, async () => withErrorHandling(() => api.get("/api/workspaces")));
+server.tool("cn_workspace_current", "Get details about the current workspace.", {}, async () => withErrorHandling(() => api.get(`/api/workspaces/${workspaceId}`)));
+// ---------------------------------------------------------------------------
+// Files
+// ---------------------------------------------------------------------------
+const FILE_MIME_MAP = {
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+};
+server.tool("cn_files_upload", "Upload an image file to the workspace. Returns the public URL. Supports .jpg, .jpeg, .png, .gif, .webp (max 5MB).", {
+    filePath: z.string().describe("Absolute path to the image file on disk"),
+}, async ({ filePath }) => withErrorHandling(async () => {
+    const absPath = path.resolve(filePath);
+    let stat;
+    try {
+        stat = statSync(absPath);
+    }
+    catch {
+        throw new Error(`File not found: ${absPath}`);
+    }
+    if (!stat.isFile())
+        throw new Error(`Not a file: ${absPath}`);
+    if (stat.size > 5 * 1024 * 1024)
+        throw new Error(`File too large (${stat.size} bytes). Maximum is 5MB.`);
+    const ext = path.extname(absPath).toLowerCase();
+    const mimeType = FILE_MIME_MAP[ext];
+    if (!mimeType)
+        throw new Error(`Unsupported file type: ${ext}. Allowed: .jpg, .jpeg, .png, .gif, .webp`);
+    const buffer = readFileSync(absPath);
+    const filename = path.basename(absPath);
+    const buildFormData = () => {
+        const fd = new FormData();
+        fd.append("image", new Blob([buffer], { type: mimeType }), filename);
+        fd.append("workspaceId", workspaceId);
+        return fd;
+    };
+    const result = await api.postFormData("/api/upload-image", buildFormData);
+    return {
+        ...result,
+        fullUrl: `${CN_SERVER}${result.url}`,
+        markdown: `![${filename}](${CN_SERVER}${result.url})`,
+    };
+}));
+// ---------------------------------------------------------------------------
+// Schema
+// ---------------------------------------------------------------------------
+server.tool("cn_schema", "Describe this workspace in one call: valid note types (with prefixes), common relationship slugs, resource field shapes, and the canvas node kinds. Call this once at the start of a session instead of guessing type names or reading docs.", {}, async () => withErrorHandling(() => buildSchema(api, workspaceId)));
+// ---------------------------------------------------------------------------
+// Start
+// ---------------------------------------------------------------------------
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    process.stderr.write("cnotes-mcp server running on stdio\n");
+}
+main().catch((e) => {
+    process.stderr.write(`cnotes-mcp fatal: ${e}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=mcp-server.js.map