@mentagen/mcp 0.1.0

package/dist/tools/create-edge.js

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+import { formatError } from '../utils/errors.js';
+export const createEdgeSchema = z.object({
+    boardId: z.string().describe('The board ID where the edge will be created'),
+    source: z.string().describe('The source node ID'),
+    target: z.string().describe('The target node ID'),
+    direction: z
+        .enum(['none', 'source', 'target'])
+        .optional()
+        .describe('Arrow direction: "none" (no arrow, default), "source" (arrow points to source), "target" (arrow points to target)'),
+});
+/**
+ * Generate a simple ObjectId-like string.
+ */
+export function generateId() {
+    const timestamp = Math.floor(Date.now() / 1000)
+        .toString(16)
+        .padStart(8, '0');
+    const random = Array.from({ length: 16 }, () => Math.floor(Math.random() * 16).toString(16)).join('');
+    return timestamp + random;
+}
+export async function handleCreateEdge(client, params) {
+    try {
+        const _id = generateId();
+        const edge = await client.addEdge({
+            _id,
+            boardId: params.boardId,
+            source: params.source,
+            target: params.target,
+            direction: params.direction,
+        });
+        const result = {
+            success: true,
+            edge: {
+                id: edge._id,
+                source: edge.source,
+                target: edge.target,
+                board: params.boardId,
+            },
+        };
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Failed to create edge: ${formatError(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}

package/dist/tools/create-graph.js

@@ -0,0 +1,174 @@
+import { z } from 'zod';
+import { formatError } from '../utils/errors.js';
+import { 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'),
+    content: z.string().optional().describe('Node content'),
+    type: z
+        .enum(['text', 'markdown', 'code', 'url'])
+        .optional()
+        .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'),
+});
+const edgeInputSchema = z.object({
+    source: z.string().describe('Source node tempId'),
+    target: z.string().describe('Target node tempId'),
+    direction: z
+        .enum(['none', 'source', 'target'])
+        .optional()
+        .describe('Arrow direction'),
+    label: z.string().optional().describe('Edge label'),
+});
+export const createGraphSchema = z.object({
+    boardId: z.string().describe('The board ID to create the graph on'),
+    nodes: z.array(nodeInputSchema).min(1).describe('Array of nodes to create'),
+    edges: z
+        .array(edgeInputSchema)
+        .optional()
+        .describe('Array of edges connecting nodes by tempId'),
+});
+const DEFAULT_NODE_COLORS = {
+    text: undefined,
+    markdown: 'cyan',
+    code: 'indigo',
+    url: 'blue',
+};
+async function createNode(client, boardId, nodeInput, idMap) {
+    const realId = generateId();
+    const type = nodeInput.type ?? 'text';
+    const color = nodeInput.color ?? DEFAULT_NODE_COLORS[type];
+    const autoSize = calculateNodeSize(nodeInput.name, type);
+    const x = nodeInput.x ?? 100;
+    const y = nodeInput.y ?? 100;
+    const width = nodeInput.width ?? autoSize.width;
+    const height = nodeInput.height ?? autoSize.height;
+    try {
+        // For code nodes, store content in the `code` field
+        const isCodeNode = type === 'code';
+        const nodeContent = nodeInput.content ?? '';
+        const node = await client.addNode({
+            _id: realId,
+            boardId,
+            node: {
+                name: nodeInput.name,
+                ...(isCodeNode ? { code: nodeContent } : { content: nodeContent }),
+                type,
+                color,
+                x,
+                y,
+                width,
+                height,
+            },
+        });
+        idMap[nodeInput.tempId] = node._id;
+        return {
+            success: true,
+            result: {
+                tempId: nodeInput.tempId,
+                id: node._id,
+                name: node.name,
+                x,
+                y,
+                width,
+                height,
+            },
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            tempId: nodeInput.tempId,
+            error: formatError(error),
+        };
+    }
+}
+async function createEdge(client, boardId, edgeInput, idMap) {
+    const sourceId = idMap[edgeInput.source];
+    const targetId = idMap[edgeInput.target];
+    if (!sourceId || !targetId) {
+        return {
+            success: false,
+            error: `Invalid edge: source=${edgeInput.source} target=${edgeInput.target}`,
+        };
+    }
+    try {
+        const realId = generateId();
+        const edge = await client.addEdge({
+            _id: realId,
+            boardId,
+            source: sourceId,
+            target: targetId,
+            direction: edgeInput.direction,
+        });
+        return {
+            success: true,
+            result: {
+                id: edge._id,
+                source: sourceId,
+                target: targetId,
+            },
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: formatError(error),
+        };
+    }
+}
+function processNodeOutcomes(outcomes) {
+    const results = [];
+    const errors = [];
+    for (const outcome of outcomes) {
+        if (outcome.success && outcome.result) {
+            results.push(outcome.result);
+        }
+        else if (!outcome.success && outcome.tempId) {
+            errors.push({ tempId: outcome.tempId, error: outcome.error });
+        }
+    }
+    return { results, errors };
+}
+function processEdgeOutcomes(outcomes) {
+    return outcomes
+        .filter((o) => o.success && !!o.result)
+        .map(o => o.result);
+}
+export async function handleCreateGraph(client, params) {
+    try {
+        const idMap = {};
+        const nodeOutcomes = await Promise.all(params.nodes.map(n => createNode(client, params.boardId, n, idMap)));
+        const { results: nodeResults, errors } = processNodeOutcomes(nodeOutcomes);
+        let edgeResults = [];
+        if (errors.length === 0 && params.edges && params.edges.length > 0) {
+            const edgeOutcomes = await Promise.all(params.edges.map(e => createEdge(client, params.boardId, e, idMap)));
+            edgeResults = processEdgeOutcomes(edgeOutcomes);
+        }
+        const response = {
+            success: errors.length === 0,
+            idMap,
+            nodes: nodeResults,
+            edges: edgeResults,
+            ...(errors.length > 0 && { errors }),
+        };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(response, null, 2) }],
+            ...(errors.length === params.nodes.length && { isError: true }),
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                { type: 'text', text: `Failed to create graph: ${formatError(error)}` },
+            ],
+            isError: true,
+        };
+    }
+}

