@mentagen/mcp 0.7.0 → 0.8.1

package/dist/index.js

@@ -2,6 +2,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { createMentagenClient } from './client/helene.js';
+import { registerPrompts } from './prompts/index.js';
 import { registerResources } from './resources/index.js';
 import { registerTools } from './tools/index.js';
 import { loadConfig } from './utils/config.js';
@@ -15,9 +16,11 @@ async function main() {
         capabilities: {
             tools: {},
             resources: {},
+            prompts: {},
         },
     });
     registerResources(mcpServer);
+    registerPrompts(mcpServer);
     registerTools(mcpServer.server, client, config);
     const transport = new StdioServerTransport();
     await mcpServer.connect(transport);

package/dist/prompts/index.js

@@ -0,0 +1,259 @@
+/**
+ * Comprehensive guide for AI agents on using Mentagen nodes effectively.
+ */
+const NODE_USAGE_GUIDE = `# Mentagen Node Usage Guide
+
+## Node Types Overview
+
+Mentagen supports several node types, each designed for specific use cases:
+
+### Markdown Nodes (Recommended for Most Content)
+- **Type**: \`markdown\`
+- **Default Color**: cyan
+- **Best For**: Documentation, notes, articles, structured content
+- **Features**:
+  - Full GitHub Flavored Markdown (GFM) support
+  - **Todos/Checklists**: Only markdown nodes support the todos feature
+  - Rich formatting with headers, lists, code blocks, tables
+- **When to Use**: Default choice for most text content
+
+### Code Nodes
+- **Type**: \`code\`
+- **Default Color**: indigo
+- **Best For**: Source code, scripts, configuration files
+- **Features**:
+  - Syntax highlighting for many languages
+  - Monospace font optimized for code
+  - **No todo support** - use markdown nodes for task lists
+- **When to Use**: When content is primarily source code
+- **Naming Convention**: Include file extension (e.g., "utils.ts", "config.json")
+
+### Text Nodes
+- **Type**: \`text\`
+- **Default Color**: none (neutral)
+- **Best For**: Simple labels, titles, short notes
+- **When to Use**: Brief content that doesn't need formatting
+
+### URL Nodes
+- **Type**: \`url\`
+- **Default Color**: blue
+- **Best For**: Bookmarks, external references, documentation links
+- **When to Use**: Storing links to external resources
+
+## Todo/Checklist Support
+
+### CRITICAL: Use Native Todos, NOT Markdown Checkboxes
+
+**ALWAYS use the native todo API** (\`mentagen_add_todo\`, \`mentagen_toggle_todo\`, etc.) instead of writing markdown checkboxes (\`- [ ]\`) in the content field.
+
+**Why native todos are better:**
+- Proper tracking with \`mentagen_list_todos\` showing completion stats
+- Toggle completion with \`mentagen_toggle_todo\` without rewriting content
+- Todos render as interactive checkboxes in the Mentagen UI
+- Each todo has a unique ID for precise manipulation
+
+**Wrong approach (don't do this):**
+\`\`\`
+mentagen_update_node({
+  content: "- [ ] Task 1\\n- [ ] Task 2"  // NO! This is just text
+})
+\`\`\`
+
+**Correct approach:**
+\`\`\`
+mentagen_add_todo({ text: "Task 1" })
+mentagen_add_todo({ text: "Task 2" })
+\`\`\`
+
+### Node Granularity
+
+Create **separate nodes for distinct task lists** rather than one giant node:
+
+- **Good**: "Sprint 1 Tasks" node, "Sprint 2 Tasks" node, "Backlog" node
+- **Bad**: One "All Tasks" node with 50 todos
+
+Each focused node should have:
+- A clear, descriptive name (the node title)
+- Related todos that belong together
+- Optional markdown content for context/notes
+
+### Supported Node Types
+
+**Only markdown and text nodes support todos.** Code nodes do NOT support todos.
+
+### Todo Operations
+- \`mentagen_add_todo\`: Add individual tasks (auto-generates UUID and order)
+- \`mentagen_toggle_todo\`: Mark tasks complete/incomplete
+- \`mentagen_list_todos\`: View all todos with completion statistics
+- \`mentagen_update_node\` with \`todos\` array: Replace all todos at once
+
+## Node Positioning
+
+### Grid System
+- 1 grid unit = 16 pixels
+- Positions snap to grid automatically
+- Use \`mentagen_find_position\` to find non-colliding positions
+
+### Spacing Guidelines
+- **Connected nodes** (with edges): Use gap of 6+ units (96px+)
+- **Unrelated nodes**: Gap of 1 unit (16px) is sufficient
+- Nodes auto-size based on their title, not content
+
+## Common Patterns
+
+### Creating a Task Board
+1. Create a markdown node for the task list
+2. Add todos using \`mentagen_add_todo\`
+3. Use \`mentagen_toggle_todo\` to track completion
+
+### Documentation Structure
+1. Use markdown nodes for content sections
+2. Connect related nodes with edges
+3. Use consistent colors for categories
+
+### Code Organization
+1. Use code nodes for source files
+2. Name nodes with file extensions
+3. Group related code with edges
+`;
+/**
+ * Guide specifically for creating and managing todo lists.
+ */
+const TODO_GUIDE = `# Creating Checklists with Todos
+
+## IMPORTANT: Native Todos vs Markdown Checkboxes
+
+**ALWAYS use native todos** via the todo API tools. Do NOT write markdown checkboxes in content.
+
+| Approach | Method | Result |
+|----------|--------|--------|
+| **CORRECT** | \`mentagen_add_todo({ text: "Task" })\` | Interactive checkbox, trackable |
+| **WRONG** | \`content: "- [ ] Task"\` | Just text, not trackable |
+
+Native todos provide:
+- Completion tracking via \`mentagen_list_todos\`
+- Toggle without rewriting content
+- Interactive checkboxes in UI
+- Unique IDs for each todo
+
+## Node Granularity Best Practices
+
+Create **focused nodes for related tasks**, not one giant task dump:
+
+**Good structure:**
+- "Feature A - Tasks" (5 todos)
+- "Feature B - Tasks" (3 todos)  
+- "Bug Fixes" (4 todos)
+
+**Bad structure:**
+- "All Project Tasks" (50 todos in one node)
+
+Each task node should:
+- Have a clear, descriptive title
+- Contain only related todos
+- Optionally include context in the markdown content field
+
+## Quick Start
+
+### Option A: Create node with initial todos (recommended for bulk)
+
+\`\`\`
+mentagen_create_node({
+  boardId: "...",
+  name: "Sprint 1 Tasks",
+  type: "markdown",
+  content: "Tasks for the first sprint milestone.",
+  todos: [
+    { text: "Implement auth" },
+    { text: "Write tests" },
+    { text: "Update docs" }
+  ]
+})
+\`\`\`
+
+Note: Just provide "text" for each todo. The id and order are auto-generated.
+
+### Option B: Create node then add todos one by one
+
+1. **Create a markdown node** for your task list:
+   \`\`\`
+   mentagen_create_node({
+     boardId: "...",
+     name: "Sprint 1 Tasks",
+     type: "markdown",
+     content: "Tasks for the first sprint milestone."
+   })
+   \`\`\`
+
+2. **Add todos using the API** (not markdown syntax):
+   \`\`\`
+   mentagen_add_todo({ boardId: "...", nodeId: "...", text: "Implement auth" })
+   mentagen_add_todo({ boardId: "...", nodeId: "...", text: "Write tests" })
+   mentagen_add_todo({ boardId: "...", nodeId: "...", text: "Update docs" })
+   \`\`\`
+
+3. **Check progress**:
+   \`\`\`
+   mentagen_list_todos({ boardId: "...", nodeId: "..." })
+   \`\`\`
+   Returns: \`{ summary: { total: 3, completed: 0, remaining: 3 } }\`
+
+4. **Mark complete**:
+   \`\`\`
+   mentagen_toggle_todo({ boardId: "...", nodeId: "...", todoId: "..." })
+   \`\`\`
+
+## Supported Node Types
+
+- **Markdown nodes**: Full todo support ✓
+- **Text nodes**: Full todo support ✓
+- **Code nodes**: NO todo support ✗
+
+## Bulk Operations
+
+To set all todos at once (useful for importing):
+\`\`\`
+mentagen_update_node({
+  boardId: "...",
+  nodeId: "...",
+  todos: [
+    { id: "uuid-1", text: "Task 1", completed: false, order: 0 },
+    { id: "uuid-2", text: "Task 2", completed: true, order: 1 }
+  ]
+})
+\`\`\`
+`;
+export function registerPrompts(mcpServer) {
+    // Enable prompts capability
+    mcpServer.server.registerCapabilities({
+        prompts: {
+            listChanged: true,
+        },
+    });
+    mcpServer.registerPrompt('node-usage-guide', {
+        description: 'Comprehensive guide for using Mentagen nodes effectively, including node types, todos, and best practices.',
+    }, async () => ({
+        messages: [
+            {
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: NODE_USAGE_GUIDE,
+                },
+            },
+        ],
+    }));
+    mcpServer.registerPrompt('todo-checklist-guide', {
+        description: 'Step-by-step guide for creating and managing todo lists/checklists on Mentagen nodes.',
+    }, async () => ({
+        messages: [
+            {
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: TODO_GUIDE,
+                },
+            },
+        ],
+    }));
+}

