zjcode 0.0.1__py3-none-any.whl

deepagents_code/mcp_config.py

@@ -0,0 +1,176 @@
+"""Validation and environment-variable expansion for MCP server config.
+
+Resolves `${VAR}` and `${VAR:-default}` references in the supported
+configuration fields (`command`, `url`, `args`, `env`, `headers`) and
+validates their types. A `${VAR:-default}` reference falls back to
+`default` when `VAR` is unset *or* empty (POSIX `:-` semantics).
+"""
+
+from __future__ import annotations
+
+import copy
+import os
+import re
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+_ENV_REF_RE = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^{}]*))?\}")
+"""Matches a supported reference: `${VAR}` or `${VAR:-default}`.
+
+Group 1 is the variable name; group 2 (present only for the `:-` form) is
+the default. A bare `$VAR` and a literal `$` are intentionally not matched.
+"""
+
+_ENV_BRACE_RE = re.compile(r"\$\{")
+"""Matches a `${` brace-open, used to catch malformed `${...}` references."""
+
+
+def _interpolate_env(value: str, *, field: str) -> str:
+    """Expand `${VAR}` / `${VAR:-default}` references in one config string.
+
+    A bare `$VAR` (no braces) and a literal `$` pass through untouched;
+    only the braced forms expand. `${VAR:-default}` uses `default` when
+    `VAR` is unset or empty. A `${...}` that does not parse as one of the
+    supported forms (e.g. `${VAR-default}` or an unterminated `${VAR`) is
+    rejected rather than silently emitted, so a typo cannot inject a
+    garbage value into a URL, command, or header.
+
+    Args:
+        value: Raw configuration string.
+        field: Fully qualified field path for error messages.
+
+    Returns:
+        The interpolated string.
+
+    Raises:
+        RuntimeError: If a required environment variable is unset, or the
+            string contains a malformed `${...}` reference.
+    """
+
+    def replace(match: re.Match[str]) -> str:
+        name = match.group(1)
+        default = match.group(2)
+        resolved = os.environ.get(name)
+        # A non-empty value always wins, for both `${VAR}` and `${VAR:-default}`.
+        if resolved:
+            return resolved
+        # `resolved` is now "" (set but empty) or None (unset).
+        if default is not None:
+            # `${VAR:-default}`: `:-` falls back for empty *and* unset (POSIX).
+            return default
+        if resolved is not None:
+            # `${VAR}` set to "": no default, so emit the empty value.
+            return resolved
+        # `${VAR}` unset with no default: the only hard error.
+        msg = (
+            f"{field} references unset env var {name}. "
+            f"Set {name} in the environment or provide a default."
+        )
+        raise RuntimeError(msg)
+
+    # Reject any `${` that isn't the start of a well-formed reference. The
+    # check is against the raw `value` (not the substituted result) so a
+    # resolved value that happens to contain `${` never trips it.
+    ref_spans = [match.span() for match in _ENV_REF_RE.finditer(value)]
+    for brace in _ENV_BRACE_RE.finditer(value):
+        if not any(start <= brace.start() < end for start, end in ref_spans):
+            msg = (
+                f"{field} contains a malformed '${{...}}' reference. "
+                "Use '${VAR}' or '${VAR:-default}'."
+            )
+            raise RuntimeError(msg)
+
+    return _ENV_REF_RE.sub(replace, value)
+
+
+def _resolve_string(value: object, *, field: str) -> str:
+    """Validate and interpolate one string field.
+
+    Args:
+        value: Raw field value.
+        field: Fully qualified field path for error messages.
+
+    Returns:
+        The validated and interpolated string.
+
+    Raises:
+        TypeError: If the field value is not a string.
+    """
+    if not isinstance(value, str):
+        msg = f"{field} must be a string, got {type(value).__name__}"
+        raise TypeError(msg)
+    return _interpolate_env(value, field=field)
+
+
+def _resolve_mapping_values(
+    values: Mapping[str, object],
+    *,
+    field: str,
+) -> dict[str, str]:
+    """Validate and interpolate string values in a mapping field.
+
+    Args:
+        values: Raw mapping values.
+        field: Fully qualified field path for error messages.
+
+    Returns:
+        A new mapping with validated and interpolated values.
+    """
+    return {
+        name: _resolve_string(value, field=f"{field}.{name}")
+        for name, value in values.items()
+    }
+
+
+def resolve_mcp_server_env(
+    server_name: str,
+    server_config: Mapping[str, object],
+) -> dict[str, Any]:
+    """Resolve `${VAR}` references in one MCP server's supported fields.
+
+    Interpolates the `command`, `url`, `args`, `env`, and `headers`
+    fields (see `_interpolate_env` for the reference syntax); every other
+    field is copied through verbatim. The input is not mutated.
+
+    Args:
+        server_name: Server name used in field-specific error messages.
+        server_config: Raw server configuration.
+
+    Returns:
+        A resolved copy of the server configuration.
+
+    Raises:
+        TypeError: If a supported field has the wrong type — a non-string
+            scalar value, or `args`/`env`/`headers` with the wrong container
+            type.
+        RuntimeError: If a required environment variable is unset.
+    """  # noqa: DOC502 - `RuntimeError` is raised by `_interpolate_env`
+    resolved: dict[str, Any] = copy.deepcopy(dict(server_config))
+    prefix = f"mcpServers.{server_name}"
+
+    for name in ("command", "url"):
+        if name in resolved:
+            resolved[name] = _resolve_string(resolved[name], field=f"{prefix}.{name}")
+
+    if "args" in resolved:
+        args = resolved["args"]
+        if not isinstance(args, list):
+            msg = f"{prefix}.args must be a list, got {type(args).__name__}"
+            raise TypeError(msg)
+        resolved["args"] = [
+            _resolve_string(value, field=f"{prefix}.args[{index}]")
+            for index, value in enumerate(args)
+        ]
+
+    for name in ("env", "headers"):
+        if name not in resolved:
+            continue
+        values = resolved[name]
+        if not isinstance(values, dict):
+            msg = f"{prefix}.{name} must be a dictionary, got {type(values).__name__}"
+            raise TypeError(msg)
+        resolved[name] = _resolve_mapping_values(values, field=f"{prefix}.{name}")
+
+    return resolved

