fix: optional-mcp import, flat-FQDN listing, and BloxOne idempotency (#175)

* fix(sdk): import mcp telemetry types under TYPE_CHECKING

The MCP telemetry seam imported McpHttpClientFactory from the optional
mcp package at module load for a single return-type annotation, so
importing dns_aid (and therefore the CLI) failed with
ModuleNotFoundError when the mcp extra was not installed. Move the
import under TYPE_CHECKING; from __future__ import annotations already
keeps the annotation lazy, so the package and CLI import with the core
dependencies alone.

Signed-off-by: Igor Racic <iracic82@gmail.com>

* fix(backends): make Infoblox BloxOne writes idempotent

create_svcb_record and create_txt_record POST-created records
unconditionally, so repeated index updates and re-publishes accumulated
duplicate records and eventually returned 409 Conflict on the
_index._agents TXT. Replace any existing record at the same (name, type)
before writing, an upsert matching the Route 53 backend's UPSERT
contract that also self-heals pre-existing duplicates.

Signed-off-by: Igor Racic <iracic82@gmail.com>

* fix(core): list flat-FQDN agents in list and list_published_agents

Listing filtered records by the _agents substring, which under draft-02
matched only the organization index and walkable aliases and missed
every flat agent owner ({name}.{domain}). Add dns_aid.core.lister to
identify DNS-AID records by structure (SVCB owners + companion TXT +
_agents bookkeeping) and use it from the CLI list command and the
list_published_agents MCP tool.

Signed-off-by: Igor Racic <iracic82@gmail.com>

* docs: changelog for cli import, flat listing, and bloxone idempotency

Signed-off-by: Igor Racic <iracic82@gmail.com>

---------

Signed-off-by: Igor Racic <iracic82@gmail.com>

Author: iracic82

CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- **`dns-aid[cli]` imports without the `mcp` extra.** The MCP telemetry seam
+  imported `mcp.shared._httpx_utils.McpHttpClientFactory` at module load for a
+  single return-type annotation, so `import dns_aid` (and therefore the CLI)
+  failed with `ModuleNotFoundError: No module named 'mcp'` whenever the `mcp`
+  extra was not installed. The import now lives under `TYPE_CHECKING`
+  (`from __future__ import annotations` already keeps the annotation lazy), so
+  the package and CLI import with the core dependencies alone.
+- **`list` and `list_published_agents` surface flat-FQDN agents.** Listing
+  filtered records by the `_agents` substring, which under draft-02 matched
+  only the organization index and walkable aliases and silently missed every
+  flat agent owner (`{name}.{domain}`). A new `dns_aid.core.lister` identifies
+  DNS-AID records by structure (SVCB owners + companion TXT + `_agents`
+  bookkeeping); the CLI `list` command and the `list_published_agents` MCP tool
+  now report the same, complete set.
+- **Idempotent Infoblox BloxOne writes.** `create_svcb_record` and
+  `create_txt_record` POST-created records unconditionally, so repeated index
+  updates and re-publishes accumulated duplicate records and eventually failed
+  with `409 Conflict` on the `_index._agents` TXT. They now replace any
+  existing record at the same `(name, type)` before writing — an upsert that
+  matches the Route 53 backend's `UPSERT` contract and self-heals pre-existing
+  duplicates.
+
 ## [0.24.3] - 2026-06-04
 
 ### Fixed

src/dns_aid/backends/infoblox/bloxone.py

@@ -291,6 +291,59 @@ def _format_svcb_rdata(
             "target_name": target,
         }
 
+    async def _delete_existing_records(
+        self, zone_id: str, name_in_zone: str, record_type: str
+    ) -> int:
+        """Delete every record at ``(name_in_zone, record_type)`` in the zone.
+
+        DNS-AID owns the names it writes (agent owners and ``_index._agents``)
+        and publishes exactly one record per ``(name, type)``. Removing any
+        existing record(s) before a create makes the write idempotent (an
+        upsert) and self-heals accidental duplicates left by earlier
+        non-idempotent writes — matching the UPSERT contract other backends
+        (e.g. Route53) already provide, and avoiding BloxOne ``409 Conflict``
+        on repeated index updates and re-publishes.
+
+        Returns the number of records deleted.
+        """
+        deleted = 0
+        # Bounded loop: re-query from the top after each batch (deletions shift
+        # pagination). The cap is a safety stop, far above any real fan-out.
+        for _ in range(50):
+            response = await self._request(
+                "GET",
+                "/dns/record",
+                params={
+                    "_filter": (
+                        f'zone=="{zone_id}" and name_in_zone=="{name_in_zone}" '
+                        f'and type=="{record_type}"'
+                    ),
+                    "_limit": "100",
+                },
+            )
+            results = response.get("results", [])
+            if not results:
+                break
+            for record in results:
+                record_id = record.get("id")
+                if record_id:
+                    await self._request("DELETE", f"/{record_id}")
+                    deleted += 1
+            # A partial page means we have just deleted the last of them, so
+            # there is nothing left to re-query. Only loop again if the page
+            # was full (which a real DNS-AID name never reaches).
+            if len(results) < 100:
+                break
+        if deleted:
+            logger.debug(
+                "Replaced existing record(s) before write",
+                zone_id=zone_id,
+                name=name_in_zone,
+                type=record_type,
+                deleted=deleted,
+            )
+        return deleted
+
     async def create_svcb_record(
         self,
         zone: str,
@@ -308,6 +361,11 @@ async def create_svcb_record(
         # name comes as "_agent._mcp._agents"
         name_in_zone = name
 
+        # Idempotent write (upsert): replace any existing SVCB at this name so
+        # re-publishing an agent updates in place instead of accumulating
+        # duplicate records (see _delete_existing_records).
+        await self._delete_existing_records(zone_id, name_in_zone, "SVCB")
+
         # Build FQDN for logging
         fqdn = f"{name}.{zone}"
 
@@ -355,6 +413,11 @@ async def create_txt_record(
         zone_info = await self._get_zone_info(zone)
         zone_id = zone_info["id"]
 
+        # Idempotent write (upsert): replace any existing TXT at this name.
+        # Without this, repeated index updates (_index._agents) POST-create
+        # duplicate TXT records and eventually 409 on BloxOne.
+        await self._delete_existing_records(zone_id, name, "TXT")
+
         # Build FQDN
         fqdn = f"{name}.{zone}"
 

src/dns_aid/cli/main.py

@@ -787,22 +787,22 @@ def list_records(
     """
     List DNS-AID records in a domain.
 
-    Shows all _agents.* records in the specified zone.
+    Shows the flat agent owners ({name}.{domain} SVCB + TXT), the organization
+    index (_index._agents), and any walkable aliases in the specified zone.
 
     Example:
         dns-aid list example.com
     """
+    from dns_aid.core.lister import list_dns_aid_records
+
     dns_backend = _get_backend(backend)
 
     console.print(f"\n[bold]DNS-AID records in {domain}:[/bold]\n")
 
     async def list_all():
         if not await dns_backend.zone_exists(domain):
             return None  # sentinel: zone not found
-        records = []
-        async for record in dns_backend.list_records(domain, name_pattern="_agents"):
-            records.append(record)
-        return records
+        return await list_dns_aid_records(dns_backend, domain)
 
     try:
         records = run_async(list_all())

src/dns_aid/core/lister.py

@@ -0,0 +1,84 @@
+# Copyright 2024-2026 The DNS-AID Authors
+# SPDX-License-Identifier: Apache-2.0
+
+"""Enumerate the DNS-AID records published in a zone, via a DNS backend.
+
+Under draft-mozleywilliams-dnsop-dnsaid-02 an agent's primary owner is the
+**flat** FQDN ``{name}.{domain}`` (SVCB + companion TXT). The pre-flat
+listing logic filtered records by the substring ``_agents`` in the owner
+label, which only ever matched the organization index (``_index._agents``)
+and walkable aliases (``{name}._agents``) — it silently missed every flat
+agent owner. This module identifies DNS-AID records by *structure* instead of
+by a name substring, so flat owners are surfaced.
+
+A record is a DNS-AID record when it is:
+
+* an **SVCB** record — every published agent (flat owner) and every walkable
+  alias has exactly one;
+* a **TXT** record sharing an owner with an SVCB record — the companion
+  capability/metadata TXT of a flat agent owner;
+* a record in the ``_agents`` bookkeeping namespace — the organization index
+  (``_index._agents``) and walkable-alias owners.
+
+System records (SOA/NS/A/AAAA/CNAME/...) are excluded. Used by ``dns-aid
+list`` (CLI) and the ``list_published_agents`` MCP tool so both interfaces
+report the same, correct set.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from dns_aid.backends.base import DNSBackend
+
+# The label that marks the DNS-AID bookkeeping namespace (index + walkable
+# aliases). Agent *primary* owners are flat and do NOT contain it — that is
+# exactly why a substring filter on it is insufficient on its own.
+_AGENTS_LABEL = "_agents"
+
+
+def _owner(record: dict[str, Any]) -> str:
+    """Stable owner key for a record: name-in-zone, falling back to the FQDN."""
+    return record.get("name") or record.get("fqdn", "")
+
+
+async def list_dns_aid_records(backend: DNSBackend, domain: str) -> list[dict[str, Any]]:
+    """Return the DNS-AID records published under ``domain``.
+
+    Issues two type-filtered backend queries (SVCB, TXT) so unrelated system
+    records are never fetched. The result preserves the backend's record-dict
+    shape (``name``, ``fqdn``, ``type``, ``ttl``, ``values``, ``id``) and
+    de-duplicates by ``(fqdn, type)``.
+
+    Args:
+        backend: DNS backend to query.
+        domain: Zone to enumerate.
+
+    Returns:
+        DNS-AID records (SVCB owners + walkable aliases + companion TXT +
+        the ``_agents`` bookkeeping records), in backend order.
+    """
+    svcb_records = [r async for r in backend.list_records(domain, record_type="SVCB")]
+    txt_records = [r async for r in backend.list_records(domain, record_type="TXT")]
+
+    svcb_owners = {_owner(r) for r in svcb_records}
+
+    out: list[dict[str, Any]] = list(svcb_records)
+    for record in txt_records:
+        owner = _owner(record)
+        # Companion TXT of a flat agent owner, or an `_agents` bookkeeping TXT.
+        if owner in svcb_owners or _AGENTS_LABEL in owner:
+            out.append(record)
+
+    # De-duplicate defensively (a backend could surface a record under both
+    # queries); keep first occurrence and preserve order.
+    seen: set[tuple[str, str]] = set()
+    deduped: list[dict[str, Any]] = []
+    for record in out:
+        key = (record.get("fqdn", ""), record.get("type", ""))
+        if key in seen:
+            continue
+        seen.add(key)
+        deduped.append(record)
+    return deduped

src/dns_aid/mcp/server.py

@@ -1009,12 +1009,11 @@ def list_published_agents(
     dns_backend = _get_dns_backend(backend)
 
     async def _list():
+        from dns_aid.core.lister import list_dns_aid_records
+
         if not await dns_backend.zone_exists(domain):
             return None  # sentinel: zone not found
-        records = []
-        async for record in dns_backend.list_records(domain, name_pattern="_agents"):
-            records.append(record)
-        return records
+        return await list_dns_aid_records(dns_backend, domain)
 
     try:
         records = _run_async(_list())

src/dns_aid/sdk/protocols/_mcp_telemetry.py

@@ -19,12 +19,19 @@
 
 import time
 from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
 
 import httpx
-from mcp.shared._httpx_utils import McpHttpClientFactory
 
 from dns_aid.sdk.telemetry.propagation import inject_otel_context
 
+if TYPE_CHECKING:
+    # `mcp` is an optional dependency (the `mcp` extra). It is referenced here
+    # only as a return-type annotation, which `from __future__ import
+    # annotations` keeps lazy — so importing this module (and therefore the
+    # whole `dns_aid` package and CLI) must not require `mcp` to be installed.
+    from mcp.shared._httpx_utils import McpHttpClientFactory
+
 
 @dataclass
 class _TelemetryCapture:

tests/unit/sdk/test_optional_mcp_import.py

@@ -0,0 +1,63 @@
+# Copyright 2024-2026 The DNS-AID Authors
+# SPDX-License-Identifier: Apache-2.0
+
+"""Regression: the package (and CLI) must import without the optional ``mcp`` extra.
+
+``mcp`` is declared in the ``mcp`` extra, not the core dependencies. A stray
+module-level ``from mcp...`` in the SDK import chain made ``import dns_aid``
+(and therefore ``dns-aid[cli]`` with no ``mcp`` extra) fail with
+``ModuleNotFoundError: No module named 'mcp'``. The MCP telemetry seam only
+references ``mcp`` as a type annotation, so the import belongs under
+``TYPE_CHECKING``. These tests pin that contract.
+"""
+
+from __future__ import annotations
+
+import builtins
+import importlib
+import sys
+
+
+def _block_mcp(monkeypatch) -> None:
+    """Make any ``import mcp`` / ``from mcp...`` raise, simulating the absent extra."""
+    for mod in list(sys.modules):
+        if mod == "mcp" or mod.startswith("mcp."):
+            monkeypatch.delitem(sys.modules, mod, raising=False)
+
+    real_import = builtins.__import__
+
+    def fake_import(name, *args, **kwargs):
+        if name == "mcp" or name.startswith("mcp."):
+            raise ModuleNotFoundError("No module named 'mcp' (simulated: extra not installed)")
+        return real_import(name, *args, **kwargs)
+
+    monkeypatch.setattr(builtins, "__import__", fake_import)
+
+
+def test_mcp_telemetry_module_imports_without_mcp(monkeypatch):
+    """The telemetry module references ``mcp`` only for typing — import must not need it."""
+    _block_mcp(monkeypatch)
+    monkeypatch.delitem(sys.modules, "dns_aid.sdk.protocols._mcp_telemetry", raising=False)
+
+    mod = importlib.import_module("dns_aid.sdk.protocols._mcp_telemetry")
+
+    assert hasattr(mod, "_make_telemetry_factory")
+    # The factory builds a plain httpx client factory and never touches ``mcp``.
+    assert "mcp" not in sys.modules
+
+
+async def test_factory_builds_without_mcp(monkeypatch):
+    """The telemetry factory is callable and returns an httpx client without ``mcp``."""
+    import httpx
+
+    _block_mcp(monkeypatch)
+    monkeypatch.delitem(sys.modules, "dns_aid.sdk.protocols._mcp_telemetry", raising=False)
+    mod = importlib.import_module("dns_aid.sdk.protocols._mcp_telemetry")
+
+    capture = mod._TelemetryCapture()
+    factory = mod._make_telemetry_factory(capture)
+    client = factory()
+    try:
+        assert isinstance(client, httpx.AsyncClient)
+    finally:
+        await client.aclose()