package/dist/tools/batch-update.js

@@ -2,15 +2,32 @@ import { z } from 'zod';
 import { formatError } from '../utils/errors.js';
 import { unitsToPixels } from '../utils/units.js';
 import { snapToGrid } from './grid-calc.js';
+import { validateTypeChange } from './update.js';
+const todoItemSchema = z.object({
+    id: z.string().describe('Unique identifier (UUID v4)'),
+    text: z.string().describe('Todo text content'),
+    completed: z.boolean().describe('Completion status'),
+    order: z.number().describe('Sort order (0-based)'),
+});
 const nodeUpdateSchema = z.object({
     nodeId: z.string().describe('The node ID to update'),
+    type: z
+        .enum(['markdown', 'code', 'url'])
+        .optional()
+        .describe('Change node type. Safe conversions: markdown ↔ code. Content is auto-migrated.'),
     name: z.string().optional().describe('New name for the node'),
     content: z.string().optional().describe('New content for the node'),
+    code: z.string().optional().describe('Code content for code-type nodes'),
+    url: z.string().optional().describe('URL for url-type nodes'),
     color: z.string().optional().describe('Node color'),
     x: z.number().optional().describe('X position in grid units'),
     y: z.number().optional().describe('Y position in grid units'),
     width: z.number().optional().describe('Node width in grid units'),
     height: z.number().optional().describe('Node height in grid units'),
+    todos: z
+        .array(todoItemSchema)
+        .optional()
+        .describe('Replace all todos on this markdown node. Only markdown/text nodes support todos.'),
 });
 const edgeUpdateSchema = z.object({
     edgeId: z.string().describe('The edge ID to update'),
@@ -25,6 +42,79 @@ export const batchUpdateSchema = z.object({
     nodes: z.array(nodeUpdateSchema).optional().describe('Array of node updates'),
     edges: z.array(edgeUpdateSchema).optional().describe('Array of edge updates'),
 });
+const POSITION_FIELDS = ['x', 'y', 'width', 'height'];
+/**
+ * Process type change and return migration fields or error.
+ */
+async function processNodeTypeChange(client, boardId, nodeId, targetType, data) {
+    try {
+        const currentNode = await client.getNode({ boardId, nodeId });
+        if (targetType === currentNode.type) {
+            return { success: true, fields: {} };
+        }
+        const result = validateTypeChange(currentNode.type, targetType, currentNode, {
+            ...data,
+            type: targetType,
+            boardId,
+            nodeId,
+            autoSize: true,
+        });
+        if (!result.valid) {
+            return { success: false, error: result.error };
+        }
+        return { success: true, fields: result.fields };
+    }
+    catch (error) {
+        return { success: false, error: formatError(error) };
+    }
+}
+/**
+ * Convert data fields to update format with pixel conversion.
+ */
+function buildNodeUpdateData(data, migrationFields) {
+    const cleanData = {
+        ...migrationFields,
+    };
+    for (const [key, value] of Object.entries(data)) {
+        if (value === undefined)
+            continue;
+        if (POSITION_FIELDS.includes(key)) {
+            cleanData[key] = snapToGrid(unitsToPixels(value));
+        }
+        else if (key === 'todos') {
+            cleanData[key] = value;
+        }
+        else {
+            cleanData[key] = value;
+        }
+    }
+    return cleanData;
+}
+/**
+ * Process a single node update.
+ */
+async function processNodeUpdate(client, boardId, update) {
+    const { nodeId, type: targetType, ...data } = update;
+    let migrationFields = {};
+    if (targetType !== undefined) {
+        const typeResult = await processNodeTypeChange(client, boardId, nodeId, targetType, data);
+        if (!typeResult.success) {
+            return { id: nodeId, success: false, error: typeResult.error };
+        }
+        migrationFields = typeResult.fields;
+    }
+    const cleanData = buildNodeUpdateData(data, migrationFields);
+    if (Object.keys(cleanData).length === 0) {
+        return { id: nodeId, success: false, error: 'No fields to update' };
+    }
+    try {
+        await client.updateNode({ boardId, nodeId, data: cleanData });
+        return { id: nodeId, success: true };
+    }
+    catch (error) {
+        return { id: nodeId, success: false, error: formatError(error) };
+    }
+}
 export async function handleBatchUpdate(client, params) {
     const nodeUpdates = params.nodes ?? [];
     const edgeUpdates = params.edges ?? [];
@@ -43,36 +133,7 @@ export async function handleBatchUpdate(client, params) {
         nodes: [],
         edges: [],
     };
-    // Process node updates in parallel
-    const nodePromises = nodeUpdates.map(async (update) => {
-        const { nodeId, ...data } = update;
-        // Filter out undefined values and convert position fields from units to pixels
-        const cleanData = {};
-        for (const [key, value] of Object.entries(data)) {
-            if (value !== undefined) {
-                if (key === 'x' || key === 'y' || key === 'width' || key === 'height') {
-                    cleanData[key] = snapToGrid(unitsToPixels(value));
-                }
-                else {
-                    cleanData[key] = value;
-                }
-            }
-        }
-        if (Object.keys(cleanData).length === 0) {
-            return { id: nodeId, success: false, error: 'No fields to update' };
-        }
-        try {
-            await client.updateNode({
-                boardId: params.boardId,
-                nodeId,
-                data: cleanData,
-            });
-            return { id: nodeId, success: true };
-        }
-        catch (error) {
-            return { id: nodeId, success: false, error: formatError(error) };
-        }
-    });
+    const nodePromises = nodeUpdates.map(update => processNodeUpdate(client, params.boardId, update));
     // Process edge updates in parallel
     const edgePromises = edgeUpdates.map(async (update) => {
         const { edgeId, direction, label } = update;

package/dist/tools/create-graph.js

@@ -1,9 +1,17 @@
 import { z } from 'zod';
 import { formatError } from '../utils/errors.js';
 import { pixelsToUnits, unitsToPixels } from '../utils/units.js';
-import { applyExtension, generateId } from './create.js';
+import { applyExtension, generateId, normalizeTodos } from './create.js';
 import { snapToGrid } from './grid-calc.js';
 import { calculateNodeSize } from './size-calc.js';
+const todoInputSchema = z.object({
+    text: z.string().describe('Todo text content'),
+    completed: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe('Completion status (default: false)'),
+});
 const nodeInputSchema = z.object({
     tempId: z.string().describe('Temporary ID for referencing in edges'),
     name: z.string().describe('The node title/name'),
@@ -13,15 +21,19 @@ const nodeInputSchema = z.object({
         .describe('File extension to append to name (e.g., ".ts", ".py"). Only applies to code nodes. Defaults to .js.'),
     content: z.string().optional().describe('Node content'),
     type: z
-        .enum(['text', 'markdown', 'code', 'url'])
+        .enum(['markdown', 'code', 'url'])
         .optional()
-        .default('text')
+        .default('markdown')
         .describe('Node type'),
     color: z.string().optional().describe('Node color'),
     x: z.number().optional().describe('X position in grid units'),
     y: z.number().optional().describe('Y position in grid units'),
     width: z.number().optional().describe('Width in grid units'),
     height: z.number().optional().describe('Height in grid units'),
+    todos: z
+        .array(todoInputSchema)
+        .optional()
+        .describe('Initial todos for the node. Only supported on markdown/text nodes. Only text is required; id and order are auto-generated.'),
 });
 const edgeInputSchema = z.object({
     source: z.string().describe('Source node tempId'),
@@ -46,24 +58,32 @@ const DEFAULT_NODE_COLORS = {
     code: 'indigo',
     url: 'blue',
 };
+/** Calculate snapped pixel dimensions for a node. */
+function calcNodeDimensions(nodeInput, autoSize) {
+    const DEFAULT_POS = 6;
+    return {
+        x: snapToGrid(unitsToPixels(nodeInput.x ?? DEFAULT_POS)),
+        y: snapToGrid(unitsToPixels(nodeInput.y ?? DEFAULT_POS)),
+        width: snapToGrid(nodeInput.width !== undefined
+            ? unitsToPixels(nodeInput.width)
+            : autoSize.width),
+        height: snapToGrid(nodeInput.height !== undefined
+            ? unitsToPixels(nodeInput.height)
+            : autoSize.height),
+    };
+}
 async function createNode(client, boardId, nodeInput, idMap) {
     const realId = generateId();
     const type = nodeInput.type ?? 'text';
     const finalName = applyExtension(nodeInput.name, type, nodeInput.extension);
     const color = nodeInput.color ?? DEFAULT_NODE_COLORS[type];
     const autoSize = calculateNodeSize(finalName, type);
-    const xPixels = snapToGrid(nodeInput.x !== undefined ? unitsToPixels(nodeInput.x) : unitsToPixels(6));
-    const yPixels = snapToGrid(nodeInput.y !== undefined ? unitsToPixels(nodeInput.y) : unitsToPixels(6));
-    const widthPixels = snapToGrid(nodeInput.width !== undefined
-        ? unitsToPixels(nodeInput.width)
-        : autoSize.width);
-    const heightPixels = snapToGrid(nodeInput.height !== undefined
-        ? unitsToPixels(nodeInput.height)
-        : autoSize.height);
+    const dims = calcNodeDimensions(nodeInput, autoSize);
+    const isCodeNode = type === 'code';
+    const nodeContent = nodeInput.content ?? '';
+    // Only pass todos for non-code nodes
+    const todos = !isCodeNode && nodeInput.todos ? normalizeTodos(nodeInput.todos) : undefined;
     try {
-        // For code nodes, store content in the `code` field
-        const isCodeNode = type === 'code';
-        const nodeContent = nodeInput.content ?? '';
         const node = await client.addNode({
             _id: realId,
             boardId,
@@ -72,10 +92,11 @@ async function createNode(client, boardId, nodeInput, idMap) {
                 ...(isCodeNode ? { code: nodeContent } : { content: nodeContent }),
                 type,
                 color,
-                x: xPixels,
-                y: yPixels,
-                width: widthPixels,
-                height: heightPixels,
+                x: dims.x,
+                y: dims.y,
+                width: dims.width,
+                height: dims.height,
+                ...(todos && { todos }),
             },
         });
         idMap[nodeInput.tempId] = node._id;
@@ -85,10 +106,10 @@ async function createNode(client, boardId, nodeInput, idMap) {
                 tempId: nodeInput.tempId,
                 id: node._id,
                 name: node.name,
-                x: pixelsToUnits(xPixels),
-                y: pixelsToUnits(yPixels),
-                width: pixelsToUnits(widthPixels),
-                height: pixelsToUnits(heightPixels),
+                x: pixelsToUnits(dims.x),
+                y: pixelsToUnits(dims.y),
+                width: pixelsToUnits(dims.width),
+                height: pixelsToUnits(dims.height),
             },
         };
     }

package/dist/tools/create.js

@@ -1,3 +1,4 @@
+import { randomUUID } from 'crypto';
 import { z } from 'zod';
 import { formatError } from '../utils/errors.js';
 import { pixelsToUnits, unitsToPixels } from '../utils/units.js';
@@ -14,7 +15,6 @@ import { calculateNodeSize } from './size-calc.js';
  */
 const DEFAULT_NODE_COLORS = {
     // Currently supported in MCP
-    text: undefined,
     markdown: 'cyan',
     code: 'indigo',
     url: 'blue',
@@ -49,7 +49,7 @@ export const createSchema = z.object({
         .string()
         .optional()
         .describe('File extension to append to name (e.g., ".ts", ".py"). Only applies to code nodes. Defaults to .js.'),
-    content: z.string().optional().describe('Content for text/markdown nodes.'),
+    content: z.string().optional().describe('Content for markdown nodes.'),
     code: z
         .string()
         .optional()
@@ -59,10 +59,10 @@ export const createSchema = z.object({
         .optional()
         .describe('The URL for url-type nodes (e.g., https://example.com). Required for type="url".'),
     type: z
-        .enum(['text', 'markdown', 'code', 'url'])
+        .enum(['markdown', 'code', 'url'])
         .optional()
-        .default('text')
-        .describe('Node type: text (default), markdown, code, or url'),
+        .default('markdown')
+        .describe('Node type: markdown (default), code, or url'),
     color: z
         .string()
         .optional()
@@ -77,6 +77,17 @@ export const createSchema = z.object({
         .number()
         .optional()
         .describe('Height in grid units (default: auto-calculated)'),
+    todos: z
+        .array(z.object({
+        text: z.string().describe('Todo text content'),
+        completed: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe('Completion status (default: false)'),
+    }))
+        .optional()
+        .describe('Initial todos for the node. Only supported on markdown/text nodes, not code nodes. Only text is required; id and order are auto-generated.'),
 });
 /**
  * Generate a simple ObjectId-like string.
@@ -89,6 +100,19 @@ export function generateId() {
     const random = Array.from({ length: 16 }, () => Math.floor(Math.random() * 16).toString(16)).join('');
     return timestamp + random;
 }
+/**
+ * Normalize todos by generating ids and orders.
+ * Auto-generates UUID for id, defaults completed to false,
+ * and assigns order based on array index.
+ */
+export function normalizeTodos(todos) {
+    return todos.map((todo, index) => ({
+        id: randomUUID(),
+        text: todo.text,
+        completed: todo.completed ?? false,
+        order: index,
+    }));
+}
 /**
  * Build node fields object with content mapped to the correct field based on type.
  * Expects params.name to already have extension applied.
@@ -102,6 +126,7 @@ function buildNodeFields(params, color, position) {
     };
     if (params.type === 'code') {
         nodeFields.code = params.code ?? params.content ?? '';
+        // Code nodes don't support todos - ignore if provided
     }
     else if (params.type === 'url') {
         if (!params.url) {
@@ -111,9 +136,15 @@ function buildNodeFields(params, color, position) {
         if (params.content) {
             nodeFields.content = params.content;
         }
+        if (params.todos) {
+            nodeFields.todos = normalizeTodos(params.todos);
+        }
     }
     else {
         nodeFields.content = params.content || '';
+        if (params.todos) {
+            nodeFields.todos = normalizeTodos(params.todos);
+        }
     }
     return nodeFields;
 }

package/dist/tools/extract-board-content.js

@@ -41,6 +41,16 @@ function stripHtml(html) {
         .replace(/'/g, "'")
         .trim();
 }
+/**
+ * Format todos as markdown checkboxes.
+ */
+function formatTodos(todos) {
+    if (!todos || todos.length === 0)
+        return '';
+    const sorted = [...todos].sort((a, b) => a.order - b.order);
+    const lines = sorted.map(t => `- [${t.completed ? 'x' : ' '}] ${t.text}`);
+    return lines.join('\n');
+}
 /**
  * Infer programming language from file extension.
  */
@@ -121,6 +131,7 @@ function formatContent(node) {
  */
 function formatNodeSection(node, baseUrl, boardId) {
     const content = formatContent(node);
+    const todos = formatTodos(node.todos);
     const link = getNodeUrl(baseUrl, boardId, node._id);
     const lines = [
         `## ${node.name}`,
@@ -128,6 +139,12 @@ function formatNodeSection(node, baseUrl, boardId) {
         '',
         content,
     ];
+    // Add todos section if present
+    if (todos) {
+        if (content)
+            lines.push('', '### Todos', '');
+        lines.push(todos);
+    }
     return lines.join('\n');
 }
 export async function handleExtractBoardContent(client, params, baseUrl) {
@@ -150,12 +167,13 @@ export async function handleExtractBoardContent(client, params, baseUrl) {
                 ],
             };
         }
-        // Filter nodes based on content
+        // Filter nodes based on content or todos
         const nodesWithContent = params.includeEmpty
             ? nodes
             : nodes.filter(n => {
                 const content = getNodeContent(n);
-                return content && content.trim().length > 0;
+                const hasTodos = n.todos && n.todos.length > 0;
+                return (content && content.trim().length > 0) || hasTodos;
             });
         if (nodesWithContent.length === 0) {
             return {

package/dist/tools/index.js

@@ -26,6 +26,7 @@ import { handleRead, readSchema } from './read.js';
 import { handleSearch, searchSchema } from './search.js';
 import { handleSearchBoards, searchBoardsSchema } from './search-boards.js';
 import { handleSizeCalc, sizeCalcSchema } from './size-calc.js';
+import { addTodoSchema, handleAddTodo, handleListTodos, handleToggleTodo, listTodosSchema, toggleTodoSchema, } from './todo.js';
 import { handleUpdate, updateSchema } from './update.js';
 import { handleUpdateBoard, updateBoardSchema } from './update-board.js';
 import { handleUpdateEdge, updateEdgeSchema } from './update-edge.js';
@@ -251,7 +252,7 @@ export function registerTools(server, client, config) {
             },
             {
                 name: 'mentagen_create_node',
-                description: 'Create a new node on a Mentagen board. IMPORTANT: Do NOT provide width/height - let auto-sizing calculate dimensions from the name. Only provide explicit dimensions if the user specifically requests a custom size. Content does not affect size (it scrolls inside the node).',
+                description: 'Create a new node on a Mentagen board. IMPORTANT: Do NOT provide width/height - let auto-sizing calculate dimensions from the name. Only provide explicit dimensions if the user specifically requests a custom size. Content does not affect size (it scrolls inside the node). For task lists, pass todos array to create with initial checklist items.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -296,6 +297,21 @@ export function registerTools(server, client, config) {
                             type: 'number',
                             description: 'DO NOT USE unless user requests specific size. Auto-calculated from name.',
                         },
+                        todos: {
+                            type: 'array',
+                            description: 'Initial todos for the node. Only supported on markdown/text nodes, not code nodes. Just provide text; id and order are auto-generated.',
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    text: { type: 'string', description: 'Todo text content' },
+                                    completed: {
+                                        type: 'boolean',
+                                        description: 'Completion status (default: false)',
+                                    },
+                                },
+                                required: ['text'],
+                            },
+                        },
                     },
                     required: ['boardId', 'name'],
                 },
@@ -508,7 +524,7 @@ export function registerTools(server, client, config) {
             },
             {
                 name: 'mentagen_create_graph',
-                description: 'Create multiple nodes with edges in a single call. IMPORTANT: Do NOT provide width/height for nodes - let auto-sizing calculate dimensions from names. Only provide explicit dimensions if the user specifically requests custom sizes.',
+                description: 'Create multiple nodes with edges in a single call. IMPORTANT: Do NOT provide width/height for nodes - let auto-sizing calculate dimensions from names. Only provide explicit dimensions if the user specifically requests custom sizes. Nodes can include initial todos for task lists.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -560,6 +576,18 @@ export function registerTools(server, client, config) {
                                         type: 'number',
                                         description: 'Height in grid units (1 unit = 16px, DO NOT USE - auto-calculated from name)',
                                     },
+                                    todos: {
+                                        type: 'array',
+                                        description: 'Initial todos for markdown/text nodes. Just provide text; id and order are auto-generated.',
+                                        items: {
+                                            type: 'object',
+                                            properties: {
+                                                text: { type: 'string' },
+                                                completed: { type: 'boolean', default: false },
+                                            },
+                                            required: ['text'],
+                                        },
+                                    },
                                 },
                                 required: ['tempId', 'name'],
                             },
@@ -887,6 +915,73 @@ export function registerTools(server, client, config) {
                     required: ['boardId'],
                 },
             },
+            // Todo tools
+            {
+                name: 'mentagen_add_todo',
+                description: 'Add a new todo item to a markdown node. Generates a unique ID and appends to the end of the list. Note: Only markdown/text nodes support todos; code nodes do not.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        boardId: {
+                            type: 'string',
+                            description: 'The board ID containing the node',
+                        },
+                        nodeId: {
+                            type: 'string',
+                            description: 'The node ID to add the todo to',
+                        },
+                        text: {
+                            type: 'string',
+                            description: 'The todo text content',
+                        },
+                    },
+                    required: ['boardId', 'nodeId', 'text'],
+                },
+            },
+            {
+                name: 'mentagen_toggle_todo',
+                description: 'Toggle a todo item completion status on a markdown node. Can set explicit state or toggle current state.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        boardId: {
+                            type: 'string',
+                            description: 'The board ID containing the node',
+                        },
+                        nodeId: {
+                            type: 'string',
+                            description: 'The node ID containing the todo',
+                        },
+                        todoId: {
+                            type: 'string',
+                            description: 'The todo ID to toggle',
+                        },
+                        completed: {
+                            type: 'boolean',
+                            description: 'Set explicit completion state. Omit to toggle current state.',
+                        },
+                    },
+                    required: ['boardId', 'nodeId', 'todoId'],
+                },
+            },
+            {
+                name: 'mentagen_list_todos',
+                description: 'List all todo items on a markdown node with summary statistics (total, completed, remaining).',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        boardId: {
+                            type: 'string',
+                            description: 'The board ID containing the node',
+                        },
+                        nodeId: {
+                            type: 'string',
+                            description: 'The node ID to list todos from',
+                        },
+                    },
+                    required: ['boardId', 'nodeId'],
+                },
+            },
         ],
     }));
     const toolHandlers = {
@@ -1011,6 +1106,19 @@ export function registerTools(server, client, config) {
             const params = visualizeBoardSchema.parse(args);
             return handleVisualizeBoard(client, params);
         },
+        // Todo handlers
+        mentagen_add_todo: async (args) => {
+            const params = addTodoSchema.parse(args);
+            return handleAddTodo(client, params);
+        },
+        mentagen_toggle_todo: async (args) => {
+            const params = toggleTodoSchema.parse(args);
+            return handleToggleTodo(client, params);
+        },
+        mentagen_list_todos: async (args) => {
+            const params = listTodosSchema.parse(args);
+            return handleListTodos(client, params);
+        },
     };
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const { name, arguments: args } = request.params;