deepagents_code/mcp_disabled.py

@@ -0,0 +1,212 @@
+"""Persistent store of MCP server names the user has disabled.
+
+Disabled servers are skipped at config merge time so their tools never
+reach the agent and no connection is attempted. State lives under
+`[mcp].disabled_servers` in `~/.deepagents/config.toml`, alongside the
+user's other MCP configuration.
+
+The store keys on server *name* alone. Two configs that both declare a
+`github` server will both be disabled by a single entry — intentional,
+since the agent cannot distinguish overlapping names at runtime anyway
+(later configs in the merge order win).
+"""
+
+from __future__ import annotations
+
+import contextlib
+import logging
+import os
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from deepagents_code.model_config import DEFAULT_CONFIG_PATH as _DEFAULT_CONFIG_PATH
+
+logger = logging.getLogger(__name__)
+
+_SECTION = "mcp"
+_KEY = "disabled_servers"
+_LEGACY_SECTION = "mcp_disabled"
+_LEGACY_KEY = "servers"
+
+
+class _ConfigLoadError(Exception):
+    """Raised when the config exists but cannot be parsed or read.
+
+    Distinct from "file does not exist" so callers can refuse to
+    overwrite a config they could not parse — otherwise a transient
+    read error or a hand-edit typo would silently truncate sibling
+    sections (e.g. model profiles) on the next write.
+    """
+
+
+def _load_config(config_path: Path) -> dict[str, Any]:
+    """Read the TOML config file.
+
+    Args:
+        config_path: Path to the TOML config file.
+
+    Returns:
+        Parsed TOML data, or an empty dict if the file does not exist.
+
+    Raises:
+        _ConfigLoadError: If the file exists but cannot be read or parsed.
+    """
+    import tomllib
+
+    if not config_path.exists():
+        return {}
+    try:
+        with config_path.open("rb") as f:
+            return tomllib.load(f)
+    except (OSError, tomllib.TOMLDecodeError) as exc:
+        logger.warning(
+            "Could not read MCP disabled config at %s: %s",
+            config_path,
+            exc,
+        )
+        msg = f"could not load {config_path}: {exc}"
+        raise _ConfigLoadError(msg) from exc
+
+
+def _save_config(data: dict[str, Any], config_path: Path) -> bool:
+    """Atomic TOML write.
+
+    Returns:
+        `True` on success, `False` on I/O failure.
+    """
+    import tomli_w
+
+    try:
+        config_path.parent.mkdir(parents=True, exist_ok=True)
+        fd, tmp_path = tempfile.mkstemp(dir=config_path.parent, suffix=".tmp")
+        try:
+            with os.fdopen(fd, "wb") as f:
+                tomli_w.dump(data, f)
+            Path(tmp_path).replace(config_path)
+        except BaseException:
+            with contextlib.suppress(OSError):
+                Path(tmp_path).unlink()
+            raise
+    except (OSError, ValueError):
+        logger.exception("Failed to save config to %s", config_path)
+        return False
+    return True
+
+
+def _coerce_entries(entries: object) -> set[str] | None:
+    """Return valid server names from a TOML value, or `None` when unset."""
+    if not isinstance(entries, list):
+        return None
+    return {name for name in entries if isinstance(name, str) and name}
+
+
+def _disabled_entries(data: dict[str, Any]) -> set[str]:
+    """Return disabled names from the current config shape with legacy fallback."""
+    section = data.get(_SECTION)
+    if isinstance(section, dict):
+        entries = _coerce_entries(section.get(_KEY))
+        if entries is not None:
+            return entries
+
+    legacy_section = data.get(_LEGACY_SECTION)
+    if isinstance(legacy_section, dict):
+        entries = _coerce_entries(legacy_section.get(_LEGACY_KEY))
+        if entries is not None:
+            return entries
+
+    return set()
+
+
+def _remove_legacy_disabled_section(data: dict[str, Any]) -> None:
+    """Drop the old top-level section after writing the folded config shape."""
+    legacy_section = data.get(_LEGACY_SECTION)
+    if not isinstance(legacy_section, dict):
+        data.pop(_LEGACY_SECTION, None)
+        return
+    legacy_section.pop(_LEGACY_KEY, None)
+    if legacy_section:
+        data[_LEGACY_SECTION] = legacy_section
+    else:
+        data.pop(_LEGACY_SECTION, None)
+
+
+def get_disabled_servers(*, config_path: Path | None = None) -> set[str]:
+    """Return the set of server names the user has disabled.
+
+    Args:
+        config_path: Override the default config location; intended for tests.
+
+    Returns:
+        Set of server names. Empty when nothing is disabled or the config
+        cannot be read.
+    """
+    if config_path is None:
+        config_path = _DEFAULT_CONFIG_PATH
+    try:
+        data = _load_config(config_path)
+    except _ConfigLoadError:
+        return set()
+    return _disabled_entries(data)
+
+
+def is_server_disabled(server_name: str, *, config_path: Path | None = None) -> bool:
+    """Return `True` when `server_name` is in the disabled set.
+
+    Args:
+        server_name: MCP server name from `mcpServers` config.
+        config_path: Override the default config location; intended for tests.
+
+    Returns:
+        `True` when the server is recorded as disabled, `False` otherwise
+        (including when the config cannot be read).
+    """
+    return server_name in get_disabled_servers(config_path=config_path)
+
+
+def set_server_disabled(
+    server_name: str,
+    disabled: bool,
+    *,
+    config_path: Path | None = None,
+) -> tuple[bool, str | None]:
+    """Add or remove `server_name` from the persistent disabled set.
+
+    Refuses to write when the existing config cannot be parsed so a
+    corrupt or permission-denied file is not silently overwritten —
+    that would discard sibling sections such as model profiles.
+
+    Args:
+        server_name: MCP server name from `mcpServers` config.
+        disabled: `True` to disable, `False` to re-enable.
+        config_path: Override the default config location; intended for tests.
+
+    Returns:
+        Tuple of `(ok, error_detail)`. `ok` is `True` on success; on
+        failure `error_detail` is a short user-facing string suitable
+        for a toast.
+    """
+    if config_path is None:
+        config_path = _DEFAULT_CONFIG_PATH
+    try:
+        data = _load_config(config_path)
+    except _ConfigLoadError as exc:
+        return False, str(exc)
+    current = _disabled_entries(data)
+    previous = set(current)
+    if disabled:
+        current.add(server_name)
+    else:
+        current.discard(server_name)
+    if current == previous and _LEGACY_SECTION not in data:
+        return True, None
+
+    section = data.get(_SECTION)
+    if not isinstance(section, dict):
+        section = {}
+    section[_KEY] = sorted(current)
+    data[_SECTION] = section
+    _remove_legacy_disabled_section(data)
+    if _save_config(data, config_path):
+        return True, None
+    return False, f"could not write {config_path}"

