instances

instances

Deterministic Domo instance resolution for the MCP server.

An instance name from a tool call is resolved against a registry by exact slug, alias, then display-name (case-folded). No fuzzy matching: an unknown or ambiguous name raises a structured error listing the candidates so the agent can re-prompt rather than act on the wrong Domo instance.

InstanceResolutionError

InstanceResolutionError(name: str, candidates: list[dict])

Bases: Exception

Raised when an instance name matches zero or multiple registry entries.

Source code in src/crew_dcs/mcp_server/instances.py

def __init__(self, name: str, candidates: list[dict]):
    self.name = name
    self.candidates = candidates
    super().__init__(
        f"Could not resolve Domo instance {name!r}. "
        f"Candidates: {[c['slug'] for c in candidates]}"
    )

list_my_domo_instances

list_my_domo_instances(
    registry: list[DomoInstance],
) -> list[dict]

Discovery catalog: slug/display_name/aliases only (never tokens).

Source code in src/crew_dcs/mcp_server/instances.py

def list_my_domo_instances(registry: list[DomoInstance]) -> list[dict]:
    """Discovery catalog: slug/display_name/aliases only (never tokens)."""
    return _catalog(registry)

load_env_registry

load_env_registry() -> list[DomoInstance]

Single-instance registry from DOMO_INSTANCE (standalone mode).

Optionally DOMO_INSTANCES may hold a JSON array of {slug, display_name, aliases} for multi-instance standalone use.

Source code in src/crew_dcs/mcp_server/instances.py

def load_env_registry() -> list[DomoInstance]:
    """Single-instance registry from DOMO_INSTANCE (standalone mode).

    Optionally DOMO_INSTANCES may hold a JSON array of
    {slug, display_name, aliases} for multi-instance standalone use.
    """
    raw = os.environ.get("DOMO_INSTANCES")
    if raw:
        return [
            DomoInstance(
                slug=e["slug"],
                display_name=e.get("display_name"),
                aliases=e.get("aliases", []),
            )
            for e in json.loads(raw)
        ]
    slug = os.environ.get("DOMO_INSTANCE")
    return [DomoInstance(slug=slug)] if slug else []

resolve_instance

resolve_instance(
    name: str, registry: list[DomoInstance]
) -> DomoInstance

Resolve name to exactly one registry entry (slug > alias > display-name).

Source code in src/crew_dcs/mcp_server/instances.py

def resolve_instance(name: str, registry: list[DomoInstance]) -> DomoInstance:
    """Resolve `name` to exactly one registry entry (slug > alias > display-name)."""
    needle = name.casefold()
    matches = [
        i
        for i in registry
        if needle == i.slug.casefold()
        or needle in {a.casefold() for a in i.aliases}
        or (i.display_name and needle == i.display_name.casefold())
    ]
    if len(matches) == 1:
        return matches[0]
    raise InstanceResolutionError(name, _catalog(registry))