[FEATURE] Extend ha_call_addon_api to support Supervisor config management (rename to ha_manage_addon)

[kingpanther13]

What would you like to see?

Extend ha_call_addon_api to also support writing addon configuration via the Supervisor API, and rename it to ha_manage_addon to reflect its broader scope.

Currently ha_call_addon_api proxies HTTP/WebSocket calls to the addon container's own web API. Addon configuration (options, network, boot mode, etc.) lives in the Supervisor API (POST /addons/{slug}/options), which no existing tool can reach — ha_call_service only exposes hassio.addon_start/stop/restart/stdin, and ha_get_addon is read-only.

Proposed changes:

1. Rename ha_call_addon_api → ha_manage_addon
2. Make path optional (currently required) to support a second mode
3. Add high-level Supervisor config params:
   • options: dict | None — addon configuration values (the Configuration tab)
   • network: dict | None — host port mappings (e.g., {"5800/tcp": 8081})
   • boot: str | None — "auto" or "manual"
   • auto_update: bool | None
   • watchdog: bool | None
4. Two operating modes:
   • Proxy mode (existing behavior): when path is provided → calls addon container API via HTTP/WebSocket, unchanged
   • Config mode (new): when any of options/network/boot/auto_update/watchdog is provided → POSTs to Supervisor API via _supervisor_api_call() (which already supports POST)
5. Validation: path and config params are mutually exclusive — error if both provided

Why do you need this?

Real use case from #912: user wants to switch kiosk addons, which requires configuring the new addon's options (FF_OPEN_URL, FF_KIOSK), setting its host port, and disabling old addon auto-start. Steps 2-4 all require manual UI interaction today because no tool reaches the Supervisor config API.

Hassio services only cover start/stop/restart — confirmed via ha_list_services(domain="hassio").

Additional context

• Replaces [FEATURE] Add ha_set_addon tool for managing addon options, network, and boot config #912 (which proposed a separate ha_set_addon tool)
• _supervisor_api_call() in tools_addons.py already accepts method and data params — the write infrastructure exists
• Supervisor API endpoint: POST /addons/{slug}/options with fields options, network, boot, auto_update, watchdog
• Validation endpoint also exists: POST /addons/{slug}/options/validate
• Follows the project's tool consolidation direction (ref: PR refactor: consolidate 3 overlapping tool pairs  #873)

[github-actions]

❌ Analysis failed

An error occurred:

YOLO mode is enabled. All tool calls will be automatically approved.
YOLO mode is enabled. All tool calls will be automatically approved.
[STARTUP] Phase 'cleanup_ops' was started but never ended. Skipping metrics.
[STARTUP] Cannot measure phase 'cleanup_ops': start mark 'startup:cleanup_ops:start' not found (likely cleared by reset).
{
  "session_id": "8fd1230a-0232-4d91-b904-969de94f0bbf",
  "error": {
    "type": "FatalTurnLimitedError",
    "message": "Reached max session turns for this session. Increase the number of turns by specifying maxSessionTurns in settings.json.",
    "code": 53
  }
}[ERROR] {
  "session_id": "8fd1230a-0232-4d91-b904-969de94f0bbf",
  "error": {
    "type": "FatalTurnLimitedError",
    "message": "Reached max session turns for this session. Increase the number of turns by specifying maxSessionTurns in settings.json.",
    "code": 53
  }
}

Please check the workflow logs.

[kingpanther13]

I'm willing to consider just changing to ha_call_addons or something like that to stick to the current naming convention. "Manage" makes more sense imo but I'm willing to do anything with it.... Just leaving it how it is won't make it very apparent as to what it can do if we add functionality.

[github-actions]

🔍 Analysis

The request to extend ha_call_addon_api to support Supervisor configuration management is well-justified. Currently, ha-mcp allows users to get information about add-ons (ha_get_addon) and call their internal APIs, but it lacks a way to programmatically update add-on settings like configuration options, network ports, or boot strategies. These operations are handled by the Home Assistant Supervisor API, which is already partially wrapped by the internal _supervisor_api_call function in tools_addons.py.

Consolidating these features into a single tool renamed to ha_manage_addon aligns with the project's goal of having intuitive, high-level tools. The proposed design cleanly separates "Proxy mode" (calling the add-on's own API) from "Config mode" (updating Supervisor settings) using mutually exclusive parameters.

This feature is particularly useful for automation scenarios where an AI needs to reconfigure a service (e.g., changing a kiosk URL or port mapping) without requiring the user to manually use the Home Assistant UI.