package/dist/tools/list-nodes.js

@@ -23,6 +23,13 @@ function truncateContent(content, maxLength) {
     return ((lastSpace > maxLength * 0.7 ? truncated.slice(0, lastSpace) : truncated) +
         '...');
 }
+/** Format todos as "completed/total" or empty string if no todos. */
+function formatTodoCounts(todos) {
+    if (!todos || todos.length === 0)
+        return '';
+    const completed = todos.filter(t => t.completed).length;
+    return `${completed}/${todos.length}`;
+}
 function formatNodesTsv(nodes) {
     const rows = nodes.map(n => ({
         id: n._id,
@@ -33,6 +40,7 @@ function formatNodesTsv(nodes) {
         width: pixelsToUnits(n.width),
         height: pixelsToUnits(n.height),
         content: truncateContent(n.content ?? null, MAX_CONTENT_LENGTH),
+        todos: formatTodoCounts(n.todos),
         updatedAt: formatDate(n.updatedAt),
         link: n.link,
     }));
@@ -49,6 +57,7 @@ function formatNodesTsv(nodes) {
             'width',
             'height',
             'content',
+            'todos',
             'updatedAt',
             'link',
         ],

package/dist/tools/size-calc.js

@@ -38,7 +38,7 @@ export const sizeCalcSchema = z.object({
     type: z
         .string()
         .optional()
-        .default('text')
+        .default('markdown')
         .describe('Node type (affects icon space calculation)'),
 });
 function roundToGrid(value) {

package/dist/tools/todo.js

@@ -0,0 +1,171 @@
+import { randomUUID } from 'crypto';
+import { z } from 'zod';
+import { formatError } from '../utils/errors.js';
+// ─────────────────────────────────────────────────────────────────────────────
+// Schemas
+// ─────────────────────────────────────────────────────────────────────────────
+export const addTodoSchema = z.object({
+    boardId: z.string().describe('The board ID containing the node'),
+    nodeId: z.string().describe('The node ID to add the todo to'),
+    text: z.string().describe('The todo text content'),
+});
+export const toggleTodoSchema = z.object({
+    boardId: z.string().describe('The board ID containing the node'),
+    nodeId: z.string().describe('The node ID containing the todo'),
+    todoId: z.string().describe('The todo ID to toggle'),
+    completed: z
+        .boolean()
+        .optional()
+        .describe('Set explicit completion state. Omit to toggle current state.'),
+});
+export const listTodosSchema = z.object({
+    boardId: z.string().describe('The board ID containing the node'),
+    nodeId: z.string().describe('The node ID to list todos from'),
+});
+/**
+ * Add a new todo to a markdown node.
+ * Generates a UUID for the todo and appends it with the next order value.
+ * Note: Only markdown/text nodes support todos; code nodes do not.
+ */
+export async function handleAddTodo(client, params) {
+    try {
+        const node = await client.getNode({
+            boardId: params.boardId,
+            nodeId: params.nodeId,
+        });
+        const existingTodos = node.todos || [];
+        const newTodo = {
+            id: randomUUID(),
+            text: params.text,
+            completed: false,
+            order: existingTodos.length,
+        };
+        const updatedTodos = [...existingTodos, newTodo];
+        await client.updateNode({
+            boardId: params.boardId,
+            nodeId: params.nodeId,
+            data: { todos: updatedTodos },
+        });
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        success: true,
+                        todo: newTodo,
+                        totalTodos: updatedTodos.length,
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Failed to add todo: ${formatError(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}
+/**
+ * Toggle a todo's completion status.
+ * Can set explicit state or toggle current state.
+ */
+export async function handleToggleTodo(client, params) {
+    try {
+        const node = await client.getNode({
+            boardId: params.boardId,
+            nodeId: params.nodeId,
+        });
+        const existingTodos = node.todos || [];
+        const todoIndex = existingTodos.findIndex(t => t.id === params.todoId);
+        if (todoIndex === -1) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Todo not found: ${params.todoId}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const todo = existingTodos[todoIndex];
+        const newCompleted = params.completed ?? !todo.completed;
+        const updatedTodos = existingTodos.map(t => t.id === params.todoId ? { ...t, completed: newCompleted } : t);
+        await client.updateNode({
+            boardId: params.boardId,
+            nodeId: params.nodeId,
+            data: { todos: updatedTodos },
+        });
+        const updatedTodo = updatedTodos[todoIndex];
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        success: true,
+                        todo: updatedTodo,
+                        action: newCompleted ? 'completed' : 'uncompleted',
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Failed to toggle todo: ${formatError(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}
+/**
+ * List all todos on a node with summary statistics.
+ */
+export async function handleListTodos(client, params) {
+    try {
+        const node = await client.getNode({
+            boardId: params.boardId,
+            nodeId: params.nodeId,
+        });
+        const todos = (node.todos || []).sort((a, b) => a.order - b.order);
+        const completedCount = todos.filter(t => t.completed).length;
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        nodeId: params.nodeId,
+                        nodeName: node.name,
+                        todos,
+                        summary: {
+                            total: todos.length,
+                            completed: completedCount,
+                            remaining: todos.length - completedCount,
+                        },
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Failed to list todos: ${formatError(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}

package/dist/tools/update.js

@@ -4,6 +4,23 @@ import { formatError } from '../utils/errors.js';
 import { pixelsToUnits, unitsToPixels } from '../utils/units.js';
 import { snapToGrid } from './grid-calc.js';
 import { calculateNodeSize } from './size-calc.js';
+/**
+ * Node types that can be converted between safely.
+ * These are text-based types where content can be migrated without data loss.
+ * Note: text nodes are accepted for conversion (legacy) but MCP only creates markdown.
+ */
+const CONVERTIBLE_TYPES = [
+    NodeType.Text,
+    NodeType.Markdown,
+    NodeType.Code,
+    NodeType.URL,
+];
+/**
+ * Check if a type is convertible (text-based).
+ */
+function isConvertibleType(type) {
+    return CONVERTIBLE_TYPES.includes(type);
+}
 export const updateSchema = z.object({
     boardId: z.string().describe('The board ID containing the node'),
     nodeId: z.string().describe('The node ID to update'),
@@ -11,8 +28,12 @@ export const updateSchema = z.object({
         .string()
         .optional()
         .describe('Move node to a different board. Provide the target board ID to move the node while preserving its type and properties.'),
+    type: z
+        .enum(['markdown', 'code', 'url'])
+        .optional()
+        .describe('Change node type. Safe conversions: markdown ↔ code. Content is auto-migrated between fields.'),
     name: z.string().optional().describe('New name for the node'),
-    content: z.string().optional().describe('Content for text/markdown nodes.'),
+    content: z.string().optional().describe('Content for markdown nodes.'),
     code: z
         .string()
         .optional()
@@ -34,8 +55,70 @@ export const updateSchema = z.object({
         .optional()
         .default(true)
         .describe('Auto-resize node when name changes (default: true). Set to false to keep current size.'),
+    todos: z
+        .array(z.object({
+        id: z.string().describe('Unique identifier (UUID v4)'),
+        text: z.string().describe('Todo text content'),
+        completed: z.boolean().describe('Completion status'),
+        order: z.number().describe('Sort order (0-based)'),
+    }))
+        .optional()
+        .describe('Replace all todos on this markdown node. Only markdown/text nodes support todos; code nodes do not. Each todo needs id, text, completed, and order fields.'),
 });
 const POSITION_FIELDS = ['x', 'y', 'width', 'height'];
+/**
+ * Compute migration fields when converting TO code type.
+ */
+function migrateToCode(node, params, fields) {
+    // Migrate content → code (unless code explicitly provided)
+    if (params.code === undefined && params.content === undefined) {
+        fields.code = node.content || '';
+    }
+    // Always clear content field when moving to code type
+    fields.content = null;
+}
+/**
+ * Compute migration fields when converting FROM code type.
+ */
+function migrateFromCode(node, params, fields) {
+    // Always clear code field
+    fields.code = null;
+    // Migrate code → content (unless content explicitly provided)
+    if (params.content === undefined && params.code === undefined) {
+        fields.content = node.code || '';
+    }
+}
+/**
+ * Validate and compute migration fields for a type change.
+ *
+ * Returns the fields that need to be set/unset to migrate content
+ * between node types, or an error if the conversion is unsafe.
+ */
+export function validateTypeChange(currentType, targetType, node, params) {
+    if (currentType === targetType) {
+        return { valid: true, fields: {} };
+    }
+    if (!isConvertibleType(currentType)) {
+        return {
+            valid: false,
+            error: `Cannot convert from '${currentType}' to '${targetType}'. Only markdown, code, and url types support conversion.`,
+        };
+    }
+    const fields = { type: targetType };
+    if (targetType === NodeType.URL && !params.url && !node.url) {
+        return {
+            valid: false,
+            error: `Converting to 'url' type requires a url field. Provide url parameter.`,
+        };
+    }
+    if (targetType === NodeType.Code) {
+        migrateToCode(node, params, fields);
+    }
+    else if (currentType === NodeType.Code) {
+        migrateFromCode(node, params, fields);
+    }
+    return { valid: true, fields };
+}
 /**
  * Add content fields to update data based on node type.
  */
@@ -61,15 +144,21 @@ function addContentFields(data, params, nodeType) {
 /**
  * Builds the update data object, mapping content/url to the correct field based on node type.
  * Code nodes store their content in `code`, url nodes use `url`, others use `content`.
+ *
+ * @param params - Update parameters from the tool call
+ * @param nodeType - The target node type (after any type change)
+ * @param migrationFields - Fields from type migration (type change, content migration)
  */
-function buildUpdateData(params, nodeType) {
-    const data = {};
+function buildUpdateData(params, nodeType, migrationFields = {}) {
+    const data = { ...migrationFields };
     if (params.name !== undefined)
         data.name = params.name;
     if (params.color !== undefined)
         data.color = params.color;
     if (params.targetBoardId !== undefined)
         data.board = params.targetBoardId;
+    if (params.todos !== undefined)
+        data.todos = params.todos;
     addContentFields(data, params, nodeType);
     for (const field of POSITION_FIELDS) {
         const value = params[field];
@@ -116,29 +205,55 @@ function formatSuccessResponse(node) {
         content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
     };
 }
+/**
+ * Process type change request and return migration context.
+ */
+function processTypeChange(currentNode, params) {
+    if (!params.type || params.type === currentNode.type) {
+        return { valid: true, fields: {}, targetType: currentNode.type };
+    }
+    const result = validateTypeChange(currentNode.type, params.type, currentNode, params);
+    if (!result.valid) {
+        return result;
+    }
+    return { valid: true, fields: result.fields, targetType: params.type };
+}
+/**
+ * Build params with auto-size dimensions applied.
+ */
+function applyAutoSize(params, autoSize) {
+    return {
+        ...params,
+        width: params.width !== undefined
+            ? params.width
+            : autoSize?.width !== undefined
+                ? pixelsToUnits(autoSize.width)
+                : undefined,
+        height: params.height !== undefined
+            ? params.height
+            : autoSize?.height !== undefined
+                ? pixelsToUnits(autoSize.height)
+                : undefined,
+    };
+}
 export async function handleUpdate(client, params) {
     try {
         const { node: currentNode, autoSize } = await getNodeContext(client, params);
-        const data = buildUpdateData({
-            ...params,
-            // Convert autoSize from pixels to units since buildUpdateData expects units
-            width: params.width !== undefined
-                ? params.width
-                : autoSize?.width !== undefined
-                    ? pixelsToUnits(autoSize.width)
-                    : undefined,
-            height: params.height !== undefined
-                ? params.height
-                : autoSize?.height !== undefined
-                    ? pixelsToUnits(autoSize.height)
-                    : undefined,
-        }, currentNode.type);
+        const typeChange = processTypeChange(currentNode, params);
+        if (!typeChange.valid) {
+            return {
+                content: [{ type: 'text', text: typeChange.error }],
+                isError: true,
+            };
+        }
+        const paramsWithSize = applyAutoSize(params, autoSize);
+        const data = buildUpdateData(paramsWithSize, typeChange.targetType, typeChange.fields);
         if (!data) {
             return {
                 content: [
                     {
                         type: 'text',
-                        text: `At least one field to update must be provided (name, content, url, color, x, y, width, height, targetBoardId).`,
+                        text: `At least one field to update must be provided (name, content, url, color, x, y, width, height, targetBoardId, type, todos).`,
                     },
                 ],
                 isError: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mentagen/mcp",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "MCP server for Mentagen knowledge base integration with Cursor",
   "type": "module",
   "bin": "dist/index.js",