en.yaml

---
configuration:
  backup_hint:
    name: Full-HA snapshot suggestion level (LLM-facing)
    description: |-
      Tunes the wording of the hint the LLM sees in the
      `ha_manage_backup(scope='snapshot')` tool description for when to
      suggest a full Home Assistant tarball backup before risky operations
      (e.g. mass device deletes). Affects ONLY this one LLM-facing prompt
      sentence.

      For per-edit automatic snapshots of automations / scripts / helpers /
      etc., use the separate **Enable auto-backup of edits** toggle below.
  secret_path:
    name: Secret path override
    description: |
      Optional custom HTTP path for the MCP server. Leave empty to use the auto-generated secure path.
  enable_tool_search:
    name: Enable tool search
    description: >-
      Replace the full tool catalog with search-based discovery. Reduces
      idle context from ~46K to ~5K tokens. ⚠️ Do NOT enable this if you
      use Claude in Sonnet or Opus modes — those models have their own
      built-in tool search / deferred tools, which conflicts with ours.
      To use ha-mcp's tool search with Claude, disable Claude's built-in
      tool search first; otherwise leave this off. Use this only with
      LLMs that lack native deferred tools (e.g. Claude Haiku, local
      OpenAI-compatible models) or with smaller context windows. Tools
      are found via ha_search_tools and executed via categorized proxies
      (read/write/delete). Requires restart to take effect.
  enable_tool_security_policies:
    name: Enable Tool Security Policies (advanced)
    description: >-
      Gate high-stakes tool calls (lock/alarm control, automation writes,
      etc.) behind user approval. When a guarded tool is called, the agent
      tells the user to open the Tool Security Policies tab in the web UI
      and click Approve before the call proceeds. Per-tool rules with
      optional argument conditions are configured in the Tool Security
      Policies tab. Off by default. Requires restart to take effect.
  enable_yaml_config_editing:
    name: Enable YAML config editing (beta)
    description: >-
      Beta feature — disabled by default. Allows AI assistants to add,
      replace, or remove top-level keys in configuration.yaml and
      packages/*.yaml. Only whitelisted keys are allowed (e.g., template,
      sensor, command_line, mqtt, knx); core keys like homeassistant, http,
      and recorder are blocked. Each edit validates YAML syntax, runs a
      config check, and creates an automatic backup. Changes to most keys
      require a full HA restart to take effect. See docs/beta.md for known
      limitations. Dedicated tools (automations, scripts, scenes, helpers,
      template sensors) should be preferred when available.
  enable_code_mode:
    name: Enable custom tool sandbox (beta)
    description: >-
      Beta feature — disabled by default. Enables the ha_manage_custom_tool
      tool, which lets AI assistants create, run, save, and delete custom
      Python code in a secure sandbox when no built-in tool can handle the
      request. Code runs in an isolated interpreter with no filesystem or
      arbitrary network access. Sandbox code can hit the HA REST API
      (api_get/api_post), send WebSocket commands (ws_send), call existing
      MCP tools (call_tool), or remove a saved tool (delete_saved_tool).
      Saved tools persist to /data/saved_tools.json by default so they
      survive add-on restarts. See docs/beta.md for known limitations.
      Requires restart to take effect.
  enable_auto_backup:
    name: Enable auto-backup of edits
    description: >-
      Captures a per-entity snapshot before every wrapped write/destructive
      MCP tool call (automation, script, scene, helper, dashboard, label,
      category, group, zone, area, calendar, todo, entity, integration, and
      sibling remove/delete tools). Snapshots are saved as YAML files under
      /data/ha_mcp_backups/ (override via HAMCP_BACKUP_DIR) and listed,
      restored, or deleted via the Backups tab in the web settings UI or
      via ha_manage_backup(scope='edits', ...). Best-effort — failures log
      a WARNING but never block the underlying write. On by default;
      uncheck to opt out. Requires restart to take effect.
  auto_backup_throttle_minutes:
    name: Auto-backup throttle (minutes)
    description: >-
      Per-entity throttle window. 0 (default) captures a snapshot on every
      wrapped write. N>0 captures at most one snapshot per N minutes per
      entity. Range 0–1440.
  auto_backup_retain_per_entity:
    name: Auto-backup retention (per entity)
    description: >-
      Maximum number of snapshots kept per entity. Older snapshots beyond
      this cap are rotated out on each successful capture. Default 100,
      range 1–10000.
  enable_lite_docstrings:
    name: Enable lite tool docstrings (beta)
    description: >-
      Beta feature — disabled by default. Replaces the docstrings on a
      handful of heavy ha-mcp tools (automations, scripts, scenes, helpers,
      dashboards, ha_call_service, ha_config_set_yaml) with shorter
      variants that defer schema and example detail to the
      ha_get_skill_guide tool (or its skill://
      resource). WARNING: this reduces idle token usage, but may degrade
      LLM performance — the trimmed descriptions rely on the LLM
      actually calling the skill tool or reading the skill resource for
      detail, which is not guaranteed (some models will skip the extra
      tool call and end up with less guidance than they had before).
      Best paired with a client that supports MCP resources or with
      enable_tool_search. Requires restart to take effect.
  enable_filesystem_tools:
    name: Enable filesystem tools (beta)
    description: >-
      Sets HAMCP_ENABLE_FILESYSTEM_TOOLS=true. Enables direct file read/write
      access to your Home Assistant filesystem. WARNING: This gives the MCP
      server sensitive direct file access to your system. Only enable if you
      trust the AI assistant with file operations. Requires restart to take
      effect.
  enable_custom_component_integration:
    name: Enable custom component integration (beta)
    description: >-
      Sets HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION=true. Enables the
      ha_install_mcp_tools installer tool, which can help install the
      ha_mcp_tools custom component. This setting does not control whether the
      MCP server loads or interacts with the custom component, and it is not
      required for filesystem tools to function. Only enable if you want to
      allow the AI assistant to use the installer tool. Requires restart to
      take effect.
  tool_search_max_results:
    name: Tool search max results
    description: >-
      Maximum number of tools returned by ha_search_tools when tool
      search is enabled. Lower values (2-3) save context tokens but
      may miss relevant tools. Range: 2-10. Requires restart.
  disabled_tools:
    name: Disabled tools (text fallback)
    description: >-
      Comma-separated tool names to disable. For a visual interface,
      click "Open Web UI" on the addon info page. This field seeds the initial config
      when the web UI hasn't been used yet. Requires restart.
  pinned_tools:
    name: Pinned tools (text fallback)
    description: >-
      Comma-separated tool names to pin (always visible in tool search).
      For a visual interface, click "Open Web UI" on the addon info page. This field
      seeds the initial config when the web UI hasn't been used yet.
      Requires restart.
  verify_ssl:
    name: Verify TLS certificate
    description: >-
      Verify the Home Assistant server's TLS certificate. The add-on
      connects via the Supervisor proxy, so this normally has no effect
      and should stay enabled. Disable only if you've reconfigured the
      add-on to talk to HA over a public HTTPS hostname with a self-signed
      certificate or hostname mismatch. Disabling weakens transport
      security — leave on unless you know you need it. Requires restart
      to take effect.
  advanced_debug_logging:
    name: Advanced debug logging
    description: >-
      Captures extra diagnostic info on kill/shutdown — sender PID
      and memory state. Useful when reporting unexplained add-on
      stops or crash loops. Off by default to keep logs concise.
      Requires restart to take effect.