@mentagen/mcp 0.1.0

package/dist/tools/search.js

@@ -0,0 +1,89 @@
+import Papa from 'papaparse';
+import { z } from 'zod';
+import { formatError } from '../utils/errors.js';
+import { formatSearchResults } from '../utils/formatting.js';
+import { getNodeUrl } from '../utils/urls.js';
+export const searchSchema = z.object({
+    query: z
+        .string()
+        .describe('The search query - can be a question or keywords'),
+    board: z
+        .string()
+        .optional()
+        .describe('Optional board ID to limit search scope'),
+    limit: z
+        .number()
+        .default(10)
+        .describe('Maximum number of results (default: 10)'),
+    semanticRatio: z
+        .number()
+        .default(0.5)
+        .describe('Balance between semantic (1.0) and keyword (0.0) search'),
+});
+const MAX_CONTENT_LENGTH = 200;
+/**
+ * Truncate content to save tokens, preserving word boundaries.
+ */
+function truncateContent(content, maxLength) {
+    if (!content)
+        return '';
+    if (content.length <= maxLength)
+        return content;
+    const truncated = content.slice(0, maxLength);
+    const lastSpace = truncated.lastIndexOf(' ');
+    return ((lastSpace > maxLength * 0.7 ? truncated.slice(0, lastSpace) : truncated) +
+        '...');
+}
+/**
+ * Format search results as TSV for compact output.
+ */
+function formatSearchTsv(results) {
+    const rows = results.map(r => ({
+        id: r.id,
+        name: r.name,
+        content: truncateContent(r.content, MAX_CONTENT_LENGTH),
+        type: r.type,
+        board: r.board || '',
+        score: Math.round(r.score * 100) / 100,
+        link: r.link,
+    }));
+    return Papa.unparse(rows, {
+        delimiter: '\t',
+        header: true,
+        newline: '\n',
+        columns: ['id', 'name', 'content', 'type', 'board', 'score', 'link'],
+    });
+}
+export async function handleSearch(client, params, baseUrl) {
+    try {
+        const results = await client.searchNodes({
+            query: params.query,
+            board: params.board,
+            semanticRatio: params.semanticRatio,
+        });
+        const formatted = formatSearchResults(results.hits.slice(0, params.limit));
+        const resultsWithLinks = formatted.results.map(r => ({
+            ...r,
+            link: r.board ? getNodeUrl(baseUrl, r.board, r.id) : '',
+        }));
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: formatSearchTsv(resultsWithLinks),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Search failed: ${formatError(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}

package/dist/tools/size-calc.js

@@ -0,0 +1,108 @@
+import { z } from 'zod';
+// Grid and constraint constants (from src/common/boards/constraints.ts)
+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;
+// Text measurement constants (from measure-node-size.ts)
+const MAX_AUTO_WIDTH = 400;
+const PADDING_X = 12;
+const PADDING_Y = 12;
+const ICON_WIDTH = 16;
+const GAP = 8;
+const LINE_HEIGHT = 24;
+// Average character width at 16px font (approximation)
+const AVG_CHAR_WIDTH = 8.5;
+// Node types that display an icon
+const NODE_TYPES_WITH_ICONS = new Set([
+    'ai-chat',
+    'board',
+    'contact',
+    'pdf',
+    'file',
+    'mermaid',
+    'code',
+    'markdown',
+    'teleprompter',
+    'excalidraw',
+    'url',
+    'voice',
+    'audio',
+    'ai-quiz',
+]);
+export const sizeCalcSchema = z.object({
+    name: z.string().describe('The node name/title to measure'),
+    type: z
+        .string()
+        .optional()
+        .default('text')
+        .describe('Node type (affects icon space calculation)'),
+});
+function roundToGrid(value) {
+    const result = Math.round(value / GRID) * GRID;
+    return Object.is(result, -0) ? 0 : result;
+}
+function hasIcon(type) {
+    return NODE_TYPES_WITH_ICONS.has(type);
+}
+/**
+ * Estimate text dimensions without DOM access.
+ * Uses average character width approximation.
+ */
+function estimateTextSize(text) {
+    if (!text || text.trim() === '') {
+        return { width: 0, lines: 1 };
+    }
+    // Split by newlines first
+    const explicitLines = text.split('\n');
+    let maxLineWidth = 0;
+    let totalLines = 0;
+    for (const line of explicitLines) {
+        const lineWidth = line.length * AVG_CHAR_WIDTH;
+        // Check if line needs wrapping
+        const maxContentWidth = MAX_AUTO_WIDTH - PADDING_X;
+        if (lineWidth > maxContentWidth) {
+            // Estimate wrapped lines
+            const wrappedLines = Math.ceil(lineWidth / maxContentWidth);
+            totalLines += wrappedLines;
+            maxLineWidth = Math.max(maxLineWidth, maxContentWidth);
+        }
+        else {
+            totalLines += 1;
+            maxLineWidth = Math.max(maxLineWidth, lineWidth);
+        }
+    }
+    return { width: maxLineWidth, lines: totalLines };
+}
+/**
+ * Calculate recommended node size based on name and type only.
+ * Content is intentionally ignored — nodes should be sized to fit their title,
+ * with content scrollable inside.
+ */
+export function calculateNodeSize(name, type) {
+    const withIcon = hasIcon(type);
+    const iconSpace = withIcon ? ICON_WIDTH + GAP : 0;
+    // Measure the title
+    const titleSize = estimateTextSize(name);
+    // Calculate width based on title
+    const contentWidth = Math.min(titleSize.width, MAX_AUTO_WIDTH - PADDING_X - iconSpace);
+    const totalWidth = contentWidth + PADDING_X + iconSpace;
+    // Calculate height from title only
+    const totalHeight = titleSize.lines * LINE_HEIGHT + PADDING_Y;
+    // Apply grid snapping and constraints
+    const width = roundToGrid(Math.max(MIN_WIDTH, Math.min(MAX_WIDTH, totalWidth)));
+    const height = roundToGrid(Math.max(MIN_HEIGHT, Math.min(MAX_HEIGHT, totalHeight)));
+    return { width, height };
+}
+export function handleSizeCalc(params) {
+    const { width, height } = calculateNodeSize(params.name, params.type);
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({ width, height }, null, 2),
+            },
+        ],
+    };
+}

