MaddoScientisto
6cc281d372
- Introduced `scripts/mqtt_z2m_diag.py` for reusable MQTT and Zigbee2MQTT diagnostics. - Added `copilot-instructions.md` section for MQTT/Zigbee diagnostics tool usage. - Created `docs/mqtt-broker-broad-analysis.md` for comprehensive MQTT broker analysis. - Documented Salotto Overview Switch investigation in `docs/salotto-overview-switch-investigation.md`.
96 lines
4.4 KiB
Markdown
96 lines
4.4 KiB
Markdown
# Home Assistant MCP Instructions
|
|
|
|
## OPNsense MCP Availability
|
|
|
|
This workspace also provides an OPNsense MCP server for network management and diagnostics.
|
|
|
|
- Preferred access path: HTTP MCP endpoint at `http://localhost:8811/mcp`
|
|
- Backed by the Docker service under `mcp/opnsense`
|
|
- Intended use: read-only diagnostics, firewall inspection, NAT inspection, routing analysis, ARP inspection, HAProxy inspection, and other OPNsense network-management tasks
|
|
|
|
When a user asks for OPNsense firewall, routing, NAT, VLAN, ARP, HAProxy, DNS blocklist, backup, or general network-diagnostics work in this workspace, prefer the available `mcp_opnsense_*` tools before falling back to manual shell commands.
|
|
|
|
Prefer read-only OPNsense operations first unless the user explicitly asks for a change.
|
|
|
|
This workspace manages two separate Home Assistant instances through MCP servers:
|
|
|
|
- `home`: use tools with the `mcp_hass-home_*` prefix.
|
|
- `casa`: use tools with the `mcp_hass-casa_*` prefix.
|
|
|
|
## Mandatory Instance Selection Rule
|
|
|
|
If a Home Assistant request does not explicitly say `home` or `casa`, do not assume.
|
|
|
|
You must ask which instance to use with the `vscode_askQuestions` tool before taking action.
|
|
|
|
Use a short forced-choice question such as:
|
|
|
|
- Header: `Home Assistant instance`
|
|
- Question: `Which Home Assistant instance should I use for this request?`
|
|
- Options: `home`, `casa`
|
|
- `allowFreeformInput: false`
|
|
|
|
This rule applies to all Home Assistant tasks, including diagnostics, state queries, automations, helpers, dashboards, scripts, devices, entities, areas, add-ons, and service calls.
|
|
|
|
## How To Distinguish The Instances
|
|
|
|
Primary distinction:
|
|
|
|
- `home` always maps to `mcp_hass-home_*` tools.
|
|
- `casa` always maps to `mcp_hass-casa_*` tools.
|
|
|
|
Operational fingerprints from diagnostics:
|
|
|
|
- `home`
|
|
- MCP prefix: `mcp_hass-home_*`
|
|
- Home Assistant location name: `Casa 24`
|
|
- Base URL: `https://home.maddo.science`
|
|
- Installation type: `Home Assistant Container`
|
|
- Host architecture: `amd64`
|
|
- Approximate size seen in diagnostics: 1391 entities, 17 areas
|
|
|
|
- `casa`
|
|
- MCP prefix: `mcp_hass-casa_*`
|
|
- Home Assistant location name: `Home`
|
|
- Base URL seen from HA: `http://supervisor/core`
|
|
- Host IP from health data: `192.168.100.69`
|
|
- Installation type: `Home Assistant OS`
|
|
- Host architecture: `aarch64` on `rpi5-64`
|
|
- Approximate size seen in diagnostics: 1414 entities, 11 areas
|
|
|
|
Do not infer the target instance from entity names, room names, or natural language alone. Only use the instance the user explicitly names, or the instance selected through `vscode_askQuestions`.
|
|
|
|
## Diagnostic Baseline
|
|
|
|
The following read-only checks were run successfully against both instances:
|
|
|
|
- `ha_check_config()`: valid on both `home` and `casa`
|
|
- `ha_get_overview(detail_level="minimal")`: successful on both
|
|
- `ha_get_system_health()`: successful on both
|
|
|
|
## Local MQTT Diagnostics File
|
|
|
|
For broker-level MQTT investigations in this workspace, first check for a local untracked file at `.local/mqtt-home.env`.
|
|
|
|
- This file is intended to stay out of git and may be missing on a fresh clone or a new PC.
|
|
- If the file is missing, incomplete, or clearly stale for the requested task, prompt the user to update it before attempting deeper MQTT diagnostics.
|
|
- Treat the file as local machine state, not repository configuration.
|
|
|
|
## Repository MQTT/Zigbee Diagnostics Tool
|
|
|
|
For broker-level MQTT and Zigbee2MQTT diagnostics in this repository, prefer the reusable script at `scripts\mqtt_z2m_diag.py` over one-off session scripts.
|
|
|
|
- Use the script for retained state checks, `get` requests, `device/configure` probes, permit-join flows, pair watches, raw topic watches, and side-by-side device comparisons.
|
|
- Prefer read-only script commands first unless the investigation explicitly needs a write-like action such as `configure`, `permit-join`, or raw publish.
|
|
- Keep `scripts\mqtt_z2m_diag.py` updated as new recurring diagnostics needs appear in this workspace.
|
|
- Keep the skill at `.github\skills\mqtt-z2m-diagnostics\SKILL.md` aligned with the script as it evolves.
|
|
|
|
## Usage Examples
|
|
|
|
- If the user says `turn on the kitchen light`, ask which instance.
|
|
- If the user says `check automations on casa`, use `mcp_hass-casa_*` tools directly.
|
|
- If the user says `what is the state of the alarm in home`, use `mcp_hass-home_*` tools directly.
|
|
|
|
## Safety Rule
|
|
|
|
Before any write action on Home Assistant, confirm you are operating on the intended instance. If the request is ambiguous, stop and ask.
|