How I built a self-maintaining Homey documentation system with Claude

Tutorials
4

Happy to share. I actually already put my MCP server I a public GitHub repo as it was the easiest way for me to deploy easily to multiple machines and keep them up to date with the latest version. So that’s at GitHub - jmdraper/homey-mcp · GitHub

I don’t want to share my actual docs but I had Claude create an example template based on my current docs - attached.

I haven’t got round to putting the Homey app in a repo yet but will do when I get a moment. Or you can ask Claude to create one to interact with this MCP!

---
flow_ids:
  - 00000000-0000-0000-0000-000000000001
  - 00000000-0000-0000-0000-000000000002
flow_snapshot:
  00000000-0000-0000-0000-000000000001:
    name: "Example flow A"
    enabled: true
    broken: false
    cards: 12
    hash: a1b2c3d4e5f67890
  00000000-0000-0000-0000-000000000002:
    name: "Example flow B"
    enabled: true
    broken: false
    cards: 8
    hash: 0987654321abcdef
last_synced: "2026-05-27T10:00:00Z"
---
# Homey [area] — [topic]
[[Homey Documentation]]

One-sentence description of what this area of automation does and why it exists.

See also: [[Related note A]] (brief description), [[Related note B]] (brief description).

## Contents
- System overview
- Flow: Example flow A
- Flow: Example flow B
- Dependencies
  - Homey apps
  - Homey variables
  - Physical and virtual devices
  - Inter-flow dependencies
  - External dependencies

## System overview
Brief description of the physical setup and how the components fit together: hardware devices, cloud services, key variables or modes the whole system pivots on.

Include a summary table if there are structured concepts (e.g. operating modes, tariff windows, thresholds).

| Mode / state | Description |
|---|---|
| Example mode | What it means and which flows it gates |

## Flow: Example flow A
**Purpose:** One sentence on what this flow does and why it exists.

**Trigger — [trigger description]:** Describe what causes the flow to fire.

**Condition — [condition label]:** Describe the branch condition and what each path does.

**Action — [outcome]:** Describe what the flow does in the happy path.

**Watchdog / edge case:** If the flow has suppression timers, retry logic, or override paths, describe them here. These are often the most important parts to document.

**State written:** List any variables this flow sets that other flows depend on.

## Flow: Example flow B
**Purpose:** One sentence on what this flow does and why it exists.

**Trigger — [trigger description]:** Describe what causes the flow to fire.

**Action — [outcome]:** Describe what the flow does.

## Dependencies

### Homey apps
| App | Version | Used for |
|---|---|---|
| App Name | 1.2.3 | Brief description of which actions/triggers it provides |

### Homey variables
| Variable | Type | Used by | Purpose |
|---|---|---|---|
| variable_name | boolean | Flow A, Flow B | What it represents and why it matters. Flag if written by one flow and read by another — these are the highest-risk dependencies. |

### Physical and virtual devices
| Device | ID | Role |
|---|---|---|
| Device Name | 71e66f94 | Trigger: Motion alarm. Control target: On/off |

### Inter-flow dependencies
| Flow | Depends on |
|---|---|
| Example flow A | Reads `variable_name` set by [[Homey other note]] — must run after that flow has written a value |

### External dependencies
| Dependency | Risk if unavailable or changed |
|---|---|
| Cloud service / API name | Describe what breaks if it's down or its configuration changes |