nodestorm-mcp 0.1.0

package/dist/index.js

@@ -0,0 +1,572 @@
+#!/usr/bin/env node
+/**
+ * NodeStorm MCP Server
+ *
+ * Provides tools for AI agents to create, read, update, and delete NodeStorm workflows.
+ *
+ * Environment variables:
+ * - NODESTORM_API_KEY (required): API key for authentication
+ * - NODESTORM_API_URL (optional): API base URL (default: https://nodestorm.ai)
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { NodeStormClient, NodeStormApiError } from './client.js';
+import { getNodeDefinitions } from './tools/describe.js';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+// Get the directory of this file
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// Read environment variables
+const apiKey = process.env.NODESTORM_API_KEY;
+const apiUrl = process.env.NODESTORM_API_URL || 'https://nodestorm.ai';
+if (!apiKey) {
+    console.error('Error: NODESTORM_API_KEY environment variable is required');
+    process.exit(1);
+}
+// Initialize client
+const client = new NodeStormClient(apiKey, apiUrl);
+// Load workflow guide (bundled with package)
+function loadWorkflowGuide() {
+    try {
+        const guidePath = join(__dirname, 'workflow-guide.md');
+        return readFileSync(guidePath, 'utf-8');
+    }
+    catch {
+        return '# Workflow Guide\n\nGuide file not found. Please reinstall the package.';
+    }
+}
+// Create MCP server
+const server = new Server({
+    name: 'nodestorm-mcp',
+    version: '0.1.0',
+}, {
+    capabilities: {
+        tools: {},
+        resources: {},
+    },
+});
+// Tool definitions
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            {
+                name: 'create_flow',
+                description: 'Create a NodeStorm flow from a natural language description, or directly from JSON (admin-only).',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        prompt: {
+                            type: 'string',
+                            description: 'What the flow should do. Mutually exclusive with workflow_json.',
+                        },
+                        name: {
+                            type: 'string',
+                            description: 'Flow name (optional, will be generated if not provided)',
+                        },
+                        workflow_json: {
+                            type: 'object',
+                            description: 'Direct workflow JSON bypass (admin-only). Skips the AI generator. Mutually exclusive with prompt.',
+                            properties: {
+                                nodes: { type: 'array', items: { type: 'object' } },
+                                edges: { type: 'array', items: { type: 'object' } },
+                            },
+                        },
+                        description: {
+                            type: 'string',
+                            description: 'Description of the workflow',
+                        },
+                    },
+                },
+            },
+            {
+                name: 'get_flow',
+                description: 'Get a flow by ID',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        id: {
+                            type: 'string',
+                            description: 'Flow ID',
+                        },
+                    },
+                    required: ['id'],
+                },
+            },
+            {
+                name: 'update_flow',
+                description: 'Update flow METADATA: name, description, schedule_*. Does NOT modify nodes or edges. ' +
+                    'For any structural change use update_flow_structure.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        id: {
+                            type: 'string',
+                            description: 'Flow ID',
+                        },
+                        flow: {
+                            type: 'object',
+                            description: 'Metadata-only updates',
+                            properties: {
+                                name: { type: 'string' },
+                                description: { type: 'string' },
+                                schedule_enabled: { type: 'boolean' },
+                                schedule_cron: { type: 'string' },
+                                schedule_timezone: { type: 'string' },
+                            },
+                        },
+                    },
+                    required: ['id', 'flow'],
+                },
+            },
+            {
+                name: 'update_flow_structure',
+                description: "Apply a list of structural operations atomically to an existing flow's nodes and edges. " +
+                    'Each operation is one of: ' +
+                    '{ op: "edit_node", node_id, data?, position? }, ' +
+                    '{ op: "add_node", node: { id?, type, position, data } }, ' +
+                    '{ op: "remove_node", node_id }, ' +
+                    '{ op: "add_edge", source, target, source_handle?, target_handle? }, ' +
+                    '{ op: "remove_edge", edge_id }. ' +
+                    'All ops apply in a single transaction; if any op fails or the final flow is invalid, the whole batch rolls back. ' +
+                    'Order matters: each op sees the cumulative state from prior ops in the batch. ' +
+                    'To remove a middle node and reconnect, batch [remove_node, add_edge] together. ' +
+                    'For a single change, pass a single-op array. ' +
+                    'Server generates ids for new nodes/edges. data deep-merges (hashes recurse, arrays replace, null deletes); ' +
+                    'position replaces outright when both x and y are provided.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        flow_id: {
+                            type: 'string',
+                            description: 'Flow ID',
+                        },
+                        operations: {
+                            type: 'array',
+                            description: 'Ordered list of operations. Discriminated by `op`.',
+                            items: {
+                                anyOf: [
+                                    {
+                                        type: 'object',
+                                        title: 'edit_node',
+                                        properties: {
+                                            op: { type: 'string', enum: ['edit_node'] },
+                                            node_id: { type: 'string', description: 'Id of the node to edit' },
+                                            data: {
+                                                type: 'object',
+                                                description: 'Deep-merged into existing data (hashes recurse, arrays replace outright, null deletes a key)',
+                                            },
+                                            position: {
+                                                type: 'object',
+                                                description: 'Replaces position outright; both x and y required',
+                                                properties: { x: { type: 'number' }, y: { type: 'number' } },
+                                                required: ['x', 'y'],
+                                            },
+                                        },
+                                        required: ['op', 'node_id'],
+                                    },
+                                    {
+                                        type: 'object',
+                                        title: 'add_node',
+                                        properties: {
+                                            op: { type: 'string', enum: ['add_node'] },
+                                            node: {
+                                                type: 'object',
+                                                description: 'Node payload. Server generates id if not provided.',
+                                                properties: {
+                                                    id: { type: 'string' },
+                                                    type: { type: 'string', description: 'Node type — see describe_nodes for the catalog' },
+                                                    data: { type: 'object' },
+                                                    position: {
+                                                        type: 'object',
+                                                        properties: { x: { type: 'number' }, y: { type: 'number' } },
+                                                        required: ['x', 'y'],
+                                                    },
+                                                },
+                                                required: ['type'],
+                                            },
+                                        },
+                                        required: ['op', 'node'],
+                                    },
+                                    {
+                                        type: 'object',
+                                        title: 'remove_node',
+                                        properties: {
+                                            op: { type: 'string', enum: ['remove_node'] },
+                                            node_id: { type: 'string' },
+                                        },
+                                        required: ['op', 'node_id'],
+                                    },
+                                    {
+                                        type: 'object',
+                                        title: 'add_edge',
+                                        properties: {
+                                            op: { type: 'string', enum: ['add_edge'] },
+                                            source: { type: 'string', description: 'Source node id' },
+                                            target: { type: 'string', description: 'Target node id' },
+                                            source_handle: { type: 'string', description: 'Optional named output handle on source' },
+                                            target_handle: { type: 'string', description: 'Optional named input handle on target' },
+                                        },
+                                        required: ['op', 'source', 'target'],
+                                    },
+                                    {
+                                        type: 'object',
+                                        title: 'remove_edge',
+                                        properties: {
+                                            op: { type: 'string', enum: ['remove_edge'] },
+                                            edge_id: { type: 'string' },
+                                        },
+                                        required: ['op', 'edge_id'],
+                                    },
+                                ],
+                            },
+                        },
+                    },
+                    required: ['flow_id', 'operations'],
+                },
+            },
+            {
+                name: 'delete_flow',
+                description: 'Delete a flow',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        id: {
+                            type: 'string',
+                            description: 'Flow ID',
+                        },
+                    },
+                    required: ['id'],
+                },
+            },
+            {
+                name: 'list_flows',
+                description: "List or search the user's workflows. " +
+                    'Pass `query` to filter by title/description. ' +
+                    "scope='user' (default) searches user's own flows; scope='public' searches published community/official entries.",
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        query: {
+                            type: 'string',
+                            description: 'Optional search query',
+                        },
+                        scope: {
+                            type: 'string',
+                            enum: ['user', 'public'],
+                            description: 'Search scope (default: user)',
+                        },
+                        limit: {
+                            type: 'number',
+                            description: 'Max results to return (default: 20)',
+                        },
+                    },
+                },
+            },
+            {
+                name: 'describe_nodes',
+                description: 'Get node type definitions for building flows',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        types: {
+                            type: 'array',
+                            items: { type: 'string' },
+                            description: "Filter to specific node types (e.g., ['prompt', 'list'])",
+                        },
+                    },
+                },
+            },
+            {
+                name: 'get_flow_run',
+                description: 'Get details of a specific flow run by ID, including execution results and node outputs',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        id: {
+                            type: 'string',
+                            description: 'Flow run ID',
+                        },
+                    },
+                    required: ['id'],
+                },
+            },
+            {
+                name: 'search_chat_history',
+                description: 'Search chat message history using semantic (meaning-based) search. Returns past messages ranked by relevance to the query. Supports filtering by role, source, and date range.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        query: {
+                            type: 'string',
+                            description: 'Natural language search query',
+                        },
+                        limit: {
+                            type: 'number',
+                            description: 'Max results (default 20, max 50)',
+                        },
+                        role: {
+                            type: 'string',
+                            enum: ['user', 'assistant'],
+                            description: 'Filter by message role',
+                        },
+                        source: {
+                            type: 'string',
+                            enum: ['chat', 'heartbeat', 'telegram'],
+                            description: 'Filter by message source',
+                        },
+                        from: {
+                            type: 'string',
+                            description: 'Start date filter (ISO8601)',
+                        },
+                        to: {
+                            type: 'string',
+                            description: 'End date filter (ISO8601)',
+                        },
+                    },
+                    required: ['query'],
+                },
+            },
+            {
+                name: 'list_flow_runs',
+                description: 'List flow runs with optional filters for debugging and monitoring',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        flow_id: {
+                            type: 'number',
+                            description: 'Filter by flow ID',
+                        },
+                        status: {
+                            type: 'string',
+                            enum: ['success', 'error', 'pending', 'running'],
+                            description: 'Filter by status',
+                        },
+                        page: {
+                            type: 'number',
+                            description: 'Page number (default: 1)',
+                        },
+                        per_page: {
+                            type: 'number',
+                            description: 'Results per page (default: 20, max: 100)',
+                        },
+                    },
+                },
+            },
+        ],
+    };
+});
+// Tool execution
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        switch (name) {
+            case 'create_flow': {
+                const { prompt, name: flowName, workflow_json, description } = args;
+                const result = await client.createFlow({ prompt, name: flowName, workflow_json, description });
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'get_flow': {
+                const { id } = args;
+                const result = await client.getFlow(id);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'update_flow': {
+                const { id, flow } = args;
+                const result = await client.updateFlow(id, flow);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'update_flow_structure': {
+                const { flow_id, operations } = args;
+                const result = await client.updateFlowStructure(flow_id, operations);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'delete_flow': {
+                const { id } = args;
+                const result = await client.deleteFlow(id);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'list_flows': {
+                const { query, scope = 'user', limit = 20 } = args;
+                const result = await client.listFlows({ query, scope, limit });
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'describe_nodes': {
+                const { types } = args;
+                const nodes = getNodeDefinitions(types);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({ nodes }, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'get_flow_run': {
+                const { id } = args;
+                const result = await client.getFlowRun(id);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'search_chat_history': {
+                const { query, limit, role, source, from, to } = args;
+                const result = await client.searchChatHistory({ query, limit, role, source, from, to });
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'list_flow_runs': {
+                const { flow_id, status, page, per_page } = args;
+                const result = await client.listFlowRuns({
+                    flowId: flow_id,
+                    status,
+                    page,
+                    perPage: per_page,
+                });
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
+            default:
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({ error: `Unknown tool: ${name}`, code: 'invalid' }),
+                        },
+                    ],
+                    isError: true,
+                };
+        }
+    }
+    catch (error) {
+        if (error instanceof NodeStormApiError) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            error: error.message,
+                            code: error.code,
+                            errors: error.errors,
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        error: error instanceof Error ? error.message : 'Unknown error',
+                        code: 'server_error',
+                    }),
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// Resource definitions
+server.setRequestHandler(ListResourcesRequestSchema, async () => {
+    return {
+        resources: [
+            {
+                uri: 'nodestorm://workflow-guide',
+                name: 'Workflow Builder Guide',
+                description: 'Complete guide for building NodeStorm flows: node types, edge rules, iteration semantics, validation, patterns, and examples',
+                mimeType: 'text/markdown',
+            },
+        ],
+    };
+});
+// Resource reading
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    const { uri } = request.params;
+    if (uri === 'nodestorm://workflow-guide') {
+        const guide = loadWorkflowGuide();
+        return {
+            contents: [
+                {
+                    uri,
+                    mimeType: 'text/markdown',
+                    text: guide,
+                },
+            ],
+        };
+    }
+    throw new Error(`Unknown resource: ${uri}`);
+});
+// Start the server
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('NodeStorm MCP server started');
+}
+main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});

package/dist/tools/describe.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Node definitions for the describe_nodes tool
+ * These are bundled statically to avoid API calls
+ */
+export interface NodeDefinition {
+    type: string;
+    description: string;
+    category: string;
+    config_schema: Record<string, any>;
+    handles: {
+        inputs: string[];
+        outputs: string[];
+    };
+}
+/**
+ * Get node definitions, optionally filtered by type
+ */
+export declare function getNodeDefinitions(types?: string[]): NodeDefinition[];