🛠️ Suggested Steps

1. Rename the tool: Update the @mcp.tool definition in src/ha_mcp/tools/tools_addons.py from ha_call_addon_api to ha_manage_addon.
2. Expand parameters: Add optional parameters for options, network, boot, auto_update, and watchdog to the tool's signature.
3. Implement logic switch:
   • If path is provided, execute the existing HTTP/WebSocket proxy logic.
   • If configuration parameters are provided, use _supervisor_api_call to POST /addons/{slug}/options.
   • Validate that users do not provide both a path and configuration parameters simultaneously.
4. Update Documentation: Update README.md, homeassistant-addon/DOCS.md, and any static site data (like site/src/data/tools.json) to reflect the new tool name and capabilities.
5. Update Tests: Modify tests/src/unit/test_tools_addons.py to cover both modes of the new ha_manage_addon tool.

📊 Technical Analysis (for maintainers)

Root Cause

The current implementation of ha_call_addon_api is strictly a proxy for the add-on's internal web server. It does not interface with the Supervisor's management endpoints, leaving a gap in functionality for changing add-on settings which are stored in the Supervisor's own state.

Affected Code

• src/ha_mcp/tools/tools_addons.py - Contains the tool definition and the _supervisor_api_call helper.
• tests/src/unit/test_tools_addons.py - Unit tests for add-on tools.

Proposed Fix

--- a/src/ha_mcp/tools/tools_addons.py
+++ b/src/ha_mcp/tools/tools_addons.py
@@ -805,27 +805,33 @@
         tags={"Add-ons"},
         annotations={
             "destructiveHint": True,
             "idempotentHint": False,
             "readOnlyHint": False,
-            "title": "Call Add-on API",
+            "title": "Manage Add-on",
         },
     )
     @log_tool_usage
