@mentagen/mcp 0.1.0 → 0.3.0

package/dist/tools/create-graph.js

@@ -1,10 +1,14 @@
 import { z } from 'zod';
 import { formatError } from '../utils/errors.js';
-import { generateId } from './create.js';
+import { applyExtension, generateId } from './create.js';
 import { calculateNodeSize } from './size-calc.js';
 const nodeInputSchema = z.object({
     tempId: z.string().describe('Temporary ID for referencing in edges'),
     name: z.string().describe('The node title/name'),
+    extension: z
+        .string()
+        .optional()
+        .describe('File extension to append to name (e.g., ".ts", ".py"). Only applies to code nodes. Defaults to .js.'),
     content: z.string().optional().describe('Node content'),
     type: z
         .enum(['text', 'markdown', 'code', 'url'])
@@ -43,8 +47,9 @@ const DEFAULT_NODE_COLORS = {
 async function createNode(client, boardId, nodeInput, idMap) {
     const realId = generateId();
     const type = nodeInput.type ?? 'text';
+    const finalName = applyExtension(nodeInput.name, type, nodeInput.extension);
     const color = nodeInput.color ?? DEFAULT_NODE_COLORS[type];
-    const autoSize = calculateNodeSize(nodeInput.name, type);
+    const autoSize = calculateNodeSize(finalName, type);
     const x = nodeInput.x ?? 100;
     const y = nodeInput.y ?? 100;
     const width = nodeInput.width ?? autoSize.width;
@@ -57,7 +62,7 @@ async function createNode(client, boardId, nodeInput, idMap) {
             _id: realId,
             boardId,
             node: {
-                name: nodeInput.name,
+                name: finalName,
                 ...(isCodeNode ? { code: nodeContent } : { content: nodeContent }),
                 type,
                 color,

package/dist/tools/create.js

@@ -27,9 +27,27 @@ const DEFAULT_NODE_COLORS = {
     excalidraw: 'teal',
     teleprompter: 'rose',
 };
+const DEFAULT_CODE_EXTENSION = '.js';
+/**
+ * Append extension to name for code nodes only.
+ * Defaults to .js if no extension provided.
+ * Avoids double extensions if name already ends with the extension.
+ */
+export function applyExtension(name, type, extension) {
+    if (type !== 'code')
+        return name;
+    const ext = extension ?? DEFAULT_CODE_EXTENSION;
+    if (name.endsWith(ext))
+        return name;
+    return `${name}${ext}`;
+}
 export const createSchema = z.object({
     boardId: z.string().describe('The board ID to create the node on'),
     name: z.string().describe('The node title/name'),
+    extension: z
+        .string()
+        .optional()
+        .describe('File extension to append to name (e.g., ".ts", ".py"). Only applies to code nodes. Defaults to .js.'),
     content: z
         .string()
         .optional()
@@ -77,6 +95,7 @@ export function generateId() {
 }
 /**
  * Build node fields object with content mapped to the correct field based on type.
+ * Expects params.name to already have extension applied.
  */
 function buildNodeFields(params, color, position) {
     const nodeFields = {
@@ -105,15 +124,16 @@ function buildNodeFields(params, color, position) {
 export async function handleCreate(client, params, mentagenUrl) {
     try {
         const _id = generateId();
+        const finalName = applyExtension(params.name, params.type, params.extension);
         const color = params.color || DEFAULT_NODE_COLORS[params.type];
-        const autoSize = calculateNodeSize(params.name, 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),
         };
-        const nodeFields = buildNodeFields(params, color, position);
+        const nodeFields = buildNodeFields({ ...params, name: finalName }, color, position);
         const node = await client.addNode({
             _id,
             boardId: params.boardId,

package/dist/tools/find-overlaps.js

@@ -0,0 +1,94 @@
+import { z } from 'zod';
+import { rectsIntersect } from '../utils/collision.js';
+import { formatError } from '../utils/errors.js';
+export const findOverlapsSchema = z.object({
+    boardId: z.string().describe('The board ID to check for overlapping nodes'),
+});
+function calculateOverlapArea(a, b) {
+    const xOverlap = Math.max(0, Math.min(a.x + a.width, b.x + b.width) - Math.max(a.x, b.x));
+    const yOverlap = Math.max(0, Math.min(a.y + a.height, b.y + b.height) - Math.max(a.y, b.y));
+    return xOverlap * yOverlap;
+}
+export async function handleFindOverlaps(client, params) {
+    try {
+        const nodes = await client.listNodes({
+            boardId: params.boardId,
+            limit: 1000,
+        });
+        if (nodes.length === 0) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'No nodes found in this board.',
+                    },
+                ],
+            };
+        }
+        const overlaps = [];
+        for (let i = 0; i < nodes.length; i++) {
+            const node1 = nodes[i];
+            const rect1 = {
+                x: node1.x,
+                y: node1.y,
+                width: node1.width,
+                height: node1.height,
+            };
+            for (let j = i + 1; j < nodes.length; j++) {
+                const node2 = nodes[j];
+                const rect2 = {
+                    x: node2.x,
+                    y: node2.y,
+                    width: node2.width,
+                    height: node2.height,
+                };
+                if (rectsIntersect(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),
+                    });
+                }
+            }
+        }
+        if (overlaps.length === 0) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `No overlapping nodes found. All ${nodes.length} nodes are properly positioned.`,
+                    },
+                ],
+            };
+        }
+        overlaps.sort((a, b) => b.overlapArea - a.overlapArea);
+        const summary = `Found ${overlaps.length} overlapping node pair(s) among ${nodes.length} nodes.\n`;
+        const details = overlaps
+            .map((o, i) => {
+            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²`);
+        })
+            .join('\n\n');
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: summary + '\n' + details,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Failed to find overlaps: ${formatError(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}

package/dist/tools/index.js

@@ -13,6 +13,7 @@ import { createGraphSchema, handleCreateGraph } from './create-graph.js';
 import { deleteSchema, handleDelete } from './delete.js';
 import { deleteEdgeSchema, handleDeleteEdge } from './delete-edge.js';
 import { extractBoardContentSchema, handleExtractBoardContent, } from './extract-board-content.js';
+import { findOverlapsSchema, handleFindOverlaps } from './find-overlaps.js';
 import { findPositionSchema, handleFindPosition } from './find-position.js';
 import { gridCalcSchema, handleGridCalc } from './grid-calc.js';
 import { handleLink, linkSchema } from './link.js';
@@ -29,6 +30,7 @@ import { handleSizeCalc, sizeCalcSchema } from './size-calc.js';
 import { handleUpdate, updateSchema } from './update.js';
 import { handleUpdateBoard, updateBoardSchema } from './update-board.js';
 import { handleUpdateEdge, updateEdgeSchema } from './update-edge.js';
+import { handleVisualizeBoard, visualizeBoardSchema, } from './visualize-board.js';
 export function registerTools(server, client, config) {
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools: [
@@ -229,7 +231,11 @@ export function registerTools(server, client, config) {
                         },
                         name: {
                             type: 'string',
-                            description: 'The node title/name (used for auto-sizing). For code nodes, use a filename with extension (e.g., "utils.ts", "app.py") for syntax highlighting.',
+                            description: 'The node title/name (used for auto-sizing). Extension is appended automatically via the extension parameter.',
+                        },
+                        extension: {
+                            type: 'string',
+                            description: 'File extension to append to name (e.g., ".ts", ".py"). Only applies to code nodes. Defaults to .js.',
                         },
                         content: {
                             type: 'string',
@@ -238,7 +244,7 @@ export function registerTools(server, client, config) {
                         type: {
                             type: 'string',
                             enum: ['text', 'markdown', 'code', 'url'],
-                            description: 'Node type: text (default), markdown, code, or url. Code nodes get syntax highlighting based on the file extension in the name.',
+                            description: 'Node type: text (default), markdown, code, or url.',
                         },
                         color: {
                             type: 'string',
@@ -476,7 +482,11 @@ export function registerTools(server, client, config) {
                                     },
                                     name: {
                                         type: 'string',
-                                        description: 'Node title/name (used for auto-sizing). For code nodes, use a filename with extension for syntax highlighting.',
+                                        description: 'Node title/name (used for auto-sizing). Extension is appended automatically via the extension parameter.',
+                                    },
+                                    extension: {
+                                        type: 'string',
+                                        description: 'File extension to append to name (e.g., ".ts", ".py"). Only applies to code nodes. Defaults to .js.',
                                     },
                                     content: {
                                         type: 'string',
@@ -485,7 +495,7 @@ export function registerTools(server, client, config) {
                                     type: {
                                         type: 'string',
                                         enum: ['text', 'markdown', 'code', 'url'],
-                                        description: 'Node type (default: text). Code nodes get syntax highlighting based on file extension in name.',
+                                        description: 'Node type (default: text).',
                                     },
                                     color: { type: 'string', description: 'Node color' },
                                     x: { type: 'number', description: 'X position' },
@@ -749,6 +759,20 @@ export function registerTools(server, client, config) {
                     required: ['boardId', 'x', 'y', 'width', 'height'],
                 },
             },
+            {
+                name: 'mentagen_find_overlaps',
+                description: 'Find all overlapping node pairs on a board. Returns a list of nodes that overlap with each other, sorted by overlap area. Use this to detect layout issues and identify nodes that need repositioning.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        boardId: {
+                            type: 'string',
+                            description: 'The board ID to check for overlapping nodes',
+                        },
+                    },
+                    required: ['boardId'],
+                },
+            },
             {
                 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.',
@@ -810,6 +834,23 @@ export function registerTools(server, client, config) {
                     required: ['name'],
                 },
             },
+            {
+                name: 'mentagen_visualize_board',
+                description: 'Generate a visual PNG image of a board showing all nodes and their connections. ' +
+                    'Each node displays its ID in the center. Edges are drawn with arrows for directed connections. ' +
+                    'Image dimensions are automatically computed to fit all nodes at a readable size. ' +
+                    'Use this to understand the spatial layout and relationships between nodes.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        boardId: {
+                            type: 'string',
+                            description: 'The board ID to visualize',
+                        },
+                    },
+                    required: ['boardId'],
+                },
+            },
         ],
     }));
     const toolHandlers = {
@@ -917,6 +958,10 @@ export function registerTools(server, client, config) {
             const params = checkCollisionSchema.parse(args);
             return handleCheckCollision(client, params);
         },
+        mentagen_find_overlaps: async (args) => {
+            const params = findOverlapsSchema.parse(args);
+            return handleFindOverlaps(client, params);
+        },
         mentagen_find_position: async (args) => {
             const params = findPositionSchema.parse(args);
             return handleFindPosition(client, params);
@@ -925,6 +970,10 @@ export function registerTools(server, client, config) {
             const params = sizeCalcSchema.parse(args);
             return handleSizeCalc(params);
         },
+        mentagen_visualize_board: async (args) => {
+            const params = visualizeBoardSchema.parse(args);
+            return handleVisualizeBoard(client, params);
+        },
     };
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const { name, arguments: args } = request.params;

package/dist/tools/visualize-board.js

@@ -0,0 +1,319 @@
+import { Resvg } from '@resvg/resvg-js';
+import { z } from 'zod';
+import { EdgeDirection } from '../client/types.js';
+import { formatError } from '../utils/errors.js';
+export const visualizeBoardSchema = z.object({
+    boardId: z.string().describe('The board ID to visualize'),
+});
+const PADDING = 60;
+const MIN_IMAGE_WIDTH = 1000;
+const MAX_IMAGE_WIDTH = 1800;
+const MIN_NODE_DISPLAY_SIZE = 100;
+function computeBounds(nodes) {
+    if (nodes.length === 0) {
+        return { minX: 0, minY: 0, maxX: 400, maxY: 300, width: 400, height: 300 };
+    }
+    const minX = Math.min(...nodes.map(n => n.x));
+    const minY = Math.min(...nodes.map(n => n.y));
+    const maxX = Math.max(...nodes.map(n => n.x + n.width));
+    const maxY = Math.max(...nodes.map(n => n.y + n.height));
+    return {
+        minX,
+        minY,
+        maxX,
+        maxY,
+        width: maxX - minX,
+        height: maxY - minY,
+    };
+}
+function computeImageDimensions(bounds, nodeCount) {
+    if (nodeCount === 0) {
+        return { width: MIN_IMAGE_WIDTH, height: 600, scale: 1 };
+    }
+    const avgNodeSize = Math.min(bounds.width, bounds.height) / Math.sqrt(nodeCount);
+    const scale = avgNodeSize < MIN_NODE_DISPLAY_SIZE
+        ? MIN_NODE_DISPLAY_SIZE / avgNodeSize
+        : 1;
+    let width = (bounds.width + PADDING * 2) * scale;
+    let height = (bounds.height + PADDING * 2) * scale;
+    if (width > MAX_IMAGE_WIDTH) {
+        const ratio = MAX_IMAGE_WIDTH / width;
+        width = MAX_IMAGE_WIDTH;
+        height = height * ratio;
+    }
+    if (width < MIN_IMAGE_WIDTH) {
+        const ratio = MIN_IMAGE_WIDTH / width;
+        width = MIN_IMAGE_WIDTH;
+        height = height * ratio;
+    }
+    height = Math.max(height, 400);
+    height = Math.min(height, 1200);
+    return {
+        width: Math.round(width),
+        height: Math.round(height),
+        scale,
+    };
+}
+function escapeXml(str) {
+    return str
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
+function calculateFontSize(nodeWidth, textLength) {
+    const charWidth = 7;
+    const padding = 16;
+    const availableWidth = nodeWidth - padding;
+    const idealSize = availableWidth / (textLength * (charWidth / 12));
+    return Math.max(10, Math.min(14, idealSize));
+}
+function getNodeColor(type) {
+    const colors = {
+        text: '#f1f5f9',
+        markdown: '#ecfeff',
+        code: '#eef2ff',
+        image: '#fef2f2',
+        pdf: '#fef3c7',
+        url: '#dbeafe',
+        'ai-chat': '#f3e8ff',
+        mermaid: '#dcfce7',
+    };
+    return colors[type] || '#f1f5f9';
+}
+function getNodeStrokeColor(type) {
+    const colors = {
+        text: '#64748b',
+        markdown: '#06b6d4',
+        code: '#6366f1',
+        image: '#ef4444',
+        pdf: '#f59e0b',
+        url: '#3b82f6',
+        'ai-chat': '#a855f7',
+        mermaid: '#22c55e',
+    };
+    return colors[type] || '#64748b';
+}
+function renderNode(node) {
+    const fill = getNodeColor(node.type);
+    const stroke = getNodeStrokeColor(node.type);
+    const id = node._id;
+    const centerX = node.x + node.width / 2;
+    const centerY = node.y + node.height / 2;
+    const fontSize = calculateFontSize(node.width, id.length);
+    return `
+    <g>
+      <rect
+        x="${node.x}"
+        y="${node.y}"
+        width="${node.width}"
+        height="${node.height}"
+        fill="${fill}"
+        stroke="${stroke}"
+        stroke-width="2"
+        rx="6"
+      />
+      <text
+        x="${centerX}"
+        y="${centerY}"
+        text-anchor="middle"
+        dominant-baseline="middle"
+        font-family="ui-monospace, SFMono-Regular, monospace"
+        font-size="${fontSize}"
+        font-weight="500"
+        fill="#1e293b"
+      >${escapeXml(id)}</text>
+    </g>
+  `;
+}
+function findNodeCenter(nodes, nodeId) {
+    const node = nodes.find(n => n._id === nodeId);
+    if (!node)
+        return null;
+    return {
+        x: node.x + node.width / 2,
+        y: node.y + node.height / 2,
+    };
+}
+function findClosestSides(sourceNode, targetNode) {
+    const sourceCenterX = sourceNode.x + sourceNode.width / 2;
+    const sourceCenterY = sourceNode.y + sourceNode.height / 2;
+    const targetCenterX = targetNode.x + targetNode.width / 2;
+    const targetCenterY = targetNode.y + targetNode.height / 2;
+    const sourceSides = {
+        top: { x: sourceCenterX, y: sourceNode.y },
+        bottom: { x: sourceCenterX, y: sourceNode.y + sourceNode.height },
+        left: { x: sourceNode.x, y: sourceCenterY },
+        right: { x: sourceNode.x + sourceNode.width, y: sourceCenterY },
+    };
+    const targetSides = {
+        top: { x: targetCenterX, y: targetNode.y },
+        bottom: { x: targetCenterX, y: targetNode.y + targetNode.height },
+        left: { x: targetNode.x, y: targetCenterY },
+        right: { x: targetNode.x + targetNode.width, y: targetCenterY },
+    };
+    let minDist = Infinity;
+    let bestSource = sourceSides.right;
+    let bestTarget = targetSides.left;
+    for (const [, sp] of Object.entries(sourceSides)) {
+        for (const [, tp] of Object.entries(targetSides)) {
+            const dist = Math.sqrt((sp.x - tp.x) ** 2 + (sp.y - tp.y) ** 2);
+            if (dist < minDist) {
+                minDist = dist;
+                bestSource = sp;
+                bestTarget = tp;
+            }
+        }
+    }
+    return { source: bestSource, target: bestTarget };
+}
+function renderEdge(edge, nodes) {
+    const sourceNode = nodes.find(n => n._id === edge.source);
+    const targetNode = nodes.find(n => n._id === edge.target);
+    if (!sourceNode || !targetNode)
+        return '';
+    const { source, target } = findClosestSides(sourceNode, targetNode);
+    const hasArrow = edge.direction && edge.direction !== EdgeDirection.None;
+    const markerId = `arrow-${edge._id}`;
+    let path = '';
+    let marker = '';
+    if (hasArrow) {
+        const isToSource = edge.direction === EdgeDirection.Source;
+        const arrowStart = isToSource ? target : source;
+        const arrowEnd = isToSource ? source : target;
+        marker = `
+      <defs>
+        <marker
+          id="${markerId}"
+          markerWidth="10"
+          markerHeight="7"
+          refX="9"
+          refY="3.5"
+          orient="auto"
+        >
+          <polygon points="0 0, 10 3.5, 0 7" fill="#64748b" />
+        </marker>
+      </defs>
+    `;
+        path = `
+      <line
+        x1="${arrowStart.x}"
+        y1="${arrowStart.y}"
+        x2="${arrowEnd.x}"
+        y2="${arrowEnd.y}"
+        stroke="#64748b"
+        stroke-width="2"
+        marker-end="url(#${markerId})"
+      />
+    `;
+    }
+    else {
+        path = `
+      <line
+        x1="${source.x}"
+        y1="${source.y}"
+        x2="${target.x}"
+        y2="${target.y}"
+        stroke="#94a3b8"
+        stroke-width="1.5"
+      />
+    `;
+    }
+    return marker + path;
+}
+function generateSvg(nodes, edges, bounds, dimensions) {
+    const viewBoxX = bounds.minX - PADDING;
+    const viewBoxY = bounds.minY - PADDING;
+    const viewBoxWidth = bounds.width + PADDING * 2;
+    const viewBoxHeight = bounds.height + PADDING * 2;
+    const edgesSvg = edges.map(e => renderEdge(e, nodes)).join('\n');
+    const nodesSvg = nodes.map(n => renderNode(n)).join('\n');
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<svg
+  xmlns="http://www.w3.org/2000/svg"
+  viewBox="${viewBoxX} ${viewBoxY} ${viewBoxWidth} ${viewBoxHeight}"
+  width="${dimensions.width}"
+  height="${dimensions.height}"
+>
+  <rect
+    x="${viewBoxX}"
+    y="${viewBoxY}"
+    width="${viewBoxWidth}"
+    height="${viewBoxHeight}"
+    fill="#ffffff"
+  />
+  ${edgesSvg}
+  ${nodesSvg}
+</svg>`;
+}
+export async function handleVisualizeBoard(client, params) {
+    try {
+        const [nodes, edges] = await Promise.all([
+            client.listNodes({ boardId: params.boardId, limit: 1000 }),
+            client.listEdges({ boardId: params.boardId, limit: 1000 }),
+        ]);
+        if (nodes.length === 0) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'No nodes found in this board.',
+                    },
+                ],
+            };
+        }
+        const bounds = computeBounds(nodes);
+        const dimensions = computeImageDimensions(bounds, nodes.length);
+        const svg = generateSvg(nodes, edges, bounds, dimensions);
+        const resvg = new Resvg(svg, {
+            fitTo: {
+                mode: 'width',
+                value: dimensions.width,
+            },
+        });
+        const pngData = resvg.render();
+        const pngBuffer = pngData.asPng();
+        const base64 = pngBuffer.toString('base64');
+        const summary = `Board visualization: ${nodes.length} nodes, ${edges.length} edges (${dimensions.width}x${dimensions.height}px)`;
+        const nodeLegend = nodes
+            .map(n => `${n._id}\t${n.type}\t${n.name}`)
+            .join('\n');
+        const edgeLegend = edges.length > 0
+            ? edges
+                .map(e => {
+                const dir = e.direction === EdgeDirection.Target
+                    ? '→'
+                    : e.direction === EdgeDirection.Source
+                        ? '←'
+                        : '—';
+                return `${e.source} ${dir} ${e.target}${e.label ? ` (${e.label})` : ''}`;
+            })
+                .join('\n')
+            : 'No edges';
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `${summary}\n\nNodes (id, type, name):\n${nodeLegend}\n\nEdges (source → target):\n${edgeLegend}`,
+                },
+                {
+                    type: 'image',
+                    data: base64,
+                    mimeType: 'image/png',
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Failed to visualize board: ${formatError(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mentagen/mcp",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "MCP server for Mentagen knowledge base integration with Cursor",
   "type": "module",
   "bin": "dist/index.js",
@@ -29,6 +29,7 @@
   "license": "UNLICENSED",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
+    "@resvg/resvg-js": "^2.6.2",
     "ejson2": "^1.1.0",
     "papaparse": "^5.5.3",
     "zod": "^3.24.1"