@mentagen/mcp 0.5.0 → 0.7.0

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

@@ -5,7 +5,6 @@ import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextpro
 import { batchUpdateSchema, handleBatchUpdate } from './batch-update.js';
 import { boardsSchema, handleBoards } from './boards.js';
 import { checkCollisionSchema, handleCheckCollision, } from './check-collision.js';
-import { colorsSchema, handleColors } from './colors.js';
 import { createSchema, handleCreate } from './create.js';
 import { createBoardSchema, handleCreateBoard } from './create-board.js';
 import { createEdgeSchema, handleCreateEdge } from './create-edge.js';
@@ -22,11 +21,9 @@ import { handleListNodes, listNodesSchema } from './list-nodes.js';
 import { handleListOrganizations, listOrganizationsSchema, } from './list-organizations.js';
 import { handleListPositions, listPositionsSchema } from './list-positions.js';
 import { handleListTeams, listTeamsSchema } from './list-teams.js';
-import { handleNodeTypes, nodeTypesSchema } from './node-types.js';
 import { handlePatchContent, patchContentSchema } from './patch-content.js';
 import { handleRead, readSchema } from './read.js';
 import { handleSearch, searchSchema } from './search.js';
-import { handleSearchBoard, searchBoardSchema } from './search-board.js';
 import { handleSearchBoards, searchBoardsSchema } from './search-boards.js';
 import { handleSizeCalc, sizeCalcSchema } from './size-calc.js';
 import { handleUpdate, updateSchema } from './update.js';
@@ -204,7 +201,7 @@ export function registerTools(server, client, config) {
             },
             {
                 name: 'mentagen_search_nodes',
-                description: 'Search for nodes across ALL your boards using semantic search. Returns matching nodes with truncated content previews and direct links. Use mentagen_search_board to search within a specific board, or mentagen_read_node with the node ID to retrieve full content.',
+                description: 'Search for nodes using semantic search. Returns matching nodes with truncated content previews and direct links. Use mentagen_read_node with the node ID to retrieve full content.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -234,34 +231,6 @@ export function registerTools(server, client, config) {
                     required: ['query'],
                 },
             },
-            {
-                name: 'mentagen_search_board',
-                description: 'Search for nodes within a SPECIFIC board using semantic search. Use this when you know which board to search in. Returns matching nodes with truncated content previews and direct links. Use mentagen_read_node with the node ID to retrieve full content.',
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        boardId: {
-                            type: 'string',
-                            description: 'The board ID to search within (required)',
-                        },
-                        query: {
-                            type: 'string',
-                            description: 'The search query - can be a question or keywords',
-                        },
-                        limit: {
-                            type: 'number',
-                            description: 'Maximum number of results (default: 10)',
-                            default: 10,
-                        },
-                        semanticRatio: {
-                            type: 'number',
-                            description: 'Balance between semantic (1.0) and keyword (0.0) search',
-                            default: 0.5,
-                        },
-                    },
-                    required: ['boardId', 'query'],
-                },
-            },
             {
                 name: 'mentagen_read_node',
                 description: 'Read a single node by ID. Returns the full node content without truncation, unlike search results. Includes a direct link to the node.',
@@ -313,11 +282,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',
@@ -359,23 +328,23 @@ export function registerTools(server, client, config) {
                         },
                         color: {
                             type: 'string',
-                            description: 'Node color name (use mentagen_colors to see available colors)',
+                            description: 'Node color name (see mentagen://colors resource for available colors)',
                         },
                         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 +392,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 +544,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'],
@@ -715,25 +702,9 @@ export function registerTools(server, client, config) {
                     required: ['boardId'],
                 },
             },
-            {
-                name: 'mentagen_colors',
-                description: 'Get the list of available colors for nodes. Returns color names and their RGB values.',
-                inputSchema: {
-                    type: 'object',
-                    properties: {},
-                },
-            },
-            {
-                name: 'mentagen_node_types',
-                description: 'Get the list of supported node types with descriptions and usage guidance. Use this to understand what types of nodes can be created.',
-                inputSchema: {
-                    type: 'object',
-                    properties: {},
-                },
-            },
             {
                 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 +715,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 +739,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 +773,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 +811,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 +821,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 +838,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 +854,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: {
@@ -966,10 +937,6 @@ export function registerTools(server, client, config) {
             const params = searchSchema.parse(args);
             return handleSearch(client, params, config.mentagenUrl);
         },
-        mentagen_search_board: async (args) => {
-            const params = searchBoardSchema.parse(args);
-            return handleSearchBoard(client, params, config.mentagenUrl);
-        },
         mentagen_read_node: async (args) => {
             const params = readSchema.parse(args);
             return handleRead(client, params, config.mentagenUrl);
@@ -1020,14 +987,6 @@ export function registerTools(server, client, config) {
             const params = linkSchema.parse(args);
             return handleLink(params, config);
         },
-        mentagen_colors: async (args) => {
-            colorsSchema.parse(args);
-            return handleColors();
-        },
-        mentagen_node_types: async (args) => {
-            nodeTypesSchema.parse(args);
-            return handleNodeTypes();
-        },
         mentagen_grid_calc: async (args) => {
             const params = gridCalcSchema.parse(args);
             return handleGridCalc(params, client);

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: [
             {