@mentagen/mcp 0.1.0

package/README.md

@@ -0,0 +1,100 @@
+# Mentagen MCP Server
+
+> **⚠️ Preview Access Only**
+>
+> This MCP server is currently in preview and available exclusively to select premium users. If you don't have access yet, please contact support or wait for the general availability release.
+
+MCP (Model Context Protocol) server that enables AI agents in Cursor to interact with your Mentagen knowledge base.
+
+## Overview
+
+This MCP server acts as a bridge between Cursor's AI agent and Mentagen's backend. Once configured, you can ask Cursor's AI to search, create, update, and manage content in your knowledge base using natural language.
+
+## Installation
+
+```bash
+# Global install
+npm install -g @mentagen/mcp
+
+# Or use npx (no install required)
+npx @mentagen/mcp
+```
+
+## Configuration
+
+### 1. Generate a Development Token
+
+1. Open Mentagen and navigate to **Settings > Developer**
+2. Click **Generate Token**
+3. Give your token a descriptive name (e.g., "Cursor MCP")
+4. Copy the generated token (starts with `sd:`)
+
+> **Important**: The token is only shown once. Store it securely.
+
+### 2. Configure Cursor
+
+Add the MCP server to your Cursor configuration:
+
+**macOS/Linux**: `~/.cursor/mcp.json`
+**Windows**: `%USERPROFILE%\.cursor\mcp.json`
+
+```json
+{
+  "mcpServers": {
+    "mentagen": {
+      "command": "npx",
+      "args": ["@mentagen/mcp"],
+      "env": {
+        "MENTAGEN_TOKEN": "sd:your-development-token-here",
+        "MENTAGEN_URL": "https://mentagen.com"
+      }
+    }
+  }
+}
+```
+
+### 3. Restart Cursor
+
+After saving the configuration, restart Cursor for the changes to take effect.
+
+## Environment Variables
+
+| Variable         | Required | Default                | Description                                |
+| ---------------- | -------- | ---------------------- | ------------------------------------------ |
+| `MENTAGEN_TOKEN` | Yes      | -                      | Your development token (starts with `sd:`) |
+| `MENTAGEN_URL`   | No       | `https://mentagen.com` | Mentagen server URL                        |
+
+## What You Can Do
+
+Once configured, ask Cursor's AI to help you with:
+
+- **Search** — Find nodes across your boards using semantic or keyword search
+- **Read & List** — View board contents, node details, and connections
+- **Create** — Add new boards, nodes, and edges
+- **Update** — Modify node content, positions, colors, and connections
+- **Organize** — Batch update multiple items, create node graphs, find non-colliding positions
+
+The AI automatically discovers available tools and their parameters — just describe what you want to accomplish.
+
+## Troubleshooting
+
+### "Authentication failed" Error
+
+- Verify your token is correct and starts with `sd:`
+- Check that the token hasn't been revoked in Settings > Developer
+- Ensure `MENTAGEN_URL` points to the correct server
+
+### Tools Not Appearing in Cursor
+
+- Restart Cursor after updating `mcp.json`
+- Check Cursor's MCP logs for errors (Help > Toggle Developer Tools)
+- Verify the JSON syntax in `mcp.json` is valid
+
+### "Permission denied" Errors
+
+- Your token may not have access to the requested board
+- Verify you have the correct permissions in Mentagen
+
+## License
+
+Proprietary. All rights reserved.

package/dist/client/helene.js

