@mentagen/mcp 0.6.0 → 0.8.0

package/dist/index.js

@@ -2,6 +2,8 @@
 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';
 async function main() {
@@ -13,8 +15,12 @@ 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/resources/index.js

@@ -0,0 +1,93 @@
+const NODE_COLORS = [
+    { name: 'amber', rgb: 'rgb(253, 230, 138)' },
+    { name: 'blue', rgb: 'rgb(0, 120, 255)' },
+    { name: 'cyan', rgb: 'rgb(0, 231, 255)' },
+    { name: 'emerald', rgb: 'rgb(0, 230, 118)' },
+    { name: 'fuchsia', rgb: 'rgb(233, 30, 99)' },
+    { name: 'green', rgb: 'rgb(52, 211, 153)' },
+    { name: 'indigo', rgb: 'rgb(72, 77, 201)' },
+    { name: 'lime', rgb: 'rgb(209, 250, 229)' },
+    { name: 'orange', rgb: 'rgb(252, 165, 0)' },
+    { name: 'pink', rgb: 'rgb(244, 143, 177)' },
+    { name: 'purple', rgb: 'rgb(156, 39, 176)' },
+    { name: 'red', rgb: 'rgb(239, 68, 68)' },
+    { name: 'rose', rgb: 'rgb(255, 204, 203)' },
+    { name: 'sky', rgb: 'rgb(0, 184, 230)' },
+    { name: 'slate', rgb: 'rgb(107, 114, 128)' },
+    { name: 'teal', rgb: 'rgb(0, 210, 183)' },
+    { name: 'violet', rgb: 'rgb(123, 31, 162)' },
+    { name: 'yellow', rgb: 'rgb(255, 251, 235)' },
+];
+/**
+ * Supported node types with their default colors.
+ *
+ * Keep in sync with: src/client/features/boards/inner-board-context-menu.tsx
+ */
+const NODE_TYPES = [
+    {
+        type: 'text',
+        defaultColor: null,
+        description: 'Simple text node with a title and optional rich text content.',
+        usage: 'Use for short notes, labels, headings, or any content that needs a title.',
+        fields: {
+            name: 'The node title (required)',
+            content: 'Optional HTML content',
+        },
+    },
+    {
+        type: 'markdown',
+        defaultColor: 'cyan',
+        description: 'Markdown node for longer-form content with full Markdown syntax support.',
+        usage: 'Use for documentation, articles, formatted notes, or any content that benefits from Markdown formatting.',
+        fields: {
+            name: 'The node title (required)',
+            content: 'Markdown content (supports full GFM syntax)',
+        },
+    },
+    {
+        type: 'code',
+        defaultColor: 'indigo',
+        description: 'Code node for storing and displaying source code with syntax highlighting.',
+        usage: 'Use for code snippets, scripts, configuration files. Supports multiple programming languages.',
+        fields: {
+            name: 'The node title (required)',
+            content: 'Source code content',
+        },
+    },
+    {
+        type: 'url',
+        defaultColor: 'blue',
+        description: 'Bookmark node that stores and displays a link to an external URL.',
+        usage: 'Use for saving references to external resources, articles, documentation, or any web link.',
+        fields: {
+            name: 'The link title (required)',
+            url: 'The full URL including protocol (e.g., https://example.com)',
+        },
+    },
+];
+export function registerResources(mcpServer) {
+    mcpServer.resource('Node Colors', 'mentagen://colors', {
+        description: 'Available colors for nodes. Use the color name when creating or updating nodes.',
+        mimeType: 'application/json',
+    }, async () => ({
+        contents: [
+            {
+                uri: 'mentagen://colors',
+                mimeType: 'application/json',
+                text: JSON.stringify({ colors: NODE_COLORS }, null, 2),
+            },
+        ],
+    }));
+    mcpServer.resource('Node Types', 'mentagen://node-types', {
+        description: 'Supported node types with descriptions and usage guidance. Specify the type parameter when creating nodes.',
+        mimeType: 'application/json',
+    }, async () => ({
+        contents: [
+            {
+                uri: 'mentagen://node-types',
+                mimeType: 'application/json',
+                text: JSON.stringify({ nodeTypes: NODE_TYPES }, null, 2),
+            },
+        ],
+    }));
+}

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),
             },
         };
     }