package/dist/tools/update-board.js

@@ -0,0 +1,64 @@
+import { z } from 'zod';
+import { formatError } from '../utils/errors.js';
+import { getBoardUrl } from '../utils/urls.js';
+export const updateBoardSchema = z
+    .object({
+    boardId: z.string().describe('The board ID to update'),
+    name: z.string().min(1).optional().describe('New name for the board'),
+    description: z
+        .string()
+        .optional()
+        .describe('New description for the board'),
+    pullRequestUrl: z
+        .string()
+        .url()
+        .optional()
+        .describe('Pull request URL for this board'),
+})
+    .refine(data => data.name !== undefined ||
+    data.description !== undefined ||
+    data.pullRequestUrl !== undefined, {
+    message: 'At least one field (name, description, or pullRequestUrl) must be provided',
+});
+export async function handleUpdateBoard(client, params, baseUrl) {
+    try {
+        const data = {};
+        if (params.name !== undefined)
+            data.name = params.name;
+        if (params.description !== undefined)
+            data.description = params.description;
+        if (params.pullRequestUrl !== undefined)
+            data.pullRequestUrl = params.pullRequestUrl;
+        const board = await client.updateBoard({
+            boardId: params.boardId,
+            data,
+        });
+        const result = {
+            success: true,
+            board: {
+                id: board._id,
+                name: board.name,
+                link: getBoardUrl(baseUrl, board._id),
+            },
+        };
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Failed to update board: ${formatError(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}

package/dist/tools/update-edge.js

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+import { EdgeDirection } from '../client/types.js';
+import { formatError } from '../utils/errors.js';
+export const updateEdgeSchema = z.object({
+    boardId: z.string().describe('The board ID containing the edge'),
+    edgeId: z.string().describe('The edge ID to update'),
+    direction: z
+        .enum(['none', 'source', 'target'])
+        .optional()
+        .describe('Edge direction: none (no arrow), source (arrow to source), target (arrow to target)'),
+    label: z.string().optional().describe('Optional label text for the edge'),
+});
+export async function handleUpdateEdge(client, params) {
+    try {
+        // Check if any updates provided
+        if (params.direction === undefined && params.label === undefined) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'No updates provided. Specify direction and/or label to update.',
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const edge = await client.updateEdge({
+            boardId: params.boardId,
+            edgeId: params.edgeId,
+            direction: params.direction,
+            label: params.label,
+        });
+        const result = {
+            success: true,
+            edge: {
+                id: edge._id,
+                source: edge.source,
+                target: edge.target,
+                direction: edge.direction || EdgeDirection.None,
+                label: edge.label || null,
+            },
+        };
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Failed to update edge: ${formatError(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}

package/dist/tools/update.js

@@ -0,0 +1,157 @@
+import { z } from 'zod';
+import { NodeType } from '../client/types.js';
+import { formatError } from '../utils/errors.js';
+import { snapToGrid } from './grid-calc.js';
+import { calculateNodeSize } from './size-calc.js';
+export const updateSchema = z.object({
+    boardId: z.string().describe('The board ID containing the node'),
+    nodeId: z.string().describe('The node ID to update'),
+    name: z.string().optional().describe('New name for the node'),
+    content: z
+        .string()
+        .optional()
+        .describe('Content for text/markdown nodes. Use "url" field for url-type nodes.'),
+    url: z
+        .string()
+        .optional()
+        .describe('The URL for url-type nodes (e.g., https://example.com). Only for type="url".'),
+    color: z
+        .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)'),
+    autoSize: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe('Auto-resize node when name changes (default: true). Set to false to keep current size.'),
+});
+const POSITION_FIELDS = ['x', 'y', 'width', 'height'];
+/**
+ * Add content fields to update data based on node type.
+ */
+function addContentFields(data, params, nodeType) {
+    if (nodeType === NodeType.Code && params.content !== undefined) {
+        data.code = params.content;
+    }
+    else if (nodeType === NodeType.URL) {
+        if (params.url !== undefined) {
+            data.url = params.url;
+        }
+        if (params.content !== undefined) {
+            data.content = params.content;
+        }
+    }
+    else if (params.content !== undefined) {
+        data.content = params.content;
+    }
+}
+/**
+ * Builds the update data object, mapping content/url to the correct field based on node type.
+ * Code nodes store their content in `code`, url nodes use `url`, others use `content`.
+ */
+function buildUpdateData(params, nodeType) {
+    const data = {};
+    if (params.name !== undefined)
+        data.name = params.name;
+    if (params.color !== undefined)
+        data.color = params.color;
+    addContentFields(data, params, nodeType);
+    for (const field of POSITION_FIELDS) {
+        const value = params[field];
+        if (value !== undefined) {
+            data[field] = snapToGrid(value);
+        }
+    }
+    return Object.keys(data).length > 0 ? data : null;
+}
+function shouldAutoSize(params) {
+    return (params.autoSize !== false &&
+        params.name !== undefined &&
+        params.width === undefined &&
+        params.height === undefined);
+}
+/**
+ * Fetches the node and calculates auto-size if needed.
+ * Returns both the node (for type detection) and optional auto-size dimensions.
+ */
+async function getNodeContext(client, params) {
+    const node = await client.getNode({
+        boardId: params.boardId,
+        nodeId: params.nodeId,
+    });
+    const autoSize = shouldAutoSize(params) && params.name
+        ? calculateNodeSize(params.name, node.type)
+        : null;
+    return { node, autoSize };
+}
+function formatSuccessResponse(node) {
+    const result = {
+        success: true,
+        node: {
+            id: node._id,
+            name: node.name,
+            x: node.x,
+            y: node.y,
+            width: node.width,
+            height: node.height,
+            updatedAt: node.updatedAt || new Date().toISOString(),
+        },
+    };
+    return {
+        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+    };
+}
+export async function handleUpdate(client, params) {
+    try {
+        const { node: currentNode, autoSize } = await getNodeContext(client, params);
+        const data = buildUpdateData({
+            ...params,
+            width: params.width ?? autoSize?.width,
+            height: params.height ?? autoSize?.height,
+        }, currentNode.type);
+        if (!data) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `At least one field to update must be provided (name, content, url, color, x, y, width, height).`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const node = await client.updateNode({
+            boardId: params.boardId,
+            nodeId: params.nodeId,
+            data,
+        });
+        return formatSuccessResponse(node);
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Failed to update node: ${formatError(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}

package/dist/utils/collision.js

@@ -0,0 +1,177 @@
+/**
+ * Collision detection utilities for board nodes.
+ *
+ * @see specs/mcp-collision-system.md
+ */
+const GRID_SIZE = 16;
+/**
+ * Check if two rectangles intersect (overlap).
+ * Edge-touching rectangles do NOT intersect.
+ */
+export function rectsIntersect(a, b) {
+    return (a.x < b.x + b.width &&
+        a.x + a.width > b.x &&
+        a.y < b.y + b.height &&
+        a.y + a.height > b.y);
+}
+/**
+ * Snap a value to the nearest grid multiple.
+ */
+export function snapToGrid(value) {
+    const result = Math.round(value / GRID_SIZE) * GRID_SIZE;
+    return Object.is(result, -0) ? 0 : result;
+}
+/**
+ * Convert node data to NodeInfo format for collision results.
+ */
+export function nodeToNodeInfo(node) {
+    return {
+        id: node._id,
+        name: node.name,
+        rect: {
+            x: node.x,
+            y: node.y,
+            width: node.width,
+            height: node.height,
+        },
+    };
+}
+/**
+ * Find all nodes that collide with a given rectangle.
+ */
+export function findCollidingNodes(rect, nodes, excludeNodeId) {
+    const collidingNodes = [];
+    for (const node of nodes) {
+        if (excludeNodeId && node._id === excludeNodeId) {
+            continue;
+        }
+        const nodeRect = {
+            x: node.x,
+            y: node.y,
+            width: node.width,
+            height: node.height,
+        };
+        if (rectsIntersect(rect, nodeRect)) {
+            collidingNodes.push(nodeToNodeInfo(node));
+        }
+    }
+    return {
+        collides: collidingNodes.length > 0,
+        collidingNodes,
+    };
+}
+/**
+ * Check if a rectangle collides with any nodes (early exit on first collision).
+ */
+export function hasCollision(rect, nodes, excludeNodeId) {
+    for (const node of nodes) {
+        if (excludeNodeId && node._id === excludeNodeId) {
+            continue;
+        }
+        const nodeRect = {
+            x: node.x,
+            y: node.y,
+            width: node.width,
+            height: node.height,
+        };
+        if (rectsIntersect(rect, nodeRect)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Calculate starting position based on anchor and direction.
+ */
+function getStartPositionFromAnchor(anchor, direction, width, height, gap) {
+    const positions = {
+        right: { x: anchor.x + anchor.width + gap, y: anchor.y },
+        below: { x: anchor.x, y: anchor.y + anchor.height + gap },
+        left: { x: anchor.x - width - gap, y: anchor.y },
+        above: { x: anchor.x, y: anchor.y - height - gap },
+    };
+    return positions[direction];
+}
+/**
+ * Get the increment for searching in a direction.
+ */
+function getDirectionIncrement(direction) {
+    const increments = {
+        right: { dx: GRID_SIZE, dy: 0 },
+        below: { dx: 0, dy: GRID_SIZE },
+        left: { dx: -GRID_SIZE, dy: 0 },
+        above: { dx: 0, dy: -GRID_SIZE },
+    };
+    return increments[direction];
+}
+/**
+ * Check if direction uses horizontal (x) axis for search.
+ */
+function isHorizontalDirection(direction) {
+    return direction === 'right' || direction === 'left';
+}
+/**
+ * Get the initial starting position for search.
+ */
+function getInitialPosition(params, direction) {
+    if (params.anchor) {
+        return getStartPositionFromAnchor(params.anchor, direction, params.width, params.height, params.gap ?? GRID_SIZE);
+    }
+    return { x: params.startX ?? 0, y: params.startY ?? 0 };
+}
+/**
+ * Execute the search loop to find a free position.
+ */
+function searchForFreePosition(startX, startY, width, height, nodes, direction, maxSearchDistance, excludeNodeId) {
+    let x = startX;
+    let y = startY;
+    const startPosition = isHorizontalDirection(direction) ? x : y;
+    const { dx, dy } = getDirectionIncrement(direction);
+    let searchSteps = 0;
+    while (true) {
+        searchSteps++;
+        if (!hasCollision({ x, y, width, height }, nodes, excludeNodeId)) {
+            return { found: true, position: { x, y }, searchSteps };
+        }
+        x += dx;
+        y += dy;
+        const currentPosition = isHorizontalDirection(direction) ? x : y;
+        if (Math.abs(currentPosition - startPosition) > maxSearchDistance) {
+            return {
+                found: false,
+                searchSteps,
+                error: `No valid position found within ${maxSearchDistance}px search limit`,
+            };
+        }
+    }
+}
+/**
+ * Find the first non-colliding position for a rectangle.
+ */
+export function findFreePosition(params) {
+    const direction = params.direction ?? 'right';
+    const maxSearchDistance = params.maxSearchDistance ?? 10000;
+    const startPos = getInitialPosition(params, direction);
+    return searchForFreePosition(snapToGrid(startPos.x), snapToGrid(startPos.y), params.width, params.height, params.nodes, direction, maxSearchDistance, params.excludeNodeId);
+}
+/**
+ * Find a suggested position when a collision is detected.
+ * Searches in the given direction from the original position.
+ */
+export function findSuggestedPosition(originalX, originalY, width, height, nodes, direction, excludeNodeId) {
+    const searchDirection = direction === 'x' ? 'right' : 'below';
+    const result = findFreePosition({
+        width,
+        height,
+        nodes,
+        startX: originalX,
+        startY: originalY,
+        direction: searchDirection,
+        excludeNodeId,
+        maxSearchDistance: 5000,
+    });
+    if (result.found && result.position) {
+        return direction === 'x' ? result.position.x : result.position.y;
+    }
+    return null;
+}

package/dist/utils/config.js

@@ -0,0 +1,16 @@
+export function loadConfig() {
+    const token = process.env.MENTAGEN_TOKEN;
+    if (!token) {
+        throw new Error('MENTAGEN_TOKEN environment variable is required.\n' +
+            'Generate a development token in Mentagen Settings > Developer.');
+    }
+    if (!token.startsWith('sd:')) {
+        throw new Error('Invalid MENTAGEN_TOKEN format.\n' +
+            'Development tokens must start with "sd:" prefix.');
+    }
+    const mentagenUrl = process.env.MENTAGEN_URL || 'https://mentagen.com';
+    return {
+        mentagenUrl,
+        token,
+    };
+}