@@ -0,0 +1,178 @@
+import { randomUUID } from 'crypto';
+/**
+ * Lightweight HTTP client for Mentagen's Helene API.
+ *
+ * Uses the HTTP transport endpoint (/__h) to call server methods.
+ * Helene expects text/plain with a specific payload/context structure.
+ */
+export class MentagenClient {
+    baseUrl;
+    token;
+    constructor(config) {
+        this.baseUrl = config.mentagenUrl.replace(/\/$/, '');
+        this.token = config.token;
+    }
+    /**
+     * Call a Helene method via HTTP.
+     *
+     * Helene's HTTP transport expects:
+     * - Content-Type: text/plain
+     * - Body: JSON with { payload: { uuid, method, params }, context: { token } }
+     */
+    async call(method, params = {}) {
+        const url = `${this.baseUrl}/__h`;
+        const body = JSON.stringify({
+            payload: {
+                uuid: randomUUID(),
+                method,
+                params,
+            },
+            context: {
+                token: this.token,
+            },
+        });
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'text/plain',
+            },
+            body,
+        });
+        if (!response.ok) {
+            const text = await response.text();
+            throw new Error(`HTTP ${response.status}: ${text}`);
+        }
+        const data = (await response.json());
+        if (data.type === 'error' || data.error) {
+            const errorMsg = data.message ||
+                (typeof data.error === 'string' ? data.error : data.error?.message);
+            throw new Error(errorMsg || 'Unknown error');
+        }
+        return data.result;
+    }
+    /**
+     * Verify the token and get the current user.
+     */
+    async getCurrentUser() {
+        try {
+            return await this.call('user.current');
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * List boards the user has access to.
+     */
+    async listBoards() {
+        const result = await this.call('boards.list', {});
+        return result.data || [];
+    }
+    /**
+     * Search boards by name.
+     */
+    async searchBoards(query, limit = 20) {
+        const result = await this.call('boards.search', {
+            query,
+            limit,
+        });
+        return result.data || [];
+    }
+    /**
+     * Search nodes using hybrid semantic/keyword search.
+     */
+    async searchNodes(params) {
+        return this.call('boards.searchNodesText', params);
+    }
+    /**
+     * Add a new node to a board.
+     */
+    async addNode(params) {
+        return this.call('boards.addNode', params);
+    }
+    /**
+     * Update a node's properties.
+     */
+    async updateNode(params) {
+        return this.call('boards.updateNode', params);
+    }
+    /**
+     * Get a single node by ID.
+     * Uses getNodeForMcp which excludes large fields (chat, textDetections, _vectors)
+     * in favor of their computed alternatives (chatConcatenated, textDetectionsConcatenated).
+     */
+    async getNode(params) {
+        return this.call('boards.getNodeForMcp', params);
+    }
+    /**
+     * List all nodes in a board (basic fields only).
+     */
+    async listNodes(params) {
+        return this.call('boards.listNodesSimple', params);
+    }
+    /**
+     * List all nodes with full content fields for extraction.
+     * Includes: content, code, chatConcatenated, textDetectionsConcatenated, pdfText, article
+     * Note: Uses computed fields instead of raw chat/textDetections.
+     */
+    async listNodesWithContent(params) {
+        return this.call('boards.listNodesWithContent', params);
+    }
+    /**
+     * Soft-delete a node.
+     */
+    async deleteNode(params) {
+        await this.call('boards.deleteNode', params);
+    }
+    /**
+     * Create a new board.
+     */
+    async createBoard(params) {
+        return this.call('boards.create', params);
+    }
+    /**
+     * Get a single board by ID.
+     */
+    async getBoard(params) {
+        return this.call('boards.get', params);
+    }
+    /**
+     * Update a board's properties.
+     */
+    async updateBoard(params) {
+        return this.call('boards.update', params);
+    }
+    /**
+     * Add an edge between two nodes.
+     */
+    async addEdge(params) {
+        return this.call('boards.addEdge', params);
+    }
+    /**
+     * List all edges in a board.
+     */
+    async listEdges(params) {
+        return this.call('boards.listEdgesSimple', params);
+    }
+    /**
+     * Update an edge's metadata (direction and/or label).
+     */
+    async updateEdge(params) {
+        return this.call('boards.updateEdgeMetadata', params);
+    }
+    /**
+     * Soft-delete an edge.
+     */
+    async deleteEdge(params) {
+        await this.call('boards.deleteEdge', params);
+    }
+}
+export async function createMentagenClient(config) {
+    const client = new MentagenClient(config);
+    const user = await client.getCurrentUser();
+    if (!user) {
+        throw new Error('Authentication failed. Please check your MENTAGEN_TOKEN.\n' +
+            'Generate a new token in Mentagen Settings > Developer if needed.');
+    }
+    return client;
+}

package/dist/client/types.js

@@ -0,0 +1,27 @@
+/**
+ * Types for Mentagen API responses.
+ * These mirror the server-side types but are standalone for the MCP package.
+ */
+export const EdgeDirection = {
+    None: 'none',
+    Source: 'source',
+    Target: 'target',
+};
+export const NodeType = {
+    Text: 'text',
+    Markdown: 'markdown',
+    Code: 'code',
+    Image: 'image',
+    PDF: 'pdf',
+    URL: 'url',
+    Voice: 'voice',
+    Contact: 'contact',
+    Board: 'board',
+    Audio: 'audio',
+    Mermaid: 'mermaid',
+    AIChat: 'ai-chat',
+    AIQuiz: 'ai-quiz',
+    File: 'file',
+    Excalidraw: 'excalidraw',
+    Teleprompter: 'teleprompter',
+};

package/dist/index.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createMentagenClient } from './client/helene.js';
+import { registerTools } from './tools/index.js';
+import { loadConfig } from './utils/config.js';
+async function main() {
+    const config = loadConfig();
+    const client = await createMentagenClient(config);
+    const mcpServer = new McpServer({
+        name: 'mentagen',
+        version: '0.1.0',
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    registerTools(mcpServer.server, client, config);
+    const transport = new StdioServerTransport();
+    await mcpServer.connect(transport);
+    process.stderr.write('Mentagen MCP server started\n');
+}
+main().catch(error => {
+    process.stderr.write(`Error: ${error.message}\n`);
+    process.exit(1);
+});

package/dist/tools/batch-update.js

@@ -0,0 +1,118 @@
+import { z } from 'zod';
+import { formatError } from '../utils/errors.js';
+const nodeUpdateSchema = z.object({
+    nodeId: z.string().describe('The node ID to update'),
+    name: z.string().optional().describe('New name for the node'),
+    content: z.string().optional().describe('New content for the node'),
+    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('Node width'),
+    height: z.number().optional().describe('Node height'),
+});
+const edgeUpdateSchema = z.object({
+    edgeId: z.string().describe('The edge ID to update'),
+    direction: z
+        .enum(['none', 'source', 'target'])
+        .optional()
+        .describe('Arrow direction'),
+    label: z.string().optional().describe('Edge label'),
+});
+export const batchUpdateSchema = z.object({
+    boardId: z.string().describe('The board ID containing the items to update'),
+    nodes: z.array(nodeUpdateSchema).optional().describe('Array of node updates'),
+    edges: z.array(edgeUpdateSchema).optional().describe('Array of edge updates'),
+});
+export async function handleBatchUpdate(client, params) {
+    const nodeUpdates = params.nodes ?? [];
+    const edgeUpdates = params.edges ?? [];
+    if (nodeUpdates.length === 0 && edgeUpdates.length === 0) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: 'No updates provided. Include at least one node or edge update.',
+                },
+            ],
+            isError: true,
+        };
+    }
+    const results = {
+        nodes: [],
+        edges: [],
+    };
+    // Process node updates in parallel
+    const nodePromises = nodeUpdates.map(async (update) => {
+        const { nodeId, ...data } = update;
+        // Filter out undefined values
+        const cleanData = Object.fromEntries(Object.entries(data).filter(([, v]) => v !== undefined));
+        if (Object.keys(cleanData).length === 0) {
+            return { id: nodeId, success: false, error: 'No fields to update' };
+        }
+        try {
+            await client.updateNode({
+                boardId: params.boardId,
+                nodeId,
+                data: cleanData,
+            });
+            return { id: nodeId, success: true };
+        }
+        catch (error) {
+            return { id: nodeId, success: false, error: formatError(error) };
+        }
+    });
+    // Process edge updates in parallel
+    const edgePromises = edgeUpdates.map(async (update) => {
+        const { edgeId, direction, label } = update;
+        if (direction === undefined && label === undefined) {
+            return { id: edgeId, success: false, error: 'No fields to update' };
+        }
+        try {
+            await client.updateEdge({
+                boardId: params.boardId,
+                edgeId,
+                direction,
+                label,
+            });
+            return { id: edgeId, success: true };
+        }
+        catch (error) {
+            return { id: edgeId, success: false, error: formatError(error) };
+        }
+    });
+    // Wait for all updates to complete
+    results.nodes = await Promise.all(nodePromises);
+    results.edges = await Promise.all(edgePromises);
+    const nodeSuccessCount = results.nodes.filter(r => r.success).length;
+    const edgeSuccessCount = results.edges.filter(r => r.success).length;
+    const nodeFailCount = results.nodes.length - nodeSuccessCount;
+    const edgeFailCount = results.edges.length - edgeSuccessCount;
+    const errors = [
+        ...results.nodes.filter(r => !r.success),
+        ...results.edges.filter(r => !r.success),
+    ];
+    const response = {
+        success: errors.length === 0,
+        updated: {
+            nodes: nodeSuccessCount,
+            edges: edgeSuccessCount,
+        },
+    };
+    if (errors.length > 0) {
+        response.failed = {
+            nodes: nodeFailCount,
+            edges: edgeFailCount,
+        };
+        response.errors = errors.map(e => ({ id: e.id, error: e.error }));
+    }
+    const allFailed = errors.length === results.nodes.length + results.edges.length;
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify(response, null, 2),
+            },
+        ],
+        ...(allFailed && { isError: true }),
+    };
+}