package/dist/tools/create.js

@@ -0,0 +1,152 @@
+import { z } from 'zod';
+import { formatError } from '../utils/errors.js';
+import { getNodeUrl } from '../utils/urls.js';
+import { snapToGrid } from './grid-calc.js';
+import { calculateNodeSize } from './size-calc.js';
+/**
+ * Default colors for node types, matching the context menu behavior.
+ *
+ * Keep in sync with: src/client/features/boards/inner-board-context-menu.tsx
+ *
+ * When adding new node types or changing default colors in the context menu,
+ * update this mapping to match.
+ */
+const DEFAULT_NODE_COLORS = {
+    // Currently supported in MCP
+    text: undefined,
+    markdown: 'cyan',
+    code: 'indigo',
+    url: 'blue',
+    // Future node types (from context menu)
+    image: undefined,
+    'ai-chat': 'blue',
+    'ai-quiz': 'green',
+    board: 'fuchsia',
+    mermaid: 'violet',
+    voice: undefined,
+    excalidraw: 'teal',
+    teleprompter: 'rose',
+};
+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'),
+    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). Required for type="url".'),
+    type: z
+        .enum(['text', 'markdown', 'code', 'url'])
+        .optional()
+        .default('text')
+        .describe('Node type: text (default), markdown, code, or url'),
+    color: z
+        .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)'),
+    width: z
+        .number()
+        .optional()
+        .describe('Width (must be multiple of 16, default: 256)'),
+    height: z
+        .number()
+        .optional()
+        .describe('Height (must be multiple of 16, default: 128)'),
+});
+/**
+ * Generate a simple ObjectId-like string.
+ * Uses timestamp + random hex for uniqueness.
+ */
+export function generateId() {
+    const timestamp = Math.floor(Date.now() / 1000)
+        .toString(16)
+        .padStart(8, '0');
+    const random = Array.from({ length: 16 }, () => Math.floor(Math.random() * 16).toString(16)).join('');
+    return timestamp + random;
+}
+/**
+ * Build node fields object with content mapped to the correct field based on type.
+ */
+function buildNodeFields(params, color, position) {
+    const nodeFields = {
+        name: params.name,
+        type: params.type,
+        color,
+        ...position,
+    };
+    if (params.type === 'code') {
+        nodeFields.code = params.content || '';
+    }
+    else if (params.type === 'url') {
+        if (!params.url) {
+            throw new Error('URL field is required for url-type nodes');
+        }
+        nodeFields.url = params.url;
+        if (params.content) {
+            nodeFields.content = params.content;
+        }
+    }
+    else {
+        nodeFields.content = params.content || '';
+    }
+    return nodeFields;
+}
+export async function handleCreate(client, params, mentagenUrl) {
+    try {
+        const _id = generateId();
+        const color = params.color || DEFAULT_NODE_COLORS[params.type];
+        const autoSize = calculateNodeSize(params.name, 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 node = await client.addNode({
+            _id,
+            boardId: params.boardId,
+            node: nodeFields,
+        });
+        const result = {
+            success: true,
+            node: {
+                id: node._id,
+                name: node.name,
+                board: params.boardId,
+                ...position,
+                link: getNodeUrl(mentagenUrl, params.boardId, node._id),
+            },
+        };
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Failed to create node: ${formatError(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}

package/dist/tools/delete-edge.js

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+import { formatError } from '../utils/errors.js';
+export const deleteEdgeSchema = z.object({
+    boardId: z.string().describe('The board ID containing the edge'),
+    edgeId: z.string().describe('The edge ID to delete'),
+});
+export async function handleDeleteEdge(client, params) {
+    try {
+        await client.deleteEdge({
+            boardId: params.boardId,
+            edgeId: params.edgeId,
+        });
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        success: true,
+                        message: 'Edge deleted successfully. This is a soft delete and can be undone in Mentagen.',
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Failed to delete edge: ${formatError(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}

package/dist/tools/delete.js

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+import { formatError } from '../utils/errors.js';
+export const deleteSchema = z.object({
+    boardId: z.string().describe('The board ID containing the node'),
+    nodeId: z.string().describe('The node ID to delete'),
+});
+export async function handleDelete(client, params) {
+    try {
+        await client.deleteNode({
+            boardId: params.boardId,
+            nodeId: params.nodeId,
+        });
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        success: true,
+                        message: 'Node deleted successfully. This is a soft delete and can be undone in Mentagen.',
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Failed to delete node: ${formatError(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}

package/dist/tools/extract-board-content.js

@@ -0,0 +1,207 @@
+import { z } from 'zod';
+import { NodeType } from '../client/types.js';
+import { formatError } from '../utils/errors.js';
+import { getNodeUrl } from '../utils/urls.js';
+export const extractBoardContentSchema = z.object({
+    boardId: z.string().describe('The board ID to extract content from'),
+    includeEmpty: z
+        .boolean()
+        .default(false)
+        .describe('Include nodes with no content (default: false)'),
+});
+/**
+ * Content extractors by node type.
+ * Returns the appropriate text content from a node based on its type.
+ */
+const contentExtractors = {
+    [NodeType.Code]: node => node.code || '',
+    [NodeType.AIChat]: node => node.chatConcatenated || '',
+    [NodeType.Image]: node => node.textDetectionsConcatenated || '',
+    [NodeType.PDF]: node => node.pdfText || node.content || '',
+    [NodeType.URL]: node => node.article || node.content || '',
+};
+/**
+ * Get the text content from a node, handling different field locations by type.
+ */
+function getNodeContent(node) {
+    const extractor = contentExtractors[node.type];
+    return extractor ? extractor(node) : node.content || '';
+}
+/**
+ * Strip HTML tags from content for cleaner output.
+ */
+function stripHtml(html) {
+    return html
+        .replace(/<[^>]*>/g, '')
+        .replace(/&nbsp;/g, ' ')
+        .replace(/&amp;/g, '&')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .trim();
+}
+/**
+ * Infer programming language from file extension.
+ */
+function inferLanguage(filename) {
+    const ext = filename.split('.').pop()?.toLowerCase() || '';
+    const langMap = {
+        ts: 'typescript',
+        tsx: 'typescript',
+        js: 'javascript',
+        jsx: 'javascript',
+        py: 'python',
+        rb: 'ruby',
+        go: 'go',
+        rs: 'rust',
+        java: 'java',
+        kt: 'kotlin',
+        swift: 'swift',
+        c: 'c',
+        cpp: 'cpp',
+        h: 'c',
+        hpp: 'cpp',
+        cs: 'csharp',
+        php: 'php',
+        sql: 'sql',
+        sh: 'bash',
+        bash: 'bash',
+        zsh: 'bash',
+        yml: 'yaml',
+        yaml: 'yaml',
+        json: 'json',
+        xml: 'xml',
+        html: 'html',
+        css: 'css',
+        scss: 'scss',
+        md: 'markdown',
+    };
+    return langMap[ext] || '';
+}
+/**
+ * Format node content based on its type.
+ */
+function formatContent(node) {
+    const raw = getNodeContent(node);
+    if (!raw)
+        return '';
+    // Code nodes: wrap in code block
+    if (node.type === NodeType.Code) {
+        const lang = inferLanguage(node.name);
+        return '```' + lang + '\n' + raw + '\n```';
+    }
+    // Markdown nodes: keep as-is (already markdown)
+    if (node.type === NodeType.Markdown) {
+        return raw;
+    }
+    // AI Chat nodes: convert server format to markdown
+    if (node.type === NodeType.AIChat) {
+        // Server returns "User: text\n\nAssistant: text", convert to markdown bold
+        return raw
+            .replace(/^User:/gm, '**User:**')
+            .replace(/^Assistant:/gm, '**Assistant:**');
+    }
+    // Image nodes with OCR: prefix with context
+    if (node.type === NodeType.Image && node.textDetectionsConcatenated) {
+        return `*Text detected in image:*\n\n${raw}`;
+    }
+    // PDF nodes: prefix with context
+    if (node.type === NodeType.PDF) {
+        return `*Extracted from PDF:*\n\n${raw}`;
+    }
+    // Text nodes with HTML: strip tags
+    if (raw.includes('<')) {
+        return stripHtml(raw);
+    }
+    return raw;
+}
+/**
+ * Format a single node as a markdown section.
+ */
+function formatNodeSection(node, baseUrl, boardId) {
+    const content = formatContent(node);
+    const link = getNodeUrl(baseUrl, boardId, node._id);
+    const lines = [
+        `## ${node.name}`,
+        `**ID:** \`${node._id}\` | **Type:** ${node.type} | [Open](${link})`,
+        '',
+        content,
+    ];
+    return lines.join('\n');
+}
+export async function handleExtractBoardContent(client, params, baseUrl) {
+    try {
+        // Fetch board metadata and nodes in parallel
+        const [board, nodes] = await Promise.all([
+            client.getBoard({ boardId: params.boardId }),
+            client.listNodesWithContent({
+                boardId: params.boardId,
+                limit: 1000,
+            }),
+        ]);
+        if (nodes.length === 0) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'No nodes found in this board.',
+                    },
+                ],
+            };
+        }
+        // Filter nodes based on content
+        const nodesWithContent = params.includeEmpty
+            ? nodes
+            : nodes.filter(n => {
+                const content = getNodeContent(n);
+                return content && content.trim().length > 0;
+            });
+        if (nodesWithContent.length === 0) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Board has ${nodes.length} nodes but none contain extractable content.`,
+                    },
+                ],
+            };
+        }
+        // Build the markdown output
+        const sections = nodesWithContent.map(n => formatNodeSection(n, baseUrl, params.boardId));
+        // Build board link
+        const boardLink = `${baseUrl}/b/${params.boardId}`;
+        // Add summary header with board metadata
+        const headerLines = [
+            `# ${board.name}`,
+            '',
+            `**Board ID:** \`${params.boardId}\` | [Open Board](${boardLink})`,
+        ];
+        // Add description if present
+        if (board.description) {
+            headerLines.push('', board.description);
+        }
+        headerLines.push('', '---', '', `**Total nodes:** ${nodesWithContent.length}${nodes.length !== nodesWithContent.length ? ` (${nodes.length - nodesWithContent.length} empty nodes excluded)` : ''}`, '', '---', '');
+        const header = headerLines.join('\n');
+        const output = header + sections.join('\n\n---\n\n');
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: output,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Failed to extract board content: ${formatError(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}