@mentagen/mcp 0.1.0

package/dist/tools/link.js

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import { getBoardUrl, getNodeUrl } from '../utils/urls.js';
+export const linkSchema = z.object({
+    boardId: z.string().describe('The board ID'),
+    nodeId: z
+        .string()
+        .optional()
+        .describe('Optional node ID to link directly to a node'),
+});
+export function handleLink(params, config) {
+    const url = params.nodeId
+        ? getNodeUrl(config.mentagenUrl, params.boardId, params.nodeId)
+        : getBoardUrl(config.mentagenUrl, params.boardId);
+    return {
+        content: [
+            {
+                type: 'text',
+                text: url,
+            },
+        ],
+    };
+}

package/dist/tools/list-edges.js

@@ -0,0 +1,58 @@
+import { z } from 'zod';
+import { EdgeDirection } from '../client/types.js';
+import { formatError } from '../utils/errors.js';
+export const listEdgesSchema = z.object({
+    boardId: z.string().describe('The board ID to list edges from'),
+    limit: z
+        .number()
+        .max(1000)
+        .optional()
+        .describe('Maximum number of edges to return (default: 1000, max: 1000)'),
+});
+/**
+ * Format edges as TSV for concise output.
+ */
+function formatEdgesTsv(edges) {
+    if (edges.length === 0) {
+        return 'No edges found on this board.';
+    }
+    const columns = ['id', 'source', 'target', 'direction', 'label'];
+    const header = columns.join('\t');
+    const rows = edges.map(edge => [edge.id, edge.source, edge.target, edge.direction, edge.label || ''].join('\t'));
+    return [header, ...rows].join('\n');
+}
+export async function handleListEdges(client, params) {
+    try {
+        const edges = await client.listEdges({
+            boardId: params.boardId,
+            limit: params.limit,
+        });
+        const formattedEdges = edges.map(edge => ({
+            id: edge._id,
+            source: edge.source,
+            target: edge.target,
+            direction: edge.direction || EdgeDirection.None,
+            label: edge.label || null,
+        }));
+        const tsv = formatEdgesTsv(formattedEdges);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Found ${edges.length} edge(s):\n\n${tsv}`,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Failed to list edges: ${formatError(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}

package/dist/tools/list-nodes.js

@@ -0,0 +1,96 @@
+import Papa from 'papaparse';
+import { z } from 'zod';
+import { formatDate } from '../utils/ejson.js';
+import { formatError } from '../utils/errors.js';
+import { getNodeUrl } from '../utils/urls.js';
+export const listNodesSchema = z.object({
+    boardId: z.string().describe('The board ID to list nodes from'),
+    limit: z
+        .number()
+        .max(1000)
+        .default(1000)
+        .describe('Maximum number of nodes to return (default: 1000, max: 1000)'),
+});
+const MAX_CONTENT_LENGTH = 100;
+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) +
+        '...');
+}
+function formatNodesTsv(nodes) {
+    const rows = nodes.map(n => ({
+        id: n._id,
+        name: n.name,
+        type: n.type,
+        x: n.x,
+        y: n.y,
+        width: n.width,
+        height: n.height,
+        content: truncateContent(n.content ?? null, MAX_CONTENT_LENGTH),
+        updatedAt: formatDate(n.updatedAt),
+        link: n.link,
+    }));
+    return Papa.unparse(rows, {
+        delimiter: '\t',
+        header: true,
+        newline: '\n',
+        columns: [
+            'id',
+            'name',
+            'type',
+            'x',
+            'y',
+            'width',
+            'height',
+            'content',
+            'updatedAt',
+            'link',
+        ],
+    });
+}
+export async function handleListNodes(client, params, baseUrl) {
+    try {
+        const nodes = await client.listNodes({
+            boardId: params.boardId,
+            limit: params.limit,
+        });
+        if (nodes.length === 0) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'No nodes found in this board.',
+                    },
+                ],
+            };
+        }
+        const nodesWithLinks = nodes.map(n => ({
+            ...n,
+            link: getNodeUrl(baseUrl, params.boardId, n._id),
+        }));
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: formatNodesTsv(nodesWithLinks),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Failed to list nodes: ${formatError(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}

package/dist/tools/list-positions.js

@@ -0,0 +1,64 @@
+import Papa from 'papaparse';
+import { z } from 'zod';
+import { formatError } from '../utils/errors.js';
+export const listPositionsSchema = z.object({
+    boardId: z.string().describe('The board ID to list node positions from'),
+    limit: z
+        .number()
+        .max(1000)
+        .default(1000)
+        .describe('Maximum number of nodes to return (default: 1000, max: 1000)'),
+});
+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,
+    }));
+    return Papa.unparse(rows, {
+        delimiter: '\t',
+        header: true,
+        newline: '\n',
+        columns: ['id', 'name', 'x', 'y', 'w', 'h'],
+    });
+}
+export async function handleListPositions(client, params) {
+    try {
+        const nodes = await client.listNodes({
+            boardId: params.boardId,
+            limit: params.limit,
+        });
+        if (nodes.length === 0) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'No nodes found in this board.',
+                    },
+                ],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: formatPositionsTsv(nodes),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Failed to list positions: ${formatError(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}

package/dist/tools/node-types.js

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+export const nodeTypesSchema = z.object({});
+/**
+ * Supported node types with their default colors.
+ *
+ * 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 list to match.
+ */
+const NODE_TYPES = [
+    {
+        type: 'text',
+        defaultColor: null,
+        description: 'Simple text node with a title and optional rich text content.',
+        usage: 'Use for short notes, labels, headings, or any content that needs a title. Content supports basic HTML formatting.',
+        fields: {
+            name: 'The node title (required)',
+            content: 'Optional HTML content (e.g., <p>paragraph</p>, <ul><li>list</li></ul>)',
+        },
+    },
+    {
+        type: 'markdown',
+        defaultColor: 'cyan',
+        description: 'Markdown node for longer-form content with full Markdown syntax support.',
+        usage: 'Use for documentation, articles, formatted notes, or any content that benefits from Markdown formatting like headers, lists, code blocks, and links.',
+        fields: {
+            name: 'The node title (required)',
+            content: 'Markdown content (supports full GFM syntax)',
+        },
+    },
+    {
+        type: 'code',
+        defaultColor: 'indigo',
+        description: 'Code node for storing and displaying source code with syntax highlighting.',
+        usage: 'Use for code snippets, scripts, configuration files, or any content that needs syntax highlighting. Supports multiple programming languages.',
+        fields: {
+            name: 'The node title (required)',
+            content: 'Source code content',
+        },
+    },
+    {
+        type: 'url',
+        defaultColor: 'blue',
+        description: 'Bookmark node that stores and displays a link to an external URL.',
+        usage: 'Use for saving references to external resources, articles, documentation, or any web link. The system will automatically fetch metadata like title and preview.',
+        fields: {
+            name: 'The link title (required)',
+            url: 'The full URL including protocol (e.g., https://example.com)',
+        },
+    },
+];
+export function handleNodeTypes() {
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({
+                    nodeTypes: NODE_TYPES,
+                    note: 'When creating nodes via mentagen_create_node, specify the type parameter. Default is "text" if not specified.',
+                }, null, 2),
+            },
+        ],
+    };
+}

package/dist/tools/patch-content.js

@@ -0,0 +1,143 @@
+import { z } from 'zod';
+import { NodeType } from '../client/types.js';
+import { formatError } from '../utils/errors.js';
+const replaceOp = z.object({
+    type: z.literal('replace'),
+    oldString: z.string().min(1),
+    newString: z.string(),
+    replaceAll: z.boolean().optional(),
+});
+const prependOp = z.object({
+    type: z.literal('prepend'),
+    content: z.string(),
+});
+const appendOp = z.object({
+    type: z.literal('append'),
+    content: z.string(),
+});
+export const patchContentSchema = z.object({
+    boardId: z.string(),
+    nodeId: z.string(),
+    operations: z
+        .array(z.discriminatedUnion('type', [replaceOp, prependOp, appendOp]))
+        .min(1),
+});
+/**
+ * Determines the content field and value for a node.
+ * Code nodes use the `code` field, all others use `content`.
+ */
+function getNodeTextField(node) {
+    if (node.type === NodeType.Code) {
+        return { field: 'code', text: node.code || '' };
+    }
+    return { field: 'content', text: node.content || '' };
+}
+/**
+ * Applies a string replacement operation.
+ * Returns the modified content or an error message.
+ */
+export function applyReplace(content, op) {
+    if (op.replaceAll) {
+        if (!content.includes(op.oldString)) {
+            return { result: content, error: 'String not found in content' };
+        }
+        return { result: content.replaceAll(op.oldString, op.newString) };
+    }
+    const index = content.indexOf(op.oldString);
+    if (index === -1) {
+        return { result: content, error: 'String not found in content' };
+    }
+    const secondIndex = content.indexOf(op.oldString, index + op.oldString.length);
+    if (secondIndex !== -1) {
+        return {
+            result: content,
+            error: `String appears multiple times (at positions ${index} and ${secondIndex}). ` +
+                `Provide more surrounding context to make oldString unique, or use replaceAll: true.`,
+        };
+    }
+    return {
+        result: content.slice(0, index) +
+            op.newString +
+            content.slice(index + op.oldString.length),
+    };
+}
+export async function handlePatchContent(client, params) {
+    try {
+        const node = await client.getNode({
+            boardId: params.boardId,
+            nodeId: params.nodeId,
+        });
+        const { field, text: initialText } = getNodeTextField(node);
+        let text = initialText;
+        const appliedOps = [];
+        for (const op of params.operations) {
+            switch (op.type) {
+                case 'replace': {
+                    const { result, error } = applyReplace(text, op);
+                    if (error) {
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: JSON.stringify({
+                                        success: false,
+                                        error: `Replace failed: ${error}`,
+                                        field,
+                                        appliedOps,
+                                        contentLength: text.length,
+                                    }, null, 2),
+                                },
+                            ],
+                            isError: true,
+                        };
+                    }
+                    text = result;
+                    appliedOps.push(`replace: "${truncate(op.oldString, 30)}" → "${truncate(op.newString, 30)}"`);
+                    break;
+                }
+                case 'prepend':
+                    text = op.content + text;
+                    appliedOps.push(`prepend: ${op.content.length} chars`);
+                    break;
+                case 'append':
+                    text = text + op.content;
+                    appliedOps.push(`append: ${op.content.length} chars`);
+                    break;
+            }
+        }
+        await client.updateNode({
+            boardId: params.boardId,
+            nodeId: params.nodeId,
+            data: { [field]: text },
+        });
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        success: true,
+                        field,
+                        operations: appliedOps,
+                        newLength: text.length,
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Patch failed: ${formatError(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}
+function truncate(str, maxLen) {
+    if (str.length <= maxLen)
+        return str;
+    return str.slice(0, maxLen - 3) + '...';
+}

package/dist/tools/read.js

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+import { formatError } from '../utils/errors.js';
+import { getNodeUrl } from '../utils/urls.js';
+export const readSchema = z.object({
+    boardId: z.string().describe('The board ID containing the node'),
+    nodeId: z.string().describe('The node ID to read'),
+});
+export async function handleRead(client, params, baseUrl) {
+    try {
+        const node = await client.getNode({
+            boardId: params.boardId,
+            nodeId: params.nodeId,
+        });
+        // Exclude large fields that aren't useful for AI consumption
+        const { _vectors, __v, textDetections, ...nodeData } = node;
+        // Add link to the response
+        const response = {
+            ...nodeData,
+            link: getNodeUrl(baseUrl, params.boardId, params.nodeId),
+        };
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(response, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Failed to read node: ${formatError(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}

package/dist/tools/search-board.js

@@ -0,0 +1,99 @@
+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 searchBoardSchema = z.object({
+    boardId: z.string().describe('The board ID to search within (required)'),
+    query: z
+        .string()
+        .describe('The search query - can be a question or keywords'),
+    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,
+        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', 'score', 'link'],
+    });
+}
+export async function handleSearchBoard(client, params, baseUrl) {
+    try {
+        const results = await client.searchNodes({
+            query: params.query,
+            board: params.boardId,
+            semanticRatio: params.semanticRatio,
+        });
+        if (results.hits.length === 0) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `No nodes found matching "${params.query}" in this board.`,
+                    },
+                ],
+            };
+        }
+        const formatted = formatSearchResults(results.hits.slice(0, params.limit));
+        const resultsWithLinks = formatted.results.map(r => ({
+            id: r.id,
+            name: r.name,
+            content: r.content,
+            type: r.type,
+            score: r.score,
+            link: getNodeUrl(baseUrl, params.boardId, 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/search-boards.js

@@ -0,0 +1,50 @@
+import Papa from 'papaparse';
+import { z } from 'zod';
+import { formatShortDate } from '../utils/ejson.js';
+import { formatError } from '../utils/errors.js';
+import { getBoardUrl } from '../utils/urls.js';
+export const searchBoardsSchema = z.object({
+    query: z.string().describe('Search query to filter boards by name'),
+});
+/**
+ * Format boards as TSV for compact output.
+ */
+function formatBoardsTsv(boards) {
+    return Papa.unparse(boards, {
+        delimiter: '\t',
+        header: true,
+        newline: '\n',
+        columns: ['id', 'name', 'nodeCount', 'updatedAt', 'link'],
+    });
+}
+export async function handleSearchBoards(client, params, baseUrl) {
+    try {
+        const boards = await client.searchBoards(params.query);
+        const formatted = boards.map(board => ({
+            id: board._id,
+            name: board.name,
+            nodeCount: board.nodeCount ?? 0,
+            updatedAt: formatShortDate(board.updatedAt),
+            link: getBoardUrl(baseUrl, board._id),
+        }));
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: formatBoardsTsv(formatted),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Failed to search boards: ${formatError(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}