package/dist/tools/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 boardsSchema = z.object({});
+/**
+ * Format boards as TSV for compact output.
+ * Uses papaparse for proper escaping of special characters.
+ */
+function formatBoardsTsv(boards) {
+    return Papa.unparse(boards, {
+        delimiter: '\t',
+        header: true,
+        newline: '\n',
+        columns: ['id', 'name', 'description', 'nodeCount', 'updatedAt', 'link'],
+    });
+}
+export async function handleBoards(client, _params, baseUrl) {
+    try {
+        const boards = await client.listBoards();
+        const formatted = boards.map(board => ({
+            id: board._id,
+            name: board.name,
+            description: board.description || '',
+            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 list boards: ${formatError(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}

package/dist/tools/check-collision.js

@@ -0,0 +1,55 @@
+import { z } from 'zod';
+import { findCollidingNodes, snapToGrid } from '../utils/collision.js';
+import { formatError } from '../utils/errors.js';
+export const checkCollisionSchema = z.object({
+    boardId: z.string().describe('The board ID to check against'),
+    x: z.number().describe('Left position of the rectangle'),
+    y: z.number().describe('Top position of the rectangle'),
+    width: z.number().describe('Width of the rectangle'),
+    height: z.number().describe('Height of the rectangle'),
+    excludeNodeId: z
+        .string()
+        .optional()
+        .describe('Optional node ID to exclude from check (for move operations)'),
+});
+export async function handleCheckCollision(client, params) {
+    try {
+        // Fetch nodes from board
+        const nodes = await client.listNodes({
+            boardId: params.boardId,
+            limit: 500,
+        });
+        // Snap position to grid
+        const rect = {
+            x: snapToGrid(params.x),
+            y: snapToGrid(params.y),
+            width: params.width,
+            height: params.height,
+        };
+        // Check for collisions
+        const result = findCollidingNodes(rect, nodes, params.excludeNodeId);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        collides: result.collides,
+                        rect,
+                        collidingNodes: result.collidingNodes,
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Failed to check collision: ${formatError(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}

package/dist/tools/colors.js

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+export const colorsSchema = z.object({});
+const NODE_COLORS = [
+    { name: 'amber', rgb: 'rgb(253, 230, 138)' },
+    { name: 'blue', rgb: 'rgb(0, 120, 255)' },
+    { name: 'cyan', rgb: 'rgb(0, 231, 255)' },
+    { name: 'emerald', rgb: 'rgb(0, 230, 118)' },
+    { name: 'fuchsia', rgb: 'rgb(233, 30, 99)' },
+    { name: 'green', rgb: 'rgb(52, 211, 153)' },
+    { name: 'indigo', rgb: 'rgb(72, 77, 201)' },
+    { name: 'lime', rgb: 'rgb(209, 250, 229)' },
+    { name: 'orange', rgb: 'rgb(252, 165, 0)' },
+    { name: 'pink', rgb: 'rgb(244, 143, 177)' },
+    { name: 'purple', rgb: 'rgb(156, 39, 176)' },
+    { name: 'red', rgb: 'rgb(239, 68, 68)' },
+    { name: 'rose', rgb: 'rgb(255, 204, 203)' },
+    { name: 'sky', rgb: 'rgb(0, 184, 230)' },
+    { name: 'slate', rgb: 'rgb(107, 114, 128)' },
+    { name: 'teal', rgb: 'rgb(0, 210, 183)' },
+    { name: 'violet', rgb: 'rgb(123, 31, 162)' },
+    { name: 'yellow', rgb: 'rgb(255, 251, 235)' },
+];
+export async function handleColors() {
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({
+                    colors: NODE_COLORS,
+                    usage: 'Use the color name (e.g., "blue", "emerald") when creating or updating nodes.',
+                }, null, 2),
+            },
+        ],
+    };
+}

package/dist/tools/create-board.js

@@ -0,0 +1,50 @@
+import { randomUUID } from 'crypto';
+import { z } from 'zod';
+import { formatError } from '../utils/errors.js';
+import { getBoardUrl } from '../utils/urls.js';
+export const createBoardSchema = z.object({
+    name: z.string().min(1).describe('The name for the new board'),
+});
+function generateObjectId() {
+    const timestamp = Math.floor(Date.now() / 1000)
+        .toString(16)
+        .padStart(8, '0');
+    const random = randomUUID().replace(/-/g, '').slice(0, 16);
+    return timestamp + random;
+}
+export async function handleCreateBoard(client, params, baseUrl) {
+    try {
+        const boardId = generateObjectId();
+        const board = await client.createBoard({
+            _id: boardId,
+            name: params.name,
+        });
+        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 create board: ${formatError(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}