@mentagen/mcp 0.4.1 → 0.6.0

package/dist/client/helene.js

@@ -64,9 +64,10 @@ export class MentagenClient {
     /**
      * List boards the user has access to.
      */
-    async listBoards() {
-        const result = await this.call('boards.list', {});
-        return result.data || [];
+    async listBoards(params) {
+        return this.call('boards.listSimple', {
+            orgId: params?.orgId,
+        });
     }
     /**
      * Search boards by name.
@@ -84,6 +85,18 @@ export class MentagenClient {
     async searchNodes(params) {
         return this.call('boards.searchNodesText', params);
     }
+    /**
+     * List organizations the user has access to.
+     */
+    async listOrganizations() {
+        return this.call('org.list', {});
+    }
+    /**
+     * List teams within an organization.
+     */
+    async listTeams(params) {
+        return this.call('team.list', params);
+    }
     /**
      * Add a new node to a board.
      */

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/boards.js

@@ -3,7 +3,12 @@ import { z } from 'zod';
 import { formatShortDate } from '../utils/ejson.js';
 import { formatError } from '../utils/errors.js';
 import { getBoardUrl } from '../utils/urls.js';
-export const boardsSchema = z.object({});
+export const boardsSchema = z.object({
+    orgId: z
+        .string()
+        .optional()
+        .describe('Optional organization ID to filter boards'),
+});
 /**
  * Format boards as TSV for compact output.
  * Uses papaparse for proper escaping of special characters.
@@ -13,18 +18,29 @@ function formatBoardsTsv(boards) {
         delimiter: '\t',
         header: true,
         newline: '\n',
-        columns: ['id', 'name', 'description', 'nodeCount', 'updatedAt', 'link'],
+        columns: [
+            'id',
+            'name',
+            'description',
+            'nodeCount',
+            'updatedAt',
+            'org',
+            'teams',
+            'link',
+        ],
     });
 }
-export async function handleBoards(client, _params, baseUrl) {
+export async function handleBoards(client, params, baseUrl) {
     try {
-        const boards = await client.listBoards();
+        const boards = await client.listBoards({ orgId: params.orgId });
         const formatted = boards.map(board => ({
             id: board._id,
             name: board.name,
             description: board.description || '',
             nodeCount: board.nodeCount ?? 0,
             updatedAt: formatShortDate(board.updatedAt),
+            org: board.org || '',
+            teams: board.teams?.join(',') || '',
             link: getBoardUrl(baseUrl, board._id),
         }));
         return {

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-board.js

@@ -4,6 +4,11 @@ import { formatError } from '../utils/errors.js';
 import { getBoardUrl } from '../utils/urls.js';
 export const createBoardSchema = z.object({
     name: z.string().min(1).describe('The name for the new board'),
+    orgId: z
+        .string()
+        .length(24)
+        .optional()
+        .describe('Optional organization ID to create the board in'),
 });
 function generateObjectId() {
     const timestamp = Math.floor(Date.now() / 1000)
@@ -18,6 +23,7 @@ export async function handleCreateBoard(client, params, baseUrl) {
         const board = await client.createBoard({
             _id: boardId,
             name: params.name,
+            org: params.orgId,
         });
         const result = {
             success: true,

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 {