en.yaml

---
configuration:
  backup_hint:
    name: Backup hint
    description: Controls when backup reminders are shown before risky operations.
  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_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); 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_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.