n8n-workflow-builder-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ifmelate
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,210 @@
+# n8n Workflow Builder MCP
+
+This project provides a Model Context Protocol (MCP) server for building and manipulating n8n workflows JSON in Cursor IDE. It's a way to build n8n workflows just by prompting with AI in chat.
+
+<a href="https://glama.ai/mcp/servers/@ifmelate/n8n-workflow-builder-mcp">
+  <img width="380" height="200" src="https://glama.ai/mcp/servers/@ifmelate/n8n-workflow-builder-mcp/badge" alt="n8n-workflow-builder-mcp MCP server" />
+</a>
+
+# DEMO VIDEO:
+[![Watch the video](https://github.com/user-attachments/assets/53706f62-7e99-449f-8537-0ce951c727e1)](https://youtu.be/MKEVLM5QmPA?si=8SJQAcYGeAIuhaBm)
+
+## Current status of implementation
+
+It's in early development stage. Basically, it's working - MCP server creates JSON file with n8n workflow that you can copy and paste to workflow editor in n8n UI.
+Current problems:
+- sometimes llm agents put wrong parameters in the request. **I plan to find a way to fix this**.
+- sometimes connection between nodes is not setting. **I'm working to resolve it**.
+- not all types of node are checked working. **I'm working to resolve it**.
+- initial prompt does matter. If it's not clear, the agent will go wrong way. **I plan to find a way to fix this**.
+
+## Key Features
+
+- **Workflow Management**: Create, update, and execute n8n workflows programmatically (execute is not implemented yet)
+- **Node Discovery**: Explore available n8n nodes and their capabilities 
+- **Connection Management**: Create connections between workflow nodes
+- **AI Integration**: Special tools for connecting AI components in workflows
+- **AI-Friendly Interface**: Designed specifically for interaction with AI agents
+
+
+## Prerequisites
+
+- Node.js (v14 or higher)
+- Cursor IDE (v0.48 or newer)
+- npm or yarn
+- TypeScript compiler (installed as a dev dependency via `npm install`)
+
+## Installation
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/ifmelate/n8n-workflow-builder-mcp.git
+   cd n8n-workflow-builder-mcp
+   ```
+
+2. Install dependencies:
+   ```bash
+   npm install
+   ```
+
+3. Build the TypeScript project:
+   ```bash
+   npm run build
+   ```
+
+4. Make the MCP server script executable (if needed):
+   ```bash
+   chmod +x dist/index.js
+   ```
+
+## Running the Server
+
+Start the MCP server:
+```bash
+npm start
+```
+This will run the compiled code from `dist/index.js`.
+
+For development with auto-rebuild and restart on changes:
+```bash
+npm run dev
+```
+
+## Cursor IDE Integration
+
+There are two ways to set up the MCP server with Cursor:
+
+### Method 1: Using Cursor Settings UI (Recommended)
+
+1. Start Cursor IDE
+2. Go to Settings > Features > MCP Servers
+3. Click "Add Server" and provide the **absolute path** to the `dist/index.js` file
+   (e.g., `/Users/yourname/n8n-workflow-builder-mcp/dist/index.js`)
+4. Make sure the server is enabled
+5. Restart Cursor IDE for changes to take effect
+
+### Method 2: Manual Configuration
+
+1. Ensure the `.cursor` directory exists:
+   ```bash
+   mkdir -p .cursor
+   ```
+
+2. Create the MCP configuration file:
+   ```bash
+   cat > .cursor/mcp.json << 'EOF'
+   {
+     "mcpServers": {
+       "n8n-workflow-builder": {
+         "command": "node",
+         "args": ["/absolute/path/to/n8n-workflow-builder-mcp/dist/index.js"]
+       }
+     }
+   }
+   EOF
+   ```
+   Make sure to replace `/absolute/path/to` with the actual path on your system.
+
+3. Restart Cursor IDE for changes to take effect
+
+## Available MCP Tools
+
+The server provides the following tools for working with n8n workflows:
+
+| Tool Name | Description | Key Parameters |
+|-----------|-------------|----------------|
+| **create_workflow** | Create a new n8n workflow | `workflow_name`, `workspace_dir` |
+| **list_workflows** | List all existing workflows | (no parameters) |
+| **get_workflow_details** | Get detailed information about a specific workflow | `workflow_name` |
+| **add_node** | Add a new node to a workflow | `workflow_name`, `node_type`, `position`, `parameters`, `node_name`, `typeVersion` |
+| **edit_node** | Edit an existing node in a workflow | `workflow_name`, `node_id`, `node_type`, `node_name`, `position`, `parameters` |
+| **delete_node** | Delete a node from a workflow | `workflow_name`, `node_id` |
+| **add_connection** | Add a connection between nodes | `workflow_name`, `source_node_id`, `source_node_output_name`, `target_node_id`, `target_node_input_name` |
+| **add_ai_connections** | Add AI connections for LangChain nodes | `workflow_name`, `agent_node_id`, `model_node_id`, `tool_node_ids` |
+| **list_available_nodes** | List available node types with optional filtering | `search_term` (optional) |
+
+## Troubleshooting Cursor Integration
+
+If you're having trouble getting the MCP server to work with Cursor, try these steps:
+
+1. **Restart Cursor**: After setting up the MCP configuration, completely close and restart Cursor.
+
+2. **Check Cursor MCP settings**:
+   - Open Cursor Settings
+   - Go to Features > MCP Servers
+   - Make sure your server is listed and enabled
+   - If it's listed but not working, try clicking the refresh button
+
+3. **Check server logs**: Look for errors in the terminal where you're running the server or in the Cursor Output panel. Select "Cursor MCP" from the dropdown in the Output panel to see MCP-specific logs.
+
+4. **Verify file permissions**: Make sure the `dist/index.js` file has execution permissions.
+
+5. **Check for port conflicts**: If there are other MCP servers running, they might conflict. Check for other processes using the same ports.
+
+6. **Try global installation**: Instead of using a local path, you can try installing the server globally:
+   ```bash
+   npm install -g n8n-workflow-builder-mcp
+   ```
+   Then update the `.cursor/mcp.json` file to use the global command.
+
+## Common Issues and Solutions
+
+### "Failed to create client"
+
+This usually happens when:
+- The MCP server isn't running
+- There's a connectivity issue between Cursor and the server
+- The server crashed during initialization
+
+Try:
+1. Running the test script to make sure the server works correctly
+2. Checking for errors in the server logs
+3. Restarting Cursor
+
+### MCP Server is not showing up in Cursor
+
+This can happen if:
+- The `.cursor/mcp.json` file is not properly formatted
+- Cursor hasn't detected the configuration change
+
+Try:
+1. Validating the JSON format of your `.cursor/mcp.json` file
+2. Restarting Cursor
+3. Manually selecting the server in Cursor settings (if it appears there)
+
+### MCP Server shows up but tools aren't available
+
+This can happen if:
+- The server isn't properly registering its tools
+- There's an issue with the ListOfferings request/response
+
+Try:
+1. Running the test script to check if tools are properly registered
+2. Clicking the refresh button in the MCP server settings in Cursor
+3. Checking the server logs for any errors
+
+## Project Structure
+
+- `/src`: Main source code
+- `/src/tools`: MCP tools implementation
+- `/src/models`: Data models
+- `/src/utils`: Utility functions
+- `/src/middleware`: Authentication and middleware
+- `/config`: Configuration files
+- `/tests`: Test files
+- `/workflow_nodes`: n8n node definitions
+- `/docs`: Additional documentation
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+Working on licence - need to have confirmation from n8n team

package/config/credentials/credentials.json

@@ -0,0 +1 @@
+{"credentials":{},"meta":{"version":"1.0","keyId":"v1"}}

package/config/default.js

@@ -0,0 +1,41 @@
+module.exports = {
+    server: {
+        port: process.env.PORT || 3000,
+        env: process.env.NODE_ENV || 'development',
+    },
+    n8n: {
+        apiUrl: process.env.N8N_API_URL || 'http://localhost:5678/api/',
+        apiKey: process.env.N8N_API_KEY,
+        workflowsPath: process.env.N8N_WORKFLOWS_PATH || './n8n-workflows',
+        integrationType: process.env.N8N_INTEGRATION_TYPE || 'auto', // 'api', 'filesystem', or 'auto'
+    },
+    auth: {
+        jwtSecret: process.env.JWT_SECRET || 'default-dev-secret',
+        jwtExpiresIn: process.env.JWT_EXPIRES_IN || '1d',
+        apiKeys: process.env.API_KEYS ? process.env.API_KEYS.split(',') : ['dev-api-key'],
+        encryptionKey: process.env.ENCRYPTION_KEY,
+        keyRotationInterval: parseInt(process.env.KEY_ROTATION_INTERVAL || '30', 10), // days
+    },
+    logging: {
+        level: process.env.LOG_LEVEL || 'info',
+    },
+    credentials: {
+        storageDir: process.env.CREDENTIALS_DIR || './config/credentials',
+    },
+    storage: {
+        workflowsPath: process.env.WORKFLOWS_PATH || './workflow_nodes',
+        versioning: {
+            enabled: process.env.ENABLE_VERSIONING !== 'false',
+            maxVersions: parseInt(process.env.MAX_VERSIONS || '10', 10),
+        },
+    },
+    llm: {
+        defaultProvider: process.env.LLM_DEFAULT_PROVIDER || 'openai',
+        openaiApiKey: process.env.OPENAI_API_KEY,
+        openaiModel: process.env.OPENAI_MODEL || 'gpt-4-turbo',
+        anthropicApiKey: process.env.ANTHROPIC_API_KEY,
+        anthropicModel: process.env.ANTHROPIC_MODEL || 'claude-3-opus-20240229',
+        temperature: parseFloat(process.env.LLM_TEMPERATURE || '0.2'),
+        maxTokens: parseInt(process.env.LLM_MAX_TOKENS || '2000', 10),
+    },
+}; 

package/package.json

@@ -0,0 +1,56 @@
+{
+    "name": "n8n-workflow-builder-mcp",
+    "version": "0.1.0",
+    "description": "MCP server for building n8n workflows",
+    "main": "src/index.js",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/ifmelate/n8n-workflow-builder-mcp.git"
+    },
+    "scripts": {
+        "start": "node dist/index.js",
+        "dev": "nodemon --watch src --ext ts,json --exec \"npm run build && node dist/index.js\"",
+        "lint": "eslint .",
+        "format": "prettier --write .",
+        "test": "jest",
+        "test:langchain": "mocha tests/unit/langchain-llm-format.test.js",
+        "mcp": "node n8n-workflow-mcp.js",
+        "build": "tsc"
+    },
+    "keywords": [
+        "n8n",
+        "mcp",
+        "workflow",
+        "automation"
+    ],
+    "author": "ifmelate",
+    "license": "MIT",
+    "dependencies": {
+        "@modelcontextprotocol/sdk": "^1.11.3",
+        "@types/uuid": "^10.0.0",
+        "abort-controller": "^3.0.0",
+        "ajv": "^8.12.0",
+        "ajv-formats": "^3.0.1",
+        "cors": "^2.8.5",
+        "dotenv": "^16.3.1",
+        "express": "^4.18.2",
+        "jsonwebtoken": "^9.0.2",
+        "morgan": "^1.10.0",
+        "node-fetch": "^2.6.7",
+        "uuid": "^9.0.1",
+        "winston": "^3.10.0",
+        "zod": "^3.24.4"
+    },
+    "devDependencies": {
+        "@types/node": "^20.0.0",
+        "chai": "^4.5.0",
+        "eslint": "^8.46.0",
+        "jest": "^29.6.2",
+        "mocha": "^10.8.2",
+        "nodemon": "^3.0.1",
+        "prettier": "^3.0.1",
+        "sinon": "^20.0.0",
+        "supertest": "^7.1.1",
+        "typescript": "^5.0.0"
+    }
+}

package/scripts/demo-n8n-integration.js

@@ -0,0 +1,161 @@
+/**
+ * n8n Integration Demo Script
+ * 
+ * This script demonstrates how to use the n8n integration module
+ * to deploy, activate, and manage workflows in n8n.
+ * 
+ * Usage:
+ * node scripts/demo-n8n-integration.js
+ */
+
+require('dotenv').config();
+const path = require('path');
+const { n8nIntegration, getIntegrationType } = require('../src/models/n8nIntegration');
+const { workflowStorage } = require('../src/models/storage');
+
+// Sample workflow data
+const sampleWorkflow = {
+    name: 'Sample API Request Workflow',
+    active: false,
+    nodes: [
+        {
+            parameters: {
+                url: 'https://jsonplaceholder.typicode.com/posts/1',
+                authentication: 'none',
+                method: 'GET',
+                options: {}
+            },
+            name: 'HTTP Request',
+            type: 'n8n-nodes-base.httpRequest',
+            typeVersion: 1,
+            position: [100, 100],
+            id: 'http-node-1'
+        },
+        {
+            parameters: {},
+            name: 'No Operation',
+            type: 'n8n-nodes-base.noOp',
+            typeVersion: 1,
+            position: [300, 100],
+            id: 'no-op-node-1'
+        }
+    ],
+    connections: {
+        'http-node-1': {
+            main: [
+                [
+                    {
+                        node: 'no-op-node-1',
+                        type: 'main',
+                        index: 0
+                    }
+                ]
+            ]
+        }
+    },
+    id: 'sample-workflow-' + Date.now(),
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString()
+};
+
+// File path for the workflow
+const workflowPath = path.join(process.cwd(), 'workflow_nodes', `${sampleWorkflow.id}.json`);
+
+// Demo function
+async function runDemo() {
+    try {
+        console.log('n8n Integration Demo');
+        console.log('===================');
+        console.log(`Integration type: ${getIntegrationType()}`);
+        console.log('');
+
+        // 1. Save workflow to filesystem
+        console.log('1. Saving workflow to filesystem...');
+        await workflowStorage.saveWorkflow(
+            sampleWorkflow.id,
+            sampleWorkflow,
+            workflowPath
+        );
+        console.log('   Workflow saved to:', workflowPath);
+        console.log('');
+
+        // 2. Deploy workflow to n8n
+        console.log('2. Deploying workflow to n8n...');
+        try {
+            const deployResult = await n8nIntegration.deployWorkflow(workflowPath);
+            console.log('   Deployment result:', JSON.stringify(deployResult, null, 2));
+        } catch (error) {
+            console.error('   Deployment error:', error.message);
+            // Continue with demo even if deploy fails
+        }
+        console.log('');
+
+        // 3. List workflows in n8n
+        console.log('3. Listing workflows in n8n...');
+        try {
+            const listResult = await n8nIntegration.listWorkflows();
+            console.log(`   Found ${listResult.count} workflows:`);
+            listResult.workflows.forEach(wf => {
+                console.log(`   - ${wf.name} (ID: ${wf.id}, Active: ${wf.active})`);
+            });
+        } catch (error) {
+            console.error('   List error:', error.message);
+        }
+        console.log('');
+
+        // 4. Activate workflow
+        console.log('4. Activating workflow...');
+        try {
+            const activateResult = await n8nIntegration.activateWorkflow(workflowPath, true);
+            console.log('   Activation result:', JSON.stringify(activateResult, null, 2));
+        } catch (error) {
+            console.error('   Activation error:', error.message);
+        }
+        console.log('');
+
+        // 5. Check execution status (only works with API integration)
+        if (getIntegrationType() === 'api') {
+            console.log('5. Checking execution status...');
+            try {
+                // Wait a moment for possible execution
+                await new Promise(resolve => setTimeout(resolve, 2000));
+
+                const statusResult = await n8nIntegration.checkExecutionStatus(sampleWorkflow.id);
+                if (statusResult.hasExecutions) {
+                    console.log('   Latest execution:', JSON.stringify(statusResult.latestExecution, null, 2));
+                } else {
+                    console.log('   No executions found for this workflow.');
+                }
+            } catch (error) {
+                console.error('   Status check error:', error.message);
+            }
+            console.log('');
+        }
+
+        // 6. Deactivate workflow
+        console.log('6. Deactivating workflow...');
+        try {
+            const deactivateResult = await n8nIntegration.activateWorkflow(workflowPath, false);
+            console.log('   Deactivation result:', JSON.stringify(deactivateResult, null, 2));
+        } catch (error) {
+            console.error('   Deactivation error:', error.message);
+        }
+        console.log('');
+
+        console.log('Demo completed!');
+        console.log('');
+        console.log('Notes:');
+        console.log('- For API integration, ensure n8n is running with REST API enabled');
+        console.log('- Set N8N_API_URL and N8N_API_KEY in your .env file');
+        console.log('- For filesystem integration, set N8N_WORKFLOWS_PATH in your .env file');
+        console.log('- You can explicitly set N8N_INTEGRATION_TYPE to "api" or "filesystem"');
+
+    } catch (error) {
+        console.error('Demo failed:', error);
+    }
+}
+
+// Run the demo
+runDemo().catch(error => {
+    console.error('Unhandled error in demo:', error);
+}); 

package/scripts/demo-workflow-generator.js

@@ -0,0 +1,102 @@
+/**
+ * Workflow Generator Demo Script
+ * 
+ * This script demonstrates how to use the workflow generator
+ * to create n8n workflows from natural language descriptions.
+ * 
+ * Usage:
+ * node scripts/demo-workflow-generator.js
+ */
+
+require('dotenv').config();
+const fs = require('fs').promises;
+const path = require('path');
+const { generateWorkflow } = require('../src/models/llmService');
+
+// Example workflow descriptions
+const workflowDescriptions = [
+    {
+        name: 'API Data Fetcher',
+        description: 'Create a workflow that fetches data from a REST API every hour, ' +
+            'processes the JSON response to extract user information, and saves it to a CSV file.'
+    },
+    {
+        name: 'Email Notification System',
+        description: 'Build a workflow that monitors a folder for new files, and when a new file ' +
+            'is detected, sends an email notification with the file name and a summary of its contents.'
+    },
+    {
+        name: 'Data Transformation Pipeline',
+        description: 'Create a workflow that takes CSV data, transforms it by cleaning empty fields, ' +
+            'standardizing date formats, and calculating a new "total" column, then outputs the processed data.'
+    }
+];
+
+// Demo function
+async function runDemo() {
+    try {
+        console.log('Workflow Generator Demo');
+        console.log('=======================');
+        console.log('This demo shows how natural language descriptions can be converted to n8n workflows\n');
+
+        // Create output directory if it doesn't exist
+        const outputDir = path.join(process.cwd(), 'generated-workflows');
+        await fs.mkdir(outputDir, { recursive: true });
+        console.log(`Output directory: ${outputDir}\n`);
+
+        // Select a workflow to generate
+        const workflowIndex = 0; // Change this to try different examples
+        const selectedWorkflow = workflowDescriptions[workflowIndex];
+
+        console.log(`Generating workflow: ${selectedWorkflow.name}`);
+        console.log(`Description: ${selectedWorkflow.description}\n`);
+        console.log('Processing...\n');
+
+        // Generate the workflow
+        const result = await generateWorkflow(selectedWorkflow.description);
+
+        // Create a complete workflow object
+        const workflow = {
+            name: selectedWorkflow.name,
+            active: false,
+            nodes: result.nodes,
+            connections: result.connections,
+            settings: {
+                executionOrder: 'v1',
+                saveExecutionProgress: true,
+                saveManualExecutions: true,
+                saveDataErrorExecution: 'all',
+                saveDataSuccessExecution: 'all',
+                callerPolicy: 'workflowsFromSameOwner',
+                errorWorkflow: ''
+            },
+            tags: [{ name: 'Generated' }],
+            pinData: {},
+            id: `demo-workflow-${Date.now()}`,
+            createdAt: new Date().toISOString(),
+            updatedAt: new Date().toISOString()
+        };
+
+        // Save to file
+        const outputPath = path.join(outputDir, `${workflow.name.replace(/[^a-z0-9]/gi, '_').toLowerCase()}.json`);
+        await fs.writeFile(outputPath, JSON.stringify(workflow, null, 2));
+
+        console.log('Workflow generated successfully!');
+        console.log(`Saved to: ${outputPath}`);
+        console.log(`Contains ${workflow.nodes.length} nodes\n`);
+
+        console.log('Next steps:');
+        console.log('1. Copy the workflow JSON file');
+        console.log('2. Import it into n8n through the Import from File option');
+        console.log('3. Customize any specific parameters as needed');
+        console.log('4. Activate and run your workflow!');
+
+    } catch (error) {
+        console.error('Demo failed:', error);
+    }
+}
+
+// Run the demo
+runDemo().catch(error => {
+    console.error('Unhandled error in demo:', error);
+}); 

package/scripts/init.sh

@@ -0,0 +1,36 @@
+#!/bin/bash
+
+# Initialize n8n-workflow-builder-mcp project
+
+# Create necessary directories
+echo "Creating project directories..."
+mkdir -p logs
+mkdir -p src/tools
+mkdir -p src/models
+mkdir -p src/utils
+mkdir -p src/middleware
+mkdir -p config
+mkdir -p tests
+
+# Check if package.json exists
+if [ ! -f package.json ]; then
+  echo "Creating package.json..."
+  npm init -y
+fi
+
+# Install dependencies
+echo "Installing dependencies..."
+npm install express cors dotenv ajv winston morgan
+
+# Install dev dependencies
+echo "Installing development dependencies..."
+npm install --save-dev eslint prettier nodemon jest
+
+# Create .env if it doesn't exist
+if [ ! -f .env ]; then
+  echo "Creating .env file from example..."
+  cp .env.example .env || echo "# Server Configuration\nPORT=3000\nNODE_ENV=development\nLOG_LEVEL=info\n\n# n8n API Configuration\nN8N_API_URL=http://localhost:5678/api/\nN8N_API_KEY=your_n8n_api_key_here" > .env
+fi
+
+echo "Project initialized successfully!"
+echo "Run 'npm run dev' to start the development server."