-    async def ha_call_addon_api(
+    async def ha_manage_addon(
         slug: Annotated[
             str,
             Field(
                 description="Add-on slug (e.g., 'a0d7b954_nodered', 'ccab4aaf_frigate'). "
                 "Use ha_get_addon() to find installed add-on slugs.",
             ),
         ],
         path: Annotated[
-            str,
-            Field(
-                description="API path relative to the add-on root (e.g., '/flows', '/api/events', '/api/stats').",
+            str | None,
+            Field(
+                description="Proxy mode: API path relative to the add-on root (e.g., '/flows', '/api/events'). "
+                "Required for calling add-on internal APIs.",
+                default=None,
             ),
-        ],
+        ] = None,
         method: Annotated[
             str,
             Field(
@@ -877,19 +883,86 @@
                 "False: return after first response batch (for quick commands). Default: true.",
                 default=True,
             ),
         ] = True,
+        options: Annotated[
+            dict[str, Any] | None,
+            Field(description="Config mode: Add-on configuration options (values in the 'Configuration' tab).", default=None),
+        ] = None,
+        network: Annotated[
+            dict[str, Any] | None,
+            Field(description="Config mode: Network port mappings (e.g., {'5800/tcp': 8081}).", default=None),
+        ] = None,
+        boot: Annotated[
+            str | None,
+            Field(description="Config mode: Boot strategy ('auto' or 'manual').", default=None),
+        ] = None,
+        auto_update: Annotated[
+            bool | None,
+            Field(description="Config mode: Enable or disable auto-updates.", default=None),
+        ] = None,
+        watchdog: Annotated[
+            bool | None,
+            Field(description="Config mode: Enable or disable Supervisor watchdog.", default=None),
+        ] = None,
     ) -> dict[str, Any]:
-        """Call an add-on's HTTP or WebSocket API.
+        """Manage a Home Assistant add-on - update configuration or call its internal API.
 
-        Sends requests directly to add-on containers. Use `websocket=true` for
-        streaming endpoints (e.g., ESPHome compile/validate). Use `port` to bypass
-        Nginx IP restrictions on community add-ons. Use ha_get_addon(slug="...")
-        to discover available ports and endpoints.
+        This tool has two operating modes:
+        1. **Config mode** (Update settings): Provide any of the configuration parameters 
+           (options, network, boot, auto_update, watchdog). This updates the add-on's 
+           Supervisor configuration.
+        2. **Proxy mode** (Call API): Provide a `path`. This sends a request directly to 
+           the add-on's internal container API (via HTTP or WebSocket).
 
         **Examples:**
-        - HTTP: ha_call_addon_api(slug="...", path="/api/events")
-        - Direct port: ha_call_addon_api(slug="...", path="/flows", port=1880)
-        - WebSocket: ha_call_addon_api(slug="...", path="/validate", port=6052, websocket=true, body={"type": "spawn", "configuration": "device.yaml"})
+        - Update options: ha_manage_addon(slug="...", options={"FF_KIOSK": True})
+        - Change boot mode: ha_manage_addon(slug="...", boot="manual")
+        - Call HTTP API: ha_manage_addon(slug="...", path="/api/events")
+        - Call WebSocket: ha_manage_addon(slug="...", path="/validate", websocket=True)
         """
+        config_data = {
+            k: v for k, v in {
+                "options": options,
+                "network": network,
+                "boot": boot,
+                "auto_update": auto_update,
+                "watchdog": watchdog,
+            }.items() if v is not None
+        }
+
+        if path and config_data:
+            raise_tool_error(create_validation_error(
+                "Cannot provide both 'path' and configuration parameters.",
+                details="Use 'path' for API proxying or configuration params for Supervisor management."
+            ))
+        
+        if not path and not config_data:
+            raise_tool_error(create_validation_error(
+                "Must provide either 'path' (for API proxy) or at least one configuration parameter.",
+                details="Config params: options, network, boot, auto_update, watchdog."
+            ))
+
+        # Config Mode: Update Supervisor settings
+        if config_data:
+            result = await _supervisor_api_call(
+                client,
+                f"/addons/{slug}/options",
+                method="POST",
+                data=config_data
+            )
+            if not result.get("success"):
+                raise_tool_error(result)
+            
+            return {
+                "success": True,
+                "message": f"Successfully updated configuration for add-on '{slug}'",
+                "applied_changes": list(config_data.keys()),
+                "note": "A restart of the add-on may be required for some changes to take effect."
+            }
+
+        # Proxy Mode: Call add-on API
         # WebSocket mode
         if websocket:

Related Issues/PRs

• [FEATURE] Add ha_set_addon tool for managing addon options, network, and boot config #912 - Proposed a separate ha_set_addon tool (closed in favor of this consolidation).
• PR refactor: consolidate 3 overlapping tool pairs  #873 - Referenced as the direction for tool consolidation.

---

🤖 Automated analysis by Issue Bot

[Patch76]

I've been looking at this as part of a broader consolidation analysis and wanted to share a design thought before anyone dives into implementation.

The rename to ha_manage_addon makes intuitive sense, but it would break the established naming convention — AGENTS.md lists the approved verb set as get / list / search / set / delete / remove / call, and manage isn't in it. That's probably worth a conscious decision either way.

One alternative that sidesteps the naming question entirely: extend ha_call_addon_api in place rather than renaming it. Make path optional instead of required, and add the Supervisor config params (options, network, boot, auto_update, watchdog) as additional optional parameters with mutual exclusivity enforcement. Existing calls that pass path keep working unchanged — it's purely additive.

That way the tool count stays flat (still one tool), the naming stays consistent, and the new capability lands without a rename that would break any existing integrations using the current tool name.

If there's a preference for ha_call_addons or another verb-compliant name as @kingpanther13 suggested, that works too. Just flagging the convention point in case it's useful for the design discussion.

[kingpanther13]

See #919, will propose adding manage as an approved verb along with the PR for this one of it makes sense. We can always change approved names, and we don't have to stick directly to those rules either way, as evidenced by the 30+ tools we have that don't follow the naming convention. Exceptions can always be made.

[kingpanther13]

Also I don't think there's a such thing as an integration that can break if a tool name changes. Tool name changes are explicitly noted as non breaking. No integrations that I'm aware of call our tools directly, they're only used in LLMs. The only breakage that occurs is if the llm is stuck with the old list of tools and you forgot to refresh the connection. Easy fix.

[Patch76]

Good points, thanks for the context. The manage verb makes sense for multi-modal tools like this, and #919 is a clean way to formalize the pattern. And fair enough on the breaking change definition — I was thinking too much in REST API terms.

ha_manage_addon it is. Ready to put up a PR when you’d like to move forward.

[Patch76]

PR up: #978

Implemented as proposed. A few design notes from verifying the Supervisor source (supervisor/api/addons.py):

• All five config fields (options, network, boot, auto_update, watchdog) are accepted by a single POST /addons/{slug}/options call — no separate endpoints needed.
• Partial updates work natively: the Supervisor only applies fields that are present in the payload.
• boot changes will fail with an error for add-ons where boot_config=MANUAL_ONLY — documented in the WARNING block.
• Added manage as an approved verb to AGENTS.md and .gemini/styleguide.md as discussed.