HomeNetwork/.github/copilot-instructions.md

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.