deepagents_code/mcp_login_service.py

@@ -0,0 +1,281 @@
+"""UI-agnostic helpers for resolving an MCP login target.
+
+The MCP login flow historically inlined config discovery, trust gating,
+shape validation, and `print()`-based error reporting. The TUI cannot
+consume those print statements, so this module extracts the same logic
+into pure functions that return structured results (`ConfigResolution`,
+`ServerSelection`) plus a typed `ConfigResolutionError`. Callers decide
+how to render those results.
+
+No `print()` calls live in this module. No imports happen at module
+top level beyond `dataclasses`/`typing`/`pathlib` so the CLI fast path
+stays cheap; the actual config loaders are imported inside the
+functions that need them.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from deepagents_code.mcp_auth import McpServerSpec
+
+
+class ConfigErrorKind(StrEnum):
+    """Discriminator for `ConfigResolutionError` reasons.
+
+    Only `NO_CONFIG_FOUND` maps to exit code 2 in `run_mcp_login`; all
+    other kinds map to exit code 1. The TUI surface translates them into
+    in-app status messages.
+    """
+
+    EXPLICIT_LOAD_FAILED = "explicit_load_failed"
+    """The `--mcp-config` path could not be parsed."""
+
+    NO_CONFIG_FOUND = "no_config_found"
+    """Auto-discovery returned zero candidate paths."""
+
+    NO_USABLE_CONFIG = "no_usable_config"
+    """Discovered paths existed but none could be loaded successfully."""
+
+    UNKNOWN_SERVER = "unknown_server"
+    """The selected server is not present in the resolved config."""
+
+    INVALID_SERVER_CONFIG = "invalid_server_config"
+    """The selected server's entry failed shape validation."""
+
+
+@dataclass(frozen=True)
+class ConfigResolutionError:
+    """Structured error returned when a login target cannot be resolved."""
+
+    kind: ConfigErrorKind
+    """Reason category — callers translate this into UI text or exit codes."""
+
+    message: str
+    """Plain-text description suitable for direct display to the user."""
+
+    untrusted_project_paths: tuple[Path, ...] = ()
+    """Project-level configs skipped because the trust store had no match.
+
+    Populated only when at least one discovered project config was
+    skipped during auto-discovery, regardless of `kind`. Callers can
+    surface a "skipping untrusted project config" hint alongside the
+    primary error.
+    """
+
+
+@dataclass(frozen=True)
+class ConfigResolution:
+    """Successful resolution of a merged MCP config for login."""
+
+    config: dict[str, Any]
+    """The merged `mcpServers`-shaped config dict."""
+
+    used_paths: tuple[Path, ...]
+    """Paths whose contents were merged into `config`, in precedence order."""
+
+    untrusted_project_paths: tuple[Path, ...] = ()
+    """Project-level configs that were skipped during this resolution."""
+
+    def __post_init__(self) -> None:
+        """Enforce the non-empty `used_paths` invariant.
+
+        Raises:
+            ValueError: If `used_paths` is empty.
+        """
+        if not self.used_paths:
+            msg = "ConfigResolution must have at least one used path"
+            raise ValueError(msg)
+
+    @property
+    def search_label(self) -> str:
+        """Human-readable join of the paths backing this resolution."""
+        return ", ".join(str(path) for path in self.used_paths)
+
+
+@dataclass(frozen=True)
+class ServerSelection:
+    """Resolved server config plus enough context for error messages."""
+
+    server_name: str
+    """Selected MCP server name (matches an `mcpServers` key)."""
+
+    server_config: McpServerSpec
+    """Validated server config payload for `mcp_auth.login`."""
+
+    search_label: str = ""
+    """Where the config came from — used in not-found errors."""
+
+    def __post_init__(self) -> None:
+        """Enforce the non-empty `server_name` invariant.
+
+        Raises:
+            ValueError: If `server_name` is empty.
+        """
+        if not self.server_name:
+            msg = "ServerSelection.server_name must not be empty"
+            raise ValueError(msg)
+
+
+def resolve_mcp_config(
+    config_path: str | None,
+) -> ConfigResolution | ConfigResolutionError:
+    """Resolve an MCP config dict for login without printing anything.
+
+    Args:
+        config_path: Explicit `--mcp-config` path, or `None` for auto-discovery.
+
+    Returns:
+        A `ConfigResolution` on success, or a `ConfigResolutionError`
+            describing why no usable config could be assembled.
+    """
+    from deepagents_code.mcp_tools import (
+        classify_discovered_configs,
+        discover_mcp_configs,
+        load_mcp_config,
+        load_mcp_config_lenient,
+        merge_mcp_configs,
+    )
+
+    if config_path is not None:
+        try:
+            config = load_mcp_config(config_path)
+        except (OSError, TypeError, ValueError, RuntimeError) as exc:
+            return ConfigResolutionError(
+                kind=ConfigErrorKind.EXPLICIT_LOAD_FAILED,
+                message=f"Failed to load MCP config {config_path}: {exc}",
+            )
+        return ConfigResolution(
+            config=config,
+            used_paths=(Path(config_path),),
+        )
+
+    found = discover_mcp_configs()
+    if not found:
+        return ConfigResolutionError(
+            kind=ConfigErrorKind.NO_CONFIG_FOUND,
+            message=(
+                "No MCP config file found in any auto-discovered location. "
+                "Pass --mcp-config <path>, or run `dcode mcp login --help` "
+                "to see the search paths and config format."
+            ),
+        )
+
+    user_paths, project_paths = classify_discovered_configs(found)
+    configs: list[dict[str, Any]] = []
+    used_paths: list[Path] = []
+    untrusted: tuple[Path, ...] = ()
+
+    for path in user_paths:
+        loaded = load_mcp_config_lenient(path)
+        if loaded is not None:
+            configs.append(loaded)
+            used_paths.append(path)
+
+    if project_paths:
+        from deepagents_code.mcp_trust import (
+            compute_config_fingerprint,
+            is_project_mcp_trusted,
+        )
+        from deepagents_code.project_utils import find_project_root
+
+        project_root = str((find_project_root() or Path.cwd()).resolve())
+        fingerprint = compute_config_fingerprint(project_paths)
+        if is_project_mcp_trusted(project_root, fingerprint):
+            for path in project_paths:
+                loaded = load_mcp_config_lenient(path)
+                if loaded is not None:
+                    configs.append(loaded)
+                    used_paths.append(path)
+        else:
+            untrusted = tuple(project_paths)
+
+    if not configs:
+        found_paths = ", ".join(str(path) for path in found)
+        return ConfigResolutionError(
+            kind=ConfigErrorKind.NO_USABLE_CONFIG,
+            message=f"No usable MCP config found in: {found_paths}",
+            untrusted_project_paths=untrusted,
+        )
+
+    return ConfigResolution(
+        config=merge_mcp_configs(configs),
+        used_paths=tuple(used_paths),
+        untrusted_project_paths=untrusted,
+    )
+
+
+def select_server(
+    resolution: ConfigResolution,
+    server: str,
+) -> ServerSelection | ConfigResolutionError:
+    """Pull `server` out of a resolved config and validate its shape.
+
+    Args:
+        resolution: A successful `resolve_mcp_config` result.
+        server: Target server name as supplied by the user.
+
+    Returns:
+        A `ServerSelection` on success, or a `ConfigResolutionError`
+            describing why the server entry is unusable.
+    """
+    from deepagents_code.mcp_tools import _validate_server_config
+
+    servers = resolution.config.get("mcpServers", {})
+    if server not in servers:
+        return ConfigResolutionError(
+            kind=ConfigErrorKind.UNKNOWN_SERVER,
+            message=(
+                f"Server {server!r} not found in {resolution.search_label}. "
+                f"Known servers: {sorted(servers)}"
+            ),
+        )
+
+    try:
+        _validate_server_config(server, servers[server])
+    except (TypeError, ValueError) as exc:
+        return ConfigResolutionError(
+            kind=ConfigErrorKind.INVALID_SERVER_CONFIG,
+            message=f"Invalid MCP server config for {server!r}: {exc}",
+        )
+
+    return ServerSelection(
+        server_name=server,
+        server_config=servers[server],
+        search_label=resolution.search_label,
+    )
+
+
+def format_untrusted_project_notice(paths: tuple[Path, ...]) -> str:
+    """Build the CLI-style hint string for skipped untrusted project configs.
+
+    Args:
+        paths: Project configs that were skipped during resolution.
+
+    Returns:
+        A single-line user-facing string. Empty when `paths` is empty.
+    """
+    if not paths:
+        return ""
+    skipped = ", ".join(str(path) for path in paths)
+    return (
+        "Skipping untrusted project MCP config "
+        f"(not yet approved or config changed): {skipped}. "
+        "Approve it by running `dcode` in this project, or "
+        "pass --mcp-config <path> to use it explicitly."
+    )
+
+
+__all__ = [
+    "ConfigErrorKind",
+    "ConfigResolution",
+    "ConfigResolutionError",
+    "ServerSelection",
+    "format_untrusted_project_notice",
+    "resolve_mcp_config",
+    "select_server",
+]