aios-core 2.1.0

package/.aios-core/infrastructure/tools/mcp/n8n.yaml

@@ -0,0 +1,551 @@
+tool:
+  schema_version: 2.0
+  id: n8n
+  type: mcp
+  name: n8n Workflow Automation
+  version: 1.0.0
+  description: n8n workflow management with execution validation and credential handling
+  knowledge_strategy: executable
+
+  executable_knowledge:
+    validators:
+      # Combined validator for execute_workflow
+      - id: validate-execute-workflow
+        validates: execute_workflow
+        language: javascript
+        checks:
+          - required_fields: [workflow_id]
+        function: |
+          (function() {
+            const errors = [];
+
+            // 1. Required workflow_id
+            if (!args.args.workflow_id && !args.args.workflowId) {
+              errors.push("workflow_id is required");
+            }
+
+            // 2. Validate data parameter structure if provided
+            if (args.args.data) {
+              if (typeof args.args.data !== 'object') {
+                errors.push("data must be an object");
+              }
+            }
+
+            // 3. Validate wait_for_completion is boolean
+            if (args.args.wait_for_completion !== undefined &&
+                typeof args.args.wait_for_completion !== 'boolean') {
+              errors.push("wait_for_completion must be boolean");
+            }
+
+            return {
+              valid: errors.length === 0,
+              errors: errors
+            };
+          })();
+
+      # Validator for create_workflow
+      - id: validate-create-workflow
+        validates: create_workflow
+        language: javascript
+        function: |
+          (function() {
+            const errors = [];
+
+            // 1. Required name field
+            if (!args.args.name) {
+              errors.push("name is required");
+            }
+
+            // 2. Validate nodes structure if provided
+            if (args.args.nodes) {
+              if (!Array.isArray(args.args.nodes)) {
+                errors.push("nodes must be an array");
+              } else {
+                args.args.nodes.forEach((node, index) => {
+                  if (!node.type) {
+                    errors.push(`nodes[${index}] missing required 'type' field`);
+                  }
+                  if (!node.name) {
+                    errors.push(`nodes[${index}] missing required 'name' field`);
+                  }
+                });
+              }
+            }
+
+            // 3. Validate connections structure
+            if (args.args.connections) {
+              if (typeof args.args.connections !== 'object') {
+                errors.push("connections must be an object");
+              }
+            }
+
+            return {
+              valid: errors.length === 0,
+              errors: errors
+            };
+          })();
+
+      # Validator for create_credential
+      - id: validate-create-credential
+        validates: create_credential
+        language: javascript
+        function: |
+          (function() {
+            const errors = [];
+
+            if (!args.args.name) {
+              errors.push("name is required for create_credential");
+            }
+            if (!args.args.type) {
+              errors.push("type is required for create_credential");
+            }
+            if (!args.args.data) {
+              errors.push("data is required for create_credential");
+            } else if (typeof args.args.data !== 'object') {
+              errors.push("data must be an object");
+            }
+
+            return {
+              valid: errors.length === 0,
+              errors: errors
+            };
+          })();
+
+      # Validator for update_credential
+      - id: validate-update-credential
+        validates: update_credential
+        language: javascript
+        function: |
+          (function() {
+            const errors = [];
+
+            if (!args.args.credential_id && !args.args.credentialId) {
+              errors.push("credential_id is required for update_credential");
+            }
+
+            return {
+              valid: errors.length === 0,
+              errors: errors
+            };
+          })();
+
+      # Validator for delete_credential
+      - id: validate-delete-credential
+        validates: delete_credential
+        language: javascript
+        function: |
+          (function() {
+            const errors = [];
+
+            if (!args.args.credential_id && !args.args.credentialId) {
+              errors.push("credential_id is required for delete_credential");
+            }
+
+            return {
+              valid: errors.length === 0,
+              errors: errors
+            };
+          })();
+
+    helpers:
+      - id: extract-workflow-state
+        language: javascript
+        runtime: isolated_vm
+        description: "Extract current state from workflow execution"
+        function: |
+          (function() {
+            const { execution } = args;
+            if (!execution) return null;
+
+            return {
+              id: execution.id,
+              status: execution.finished ? 'finished' : execution.stoppedAt ? 'stopped' : 'running',
+              startedAt: execution.startedAt,
+              finishedAt: execution.finishedAt,
+              mode: execution.mode
+            };
+          })();
+
+      - id: validate-node-connections
+        language: javascript
+        runtime: isolated_vm
+        description: "Validate node connections in workflow"
+        function: |
+          (function() {
+            const { nodes, connections } = args;
+            if (!nodes || !connections) {
+              return { valid: false, errors: ['Missing nodes or connections'] };
+            }
+
+            const errors = [];
+            const nodeNames = new Set(nodes.map(n => n.name));
+
+            // Check all connection sources exist
+            for (const [sourceName, outputs] of Object.entries(connections)) {
+              if (!nodeNames.has(sourceName)) {
+                errors.push(`Connection source '${sourceName}' not found in nodes`);
+              }
+
+              // Check all connection targets exist
+              // n8n structure: outputs = { main: [[{node, type, index}]], error: [[...]] }
+              for (const outputConnections of Object.values(outputs || {})) {
+                if (Array.isArray(outputConnections)) {
+                  // outputConnections is an array of arrays
+                  outputConnections.forEach(connectionGroup => {
+                    if (Array.isArray(connectionGroup)) {
+                      connectionGroup.forEach(conn => {
+                        if (conn.node && !nodeNames.has(conn.node)) {
+                          errors.push(`Connection target '${conn.node}' not found in nodes`);
+                        }
+                      });
+                    }
+                  });
+                }
+              }
+            }
+
+            return {
+              valid: errors.length === 0,
+              errors: errors
+            };
+          })();
+
+      - id: format-workflow-data
+        language: javascript
+        runtime: isolated_vm
+        description: "Format input data for workflow execution"
+        function: |
+          (function() {
+            const { data, workflowData } = args;
+
+            // If workflow expects specific input format, validate it
+            if (workflowData && workflowData.nodes) {
+              const triggerNode = workflowData.nodes.find(n =>
+                n.type.includes('trigger') ||
+                n.type.includes('webhook') ||
+                n.type === 'n8n-nodes-base.start'
+              );
+
+              if (triggerNode && triggerNode.parameters !== undefined) {
+                // Format data according to trigger expectations
+                return {
+                  formatted: true,
+                  data: data || {},
+                  triggerNode: triggerNode.name
+                };
+              }
+            }
+
+            return {
+              formatted: false,
+              data: data || {}
+            };
+          })();
+
+      - id: parse-execution-error
+        language: javascript
+        runtime: isolated_vm
+        description: "Parse and format execution errors"
+        function: |
+          (function() {
+            const { error, execution } = args;
+            if (!error) return null;
+
+            return {
+              message: error.message || 'Unknown error',
+              node: error.node || 'unknown',
+              timestamp: error.timestamp || execution?.stoppedAt,
+              stack: error.stack || null
+            };
+          })();
+
+      - id: validate-credential-type
+        language: javascript
+        runtime: isolated_vm
+        description: "Validate credential type is supported"
+        function: |
+          (function() {
+            const { type } = args;
+
+            // Common n8n credential types
+            const validTypes = [
+              'httpBasicAuth',
+              'httpHeaderAuth',
+              'oAuth2Api',
+              'apiKey',
+              'postgres',
+              'mysql',
+              'mongodb',
+              'redis',
+              'aws',
+              'googleApi',
+              'slackApi',
+              'githubApi',
+              'jwtAuth'
+            ];
+
+            return validTypes.includes(type);
+          })();
+
+      - id: build-workflow-structure
+        language: javascript
+        runtime: isolated_vm
+        description: "Build workflow structure from nodes and connections"
+        function: |
+          (function() {
+            const { name, nodes, connections } = args;
+
+            if (!name) {
+              return { error: 'Workflow name is required' };
+            }
+
+            return {
+              name: name,
+              nodes: nodes || [],
+              connections: connections || {},
+              active: false,
+              settings: {},
+              staticData: null
+            };
+          })();
+
+      - id: calculate-workflow-complexity
+        language: javascript
+        runtime: isolated_vm
+        description: "Calculate workflow complexity score"
+        function: |
+          (function() {
+            const { nodes, connections } = args;
+
+            if (!nodes) return { complexity: 0 };
+
+            let complexity = nodes.length; // Base complexity from node count
+
+            // Add complexity for connections
+            if (connections) {
+              const connectionCount = Object.values(connections).reduce((sum, outputs) => {
+                return sum + Object.values(outputs || {}).reduce((s, conns) => {
+                  return s + (Array.isArray(conns) ? conns.length : 0);
+                }, 0);
+              }, 0);
+              complexity += connectionCount * 0.5;
+            }
+
+            // Add complexity for certain node types
+            const complexNodeTypes = ['n8n-nodes-base.if', 'n8n-nodes-base.switch', 'n8n-nodes-base.function'];
+            const complexNodes = nodes.filter(n => complexNodeTypes.includes(n.type)).length;
+            complexity += complexNodes * 2;
+
+            return {
+              complexity: Math.round(complexity),
+              nodeCount: nodes.length,
+              connectionCount: Object.keys(connections || {}).length,
+              hasComplexLogic: complexNodes > 0
+            };
+          })();
+
+  api_complexity:
+    workflow_execution_state:
+      - state: waiting
+        description: "Workflow is queued for execution"
+        next_states: [running, failed]
+
+      - state: running
+        description: "Workflow is currently executing"
+        next_states: [finished, stopped, error]
+
+      - state: finished
+        description: "Workflow completed successfully"
+        terminal: true
+
+      - state: stopped
+        description: "Workflow was manually stopped"
+        terminal: true
+
+      - state: error
+        description: "Workflow encountered an error"
+        terminal: true
+        retry_allowed: true
+
+    credential_types:
+      - type: httpBasicAuth
+        fields: [username, password]
+        description: "HTTP Basic Authentication"
+
+      - type: httpHeaderAuth
+        fields: [name, value]
+        description: "HTTP Header Authentication"
+
+      - type: oAuth2Api
+        fields: [clientId, clientSecret, authUrl, accessTokenUrl]
+        description: "OAuth 2.0 Authentication"
+
+      - type: apiKey
+        fields: [apiKey]
+        description: "API Key Authentication"
+
+    node_execution_patterns:
+      - pattern: sequential
+        description: "Nodes execute in order, one after another"
+        use_case: "Simple linear workflows"
+
+      - pattern: parallel
+        description: "Multiple nodes execute simultaneously"
+        use_case: "Independent data processing"
+
+      - pattern: conditional
+        description: "Execution path depends on node conditions"
+        nodes: [n8n-nodes-base.if, n8n-nodes-base.switch]
+
+      - pattern: loop
+        description: "Repeated execution over data items"
+        nodes: [n8n-nodes-base.splitInBatches]
+
+  anti_patterns:
+    - pattern: missing_error_handling
+      description: "Not handling node execution errors"
+      category: reliability
+      severity: high
+      wrong: |
+        execute_workflow({
+          workflow_id: "123"
+          // ❌ No error handling for failed execution
+        })
+      correct: |
+        const result = execute_workflow({
+          workflow_id: "123",
+          wait_for_completion: true
+        })
+
+        if (result.status === 'error') {
+          // ✅ Handle error appropriately
+          handle_execution_error(result)
+        }
+      rationale: "Always check execution status and handle errors gracefully."
+
+    - pattern: invalid_node_connections
+      description: "Creating workflows with disconnected or invalid nodes"
+      category: workflow_structure
+      severity: medium
+      wrong: |
+        create_workflow({
+          name: "Test",
+          nodes: [{name: "Start", type: "trigger"}, {name: "End", type: "action"}],
+          connections: {
+            "NonExistent": { // ❌ Node doesn't exist
+              main: [[{node: "End"}]]
+            }
+          }
+        })
+      correct: |
+        create_workflow({
+          name: "Test",
+          nodes: [{name: "Start", type: "trigger"}, {name: "End", type: "action"}],
+          connections: {
+            "Start": { // ✅ Correct node name
+              main: [[{node: "End", type: "main", index: 0}]]
+            }
+          }
+        })
+      rationale: "Use validate-node-connections helper to verify connections before workflow creation."
+
+    - pattern: missing_credentials
+      description: "Referencing credentials that don't exist"
+      category: authentication
+      severity: high
+      wrong: |
+        create_workflow({
+          nodes: [{
+            type: "n8n-nodes-base.httpRequest",
+            credentials: {
+              httpBasicAuth: "nonexistent" // ❌ Credential not created
+            }
+          }]
+        })
+      correct: |
+        // First create credential
+        const cred = create_credential({
+          type: "httpBasicAuth",
+          name: "My API Auth",
+          data: {username: "user", password: "pass"}
+        })
+
+        // Then reference it
+        create_workflow({
+          nodes: [{
+            type: "n8n-nodes-base.httpRequest",
+            credentials: {
+              httpBasicAuth: cred.id // ✅ Valid credential reference
+            }
+          }]
+        })
+      rationale: "Always create and verify credentials before referencing them in workflows."
+
+  examples:
+    execute_workflow:
+      - scenario: success
+        description: "Execute workflow and wait for completion"
+        input:
+          workflow_id: "wf_abc123"
+          wait_for_completion: true
+          data: { key: "value" }
+        output:
+          execution_id: "exec_xyz789"
+          status: "finished"
+          data: { result: "success" }
+
+      - scenario: failure_invalid_param
+        description: "Missing required workflow_id"
+        input:
+          data: { key: "value" }
+        error:
+          code: VALIDATION_ERROR
+          message: "workflow_id is required"
+          validator: validate-execute-workflow
+
+    create_workflow:
+      - scenario: success
+        description: "Create simple workflow"
+        input:
+          name: "Data Processor"
+          nodes:
+            - type: n8n-nodes-base.start
+              name: Start
+              parameters: {}
+            - type: n8n-nodes-base.httpRequest
+              name: Fetch Data
+              parameters:
+                url: "https://api.example.com/data"
+          connections:
+            Start:
+              main: [[{node: "Fetch Data", type: "main", index: 0}]]
+        output:
+          workflow_id: "wf_new123"
+          name: "Data Processor"
+          active: false
+
+      - scenario: failure_invalid_param
+        description: "Invalid node structure"
+        input:
+          name: "Test Workflow"
+          nodes: "not an array"
+        error:
+          code: VALIDATION_ERROR
+          message: "nodes must be an array"
+          validator: validate-create-workflow
+
+  mcp_specific:
+    server_command: "npx -y @illuminaresolutions/n8n-mcp-server"
+    transport: stdio
+    environment_variables:
+      - name: N8N_HOST
+        required: true
+        description: "n8n instance URL (e.g., https://your-n8n-instance.com)"
+      - name: N8N_API_KEY
+        required: true
+        description: "n8n API key for authentication"
+    health_check:
+      method: tool_call
+      command: list_workflows
+      expected_response: "Array of workflows"
+      timeout_ms: 5000