feat(site): add Hermes Agent support to setup wizard (#2208)

* feat(site): add Hermes Agent support to setup wizard

Hermes reads its MCP servers from ~/.hermes/config.yaml under an
`mcp_servers` mapping keyed by server name. That is incompatible with the
`mcpServers:` list Continue expects, and Continue was the only other client
with `configFormat: "yaml"`, so the wizard's YAML arm had no id guard at all
— a metadata-only entry would have handed Hermes users a well-formed config
their client ignores.

Adds the client entry, a Hermes branch covering stdio (uvx and Docker) and
Streamable HTTP with an authenticated-headers variant, and the brand icon for
the picker tile. The new test pins each YAML client to its own root key: the
existing per-client test only asserts that a branch emitted something, so it
stays green when a client falls through to the other schema.

* docs(internal): refresh the setup-wizard data map in site/AGENTS.md

The array list still described the pre-rework model: it named
`connectionsData` and `deploymentData`, neither of which exists in the
frontmatter anymore, and omitted `scopeData` plus the two client-capability
lists that replaced them. The client count was already one behind before this
branch added Hermes.

Also records that a `configFormat` shared by clients with incompatible
schemas needs its own id guard, which is the step this file's checklist did
not cover.

* fix(site): stop offering SSE in the Hermes instructions

Hermes can switch a server to SSE, but the ha-mcp endpoint cannot receive
it: the HTTP run path pins `mcp.run(transport="http")`, so the MCP path is
POST-only Streamable HTTP and answers the GET an SSE-style pre-flight sends
with 405 (documented on `ProbeAccessLogFilter` in `src/ha_mcp/__main__.py`).
The instructions now say to leave the transport alone and name that limit.

The claim about the client was verified, the one about our own server was
not — so the guard added here asserts the rendered Hermes instructions never
offer `transport: sse`, with a plausibility floor so an empty capture cannot
satisfy the absence check.

Author: Patch76

site/AGENTS.md

@@ -13,25 +13,26 @@ npm run preview  # Preview production build locally
 
 ## Setup Wizard (`site/src/pages/setup.astro`)
 
-Single-file Astro page that drives the on-site setup flow. Both the metadata (which clients/platforms/connections/deployments exist) and the per-client instruction prose live in this one file.
+Single-file Astro page that drives the on-site setup flow. Both the metadata (which clients/platforms/scopes exist) and the per-client instruction prose live in this one file.
 
-**Data** — four pre-sorted JS arrays at the top of the component frontmatter:
+**Data** — three pre-sorted JS arrays at the top of the component frontmatter, plus two client-capability lists:
 
 ```ts
-const clientsData = [...]    // 19 supported AI clients
-const platformsData = [...]  // macOS / Linux / Windows / Docker
-const connectionsData = [...]// local / network / remote
-const deploymentData = [...] // uvx / docker / ha-addon / cloudflared / webhook-proxy
+const clientsData = [...]     // 21 supported AI clients
+const platformsData = [...]   // macOS / Linux / Windows / Docker
+const scopeData = [...]       // local / remote
+const stdioOnlyClients = [..] // need the fastmcp-remote bridge for HTTP
+const remoteOnlyClients = [..]// cannot use a local endpoint, need public HTTPS
 ```
 
-These feed the picker tiles in the markup section AND the wizard `<script>` block (`state.client`, `state.connection`, etc.).
+These feed the picker tiles in the markup section AND the wizard `<script>` block (`state.client`, `state.scope`, etc.).
 
-**Instruction templates** are JS template literals inside the `<script>` block, keyed off `state.client.id` / `platformId` / `state.connection.id` / `state.proxy`. Cross-cutting troubleshooting and restart-related help lives in `site/src/pages/faq.astro`; OS-specific install walkthroughs live in `guide-macos.astro` / `guide-windows.astro`.
+**Instruction templates** are JS template literals inside the `<script>` block, keyed off `state.client.id` / `state.client.configFormat` / `platformId` / `state.method` / `state.remotePath`. Cross-cutting troubleshooting and restart-related help lives in `site/src/pages/faq.astro`; OS-specific install walkthroughs live in `guide-macos.astro` / `guide-windows.astro`.
 
-**Adding a new client / platform / connection / deployment:**
+**Adding a new client / platform / scope / server method / remote path:**
 
 1. Add an entry to the appropriate inline array (insert at the right `order` position). Keep each array ordered by the `order` field — the wizard renders entries in array order without re-sorting.
-2. Add a wizard branch in the `<script>` block keyed off the new entry's `id`. Match neighboring patterns: JSON clients add an `else if` in the JSON config builder; CLI clients add a CLI command emit; UI clients add an `instruction-block` div with click steps. See `cursor` / `chatgpt` / `claude-code` / `cloudflared` for examples.
+2. Add a wizard branch in the `<script>` block keyed off the new entry's `id`. Match neighboring patterns: JSON clients add an `else if` in the JSON config builder; CLI clients add a CLI command emit; UI clients add an `instruction-block` div with click steps. A `configFormat` shared by clients with incompatible schemas needs an `id` guard of its own — see the `hermes` branch, which would otherwise inherit Continue's YAML shape. See `cursor` / `chatgpt` / `claude-code` / `cloudflared` for examples.
 3. If the addition has cross-cutting troubleshooting content (PATH issues, restart requirements, version requirements), add it to `faq.astro`.
 
 ## Accessibility & checks

site/public/logos/hermes.png

@@ -243,6 +243,18 @@ const clientsData = [
     "httpNote": "Requires HTTPS - Remote deployment required",
     "clientNote": "Custom connected apps are OAuth-only. Only the HA-MCP Server component's legacy OAuth mode currently works with Spark — see the steps below.",
   },
+  {
+    "id": "hermes",
+    "name": "Hermes Agent",
+    "company": "Nous Research",
+    "logo": "/logos/hermes.png",
+    "transports": ["stdio", "sse", "streamable-http"],
+    "configFormat": "yaml",
+    "configLocation": "~/.hermes/config.yaml",
+    "accuracy": 4,
+    "order": 21,
+    "clientNote": "Run /reload-mcp in an active session after editing the config — Hermes picks up MCP changes without a restart.",
+  },
 ].map(c => ({ ...c, logo: withBase(c.logo) }));
 
 const platformsData: { id: string; name: string; icon: IconName; order: number }[] = [
@@ -2260,6 +2272,64 @@ ingress:
         </div>`);
       }
 
+    } else if (state.client.configFormat === 'yaml' && state.client.id === 'hermes') {
+      // Hermes keeps its servers in ~/.hermes/config.yaml under `mcp_servers`,
+      // a mapping keyed by server name — not Continue's list of
+      // {name, type, url} entries, so it needs its own YAML shape here.
+      if (isStdio) {
+        if (isDocker) {
+          config = `mcp_servers:
+  home-assistant:
+    command: "docker"
+    args:
+      - "run"
+      - "--rm"
+      - "-i"
+      - "-v"
+      - "ha-mcp-data:/home/mcpuser/.ha-mcp"
+      - "-e"
+      - "HOMEASSISTANT_URL={{HOMEASSISTANT_URL}}"
+      - "-e"
+      - "HOMEASSISTANT_TOKEN={{HOMEASSISTANT_TOKEN}}"
+      - "ghcr.io/homeassistant-ai/ha-mcp:latest"`;
+        } else {
+          config = `mcp_servers:
+  home-assistant:
+    command: "uvx"
+    args:
+      - "ha-mcp@latest"
+    env:
+      HOMEASSISTANT_URL: "{{HOMEASSISTANT_URL}}"
+      HOMEASSISTANT_TOKEN: "{{HOMEASSISTANT_TOKEN}}"`;
+        }
+      } else {
+        config = `mcp_servers:
+  home-assistant:
+    url: "${mcpUrl}"`;
+      }
+      if (!isStdio) {
+        instructions.push(`<div class="instruction-block">
+          <h3 class="instruction-title">Alternative: With Authentication Headers</h3>
+          <div class="text-sm text-slate-300 space-y-2">
+            <p class="text-slate-400">If your endpoint is behind a Bearer token, add a <code class="bg-slate-800 px-1 rounded">headers</code> block. Replace the config above with:</p>
+            <pre class="bg-slate-800 rounded p-2 text-xs overflow-x-auto">mcp_servers:
+  home-assistant:
+    url: "${mcpUrl}"
+    headers:
+      Authorization: "Bearer \${env:HA_TOKEN}"</pre>
+            <p class="text-slate-400">Hermes resolves <code class="bg-slate-800 px-1 rounded">\${env:VAR}</code> (and <code class="bg-slate-800 px-1 rounded">\${VAR}</code>) from <code class="bg-slate-800 px-1 rounded">~/.hermes/.env</code>, so the token stays out of the config file. For an endpoint that speaks OAuth instead, drop the headers and set <code class="bg-slate-800 px-1 rounded">auth: oauth</code> on the entry.</p>
+            <p class="text-slate-400">Leave the transport at its default. Hermes can switch a server to SSE, but the ha-mcp endpoint is Streamable HTTP only — it is POST-only and answers an SSE-style pre-flight with <code class="bg-slate-800 px-1 rounded">405</code>.</p>
+          </div>
+        </div>`);
+      }
+      instructions.push(`<div class="instruction-block">
+        <h3 class="instruction-title">Hermes Notes</h3>
+        <div class="text-sm text-slate-400 space-y-2">
+          <p><strong class="text-slate-300">Tool names:</strong> ha-mcp tools show up as <code class="bg-slate-800 px-1 rounded">mcp__home_assistant__&lt;tool&gt;</code> (Hermes replaces the hyphen in the server name with an underscore).</p>
+          <p><strong class="text-slate-300">Trimming the catalog:</strong> <code class="bg-slate-800 px-1 rounded">tools.include</code> / <code class="bg-slate-800 px-1 rounded">tools.exclude</code> on the server entry take exact tool names or globs. Use the <strong>original</strong> ha-mcp names (e.g. <code class="bg-slate-800 px-1 rounded">ha_get_state</code>), not the prefixed ones.</p>
+          <p><a href="https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp" class="text-blue-400 hover:underline" target="_blank" rel="noopener noreferrer">Hermes MCP docs →</a></p>
+        </div>
+      </div>`);
     } else if (state.client.configFormat === 'yaml') {
       // Continue uses YAML format
       if (isStdio) {

site/src/pages/setup.astro

@@ -1,7 +1,7 @@
 """Behavioural tests for ``site/src/pages/setup.astro``'s wizard script.
 
 The setup wizard's correctness is a multidimensional grid (5 server
-methods x 19 clients x 2 scopes x 4 platforms x 4 remote paths). The
+methods x 21 clients x 2 scopes x 4 platforms x 4 remote paths). The
 script is one giant state machine driving per-client instruction
 templates; a typo or condition inversion silently breaks setup for one
 or more branches and the only signal today is a user complaint.
@@ -19,6 +19,9 @@
   ``config-output`` AND that the emitted content is non-empty (so a typo
   that drops the JSON / CLI / instruction block is caught — not just "no
   JS error", which fires the moment any badge renders).
+* Pin the schema each YAML client gets, which the loop above cannot see:
+  both Continue and Hermes emit valid YAML, so a client falling through to
+  the other one's branch still counts as "emitted something".
 
 The harness rebuilds Astro's ``<script define:vars={...}>`` injection
 by reading the real arrays out of the page frontmatter, so changes to
@@ -588,6 +591,134 @@ def test_generate_config_emits_for_client(
         )
 
 
+# ---------------------------------------------------------------------------
+# YAML dialects
+# ---------------------------------------------------------------------------
+
+
+# client id -> (marker its own config must carry, marker that belongs to the
+# other YAML client and must therefore not appear).
+YAML_DIALECTS = {
+    "continue": ("mcpServers:", "mcp_servers:"),
+    "hermes": ("mcp_servers:", "mcpServers:"),
+}
+
+
+class TestYamlDialects:
+    """``configFormat: "yaml"`` covers two incompatible schemas.
+
+    Continue takes a ``mcpServers:`` list of ``{name, type, url}`` entries;
+    Hermes takes a ``mcp_servers:`` mapping keyed by server name in
+    ``~/.hermes/config.yaml``. Both are well-formed YAML, so a client that
+    falls through to the other one's branch still emits *a* config and
+    ``TestPerClientInstructionTemplate`` — which only asserts that the branch
+    emitted something — stays green while the user copies a config their
+    client ignores. These assertions pin the dialect itself.
+    """
+
+    @pytest.mark.parametrize("stdio", [True, False], ids=["stdio", "http"])
+    @pytest.mark.parametrize(
+        "client_id", sorted(YAML_DIALECTS), ids=sorted(YAML_DIALECTS)
+    )
+    def test_yaml_client_gets_its_own_schema(
+        self,
+        client_id: str,
+        stdio: bool,
+        setup_script: str,
+        prelude: str,
+        wizard_vars: dict[str, Any],
+    ) -> None:
+        clients = {c["id"]: c for c in wizard_vars["clientsData"]}
+        assert clients[client_id]["configFormat"] == "yaml", (
+            f"test premise: {client_id!r} must be a YAML-config client"
+        )
+        own_marker, foreign_marker = YAML_DIALECTS[client_id]
+
+        # stdio-local always asks for the platform; an HTTP method serving a
+        # client with native HTTP support reaches config after scope alone.
+        flow = (
+            _click("server-method", "stdio-local")
+            + _click("client", client_id)
+            + _click("platform", "macos")
+            if stdio
+            else _click("server-method", "ha-addon")
+            + _click("client", client_id)
+            + _click("scope", "local")
+        )
+        result = run_script(
+            setup_script,
+            prelude=prelude,
+            initial_html=_build_wizard_dom(wizard_vars),
+            invoke=(
+                flow + "document.body.dataset.configCode = "
+                "document.querySelector('#config-output code').textContent || '';\n"
+            ),
+        )
+        _assert_clean_init(result)
+        match = re.search(r'data-config-code="([^"]*)"', result.dom)
+        assert match is not None, "config-output was not captured"
+        config = match.group(1)
+
+        assert own_marker in config, (
+            f"{client_id} ({'stdio' if stdio else 'http'}): emitted config is "
+            f"missing its own root key {own_marker!r}; config={config!r}"
+        )
+        assert foreign_marker not in config, (
+            f"{client_id} ({'stdio' if stdio else 'http'}): emitted config "
+            f"carries {foreign_marker!r}, which belongs to the other YAML "
+            f"client — the branch fell through to the wrong schema; "
+            f"config={config!r}"
+        )
+
+    def test_hermes_http_instructions_do_not_offer_sse(
+        self,
+        setup_script: str,
+        prelude: str,
+        wizard_vars: dict[str, Any],
+    ) -> None:
+        """Hermes can speak SSE; the ha-mcp endpoint cannot.
+
+        ``mcp.run(transport="http")`` serves Streamable HTTP only, and a GET
+        against the MCP path — which is what an SSE-style pre-flight sends —
+        is answered with 405 (see ``ProbeAccessLogFilter`` in
+        ``src/ha_mcp/__main__.py``). Telling a Hermes user they may add
+        ``transport: sse`` therefore points them at a transport this server
+        does not serve, so the instructions must not offer it.
+        """
+        result = run_script(
+            setup_script,
+            prelude=prelude,
+            initial_html=_build_wizard_dom(wizard_vars),
+            invoke=(
+                _click("server-method", "ha-addon")
+                + _click("client", "hermes")
+                + _click("scope", "local")
+                + """
+                const instructionsEl = document.getElementById('setup-instructions');
+                document.body.dataset.instructionsHtml = String(
+                  (instructionsEl && instructionsEl.innerHTML) || ''
+                );
+                """
+            ),
+        )
+        _assert_clean_init(result)
+        match = re.search(r'data-instructions-html="([^"]*)"', result.dom)
+        assert match is not None, "setup-instructions was not captured"
+        html = match.group(1)
+
+        # Plausibility floor: an empty capture must not pass the absence
+        # assertion below by saying nothing at all.
+        assert "Streamable HTTP" in html, (
+            "hermes: HTTP instructions never rendered — the absence check "
+            f"below would pass vacuously; html={html[:300]!r}"
+        )
+        assert "transport: sse" not in html, (
+            "hermes: the instructions offer `transport: sse`, but the ha-mcp "
+            "endpoint is Streamable HTTP only and answers an SSE-style "
+            "pre-flight with 405"
+        )
+
+
 class TestStdioBridgeChoice:
     """The generated stdio-bridge config must use a bridge with a bounded SDK.