@mentagen/mcp 0.5.0 → 0.6.0

package/dist/tools/batch-update.js

@@ -1,14 +1,16 @@
 import { z } from 'zod';
 import { formatError } from '../utils/errors.js';
+import { unitsToPixels } from '../utils/units.js';
+import { snapToGrid } from './grid-calc.js';
 const nodeUpdateSchema = z.object({
     nodeId: z.string().describe('The node ID to update'),
     name: z.string().optional().describe('New name for the node'),
     content: z.string().optional().describe('New content for the node'),
     color: z.string().optional().describe('Node color'),
-    x: z.number().optional().describe('X position'),
-    y: z.number().optional().describe('Y position'),
-    width: z.number().optional().describe('Node width'),
-    height: z.number().optional().describe('Node height'),
+    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'),
 });
 const edgeUpdateSchema = z.object({
     edgeId: z.string().describe('The edge ID to update'),
@@ -44,8 +46,18 @@ export async function handleBatchUpdate(client, params) {
     // Process node updates in parallel
     const nodePromises = nodeUpdates.map(async (update) => {
         const { nodeId, ...data } = update;
-        // Filter out undefined values
-        const cleanData = Object.fromEntries(Object.entries(data).filter(([, v]) => v !== undefined));
+        // 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' };
         }

package/dist/tools/check-collision.js

@@ -1,12 +1,13 @@
 import { z } from 'zod';
 import { findCollidingNodes, snapToGrid } from '../utils/collision.js';
 import { formatError } from '../utils/errors.js';
+import { pixelsToUnits, unitsToPixels } from '../utils/units.js';
 export const checkCollisionSchema = z.object({
     boardId: z.string().describe('The board ID to check against'),
-    x: z.number().describe('Left position of the rectangle'),
-    y: z.number().describe('Top position of the rectangle'),
-    width: z.number().describe('Width of the rectangle'),
-    height: z.number().describe('Height of the rectangle'),
+    x: z.number().describe('Left position of the rectangle in grid units'),
+    y: z.number().describe('Top position of the rectangle in grid units'),
+    width: z.number().describe('Width of the rectangle in grid units'),
+    height: z.number().describe('Height of the rectangle in grid units'),
     excludeNodeId: z
         .string()
         .optional()
@@ -19,15 +20,32 @@ export async function handleCheckCollision(client, params) {
             boardId: params.boardId,
             limit: 500,
         });
-        // Snap position to grid
-        const rect = {
-            x: snapToGrid(params.x),
-            y: snapToGrid(params.y),
-            width: params.width,
-            height: params.height,
+        // Convert units to pixels and snap position to grid
+        // Note: width/height don't need snapToGrid since unitsToPixels already produces grid-aligned values
+        const rectPixels = {
+            x: snapToGrid(unitsToPixels(params.x)),
+            y: snapToGrid(unitsToPixels(params.y)),
+            width: unitsToPixels(params.width),
+            height: unitsToPixels(params.height),
         };
         // Check for collisions
-        const result = findCollidingNodes(rect, nodes, params.excludeNodeId);
+        const result = findCollidingNodes(rectPixels, nodes, params.excludeNodeId);
+        // Convert results back to units
+        const rect = {
+            x: pixelsToUnits(rectPixels.x),
+            y: pixelsToUnits(rectPixels.y),
+            width: pixelsToUnits(rectPixels.width),
+            height: pixelsToUnits(rectPixels.height),
+        };
+        const collidingNodes = result.collidingNodes.map(node => ({
+            ...node,
+            rect: {
+                x: pixelsToUnits(node.rect.x),
+                y: pixelsToUnits(node.rect.y),
+                width: pixelsToUnits(node.rect.width),
+                height: pixelsToUnits(node.rect.height),
+            },
+        }));
         return {
             content: [
                 {
@@ -35,7 +53,7 @@ export async function handleCheckCollision(client, params) {
                     text: JSON.stringify({
                         collides: result.collides,
                         rect,
-                        collidingNodes: result.collidingNodes,
+                        collidingNodes,
                     }, null, 2),
                 },
             ],

package/dist/tools/create-graph.js

@@ -1,6 +1,8 @@
 import { z } from 'zod';
 import { formatError } from '../utils/errors.js';
+import { pixelsToUnits, unitsToPixels } from '../utils/units.js';
 import { applyExtension, generateId } from './create.js';
+import { snapToGrid } from './grid-calc.js';
 import { calculateNodeSize } from './size-calc.js';
 const nodeInputSchema = z.object({
     tempId: z.string().describe('Temporary ID for referencing in edges'),
@@ -16,10 +18,10 @@ const nodeInputSchema = z.object({
         .default('text')
         .describe('Node type'),
     color: z.string().optional().describe('Node color'),
-    x: z.number().optional().describe('X position'),
-    y: z.number().optional().describe('Y position'),
-    width: z.number().optional().describe('Width'),
-    height: z.number().optional().describe('Height'),
+    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'),
 });
 const edgeInputSchema = z.object({
     source: z.string().describe('Source node tempId'),
@@ -50,10 +52,14 @@ async function createNode(client, boardId, nodeInput, idMap) {
     const finalName = applyExtension(nodeInput.name, type, nodeInput.extension);
     const color = nodeInput.color ?? DEFAULT_NODE_COLORS[type];
     const autoSize = calculateNodeSize(finalName, type);
-    const x = nodeInput.x ?? 100;
-    const y = nodeInput.y ?? 100;
-    const width = nodeInput.width ?? autoSize.width;
-    const height = nodeInput.height ?? autoSize.height;
+    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);
     try {
         // For code nodes, store content in the `code` field
         const isCodeNode = type === 'code';
@@ -66,10 +72,10 @@ async function createNode(client, boardId, nodeInput, idMap) {
                 ...(isCodeNode ? { code: nodeContent } : { content: nodeContent }),
                 type,
                 color,
-                x,
-                y,
-                width,
-                height,
+                x: xPixels,
+                y: yPixels,
+                width: widthPixels,
+                height: heightPixels,
             },
         });
         idMap[nodeInput.tempId] = node._id;
@@ -79,10 +85,10 @@ async function createNode(client, boardId, nodeInput, idMap) {
                 tempId: nodeInput.tempId,
                 id: node._id,
                 name: node.name,
-                x,
-                y,
-                width,
-                height,
+                x: pixelsToUnits(xPixels),
+                y: pixelsToUnits(yPixels),
+                width: pixelsToUnits(widthPixels),
+                height: pixelsToUnits(heightPixels),
             },
         };
     }

package/dist/tools/create.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { formatError } from '../utils/errors.js';
+import { pixelsToUnits, unitsToPixels } from '../utils/units.js';
 import { getNodeUrl } from '../utils/urls.js';
 import { snapToGrid } from './grid-calc.js';
 import { calculateNodeSize } from './size-calc.js';
@@ -66,22 +67,16 @@ export const createSchema = z.object({
         .string()
         .optional()
         .describe('Optional color override. If not specified, uses default for type (markdown=cyan, code=indigo, url=blue)'),
-    x: z
-        .number()
-        .optional()
-        .describe('X position (must be multiple of 16, default: 96)'),
-    y: z
-        .number()
-        .optional()
-        .describe('Y position (must be multiple of 16, default: 96)'),
+    x: z.number().optional().describe('X position in grid units (default: 6)'),
+    y: z.number().optional().describe('Y position in grid units (default: 6)'),
     width: z
         .number()
         .optional()
-        .describe('Width (must be multiple of 16, default: 256)'),
+        .describe('Width in grid units (default: auto-calculated)'),
     height: z
         .number()
         .optional()
-        .describe('Height (must be multiple of 16, default: 128)'),
+        .describe('Height in grid units (default: auto-calculated)'),
 });
 /**
  * Generate a simple ObjectId-like string.
@@ -129,10 +124,14 @@ export async function handleCreate(client, params, mentagenUrl) {
         const color = params.color || DEFAULT_NODE_COLORS[params.type];
         const autoSize = calculateNodeSize(finalName, params.type);
         const position = {
-            x: snapToGrid(params.x ?? 96),
-            y: snapToGrid(params.y ?? 96),
-            width: snapToGrid(params.width ?? autoSize.width),
-            height: snapToGrid(params.height ?? autoSize.height),
+            x: snapToGrid(unitsToPixels(params.x ?? 6)),
+            y: snapToGrid(unitsToPixels(params.y ?? 6)),
+            width: snapToGrid(params.width !== undefined
+                ? unitsToPixels(params.width)
+                : autoSize.width),
+            height: snapToGrid(params.height !== undefined
+                ? unitsToPixels(params.height)
+                : autoSize.height),
         };
         const nodeFields = buildNodeFields({ ...params, name: finalName }, color, position);
         const node = await client.addNode({
@@ -146,7 +145,10 @@ export async function handleCreate(client, params, mentagenUrl) {
                 id: node._id,
                 name: node.name,
                 board: params.boardId,
-                ...position,
+                x: pixelsToUnits(position.x),
+                y: pixelsToUnits(position.y),
+                width: pixelsToUnits(position.width),
+                height: pixelsToUnits(position.height),
                 link: getNodeUrl(mentagenUrl, params.boardId, node._id),
             },
         };

package/dist/tools/find-overlaps.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { rectsIntersect } from '../utils/collision.js';
 import { formatError } from '../utils/errors.js';
+import { pixelsToUnits } from '../utils/units.js';
 export const findOverlapsSchema = z.object({
     boardId: z.string().describe('The board ID to check for overlapping nodes'),
 });
@@ -43,10 +44,29 @@ export async function handleFindOverlaps(client, params) {
                     height: node2.height,
                 };
                 if (rectsIntersect(rect1, rect2)) {
+                    const overlapAreaPixels = calculateOverlapArea(rect1, rect2);
                     overlaps.push({
-                        node1: { id: node1._id, name: node1.name, rect: rect1 },
-                        node2: { id: node2._id, name: node2.name, rect: rect2 },
-                        overlapArea: calculateOverlapArea(rect1, rect2),
+                        node1: {
+                            id: node1._id,
+                            name: node1.name,
+                            rect: {
+                                x: pixelsToUnits(rect1.x),
+                                y: pixelsToUnits(rect1.y),
+                                width: pixelsToUnits(rect1.width),
+                                height: pixelsToUnits(rect1.height),
+                            },
+                        },
+                        node2: {
+                            id: node2._id,
+                            name: node2.name,
+                            rect: {
+                                x: pixelsToUnits(rect2.x),
+                                y: pixelsToUnits(rect2.y),
+                                width: pixelsToUnits(rect2.width),
+                                height: pixelsToUnits(rect2.height),
+                            },
+                        },
+                        overlapArea: overlapAreaPixels,
                     });
                 }
             }
@@ -68,7 +88,7 @@ export async function handleFindOverlaps(client, params) {
             return (`${i + 1}. ${o.node1.name} (${o.node1.id})\n` +
                 `   overlaps with\n` +
                 `   ${o.node2.name} (${o.node2.id})\n` +
-                `   Overlap area: ${o.overlapArea}px²`);
+                `   Overlap area: ${o.overlapArea}px² (${Math.round(o.overlapArea / 256)} units²)`);
         })
             .join('\n\n');
         return {

package/dist/tools/find-position.js

@@ -1,10 +1,11 @@
 import { z } from 'zod';
 import { findFreePosition, } from '../utils/collision.js';
 import { formatError } from '../utils/errors.js';
+import { pixelsToUnits, unitsToPixels } from '../utils/units.js';
 export const findPositionSchema = z.object({
     boardId: z.string().describe('The board ID to search'),
-    width: z.number().describe('Width of the node to place'),
-    height: z.number().describe('Height of the node to place'),
+    width: z.number().describe('Width of the node to place in grid units'),
+    height: z.number().describe('Height of the node to place in grid units'),
     anchorNodeId: z
         .string()
         .optional()
@@ -16,92 +17,116 @@ export const findPositionSchema = z.object({
     gap: z
         .number()
         .optional()
-        .describe('Gap between nodes in pixels (default: 16)'),
+        .describe('Gap between nodes in grid units. Use 6+ for connected nodes, 1 for unrelated (default: 1)'),
     startX: z
         .number()
         .optional()
-        .describe('Explicit start X (ignored if anchorNodeId provided)'),
+        .describe('Explicit start X in grid units (ignored if anchorNodeId provided)'),
     startY: z
         .number()
         .optional()
-        .describe('Explicit start Y (ignored if anchorNodeId provided)'),
+        .describe('Explicit start Y in grid units (ignored if anchorNodeId provided)'),
 });
+function findAnchorNode(nodes, anchorNodeId) {
+    const anchorNode = nodes.find(n => n._id === anchorNodeId);
+    if (!anchorNode)
+        return null;
+    return {
+        anchor: {
+            x: anchorNode.x,
+            y: anchorNode.y,
+            width: anchorNode.width,
+            height: anchorNode.height,
+        },
+        anchorInfo: {
+            id: anchorNode._id,
+            name: anchorNode.name,
+        },
+    };
+}
+function formatSuccessResponse(position, anchorInfo, direction, searchSteps) {
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({
+                    found: true,
+                    position: {
+                        x: pixelsToUnits(position.x),
+                        y: pixelsToUnits(position.y),
+                    },
+                    anchor: anchorInfo || null,
+                    direction: direction || 'right',
+                    searchSteps,
+                }, null, 2),
+            },
+        ],
+    };
+}
+function formatErrorResponse(error, searchSteps) {
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({
+                    found: false,
+                    error: error || 'No valid position found',
+                    searchSteps,
+                }, null, 2),
+            },
+        ],
+        isError: true,
+    };
+}
+async function prepareSearchParams(client, params) {
+    const nodes = await client.listNodes({
+        boardId: params.boardId,
+        limit: 500,
+    });
+    if (!params.anchorNodeId) {
+        return { nodes };
+    }
+    const anchorData = findAnchorNode(nodes, params.anchorNodeId);
+    if (!anchorData) {
+        return {
+            error: {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Anchor node not found: ${params.anchorNodeId}`,
+                    },
+                ],
+                isError: true,
+            },
+        };
+    }
+    return {
+        nodes,
+        anchor: anchorData.anchor,
+        anchorInfo: anchorData.anchorInfo,
+    };
+}
 export async function handleFindPosition(client, params) {
     try {
-        // Fetch nodes from board
-        const nodes = await client.listNodes({
-            boardId: params.boardId,
-            limit: 500,
-        });
-        // Find anchor node if specified
-        let anchor;
-        let anchorInfo;
-        if (params.anchorNodeId) {
-            const anchorNode = nodes.find(n => n._id === params.anchorNodeId);
-            if (!anchorNode) {
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: `Anchor node not found: ${params.anchorNodeId}`,
-                        },
-                    ],
-                    isError: true,
-                };
-            }
-            anchor = {
-                x: anchorNode.x,
-                y: anchorNode.y,
-                width: anchorNode.width,
-                height: anchorNode.height,
-            };
-            anchorInfo = {
-                id: anchorNode._id,
-                name: anchorNode.name,
-            };
+        const prepared = await prepareSearchParams(client, params);
+        if ('error' in prepared) {
+            return prepared.error;
         }
-        // Find free position
+        const { nodes, anchor, anchorInfo } = prepared;
         const result = findFreePosition({
-            width: params.width,
-            height: params.height,
-            nodes,
+            width: unitsToPixels(params.width),
+            height: unitsToPixels(params.height),
+            nodes: nodes,
             anchor,
             direction: params.direction,
-            gap: params.gap,
-            startX: params.startX,
-            startY: params.startY,
+            gap: params.gap !== undefined ? unitsToPixels(params.gap) : undefined,
+            startX: params.startX !== undefined ? unitsToPixels(params.startX) : undefined,
+            startY: params.startY !== undefined ? unitsToPixels(params.startY) : undefined,
         });
         if (result.found && result.position) {
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: JSON.stringify({
-                            found: true,
-                            position: result.position,
-                            anchor: anchorInfo || null,
-                            direction: params.direction || 'right',
-                            searchSteps: result.searchSteps,
-                        }, null, 2),
-                    },
-                ],
-            };
-        }
-        else {
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: JSON.stringify({
-                            found: false,
-                            error: result.error || 'No valid position found',
-                            searchSteps: result.searchSteps,
-                        }, null, 2),
-                    },
-                ],
-                isError: true,
-            };
+            return formatSuccessResponse(result.position, anchorInfo, params.direction, result.searchSteps);
         }
+        return formatErrorResponse(result.error, result.searchSteps);
     }
     catch (error) {
         return {

package/dist/tools/grid-calc.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { findCollidingNodes, findSuggestedPosition, } from '../utils/collision.js';
+import { pixelsToUnits, unitsToPixels } from '../utils/units.js';
 const GRID_SIZE = 16;
 export const gridCalcSchema = z
     .object({
@@ -9,23 +10,23 @@ export const gridCalcSchema = z
     value: z
         .number()
         .optional()
-        .describe('Value to snap to the grid (for snap operation)'),
+        .describe('Value to snap to the grid in units (for snap operation)'),
     position: z
         .number()
         .optional()
-        .describe('Current x or y position (for next_x/next_y operations)'),
+        .describe('Current x or y position in units (for next_x/next_y operations)'),
     size: z
         .number()
         .optional()
-        .describe('Width or height of the current node (for next_x/next_y)'),
+        .describe('Width or height of the current node in units (for next_x/next_y)'),
     gap: z
         .number()
         .optional()
-        .describe('Gap between nodes in pixels (default: 16)'),
+        .describe('Gap between nodes in grid units. Use 6+ for connected nodes, 1 for unrelated (default: 1)'),
     units: z
         .number()
         .optional()
-        .describe('Number of grid units to convert to pixels (for grid_units)'),
+        .describe('Number of grid units (for grid_units operation - deprecated, returns same value)'),
     // Collision-aware params (optional)
     boardId: z
         .string()
@@ -34,19 +35,19 @@ export const gridCalcSchema = z
     nodeWidth: z
         .number()
         .optional()
-        .describe('Width of node being placed (required with boardId)'),
+        .describe('Width of node being placed in grid units (required with boardId)'),
     nodeHeight: z
         .number()
         .optional()
-        .describe('Height of node being placed (required with boardId)'),
+        .describe('Height of node being placed in grid units (required with boardId)'),
     nodeY: z
         .number()
         .optional()
-        .describe('Y position of node (required for next_x collision check)'),
+        .describe('Y position of node in grid units (required for next_x collision check)'),
     nodeX: z
         .number()
         .optional()
-        .describe('X position of node (required for next_y collision check)'),
+        .describe('X position of node in grid units (required for next_y collision check)'),
     excludeNodeId: z
         .string()
         .optional()
@@ -85,30 +86,26 @@ export function snapToGrid(value) {
 }
 /**
  * Calculate the next position after a node, with a gap.
- * Result is snapped to the grid.
+ * All inputs and output are in grid units.
  */
 export function calculateNextPosition(position, size, gap) {
-    return snapToGrid(position + size + gap);
-}
-/**
- * Convert grid units to pixels.
- * 1 grid unit = 16 pixels.
- */
-export function gridUnitsToPixels(units) {
-    return units * GRID_SIZE;
+    return position + size + gap;
 }
 /**
  * Calculate result based on operation type.
+ * All operations now work with grid units.
  */
 function calculateResult(params) {
     if (params.operation === 'snap') {
-        return snapToGrid(params.value);
+        // Snap to nearest integer unit
+        return Math.round(params.value);
     }
     if (params.operation === 'grid_units') {
-        return gridUnitsToPixels(params.units);
+        // Deprecated: just return the units value (identity operation)
+        return params.units;
     }
     // next_x or next_y
-    return calculateNextPosition(params.position, params.size, params.gap ?? GRID_SIZE);
+    return calculateNextPosition(params.position, params.size, params.gap ?? 1);
 }
 /**
  * Build input object for result output.
@@ -156,18 +153,38 @@ function supportsCollisionCheck(operation) {
  */
 async function checkPositionCollision(params, baseResult, client) {
     const nodes = await client.listNodes({ boardId: params.boardId, limit: 500 });
-    const x = params.operation === 'next_x' ? baseResult.result : (params.nodeX ?? 0);
-    const y = params.operation === 'next_y' ? baseResult.result : (params.nodeY ?? 0);
-    const rect = { x, y, width: params.nodeWidth, height: params.nodeHeight };
-    const collisionResult = findCollidingNodes(rect, nodes, params.excludeNodeId);
+    // Convert units to pixels for collision checking
+    const xPixels = params.operation === 'next_x'
+        ? unitsToPixels(baseResult.result)
+        : unitsToPixels(params.nodeX ?? 0);
+    const yPixels = params.operation === 'next_y'
+        ? unitsToPixels(baseResult.result)
+        : unitsToPixels(params.nodeY ?? 0);
+    const rectPixels = {
+        x: xPixels,
+        y: yPixels,
+        width: unitsToPixels(params.nodeWidth),
+        height: unitsToPixels(params.nodeHeight),
+    };
+    const collisionResult = findCollidingNodes(rectPixels, nodes, params.excludeNodeId);
     const collision = {
         checked: true,
         collides: collisionResult.collides,
-        collidingNodes: collisionResult.collidingNodes,
+        collidingNodes: collisionResult.collidingNodes.map(node => ({
+            ...node,
+            rect: {
+                x: pixelsToUnits(node.rect.x),
+                y: pixelsToUnits(node.rect.y),
+                width: pixelsToUnits(node.rect.width),
+                height: pixelsToUnits(node.rect.height),
+            },
+        })),
     };
     if (collisionResult.collides) {
         const direction = params.operation === 'next_x' ? 'x' : 'y';
-        collision.suggestedPosition = findSuggestedPosition(x, y, params.nodeWidth, params.nodeHeight, nodes, direction, params.excludeNodeId);
+        const suggestedPixels = findSuggestedPosition(xPixels, yPixels, rectPixels.width, rectPixels.height, nodes, direction, params.excludeNodeId);
+        collision.suggestedPosition =
+            suggestedPixels !== null ? pixelsToUnits(suggestedPixels) : null;
     }
     return collision;
 }

package/dist/tools/index.js

@@ -313,11 +313,11 @@ export function registerTools(server, client, config) {
                         },
                         x: {
                             type: 'number',
-                            description: 'X position (snapped to 16px grid, default: 96)',
+                            description: 'X position in grid units (1 unit = 16px, default: 6)',
                         },
                         y: {
                             type: 'number',
-                            description: 'Y position (snapped to 16px grid, default: 96)',
+                            description: 'Y position in grid units (1 unit = 16px, default: 6)',
                         },
                         width: {
                             type: 'number',
@@ -363,19 +363,19 @@ export function registerTools(server, client, config) {
                         },
                         x: {
                             type: 'number',
-                            description: 'X position on the board canvas (multiple of 16)',
+                            description: 'X position in grid units (1 unit = 16px)',
                         },
                         y: {
                             type: 'number',
-                            description: 'Y position on the board canvas (multiple of 16)',
+                            description: 'Y position in grid units (1 unit = 16px)',
                         },
                         width: {
                             type: 'number',
-                            description: 'Node width in pixels (multiple of 16)',
+                            description: 'Node width in grid units (1 unit = 16px)',
                         },
                         height: {
                             type: 'number',
-                            description: 'Node height in pixels (multiple of 16)',
+                            description: 'Node height in grid units (1 unit = 16px)',
                         },
                         autoSize: {
                             type: 'boolean',
@@ -423,10 +423,22 @@ export function registerTools(server, client, config) {
                                     name: { type: 'string', description: 'New name' },
                                     content: { type: 'string', description: 'New content' },
                                     color: { type: 'string', description: 'Node color' },
-                                    x: { type: 'number', description: 'X position' },
-                                    y: { type: 'number', description: 'Y position' },
-                                    width: { type: 'number', description: 'Width' },
-                                    height: { type: 'number', description: 'Height' },
+                                    x: {
+                                        type: 'number',
+                                        description: 'X position in grid units (1 unit = 16px)',
+                                    },
+                                    y: {
+                                        type: 'number',
+                                        description: 'Y position in grid units (1 unit = 16px)',
+                                    },
+                                    width: {
+                                        type: 'number',
+                                        description: 'Width in grid units (1 unit = 16px)',
+                                    },
+                                    height: {
+                                        type: 'number',
+                                        description: 'Height in grid units (1 unit = 16px)',
+                                    },
                                 },
                                 required: ['nodeId'],
                             },
@@ -563,15 +575,21 @@ export function registerTools(server, client, config) {
                                         description: 'Node type (default: text).',
                                     },
                                     color: { type: 'string', description: 'Node color' },
-                                    x: { type: 'number', description: 'X position' },
-                                    y: { type: 'number', description: 'Y position' },
+                                    x: {
+                                        type: 'number',
+                                        description: 'X position in grid units (1 unit = 16px)',
+                                    },
+                                    y: {
+                                        type: 'number',
+                                        description: 'Y position in grid units (1 unit = 16px)',
+                                    },
                                     width: {
                                         type: 'number',
-                                        description: 'DO NOT USE - auto-calculated from name',
+                                        description: 'Width in grid units (1 unit = 16px, DO NOT USE - auto-calculated from name)',
                                     },
                                     height: {
                                         type: 'number',
-                                        description: 'DO NOT USE - auto-calculated from name',
+                                        description: 'Height in grid units (1 unit = 16px, DO NOT USE - auto-calculated from name)',
                                     },
                                 },
                                 required: ['tempId', 'name'],
@@ -733,7 +751,7 @@ export function registerTools(server, client, config) {
             },
             {
                 name: 'mentagen_grid_calc',
-                description: 'Math helper for calculating node positions on the 16px grid. Use gap=96+ for connected nodes, gap=16 for unrelated nodes. Operations: "snap" rounds to 16px, "next_x"/"next_y" calculate position after a node, "grid_units" converts units to pixels.',
+                description: 'Math helper for calculating node positions in grid units (1 unit = 16px). Use gap=6+ for connected nodes, gap=1 for unrelated nodes. Operations: "snap" rounds to nearest integer unit, "next_x"/"next_y" calculate position after a node, "grid_units" is deprecated (returns same value).',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -744,23 +762,23 @@ export function registerTools(server, client, config) {
                         },
                         value: {
                             type: 'number',
-                            description: 'Value to snap to the grid (for snap operation)',
+                            description: 'Value to snap to the grid in units (for snap operation)',
                         },
                         position: {
                             type: 'number',
-                            description: 'Current x or y position (for next_x/next_y operations)',
+                            description: 'Current x or y position in units (for next_x/next_y operations)',
                         },
                         size: {
                             type: 'number',
-                            description: 'Width or height of the current node (for next_x/next_y)',
+                            description: 'Width or height of the current node in units (for next_x/next_y)',
                         },
                         gap: {
                             type: 'number',
-                            description: 'Gap in pixels. Use 96+ for connected nodes, 16 for unrelated (default: 16)',
+                            description: 'Gap in grid units (1 unit = 16px). Use 6+ for connected nodes, 1 for unrelated (default: 1)',
                         },
                         units: {
                             type: 'number',
-                            description: 'Number of grid units to convert to pixels (for grid_units)',
+                            description: 'Number of grid units (1 unit = 16px, for grid_units operation - deprecated, returns same value)',
                         },
                         boardId: {
                             type: 'string',
@@ -768,19 +786,19 @@ export function registerTools(server, client, config) {
                         },
                         nodeWidth: {
                             type: 'number',
-                            description: 'Width of node being placed (required with boardId)',
+                            description: 'Width of node being placed in grid units (1 unit = 16px, required with boardId)',
                         },
                         nodeHeight: {
                             type: 'number',
-                            description: 'Height of node being placed (required with boardId)',
+                            description: 'Height of node being placed in grid units (1 unit = 16px, required with boardId)',
                         },
                         nodeY: {
                             type: 'number',
-                            description: 'Y position of node (for next_x collision check)',
+                            description: 'Y position of node in grid units (1 unit = 16px, for next_x collision check)',
                         },
                         nodeX: {
                             type: 'number',
-                            description: 'X position of node (for next_y collision check)',
+                            description: 'X position of node in grid units (1 unit = 16px, for next_y collision check)',
                         },
                         excludeNodeId: {
                             type: 'string',
@@ -802,19 +820,19 @@ export function registerTools(server, client, config) {
                         },
                         x: {
                             type: 'number',
-                            description: 'Left position of the rectangle',
+                            description: 'Left position of the rectangle in grid units (1 unit = 16px)',
                         },
                         y: {
                             type: 'number',
-                            description: 'Top position of the rectangle',
+                            description: 'Top position of the rectangle in grid units (1 unit = 16px)',
                         },
                         width: {
                             type: 'number',
-                            description: 'Width of the rectangle',
+                            description: 'Width of the rectangle in grid units (1 unit = 16px)',
                         },
                         height: {
                             type: 'number',
-                            description: 'Height of the rectangle',
+                            description: 'Height of the rectangle in grid units (1 unit = 16px)',
                         },
                         excludeNodeId: {
                             type: 'string',
@@ -840,7 +858,7 @@ export function registerTools(server, client, config) {
             },
             {
                 name: 'mentagen_find_position',
-                description: 'Find a valid non-colliding position for a new node. IMPORTANT: Use gap=96 or more when nodes will be connected by edges, otherwise gap=16 is fine for unrelated nodes.',
+                description: 'Find a valid non-colliding position for a new node. IMPORTANT: Use gap=6+ (96px+) when nodes will be connected by edges, otherwise gap=1 (16px) is fine for unrelated nodes. All positions are in grid units (1 unit = 16px).',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -850,11 +868,11 @@ export function registerTools(server, client, config) {
                         },
                         width: {
                             type: 'number',
-                            description: 'Width of the node to place',
+                            description: 'Width of the node to place in grid units (1 unit = 16px)',
                         },
                         height: {
                             type: 'number',
-                            description: 'Height of the node to place',
+                            description: 'Height of the node to place in grid units (1 unit = 16px)',
                         },
                         anchorNodeId: {
                             type: 'string',
@@ -867,15 +885,15 @@ export function registerTools(server, client, config) {
                         },
                         gap: {
                             type: 'number',
-                            description: 'Gap between nodes in pixels. Use 96+ for connected nodes (edges), 16 for unrelated nodes',
+                            description: 'Gap between nodes in grid units (1 unit = 16px). Use 6+ for connected nodes (edges), 1 for unrelated nodes',
                         },
                         startX: {
                             type: 'number',
-                            description: 'Explicit start X (ignored if anchorNodeId provided)',
+                            description: 'Explicit start X in grid units (1 unit = 16px, ignored if anchorNodeId provided)',
                         },
                         startY: {
                             type: 'number',
-                            description: 'Explicit start Y (ignored if anchorNodeId provided)',
+                            description: 'Explicit start Y in grid units (1 unit = 16px, ignored if anchorNodeId provided)',
                         },
                     },
                     required: ['boardId', 'width', 'height'],
@@ -883,7 +901,7 @@ export function registerTools(server, client, config) {
             },
             {
                 name: 'mentagen_size_calc',
-                description: 'Calculate recommended node dimensions based on name and type. Returns width and height values (multiples of 16) sized to fit the title. Content is intentionally ignored — nodes are sized for their title with content scrollable inside.',
+                description: 'Calculate recommended node dimensions based on name and type. Returns width and height values in grid units (1 unit = 16px) sized to fit the title. Content is intentionally ignored — nodes are sized for their title with content scrollable inside.',
                 inputSchema: {
                     type: 'object',
                     properties: {

package/dist/tools/list-nodes.js

@@ -2,6 +2,7 @@ import Papa from 'papaparse';
 import { z } from 'zod';
 import { formatDate } from '../utils/ejson.js';
 import { formatError } from '../utils/errors.js';
+import { pixelsToUnits } from '../utils/units.js';
 import { getNodeUrl } from '../utils/urls.js';
 export const listNodesSchema = z.object({
     boardId: z.string().describe('The board ID to list nodes from'),
@@ -27,10 +28,10 @@ function formatNodesTsv(nodes) {
         id: n._id,
         name: n.name,
         type: n.type,
-        x: n.x,
-        y: n.y,
-        width: n.width,
-        height: n.height,
+        x: pixelsToUnits(n.x),
+        y: pixelsToUnits(n.y),
+        width: pixelsToUnits(n.width),
+        height: pixelsToUnits(n.height),
         content: truncateContent(n.content ?? null, MAX_CONTENT_LENGTH),
         updatedAt: formatDate(n.updatedAt),
         link: n.link,

package/dist/tools/list-positions.js

@@ -1,6 +1,7 @@
 import Papa from 'papaparse';
 import { z } from 'zod';
 import { formatError } from '../utils/errors.js';
+import { pixelsToUnits } from '../utils/units.js';
 export const listPositionsSchema = z.object({
     boardId: z.string().describe('The board ID to list node positions from'),
     limit: z
@@ -13,10 +14,10 @@ function formatPositionsTsv(nodes) {
     const rows = nodes.map(n => ({
         id: n._id,
         name: n.name,
-        x: n.x,
-        y: n.y,
-        w: n.width,
-        h: n.height,
+        x: pixelsToUnits(n.x),
+        y: pixelsToUnits(n.y),
+        w: pixelsToUnits(n.width),
+        h: pixelsToUnits(n.height),
     }));
     return Papa.unparse(rows, {
         delimiter: '\t',

package/dist/tools/read.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { formatError } from '../utils/errors.js';
+import { pixelsToUnits } from '../utils/units.js';
 import { getNodeUrl } from '../utils/urls.js';
 export const readSchema = z.object({
     boardId: z.string().describe('The board ID containing the node'),
@@ -13,9 +14,21 @@ export async function handleRead(client, params, baseUrl) {
         });
         // Exclude large fields that aren't useful for AI consumption
         const { _vectors, __v, textDetections, ...nodeData } = node;
-        // Add link to the response
+        // Convert position fields from pixels to units
         const response = {
             ...nodeData,
+            x: 'x' in nodeData && typeof nodeData.x === 'number'
+                ? pixelsToUnits(nodeData.x)
+                : nodeData.x,
+            y: 'y' in nodeData && typeof nodeData.y === 'number'
+                ? pixelsToUnits(nodeData.y)
+                : nodeData.y,
+            width: 'width' in nodeData && typeof nodeData.width === 'number'
+                ? pixelsToUnits(nodeData.width)
+                : nodeData.width,
+            height: 'height' in nodeData && typeof nodeData.height === 'number'
+                ? pixelsToUnits(nodeData.height)
+                : nodeData.height,
             link: getNodeUrl(baseUrl, params.boardId, params.nodeId),
         };
         return {

package/dist/tools/size-calc.js

@@ -1,10 +1,12 @@
 import { z } from 'zod';
+import { pixelsToUnits } from '../utils/units.js';
 // Grid and constraint constants (from src/common/boards/constraints.ts)
+// Values in pixels (internal calculations)
 const GRID = 16;
-const MIN_WIDTH = 128;
-const MIN_HEIGHT = 64;
-const MAX_WIDTH = 512; // Reasonable max for auto-sizing (not the 4096 absolute max)
-const MAX_HEIGHT = 512;
+const MIN_WIDTH = 128; // 8 units
+const MIN_HEIGHT = 64; // 4 units
+const MAX_WIDTH = 512; // 32 units - reasonable max for auto-sizing (not the 4096 absolute max)
+const MAX_HEIGHT = 512; // 32 units
 // Text measurement constants (from measure-node-size.ts)
 const MAX_AUTO_WIDTH = 400;
 const PADDING_X = 12;
@@ -96,7 +98,10 @@ export function calculateNodeSize(name, type) {
     return { width, height };
 }
 export function handleSizeCalc(params) {
-    const { width, height } = calculateNodeSize(params.name, params.type);
+    const { width: widthPixels, height: heightPixels } = calculateNodeSize(params.name, params.type);
+    // Convert output to units
+    const width = pixelsToUnits(widthPixels);
+    const height = pixelsToUnits(heightPixels);
     return {
         content: [
             {

package/dist/tools/update.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { NodeType } from '../client/types.js';
 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';
 export const updateSchema = z.object({
@@ -24,22 +25,10 @@ export const updateSchema = z.object({
         .string()
         .optional()
         .describe('Node color name (use mentagen_colors to see available colors)'),
-    x: z
-        .number()
-        .optional()
-        .describe('X position on the board canvas (must be multiple of 16)'),
-    y: z
-        .number()
-        .optional()
-        .describe('Y position on the board canvas (must be multiple of 16)'),
-    width: z
-        .number()
-        .optional()
-        .describe('Node width in pixels (must be multiple of 16)'),
-    height: z
-        .number()
-        .optional()
-        .describe('Node height in pixels (must be multiple of 16)'),
+    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'),
     autoSize: z
         .boolean()
         .optional()
@@ -85,7 +74,7 @@ function buildUpdateData(params, nodeType) {
     for (const field of POSITION_FIELDS) {
         const value = params[field];
         if (value !== undefined) {
-            data[field] = snapToGrid(value);
+            data[field] = snapToGrid(unitsToPixels(value));
         }
     }
     return Object.keys(data).length > 0 ? data : null;
@@ -116,10 +105,10 @@ function formatSuccessResponse(node) {
         node: {
             id: node._id,
             name: node.name,
-            x: node.x,
-            y: node.y,
-            width: node.width,
-            height: node.height,
+            x: pixelsToUnits(node.x),
+            y: pixelsToUnits(node.y),
+            width: pixelsToUnits(node.width),
+            height: pixelsToUnits(node.height),
             updatedAt: node.updatedAt || new Date().toISOString(),
         },
     };
@@ -132,8 +121,17 @@ export async function handleUpdate(client, params) {
         const { node: currentNode, autoSize } = await getNodeContext(client, params);
         const data = buildUpdateData({
             ...params,
-            width: params.width ?? autoSize?.width,
-            height: params.height ?? autoSize?.height,
+            // 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);
         if (!data) {
             return {

package/dist/utils/units.js

@@ -0,0 +1,19 @@
+/**
+ * Unit conversion utilities for grid-based positioning.
+ * 1 grid unit = 16 pixels
+ */
+const GRID_SIZE = 16;
+/**
+ * Convert grid units to pixels.
+ * Rounds the input to the nearest integer before conversion.
+ */
+export function unitsToPixels(units) {
+    return Math.round(units) * GRID_SIZE;
+}
+/**
+ * Convert pixels to grid units.
+ * Rounds the result to the nearest integer unit.
+ */
+export function pixelsToUnits(pixels) {
+    return Math.round(pixels / GRID_SIZE);
+}

package/package.json

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