@gmag11/nodered-mcp-server 1.0.1

package/resources/skills/nodered-subflows/SKILL.md

@@ -0,0 +1,261 @@
+---
+name: nodered-subflows
+description: >-
+  Comprehensive guide for working with Node-RED subflows via MCP tools.
+  Covers subflow vocabulary, discovery, creation from scratch, instantiation,
+  editing, export/import, deletion, common patterns, and limitations.
+tools:
+  - get-subflows
+  - get-subflow-detail
+  - create-subflow
+  - update-subflow
+  - delete-subflow
+  - create-subflow-instance
+  - export-subflow
+  - import-flow
+---
+
+# Node-RED Subflows
+
+Comprehensive guide for creating, managing, and using Node-RED subflows via MCP tools.
+
+> **⚠️ Staging reminder:** All subflow operations (create, update, delete, instantiate) stage changes locally. Call `deploy()` after making changes to push them to the Node-RED runtime. Use `get-staging-status` to check what's pending.
+
+> **Prerequisites:** Read `nodered-fundamentals` first for core vocabulary and `nodered-flow-builder` for basic flow construction patterns. See `nodered-flow-layout` for positioning rules when placing subflow instances on the canvas.
+
+---
+
+## Subflow Vocabulary
+
+A subflow is a **reusable, encapsulated flow** that can be instantiated multiple times across different flow tabs. It has three layers in the Node-RED JSON:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                    SUBFLOW MODEL                                  │
+├──────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  1. DEFINITION (type: "subflow")                                 │
+│     - id, name, info (markdown description)                      │
+│     - in  → input port definitions (where messages enter)        │
+│     - out → output port definitions (where messages exit)        │
+│     - category, color, icon → palette metadata                   │
+│                                                                  │
+│  2. INTERNAL NODES (z = subflowId)                               │
+│     - Regular nodes placed inside the subflow canvas             │
+│     - Wired together to form the internal logic                  │
+│     - Managed with the same tools as flow tab nodes              │
+│                                                                  │
+│  3. INSTANCES (type: "subflow:<subflowId>")                      │
+│     - Placed in flow tabs (z = tabId)                            │
+│     - Each has its own name, env vars, and wire connections      │
+│     - Output wires auto-size to match definition's out ports     │
+│                                                                  │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+### Key properties
+
+| Concept | Field | Example |
+|---------|-------|---------|
+| Subflow ID | `id` | `"7b6d939fa36f99ef"` |
+| Instance type | `type` | `"subflow:7b6d939fa36f99ef"` |
+| Internal parent | `z` | `z = "7b6d939fa36f99ef"` |
+| Instance location | `z` | `z = "c9a401de7611c87e"` (tab ID) |
+| Input ports | `in` | Array of `{ x, y, wires: [{ id, port }] }` |
+| Output ports | `out` | Array of `{ x, y, wires: [{ id, port }] }` |
+| Instance env vars | `env` | Array of `{ name, value, type }` |
+
+---
+
+## Workflow A — Discover Available Subflows
+
+### Step 1: List all subflows
+```
+get-subflows()
+```
+Returns enriched summary of each subflow: name, description, input/output counts, internal node types, instance count and locations.
+
+### Step 2: Inspect a subflow deeply
+```
+get-subflow-detail(subflowId: "<subflowId>")
+```
+Returns the full definition, all internal nodes (with sanitized configs), all instances and their locations, and a Mermaid diagram of the internal flow. **Always call this before instantiating or modifying a subflow** to understand what it does.
+
+---
+
+## Workflow B — Create a Subflow from Scratch
+
+Follow these steps in exact order:
+
+### Step 1: Create the subflow definition (empty container)
+```
+create-subflow(name: "My Subflow", info: "Processes incoming data and routes by type")
+```
+Save the returned `subflowId` — you'll use it as `flowId` for internal nodes.
+
+### Step 2: Populate internal nodes
+```
+create-node(type: "mqtt in", flowId: "<subflowId>", properties: { topic: "test/#", broker: "<brokerId>" }, x: 100, y: 100)
+create-node(type: "switch", flowId: "<subflowId>", properties: { property: "topic", outputs: 3 }, x: 300, y: 100)
+create-node(type: "debug", flowId: "<subflowId>", properties: { complete: "payload" }, x: 500, y: 100)
+```
+Use `<subflowId>` as `flowId` — the same `create-node` tool works for subflow internals.
+
+### Step 3: Wire internal nodes
+```
+connect-nodes(fromNodeId: "<mqttId>", outputPort: 0, toNodeId: "<switchId>")
+connect-nodes(fromNodeId: "<switchId>", outputPort: 0, toNodeId: "<debugId>")
+```
+
+### Step 4: Define input/output ports
+```
+update-subflow(subflowId: "<subflowId>", updates: {
+  out: [
+    { x: 600, y: 100, wires: [{ id: "<switchId>", port: 0 }] },
+    { x: 600, y: 180, wires: [{ id: "<switchId>", port: 1 }] },
+    { x: 600, y: 260, wires: [{ id: "<switchId>", port: 2 }] }
+  ]
+})
+```
+**Important:** Port wires must reference internal node IDs. The `x`/`y` values are the port position on the subflow's input/output bar in the UI.
+
+### Step 5: Verify
+```
+get-subflow-detail(subflowId: "<subflowId>")
+```
+Check the Mermaid diagram shows correct internal wiring.
+
+---
+
+## Workflow C — Instantiate a Subflow in a Flow Tab
+
+### Basic instantiation
+```
+create-subflow-instance(
+  subflowId: "<subflowId>",
+  flowId: "<tabId>"
+)
+```
+The tool auto-sizes output wires to match the subflow's output port count. Returns `nodeId`.
+
+### With environment variables
+```
+create-subflow-instance(
+  subflowId: "<subflowId>",
+  flowId: "<tabId>",
+  name: "Sensor Processor",
+  env: [
+    { name: "THRESHOLD", value: "42", type: "num" },
+    { name: "API_URL", value: "https://example.com", type: "str" }
+  ]
+)
+```
+Environment variables are passed to internal nodes. Inside a function node, access them with `env.get("THRESHOLD")`.
+
+### Wire the instance outputs
+```
+connect-nodes(fromNodeId: "<instanceId>", outputPort: 0, toNodeId: "<target1Id>")
+connect-nodes(fromNodeId: "<instanceId>", outputPort: 1, toNodeId: "<target2Id>")
+```
+Each output port corresponds to one entry in the subflow's `out` array (0-indexed).
+
+---
+
+## Workflow D — Editing Subflows
+
+### Editing metadata or ports
+```
+update-subflow(subflowId: "<subflowId>", updates: {
+  name: "New Name",
+  info: "Updated description",
+  out: [ ... new port definitions ... ]
+})
+```
+Only allowed fields are updated: `name`, `info`, `category`, `color`, `icon`, `in`, `out`. All other fields are preserved.
+
+### Editing internal nodes
+Use the standard tools with `flowId` set to the subflow ID:
+```
+update-node(nodeId: "<internalNodeId>", properties: { ... })
+connect-nodes(fromNodeId: "<a>", toNodeId: "<b>")
+disconnect-nodes(fromNodeId: "<a>", toNodeId: "<b>")
+create-node(type: "function", flowId: "<subflowId>", ...)
+delete-node(nodeId: "<internalNodeId>")
+```
+
+### Editing an instance
+Instances are just nodes — use standard tools:
+```
+update-node(nodeId: "<instanceId>", properties: { name: "New Name", env: [...] })
+```
+
+---
+
+## Workflow E — Exporting and Importing
+
+### Export a subflow
+```
+export-subflow(subflowId: "<subflowId>")
+```
+Returns a JSON string containing the subflow definition, all internal nodes, and any referenced config nodes (e.g., mqtt-broker). Instances are NOT included — they belong to their parent flow tabs.
+
+### Import (duplicate or restore)
+```
+import-flow(flowJson: "<exportedJson>", conflictStrategy: "regenerate")
+```
+Use `"regenerate"` to create a safe duplicate with new IDs. Use `"overwrite"` to replace an existing subflow by ID.
+
+---
+
+## Workflow F — Deleting a Subflow
+
+### Cascade delete (default, safest)
+```
+delete-subflow(subflowId: "<subflowId>")
+```
+Removes: the subflow definition + all internal nodes + all instances. The `previousState` response enables undo via `import-flow`.
+
+### Delete definition only, keep instances
+```
+delete-subflow(subflowId: "<subflowId>", deleteInstances: false)
+```
+⚠️ **Dangerous**: instances become orphan nodes of type `subflow:<deletedId>`. They will appear as "unknown" in the Node-RED UI. Only use this when migrating instances to a new subflow.
+
+### Recover from deletion
+```
+import-flow(flowJson: JSON.stringify(previousState.definition, ...previousState.internalNodes, ...previousState.instances), conflictStrategy: "regenerate")
+```
+
+---
+
+## Common Patterns
+
+### Parametrized subflow pattern
+Create a subflow with env variables for configuration:
+1. Define the subflow with a function node reading `env.get("PARAM")`
+2. Instantiate with different `env` values per instance
+3. Each instance behaves differently based on its env vars
+
+### Subflow as data pipeline
+```
+[tab: Main Flow]
+  [mqtt in] → [subflow instance: Transform] → [debug]
+                           │
+[tab: Analytics]           │
+  [http in] → [subflow instance: Transform] → [http response]
+```
+Same subflow, different contexts.
+
+### When to use subflows vs link nodes vs tabs
+- **Subflow**: Reusable logic with configurable parameters (env vars)
+- **Link nodes**: Cross-tab message passing without duplication
+- **Separate tabs**: Organizational separation, not functional reuse
+
+---
+
+## Limitations
+
+- **No nested subflows**: Node-RED's UI does not support placing a subflow instance inside another subflow. While technically possible in JSON, the UI will not render it correctly.
+- **UI refresh required**: Subflow changes made via MCP tools may not be immediately visible in the Node-RED editor. The user may need to refresh the browser.
+- **Port wiring**: Input/output port `wires` in the subflow definition must reference internal node IDs. Invalid references will cause a deploy error.
+- **Config node sharing**: Config nodes (mqtt-broker, etc.) referenced by subflow internal nodes are included in `export-subflow` but shared across instances at runtime.