agent-capmap 0.1.0__py3-none-any.whl

agentcapmap/discovery/claude_code.py

@@ -0,0 +1,258 @@
+"""Claude Code: project `.mcp.json`, the user's `~/.claude.json`, and permission settings.
+
+Where Claude Code keeps MCP servers (https://code.claude.com/docs/en/mcp):
+- user scope:    top-level `mcpServers` in `~/.claude.json` (every project)
+- local scope:   `projects.<path>.mcpServers` in `~/.claude.json` (one project, private)
+- project scope: `.mcp.json` at the project root (shared through version control)
+The same name in several scopes resolves local > project > user, whole entry.
+
+Approval (https://code.claude.com/docs/en/permissions): in the default permission
+mode Claude Code asks before an MCP tool call unless a `permissions.allow` rule
+(`mcp__<server>`, `mcp__<server>__*`, `mcp__<server>__<tool>`) covers it.
+`bypassPermissions` and `auto` modes skip the human prompt; `dontAsk` refuses calls that
+would prompt; `permissions.deny` rules remove tools.
+
+`~/.claude.json` also holds account data (and possibly `primaryApiKey`). Only MCP
+server entries and per-project MCP toggles are read from it; nothing else is output.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import json
+import re
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Literal
+
+from agentcapmap.discovery._common import ConfigError, ConfigFormat, load_jsonc, parse_server_map
+from agentcapmap.limits import MAX_CONFIG_BYTES
+from agentcapmap.models import ApprovalConfig, Server
+from agentcapmap.redact import get_logger, known_secrets
+
+log = get_logger(__name__)
+
+# ~/.claude.json grows with per-project history; allow more than a normal config.
+USER_CONFIG_MAX_BYTES = 64 * 1024 * 1024
+_RULE_NAME = re.compile(r"[^A-Za-z0-9_-]")
+_PROMPTING_MODES = {None, "default", "manual", "acceptEdits", "plan"}
+_NO_PROMPT_MODES = {"bypassPermissions", "auto"}
+
+
+@dataclass
+class Permissions:
+    allow: list[str] = field(default_factory=list)
+    deny: list[str] = field(default_factory=list)
+    mode: str | None = None
+    sources: list[str] = field(default_factory=list)
+    disabled_mcpjson: set[str] = field(default_factory=set)
+
+
+def _read_json(path: Path, limit: int = MAX_CONFIG_BYTES) -> dict[str, Any] | None:
+    try:
+        if not path.is_file() or path.stat().st_size > limit:
+            return None
+        data = load_jsonc(path.read_text(encoding="utf-8-sig"))
+    except (OSError, UnicodeDecodeError, ConfigError) as exc:
+        log.warning("ignoring unreadable Claude Code file %s: %s", path.name, exc)
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def _strings(value: Any) -> list[str]:
+    return [v for v in value if isinstance(v, str)] if isinstance(value, list) else []
+
+
+def read_permissions(settings_files: list[Path]) -> Permissions:
+    """Merge permission settings; later files (higher precedence) win for the mode."""
+    perms = Permissions()
+    for path in settings_files:
+        data = _read_json(path)
+        if data is None:
+            continue
+        raw = data.get("permissions")
+        section: dict[str, Any] = raw if isinstance(raw, dict) else {}
+        perms.allow += _strings(section.get("allow"))
+        perms.deny += _strings(section.get("deny"))
+        mode = section.get("defaultMode", data.get("defaultMode"))
+        if isinstance(mode, str):
+            perms.mode = mode
+        perms.disabled_mcpjson |= set(_strings(data.get("disabledMcpjsonServers")))
+        perms.sources.append(path.name if path.parent.name != ".claude" else f".claude/{path.name}")
+    return perms
+
+
+def _tool_pattern(rule: str, server_key: str) -> str | None:
+    """The tool-name glob an `mcp__...` rule grants for this server, if any."""
+    if "(" in rule:  # Claude Code skips parameterized mcp__ rules in settings files
+        return None
+    if rule == server_key:
+        return "*"
+    prefix = f"{server_key}__"
+    if rule.startswith(prefix):
+        return rule[len(prefix) :] or "*"
+    return None
+
+
+def server_approval(
+    name: str, perms: Permissions, extra_allow: Sequence[str] = ()
+) -> ApprovalConfig:
+    key = "mcp__" + _RULE_NAME.sub("_", name)
+    allow = [p for r in [*perms.allow, *extra_allow] if (p := _tool_pattern(r, key))]
+    deny = [p for r in perms.deny if (p := _tool_pattern(r, key))]
+    if any(r in ("*", "mcp__*") for r in perms.deny):
+        deny.append("*")
+    mode = perms.mode
+    gate: Literal["required", "none", "unknown", "blocked"]
+    if mode in _NO_PROMPT_MODES:
+        gate, reason = "none", f"Claude Code permission mode {mode!r} skips approval prompts"
+    elif mode == "dontAsk":
+        gate, reason = "blocked", "Claude Code 'dontAsk' mode refuses calls that need approval"
+    elif mode in _PROMPTING_MODES:
+        gate, reason = "required", "Claude Code asks before MCP tool calls in this permission mode"
+    else:
+        gate, reason = "unknown", f"unrecognized Claude Code permission mode {mode!r}"
+    return ApprovalConfig(
+        auto_approve_all="*" in allow,
+        auto_approved_patterns=sorted(set(allow)),
+        denied_patterns=sorted(set(deny)),
+        default_gate=gate,
+        default_reason=reason,
+        sources=[f"settings: {', '.join(perms.sources)}"] if perms.sources else [],
+    )
+
+
+def tool_matches(patterns: list[str], tool: str) -> bool:
+    return any(fnmatch.fnmatchcase(tool, p) for p in patterns)
+
+
+def _project_settings(project: Path) -> list[Path]:
+    return [project / ".claude" / "settings.json", project / ".claude" / "settings.local.json"]
+
+
+def _apply(servers: list[Server], perms: Permissions, extra_allow: Sequence[str] = ()) -> None:
+    for server in servers:
+        server.approval = server_approval(server.name, perms, extra_allow)
+
+
+# --- project .mcp.json ------------------------------------------------------------------
+
+
+def _parse_mcp_json(text: str, path: Path, display: str) -> list[Server]:
+    data = load_jsonc(text)
+    if not isinstance(data, dict):
+        raise ConfigError("top level must be an object")
+    return parse_server_map(
+        data.get("mcpServers"),
+        config_path=display,
+        text=text,
+        section_key="mcpServers",
+        base_dir=path.parent,
+    )
+
+
+def parse_project(text: str, path: Path, display: str) -> list[Server]:
+    """A repository's `.mcp.json`, with approvals from that project's own settings only
+    (a repository scan must not depend on the scanning machine's user settings)."""
+    servers = _parse_mcp_json(text, path, display)
+    perms = read_permissions(_project_settings(path.parent))
+    servers = [s for s in servers if s.name not in perms.disabled_mcpjson]
+    _apply(servers, perms)
+    return servers
+
+
+# --- ~/.claude.json ---------------------------------------------------------------------
+
+
+def _merge(*scopes: list[Server]) -> list[Server]:
+    """First scope wins per name (pass highest precedence first)."""
+    merged: dict[str, Server] = {}
+    for scope in scopes:
+        for server in scope:
+            merged.setdefault(server.name, server)
+    return list(merged.values())
+
+
+def _section_start(text: str, project_key: str) -> int:
+    """Offset just after the project's key, matching the JSON-escaped form in the file."""
+    match = re.search(re.escape(json.dumps(project_key)) + r"\s*:", text)
+    return match.end() if match else 0
+
+
+def parse_user_agents(text: str, path: Path, display: str) -> list[tuple[str, list[Server]]]:
+    data = load_jsonc(text)
+    if not isinstance(data, dict):
+        raise ConfigError("top level must be an object")
+    if isinstance(data.get("primaryApiKey"), str):
+        known_secrets.add(data["primaryApiKey"])  # never output, scrubbed if it ever appears
+
+    user_settings = [path.parent / ".claude" / "settings.json"]
+
+    def user_scope() -> list[Server]:
+        return parse_server_map(
+            data.get("mcpServers"),
+            config_path=display,
+            text=text,
+            section_key="mcpServers",
+            base_dir=path.parent,
+        )
+
+    user_servers = user_scope()
+    _apply(user_servers, read_permissions(user_settings))
+    agents: list[tuple[str, list[Server]]] = [("user", user_servers)]
+
+    projects = data.get("projects")
+    for project_key, entry in sorted(projects.items() if isinstance(projects, dict) else []):
+        if not isinstance(entry, dict):
+            continue
+        project = Path(project_key)
+        local = parse_server_map(
+            entry.get("mcpServers"),
+            config_path=display,
+            text=text,
+            section_key="mcpServers",
+            base_dir=project,
+            search_from=_section_start(text, project_key),
+        )
+        mcp_json = project / ".mcp.json"
+        shared: list[Server] = []
+        if mcp_json.is_file():
+            try:
+                shared_text = mcp_json.read_text(encoding="utf-8-sig")
+                shared = _parse_mcp_json(shared_text, mcp_json, mcp_json.as_posix())
+            except (OSError, UnicodeDecodeError, ConfigError) as exc:
+                log.warning("ignoring %s: %s", mcp_json.as_posix(), exc)
+        if not local and not shared:
+            continue  # same reach as the user-scope agent
+
+        perms = read_permissions([*user_settings, *_project_settings(project)])
+        perms.disabled_mcpjson |= set(_strings(entry.get("disabledMcpjsonServers")))
+        shared = [s for s in shared if s.name not in perms.disabled_mcpjson]
+        servers = _merge(local, shared, user_scope())
+        toggled_off = set(_strings(entry.get("disabledMcpServers")))
+        for server in servers:
+            if server.name in toggled_off:
+                server.disabled = True
+        _apply(servers, perms, _strings(entry.get("allowedTools")))
+        agents.append((f"project:{project.as_posix()}", servers))
+    return agents
+
+
+def _parse_user(text: str, path: Path, display: str) -> list[Server]:
+    return parse_user_agents(text, path, display)[0][1]
+
+
+FORMATS = [
+    ConfigFormat(
+        "claude_code_user",
+        "claude-code",
+        lambda p: p.name.lower() == ".claude.json",
+        _parse_user,
+        parse_agents=parse_user_agents,
+        max_bytes=USER_CONFIG_MAX_BYTES,
+    ),
+    ConfigFormat(
+        "claude_code", "claude-code", lambda p: p.name.lower() == ".mcp.json", parse_project
+    ),
+]

agentcapmap/discovery/claude_desktop.py

@@ -0,0 +1,28 @@
+"""Claude Desktop: claude_desktop_config.json with a top-level `mcpServers` map."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from agentcapmap.discovery._common import ConfigError, ConfigFormat, load_jsonc, parse_server_map
+from agentcapmap.models import Server
+
+
+def matches(path: Path) -> bool:
+    return path.name.lower() == "claude_desktop_config.json"
+
+
+def parse(text: str, path: Path, display_path: str) -> list[Server]:
+    data = load_jsonc(text)
+    if not isinstance(data, dict):
+        raise ConfigError("top level must be an object")
+    return parse_server_map(
+        data.get("mcpServers"),
+        config_path=display_path,
+        text=text,
+        section_key="mcpServers",
+        base_dir=path.parent,
+    )
+
+
+FORMATS = [ConfigFormat("claude_desktop", "claude-desktop", matches, parse)]

agentcapmap/discovery/cursor.py

@@ -0,0 +1,33 @@
+"""Cursor: `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global).
+
+Same `mcpServers` shape as Claude Desktop, but entries may be remote (`url` + `headers`)
+and values may use `${env:NAME}` interpolation.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from agentcapmap.discovery._common import ConfigError, ConfigFormat, load_jsonc, parse_server_map
+from agentcapmap.models import Server
+
+
+def matches(path: Path) -> bool:
+    return path.name.lower() == "mcp.json" and path.parent.name.lower() == ".cursor"
+
+
+def parse(text: str, path: Path, display_path: str) -> list[Server]:
+    data = load_jsonc(text)
+    if not isinstance(data, dict):
+        raise ConfigError("top level must be an object")
+    # Workspace root is the directory containing .cursor/.
+    return parse_server_map(
+        data.get("mcpServers"),
+        config_path=display_path,
+        text=text,
+        section_key="mcpServers",
+        base_dir=path.parent.parent,
+    )
+
+
+FORMATS = [ConfigFormat("cursor", "cursor", matches, parse)]

agentcapmap/discovery/mcp_json.py

@@ -0,0 +1,29 @@
+"""Generic `mcp.json` files.
+
+Uses the `mcpServers` map. A generic `mcp.json` that uses `servers` instead is treated
+as VS Code-shaped. (Claude Code's `.mcp.json` lives in `claude_code.py`.)
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from agentcapmap.discovery._common import ConfigError, ConfigFormat, load_jsonc, parse_server_map
+from agentcapmap.models import Server
+
+
+def parse(text: str, path: Path, display_path: str) -> list[Server]:
+    data = load_jsonc(text)
+    if not isinstance(data, dict):
+        raise ConfigError("top level must be an object")
+    key = "servers" if "servers" in data and "mcpServers" not in data else "mcpServers"
+    return parse_server_map(
+        data.get(key),
+        config_path=display_path,
+        text=text,
+        section_key=key,
+        base_dir=path.parent,
+    )
+
+
+FORMATS = [ConfigFormat("mcp_json", "generic", lambda p: p.name.lower() == "mcp.json", parse)]

agentcapmap/discovery/vscode.py

@@ -0,0 +1,65 @@
+"""VS Code: `.vscode/mcp.json`, user-profile `mcp.json`, and the `mcp` key in settings.json.
+
+VS Code files are JSONC. Servers live under `servers` (not `mcpServers`), declare
+`type` explicitly, and may reference prompted secrets via `${input:id}`.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from agentcapmap.discovery._common import ConfigError, ConfigFormat, load_jsonc, parse_server_map
+from agentcapmap.models import Server
+
+
+def _workspace_root(path: Path) -> Path:
+    return path.parent.parent if path.parent.name.lower() == ".vscode" else path.parent
+
+
+def matches_mcp_json(path: Path) -> bool:
+    return path.name.lower() == "mcp.json" and path.parent.name.lower() in (".vscode", "user")
+
+
+def parse_mcp_json(text: str, path: Path, display_path: str) -> list[Server]:
+    data = load_jsonc(text)
+    if not isinstance(data, dict):
+        raise ConfigError("top level must be an object")
+    return parse_server_map(
+        data.get("servers"),
+        config_path=display_path,
+        text=text,
+        section_key="servers",
+        base_dir=_workspace_root(path),
+    )
+
+
+def matches_settings(path: Path) -> bool:
+    return path.name.lower() == "settings.json" and path.parent.name.lower() in (".vscode", "user")
+
+
+def parse_settings(text: str, path: Path, display_path: str) -> list[Server]:
+    """settings.json with an embedded `"mcp": {"servers": {...}}` block."""
+    data = load_jsonc(text)
+    if not isinstance(data, dict):
+        raise ConfigError("top level must be an object")
+    mcp = data.get("mcp")
+    if mcp is None:
+        return []
+    if not isinstance(mcp, dict):
+        raise ConfigError("'mcp' must be an object")
+    m = re.search(r'"mcp"\s*:', text)
+    return parse_server_map(
+        mcp.get("servers"),
+        config_path=display_path,
+        text=text,
+        section_key="servers",
+        base_dir=_workspace_root(path),
+        search_from=m.end() if m else 0,
+    )
+
+
+FORMATS = [
+    ConfigFormat("vscode", "vscode", matches_mcp_json, parse_mcp_json),
+    ConfigFormat("vscode_settings", "vscode", matches_settings, parse_settings),
+]

agentcapmap/enumerate/__init__.py

@@ -0,0 +1,278 @@
+"""Connect to MCP servers and list their tools. Only `initialize` and `tools/list` are sent."""
+
+from __future__ import annotations
+
+import os
+import re
+import time
+from collections.abc import Callable, Iterable
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlsplit
+
+from agentcapmap import __version__
+from agentcapmap.enumerate.hashing import server_definition_hash, tool_definition_hash
+from agentcapmap.enumerate.http import LegacySseTransport, StreamableHttpTransport
+from agentcapmap.enumerate.netguard import check_remote_url
+from agentcapmap.enumerate.stdio import StdioTransport
+from agentcapmap.enumerate.transport import (
+    AuthRequired,
+    MCPError,
+    RequestTimeout,
+    Transport,
+    TransportError,
+)
+from agentcapmap.limits import MAX_CONFIG_BYTES, MAX_TOOLS_PER_SERVER
+from agentcapmap.models import (
+    AuthHint,
+    AuthMethod,
+    EnumerationResult,
+    EnumerationStatus,
+    Inventory,
+    LaunchSpec,
+    Server,
+    ToolDefinition,
+)
+from agentcapmap.models import Transport as TransportKind
+from agentcapmap.redact import get_logger, known_secrets, redact_text
+
+log = get_logger(__name__)
+
+PROTOCOL_VERSION = "2025-06-18"
+DEFAULT_TIMEOUT = 30.0
+_MAX_PAGES = 100
+_VAR = re.compile(r"\$\{([^}]+)\}")
+
+
+class UnresolvedVariable(Exception):
+    pass
+
+
+def _load_env_file(path: Path) -> dict[str, str]:
+    values: dict[str, str] = {}
+    if path.stat().st_size > MAX_CONFIG_BYTES:
+        raise ValueError("envFile too large")
+    for line in path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = line.removeprefix("export ").partition("=")
+        value = value.strip()
+        if len(value) >= 2 and value[0] == value[-1] and value[0] in "\"'":
+            value = value[1:-1]
+        values[key.strip()] = value
+    return values
+
+
+def _resolver(spec: LaunchSpec, env: dict[str, str]) -> Callable[[str], str]:
+    base_dir = spec.base_dir or str(Path.cwd())
+
+    def resolve(text: str) -> str:
+        def sub(m: re.Match[str]) -> str:
+            name = m.group(1).strip()
+            if name in ("workspaceFolder", "workspaceRoot"):
+                return base_dir
+            if name == "userHome":
+                return str(Path.home())
+            if name.startswith("input:"):
+                raise UnresolvedVariable(f"requires interactive input ${{{name}}}")
+            if name.startswith("env:"):
+                name = name[4:]
+            name, _, default = name.partition(":-")
+            if name in env:
+                return env[name]
+            if default:
+                return default
+            raise UnresolvedVariable(f"environment variable {name} is not set")
+
+        return _VAR.sub(sub, text)
+
+    return resolve
+
+
+def resolve_launch(spec: LaunchSpec) -> LaunchSpec:
+    """Expand ${...} references the way MCP clients do. Raises UnresolvedVariable."""
+    lookup_env = dict(os.environ)
+    resolve = _resolver(spec, lookup_env)
+    file_env: dict[str, str] = {}
+    if spec.env_file:
+        env_path = Path(resolve(spec.env_file))
+        if not env_path.is_absolute():
+            env_path = Path(spec.base_dir or ".") / env_path
+        try:
+            file_env = _load_env_file(env_path)
+        except OSError as exc:
+            raise UnresolvedVariable(f"cannot read envFile: {exc.strerror}") from None
+        except (UnicodeDecodeError, ValueError):
+            raise UnresolvedVariable("cannot read envFile: not a UTF-8 text file") from None
+        for value in file_env.values():
+            known_secrets.add(value)
+    lookup_env.update(file_env)
+    env = {**file_env, **{k: resolve(v) for k, v in spec.env.items()}}
+    lookup_env.update(env)
+    resolve = _resolver(spec, lookup_env)
+    resolved = LaunchSpec(
+        command=resolve(spec.command) if spec.command else None,
+        args=[resolve(a) for a in spec.args],
+        env=env,
+        cwd=resolve(spec.cwd) if spec.cwd else spec.base_dir,
+        url=resolve(spec.url) if spec.url else None,
+        headers={k: resolve(v) for k, v in spec.headers.items()},
+        base_dir=spec.base_dir,
+    )
+    for value in [*resolved.env.values(), *resolved.headers.values()]:
+        known_secrets.add(value)
+    return resolved
+
+
+def open_transport(server: Server, spec: LaunchSpec, timeout: float) -> Transport:
+    if server.transport is TransportKind.STDIO:
+        if not spec.command:
+            raise TransportError("stdio server has no command")
+        cwd = spec.cwd if spec.cwd and Path(spec.cwd).is_dir() else None
+        return StdioTransport(spec.command, spec.args, spec.env, cwd)
+    if not spec.url:
+        raise TransportError("remote server has no URL")
+    if urlsplit(spec.url).scheme.lower() not in ("http", "https"):
+        raise TransportError("remote server URL must use http or https")
+    check_remote_url(spec.url)
+    if server.transport is TransportKind.SSE:
+        return LegacySseTransport(spec.url, spec.headers, timeout)
+    return StreamableHttpTransport(spec.url, spec.headers, timeout)
+
+
+def _parse_tools(raw_tools: Any) -> list[ToolDefinition]:
+    if not isinstance(raw_tools, list):
+        raise TransportError("tools/list result has no 'tools' array")
+    tools: list[ToolDefinition] = []
+    for raw in raw_tools:
+        if not isinstance(raw, dict) or not isinstance(raw.get("name"), str):
+            log.debug("skipping malformed tool entry")
+            continue
+        description = raw.get("description")
+        schema = raw.get("inputSchema")
+        annotations = raw.get("annotations")
+        description = description if isinstance(description, str) else ""
+        schema = schema if isinstance(schema, dict) else {}
+        tools.append(
+            ToolDefinition(
+                name=raw["name"],
+                description=description,
+                input_schema=schema,
+                annotations=annotations if isinstance(annotations, dict) else None,
+                definition_hash=tool_definition_hash(raw["name"], description, schema),
+            )
+        )
+    return tools
+
+
+def list_tools(transport: Transport, timeout: float) -> EnumerationResult:
+    """Run the handshake and page through tools/list within one overall deadline."""
+    deadline = time.monotonic() + timeout
+
+    def remaining() -> float:
+        left = deadline - time.monotonic()
+        if left <= 0:
+            raise RequestTimeout(f"enumeration exceeded {timeout:.0f}s")
+        return left
+
+    init = transport.request(
+        "initialize",
+        {
+            "protocolVersion": PROTOCOL_VERSION,
+            "capabilities": {},
+            "clientInfo": {"name": "agent-capmap", "version": __version__},
+        },
+        remaining(),
+    )
+    transport.notify("notifications/initialized")
+    server_info = init.get("serverInfo") if isinstance(init.get("serverInfo"), dict) else None
+    protocol_version = init.get("protocolVersion")
+    capabilities = init.get("capabilities") if isinstance(init.get("capabilities"), dict) else {}
+
+    tools: list[ToolDefinition] = []
+    if capabilities is not None and "tools" in capabilities:
+        cursor: str | None = None
+        seen_cursors: set[str] = set()
+        for _ in range(_MAX_PAGES):
+            params: dict[str, Any] = {"cursor": cursor} if cursor else {}
+            page = transport.request("tools/list", params, remaining())
+            tools.extend(_parse_tools(page.get("tools")))
+            if len(tools) > MAX_TOOLS_PER_SERVER:
+                raise TransportError(f"server returned more than {MAX_TOOLS_PER_SERVER} tools")
+            next_cursor = page.get("nextCursor")
+            if not isinstance(next_cursor, str) or not next_cursor or next_cursor in seen_cursors:
+                break
+            seen_cursors.add(next_cursor)
+            cursor = next_cursor
+
+    return EnumerationResult(
+        status=EnumerationStatus.OK,
+        protocol_version=protocol_version if isinstance(protocol_version, str) else None,
+        server_info=server_info,
+        tools=tools,
+        definition_hash=server_definition_hash(t.definition_hash for t in tools),
+    )
+
+
+def enumerate_server(server: Server, timeout: float = DEFAULT_TIMEOUT) -> EnumerationResult:
+    """Enumerate one server's tools. Never raises; failures become a non-OK status."""
+    if server.disabled:
+        return EnumerationResult(status=EnumerationStatus.SKIPPED, error="disabled in config")
+    if server.transport is TransportKind.WS:
+        return EnumerationResult(
+            status=EnumerationStatus.SKIPPED, error="WebSocket servers are not enumerated yet"
+        )
+    try:
+        spec = resolve_launch(server.launch)
+    except UnresolvedVariable as exc:
+        return EnumerationResult(status=EnumerationStatus.SKIPPED, error=redact_text(str(exc)))
+
+    transport: Transport | None = None
+    try:
+        transport = open_transport(server, spec, timeout)
+        result = list_tools(transport, timeout)
+    except AuthRequired as exc:
+        challenge = (exc.www_authenticate or "").lower()
+        if server.auth.method is AuthMethod.UNKNOWN and "bearer" in challenge:
+            server.auth = AuthHint(method=AuthMethod.OAUTH, evidence=["www-authenticate:Bearer"])
+        return EnumerationResult(
+            status=EnumerationStatus.AUTH_REQUIRED, error=redact_text(str(exc))
+        )
+    except RequestTimeout as exc:
+        return EnumerationResult(status=EnumerationStatus.TIMEOUT, error=redact_text(str(exc)))
+    except (TransportError, MCPError) as exc:
+        return EnumerationResult(status=EnumerationStatus.ERROR, error=redact_text(str(exc)))
+    finally:
+        if transport is not None:
+            try:
+                transport.close()
+            except Exception as exc:  # cleanup must not mask the real result
+                log.debug("error closing transport for %s: %s", server.name, exc)
+
+    if server.transport is not TransportKind.STDIO and server.auth.method is AuthMethod.UNKNOWN:
+        server.auth = AuthHint(
+            method=AuthMethod.NONE, evidence=["tools/list succeeded without credentials"]
+        )
+    return result
+
+
+def enumerate_inventory(
+    inventory: Inventory, *, timeout: float = DEFAULT_TIMEOUT, concurrency: int = 4
+) -> None:
+    """Enumerate every server in place."""
+    servers: Iterable[Server] = [s for agent in inventory.agents for s in agent.servers]
+
+    def run(server: Server) -> None:
+        log.info("enumerating %s (%s)", server.name, server.transport.value)
+        server.enumeration = enumerate_server(server, timeout)
+        log.info(
+            "  %s: %s, %d tool(s)",
+            server.name,
+            server.enumeration.status.value,
+            len(server.enumeration.tools),
+        )
+
+    with ThreadPoolExecutor(max_workers=max(1, concurrency)) as pool:
+        list(pool.map(run, servers))