@awesomate/hosting-mcp 0.12.1 → 0.13.0

package/skill/awesomate-n8n/references/vendor/node-configuration/SKILL.md

@@ -0,0 +1,583 @@
+<!--
+  VENDORED from n8n-builder@d293559 (n8n-node-configuration/SKILL.md) — DO NOT EDIT HERE.
+  Edit the source in ~/Projects/n8n-builder, then re-run:
+    node mcp/scripts/sync-n8n-references.mjs --write
+
+  Awesomate platform overrides — where this file conflicts with
+  ../platform-notes.md, platform-notes wins:
+    - $env is BLOCKED fleet-wide → use {{ $vars.key || 'fallback' }}
+    - Task runners are ON → no $helpers in Code nodes; use HTTP Request nodes
+    - Webhook payloads live at $json.body
+    - saveExecutionProgress must stay false
+-->
+
+# n8n Node Configuration
+
+Expert guidance for operation-aware node configuration with property dependencies.
+
+---
+
+## Configuration Philosophy
+
+**Progressive disclosure**: Start minimal, add complexity as needed
+
+Configuration best practices:
+- Start from the operation patterns in this skill ([OPERATION_PATTERNS.md](OPERATION_PATTERNS.md)) — they cover the most-used nodes
+- Consult n8n's official docs (docs.n8n.io) for nodes or operations not covered here
+- Always produce complete node JSON with `resource` and `operation` set together
+
+**Key insight**: Most configurations need only the required fields for the chosen operation, not every possible option!
+
+---
+
+## Core Concepts
+
+### 1. Operation-Aware Configuration
+
+**Not all fields are always required** - it depends on operation!
+
+**Example**: Slack node
+```javascript
+// For operation='post'
+{
+  "resource": "message",
+  "operation": "post",
+  "channel": "#general",  // Required for post
+  "text": "Hello!"        // Required for post
+}
+
+// For operation='update'
+{
+  "resource": "message",
+  "operation": "update",
+  "messageId": "123",     // Required for update (different!)
+  "text": "Updated!"      // Required for update
+  // channel NOT required for update
+}
+```
+
+**Key**: Resource + operation determine which fields are required — always set them together!
+
+### 2. Property Dependencies
+
+**Fields appear/disappear based on other field values**
+
+**Example**: HTTP Request node
+```javascript
+// When method='GET'
+{
+  "method": "GET",
+  "url": "https://api.example.com"
+  // sendBody not shown (GET doesn't have body)
+}
+
+// When method='POST'
+{
+  "method": "POST",
+  "url": "https://api.example.com",
+  "sendBody": true,       // Now visible!
+  "body": {               // Required when sendBody=true
+    "contentType": "json",
+    "content": {...}
+  }
+}
+```
+
+**Mechanism**: displayOptions control field visibility
+
+### 3. Finding Requirements Without Tools
+
+In the claude.ai app there is no live n8n schema access. Determine requirements by:
+
+1. **Operation patterns in this skill** - [OPERATION_PATTERNS.md](OPERATION_PATTERNS.md) covers the top 20 nodes with minimal valid configs
+2. **Official docs** - docs.n8n.io documents every node's operations and fields
+3. **The n8n editor itself** - the user opens the node in their editor; missing or invalid required fields show warnings in the parameter panel
+
+---
+
+## Configuration Workflow
+
+### Standard Process
+
+```
+1. Identify node type and operation
+   ↓
+2. Check OPERATION_PATTERNS.md / docs.n8n.io for requirements
+   ↓
+3. Write complete node JSON (resource + operation + required fields)
+   ↓
+4. User applies it in the n8n editor
+   (paste via Workflow → Import from Clipboard, or configure the parameter panel)
+   ↓
+5. User opens the node — warnings flag missing/invalid required fields
+   ↓
+6. Add optional fields as needed
+   ↓
+7. User re-checks in the editor, then executes the node to verify
+```
+
+### Example: Configuring HTTP Request
+
+**Step 1**: Identify what you need
+```javascript
+// Goal: POST JSON to API
+```
+
+**Step 2**: Check the pattern
+The POST-with-JSON pattern (see [OPERATION_PATTERNS.md](OPERATION_PATTERNS.md)) requires: method, url, sendBody, body.
+
+**Step 3**: Write the complete configuration
+```javascript
+{
+  "method": "POST",
+  "url": "https://api.example.com/create",
+  "authentication": "none",
+  "sendBody": true,                       // Required for POST with body
+  "body": {                               // Required when sendBody=true
+    "contentType": "json",
+    "content": {
+      "name": "={{$json.name}}",
+      "email": "={{$json.email}}"
+    }
+  }
+}
+```
+
+**Step 4**: Verify in the editor
+The user pastes the node into their n8n editor and opens it — a missing `sendBody` or `body` would show a warning in the parameter panel. Execute the node with test data to confirm.
+
+---
+
+## Property Dependencies Deep Dive
+
+### displayOptions Mechanism
+
+**Fields have visibility rules**:
+
+```javascript
+{
+  "name": "body",
+  "displayOptions": {
+    "show": {
+      "sendBody": [true],
+      "method": ["POST", "PUT", "PATCH"]
+    }
+  }
+}
+```
+
+**Translation**: "body" field shows when:
+- sendBody = true AND
+- method = POST, PUT, or PATCH
+
+### Common Dependency Patterns
+
+#### Pattern 1: Boolean Toggle
+
+**Example**: HTTP Request sendBody
+```javascript
+// sendBody controls body visibility
+{
+  "sendBody": true   // → body field appears
+}
+```
+
+#### Pattern 2: Operation Switch
+
+**Example**: Slack resource/operation
+```javascript
+// Different operations → different fields
+{
+  "resource": "message",
+  "operation": "post"
+  // → Shows: channel, text, attachments, etc.
+}
+
+{
+  "resource": "message",
+  "operation": "update"
+  // → Shows: messageId, text (different fields!)
+}
+```
+
+#### Pattern 3: Type Selection
+
+**Example**: IF node conditions
+```javascript
+{
+  "type": "string",
+  "operation": "contains"
+  // → Shows: value1, value2
+}
+
+{
+  "type": "boolean",
+  "operation": "equals"
+  // → Shows: value1, value2, different operators
+}
+```
+
+### Finding Property Dependencies
+
+**Use the n8n editor**: add the node, toggle the controlling field (e.g. `sendBody`, `operation`), and watch which fields appear or disappear in the parameter panel — that IS the displayOptions rule in action.
+
+**Or check docs.n8n.io**: each node's docs list fields per operation.
+
+**Use this when**: the editor warns about a missing field you don't see, or a field seems to vanish after changing another value.
+
+---
+
+## Common Node Patterns
+
+### Pattern 1: Resource/Operation Nodes
+
+**Examples**: Slack, Google Sheets, Airtable
+
+**Structure**:
+```javascript
+{
+  "resource": "<entity>",      // What type of thing
+  "operation": "<action>",     // What to do with it
+  // ... operation-specific fields
+}
+```
+
+**How to configure**:
+1. Choose resource
+2. Choose operation
+3. Check the operation's requirements (this skill's patterns or docs.n8n.io)
+4. Configure required fields — always include `resource` and `operation` together in the JSON
+
+### Pattern 2: HTTP-Based Nodes
+
+**Examples**: HTTP Request, Webhook
+
+**Structure**:
+```javascript
+{
+  "method": "<HTTP_METHOD>",
+  "url": "<endpoint>",
+  "authentication": "<type>",
+  // ... method-specific fields
+}
+```
+
+**Dependencies**:
+- POST/PUT/PATCH → sendBody available
+- sendBody=true → body required
+- authentication != "none" → credentials required
+
+### Pattern 3: Database Nodes
+
+**Examples**: Postgres, MySQL, MongoDB
+
+**Structure**:
+```javascript
+{
+  "operation": "<query|insert|update|delete>",
+  // ... operation-specific fields
+}
+```
+
+**Dependencies**:
+- operation="executeQuery" → query required
+- operation="insert" → table + values required
+- operation="update" → table + values + where required
+
+### Pattern 4: Conditional Logic Nodes
+
+**Examples**: IF, Switch, Merge
+
+**Structure**:
+```javascript
+{
+  "conditions": {
+    "<type>": [
+      {
+        "operation": "<operator>",
+        "value1": "...",
+        "value2": "..."  // Only for binary operators
+      }
+    ]
+  }
+}
+```
+
+**Dependencies**:
+- Binary operators (equals, contains, etc.) → value1 + value2
+- Unary operators (isEmpty, isNotEmpty) → value1 only + singleValue: true
+
+---
+
+## Operation-Specific Configuration
+
+### Slack Node Examples
+
+#### Post Message
+```javascript
+{
+  "resource": "message",
+  "operation": "post",
+  "channel": "#general",      // Required
+  "text": "Hello!",           // Required
+  "attachments": [],          // Optional
+  "blocks": []                // Optional
+}
+```
+
+#### Update Message
+```javascript
+{
+  "resource": "message",
+  "operation": "update",
+  "messageId": "1234567890",  // Required (different from post!)
+  "text": "Updated!",         // Required
+  "channel": "#general"       // Optional (can be inferred)
+}
+```
+
+#### Create Channel
+```javascript
+{
+  "resource": "channel",
+  "operation": "create",
+  "name": "new-channel",      // Required
+  "isPrivate": false          // Optional
+  // Note: text NOT required for this operation
+}
+```
+
+### HTTP Request Node Examples
+
+#### GET Request
+```javascript
+{
+  "method": "GET",
+  "url": "https://api.example.com/users",
+  "authentication": "predefinedCredentialType",
+  "nodeCredentialType": "httpHeaderAuth",
+  "sendQuery": true,                    // Optional
+  "queryParameters": {                  // Shows when sendQuery=true
+    "parameters": [
+      {
+        "name": "limit",
+        "value": "100"
+      }
+    ]
+  }
+}
+```
+
+#### POST with JSON
+```javascript
+{
+  "method": "POST",
+  "url": "https://api.example.com/users",
+  "authentication": "none",
+  "sendBody": true,                     // Required for POST
+  "body": {                             // Required when sendBody=true
+    "contentType": "json",
+    "content": {
+      "name": "John Doe",
+      "email": "john@example.com"
+    }
+  }
+}
+```
+
+### IF Node Examples
+
+#### String Comparison (Binary)
+```javascript
+{
+  "conditions": {
+    "string": [
+      {
+        "value1": "={{$json.status}}",
+        "operation": "equals",
+        "value2": "active"              // Binary: needs value2
+      }
+    ]
+  }
+}
+```
+
+#### Empty Check (Unary)
+```javascript
+{
+  "conditions": {
+    "string": [
+      {
+        "value1": "={{$json.email}}",
+        "operation": "isEmpty",
+        // No value2 - unary operator
+        "singleValue": true             // Required for unary operators
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Handling Conditional Requirements
+
+### Example: HTTP Request Body
+
+**Scenario**: body field required, but only sometimes
+
+**Rule**:
+```
+body is required when:
+  - sendBody = true AND
+  - method IN (POST, PUT, PATCH, DELETE)
+```
+
+**How to discover**:
+- The editor's parameter panel warns when body is enabled but empty
+- docs.n8n.io HTTP Request page documents the body options per method
+- Start from the minimal patterns in this skill and add only what the operation needs
+
+### Example: IF Node singleValue
+
+**Scenario**: singleValue property applies to unary operators
+
+**Rule**:
+```
+singleValue should be true when:
+  - operation IN (isEmpty, isNotEmpty, true, false)
+```
+
+Include `"singleValue": true` in the JSON for unary operators, and omit `value2`. (The n8n editor normalizes this structure when the node is configured through the UI.)
+
+---
+
+## Configuration Anti-Patterns
+
+### ❌ Don't: Over-configure Upfront
+
+**Bad**:
+```javascript
+// Adding every possible field
+{
+  "method": "GET",
+  "url": "...",
+  "sendQuery": false,
+  "sendHeaders": false,
+  "sendBody": false,
+  "timeout": 10000,
+  "ignoreResponseCode": false,
+  // ... 20 more optional fields
+}
+```
+
+**Good**:
+```javascript
+// Start minimal
+{
+  "method": "GET",
+  "url": "...",
+  "authentication": "none"
+}
+// Add fields only when needed
+```
+
+### ❌ Don't: Skip Editor Verification
+
+**Bad**: Hand over node JSON and call it done.
+
+**Good**: Tell the user to open the node in their n8n editor — missing or invalid required fields show warnings in the parameter panel — and execute it with test data before relying on it.
+
+### ❌ Don't: Ignore Operation Context
+
+**Bad**:
+```javascript
+// Same config for all Slack operations
+{
+  "resource": "message",
+  "operation": "post",
+  "channel": "#general",
+  "text": "..."
+}
+
+// Then switching operation without updating config
+{
+  "resource": "message",
+  "operation": "update",  // Changed
+  "channel": "#general",  // Wrong field for update!
+  "text": "..."
+}
+```
+
+**Good**: When the operation changes, re-check that operation's requirements (update needs `messageId`, not `channel`) and rewrite the config for the new context.
+
+---
+
+## Best Practices
+
+### ✅ Do
+
+1. **Start from known patterns**
+   - [OPERATION_PATTERNS.md](OPERATION_PATTERNS.md) has minimal valid configs for the top 20 nodes
+   - docs.n8n.io covers the rest
+
+2. **Always set resource + operation together**
+   - They jointly determine every other requirement
+   - Never emit one without the other
+
+3. **Verify in the n8n editor**
+   - Open the node — warnings flag missing/invalid required fields
+   - Execute with test data before relying on the configuration
+
+4. **Respect operation context**
+   - Different operations = different requirements
+   - Re-check requirements whenever the operation changes
+   - Don't assume configs are transferable
+
+5. **Iterate**
+   - Configure minimal → verify in editor → add what's flagged → repeat
+   - 2-3 iterations is normal
+
+### ❌ Don't
+
+1. **Configure blindly**
+   - Understand why fields are required
+   - Watch the parameter panel to learn what controls conditional fields
+
+2. **Copy configs without understanding**
+   - Different operations need different fields
+   - Adjust for the new context and re-verify in the editor
+
+3. **Guess field names for unfamiliar nodes**
+   - Check docs.n8n.io or have the user read the field names off their editor's parameter panel
+
+---
+
+## Detailed References
+
+For comprehensive guides on specific topics:
+
+- **[DEPENDENCIES.md](DEPENDENCIES.md)** - Deep dive into property dependencies and displayOptions
+- **[OPERATION_PATTERNS.md](OPERATION_PATTERNS.md)** - Common configuration patterns by node type
+
+---
+
+## Summary
+
+**Configuration Strategy**:
+1. Identify node type and operation
+2. Look up requirements (this skill's patterns, then docs.n8n.io)
+3. Write complete node JSON with resource + operation + required fields
+4. User applies it in their n8n editor and checks for warnings
+5. Iterate until the node executes cleanly
+
+**Key Principles**:
+- **Operation-aware**: Different operations = different requirements
+- **Progressive disclosure**: Start minimal, add as needed
+- **Dependency-aware**: Understand field visibility rules
+- **Editor-verified**: The n8n parameter panel is the ground truth
+
+**Related Skills**:
+- **n8n Validation Expert** - Interpret editor/execution errors
+- **n8n Expression Syntax** - Configure expression fields
+- **n8n Workflow Patterns** - Apply patterns with proper configuration