talkops-opscloud 0.3.0b1__py3-none-any.whl

opscloud/mcp/config.py

@@ -0,0 +1,203 @@
+"""Validation and environment-variable expansion for MCP server config.
+
+Resolves `${VAR}` and `${VAR:-default}` references in 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:
+        """Resolve regex environment variable substitution match.
+
+        Args:
+            match: Regular expression match containing variable name and default.
+
+        Returns:
+            str: Resolved environment variable value or fallback default.
+
+        Raises:
+            RuntimeError: If variable is required and unset without a default.
+        """
+        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:
+            if (resolved.startswith('"') and resolved.endswith('"')) or (
+                resolved.startswith("'") and resolved.endswith("'")
+            ):
+                resolved = resolved[1:-1]
+            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).
+            if (default.startswith('"') and default.endswith('"')) or (
+                default.startswith("'") and default.endswith("'")
+            ):
+                default = default[1:-1]
+            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}. Set {name} in the environment or provide a default."
+        raise RuntimeError(msg)
+
+    # Reject any `${` that isn't the start of a well-formed reference.
+    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."""
+    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."""
+    result: dict[str, str] = {}
+    for name, value in values.items():
+        resolved_val = _resolve_string(value, field=f"{field}.{name}")
+        if field.endswith("headers"):
+            resolved_val = resolved_val.strip()
+            if (resolved_val.startswith('"') and resolved_val.endswith('"')) or (
+                resolved_val.startswith("'") and resolved_val.endswith("'")
+            ):
+                resolved_val = resolved_val[1:-1].strip()
+        result[name] = resolved_val
+    return result
+
+
+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; 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 or reference is malformed.
+    """
+    resolved: dict[str, Any] = copy.deepcopy(dict(server_config))
+    prefix = f"mcpServers.{server_name}"
+
+    for name in ("command", "url"):
+        if name in resolved and resolved[name] is not None:
+            resolved[name] = _resolve_string(resolved[name], field=f"{prefix}.{name}")
+
+    if "args" in resolved and resolved["args"] is not None:
+        args = resolved["args"]
+        if not isinstance(args, (list, tuple)):
+            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 or resolved[name] is None:
+            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
+
+
+def sync_mcp_env_aliases() -> None:
+    """Harmonize environment variable aliases for MCP server compatibility.
+
+    Ensures bidirectional synchronization between standard cloud/AWS config keys:
+    - AWS_REGION <-> AWS_DEFAULT_REGION
+    - AWS_PROFILE <-> AWS_DEFAULT_PROFILE
+    - KUBECONFIG <-> K8S_KUBECONFIG
+    """
+    # AWS Region
+    region = os.environ.get("AWS_REGION")
+    default_region = os.environ.get("AWS_DEFAULT_REGION")
+    if region and not default_region:
+        os.environ["AWS_DEFAULT_REGION"] = region
+    elif default_region and not region:
+        os.environ["AWS_REGION"] = default_region
+
+    # AWS Profile
+    profile = os.environ.get("AWS_PROFILE")
+    default_profile = os.environ.get("AWS_DEFAULT_PROFILE")
+    if profile and not default_profile:
+        os.environ["AWS_DEFAULT_PROFILE"] = profile
+    elif default_profile and not profile:
+        os.environ["AWS_PROFILE"] = default_profile
+
+    # Kubeconfig
+    kube = os.environ.get("KUBECONFIG")
+    k8s_kube = os.environ.get("K8S_KUBECONFIG")
+    if kube and not k8s_kube:
+        os.environ["K8S_KUBECONFIG"] = kube
+    elif k8s_kube and not kube:
+        os.environ["KUBECONFIG"] = k8s_kube
+

opscloud/mcp/discovery.py

@@ -0,0 +1,229 @@
+"""Discovers and parses MCP server configs from files with clear precedence.
+
+Pure file-based discovery (no database dependency):
+Precedence (lowest to highest):
+1. Global user configs (~/.agents/mcp.json, ~/.agents/.mcp.json)
+2. User configs (~/.opscloud/mcp.json, ~/.opscloud/.mcp.json)
+3. Plugin-declared MCP configs
+4. Project configs (e.g. {project_root}/.opscloud/mcp.json, {project_root}/.mcp.json)
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, TypedDict
+
+from opscloud.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class MCPServerConfig(TypedDict, total=False):
+    """Configuration for a discovered MCP server (command, args, env, transport)."""
+
+    command: str | None
+    args: list[str] | None
+    env: dict[str, str] | None
+    url: str | None
+    transport: str | None
+    headers: dict[str, str] | None
+    source: str | None
+    auth_token_env_var: str | None
+    disabled_tools: list[str] | None
+    allowed_tools: list[str] | None
+    enabled: bool
+    trusted: bool
+
+
+def _load_mcp_json(path: Path) -> dict[str, dict[str, Any]]:
+    """Safely load and parse an .mcp.json file into a dictionary of server configs."""
+    if not path.is_file():
+        return {}
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+        if not isinstance(data, dict):
+            return {}
+
+        servers = data.get("mcpServers") or data.get("mcp_servers")
+        if servers is None and ("command" in data or "url" in data or "serverUrl" in data):
+            # Single server definition (fallback)
+            servers = {path.stem: data}
+        elif servers is None:
+            # Check if root dict is already mapping name -> config
+            if data and all(
+                isinstance(v, dict) and ("command" in v or "url" in v or "serverUrl" in v)
+                for v in data.values()
+            ):
+                servers = data
+
+        if isinstance(servers, dict):
+            return servers
+    except Exception as exc:
+        logger.warning("Failed to parse MCP config at %s: %s", path, exc)
+    return {}
+
+
+def _parse_server_config(
+    name: str, config: dict[str, Any], source_name: str
+) -> MCPServerConfig:
+    """Normalize a raw server config dictionary into MCPServerConfig."""
+    url = config.get("url") or config.get("serverUrl")
+    command = config.get("command")
+    transport = config.get("transport") or config.get("type")
+    if not transport:
+        transport = ("sse" if "sse" in str(url).lower() else "http") if url else "stdio"
+
+    # Enabled status
+    enabled = True
+    if "disabled" in config:
+        enabled = not bool(config["disabled"])
+    elif "enabled" in config:
+        enabled = bool(config["enabled"])
+
+    raw_disabled = config.get("disabled_tools") or config.get("disabledTools") or []
+    raw_allowed = config.get("allowed_tools") or config.get("allowedTools") or []
+
+    disabled_tools = list(raw_disabled) if isinstance(raw_disabled, (list, tuple)) else []
+    allowed_tools = list(raw_allowed) if isinstance(raw_allowed, (list, tuple)) else []
+
+    trusted = bool(config.get("trusted", source_name != "project"))
+
+    return MCPServerConfig(
+        command=command,
+        args=list(config.get("args") or []),
+        env=dict(config.get("env") or {}),
+        url=url,
+        transport=transport,
+        headers=dict(config.get("headers") or {}),
+        source=source_name,
+        auth_token_env_var=config.get("auth_token_env_var"),
+        disabled_tools=disabled_tools,
+        allowed_tools=allowed_tools,
+        enabled=enabled,
+        trusted=trusted,
+    )
+
+
+class MCPDiscovery:
+    """Discovers and parses MCP server configs from filesystem sources."""
+
+    def __init__(self, store: Any = None) -> None:
+        """Initialize MCPDiscovery.
+        
+        Args:
+            store: Kept for backwards compatibility; not used in terminal file-based model.
+        """
+        self._store = store
+
+    def discover(self, project_root: Path | None = None) -> dict[str, MCPServerConfig]:
+        """Discover and merge MCP server configs across global, user, plugin, and project files.
+
+        Precedence (lowest to highest):
+          1. Global configs (~/.agents/mcp.json)
+          2. User configs (~/.opscloud/.mcp.json)
+          3. Plugin-declared configs
+          4. Project configs (project root .mcp.json)
+        """
+        from opscloud.config import paths
+
+        effective_project_root = project_root or Path.cwd()
+
+        # Build candidate file list in lowest -> highest precedence order
+        candidates: list[tuple[Path, str]] = []
+
+        # 1. Global user configs (~/.agents/)
+        candidates.append((paths.AGENTS_SHARED_DIR / "mcp.json", "global"))
+        candidates.append((paths.AGENTS_SHARED_DIR / ".mcp.json", "global"))
+
+        # 2. User data dir configs (~/.opscloud/)
+        candidates.append((paths.DATA_DIR / "mcp.json", "user"))
+        candidates.append((paths.GLOBAL_MCP_PATH, "user"))
+
+        merged_servers: dict[str, MCPServerConfig] = {}
+
+        # Load global and user configs first
+        for path, source_name in candidates:
+            servers = _load_mcp_json(path)
+            for name, config in servers.items():
+                if isinstance(config, dict):
+                    clean_config = _parse_server_config(name, config, source_name)
+                    if name not in merged_servers:
+                        merged_servers[name] = clean_config
+                    else:
+                        merged_servers[name] = {**merged_servers[name], **clean_config}
+
+        # 3. Discover plugin-declared MCP servers
+        try:
+            from opscloud.plugins.adapters.mcp import discover_plugin_mcp_configs
+
+            plugin_configs = discover_plugin_mcp_configs(project_dir=effective_project_root)
+            if isinstance(plugin_configs, dict):
+                for name, config in plugin_configs.items():
+                    if isinstance(config, dict):
+                        clean_config = _parse_server_config(name, config, "plugin")
+                        if name not in merged_servers:
+                            merged_servers[name] = clean_config
+                        else:
+                            merged_servers[name] = {**merged_servers[name], **clean_config}
+        except Exception as exc:
+            logger.debug("Could not discover plugin MCP configs: %s", exc)
+
+        # 3b. Local workspace plugins (.mcp.json in plugins/ directories)
+        plugins_dir = effective_project_root / "plugins"
+        if plugins_dir.is_dir():
+            for plugin in sorted(plugins_dir.iterdir()):
+                if plugin.is_dir() and not plugin.name.startswith("."):
+                    from opscloud.plugins.models import is_agent_plugin_dir
+
+                    if is_agent_plugin_dir(plugin):
+                        continue  # Dynamic subagent plugins isolate their own MCP servers
+                    for candidate in (plugin / ".mcp.json", plugin / "mcp.json"):
+                        if candidate.is_file():
+                            for name, config in _load_mcp_json(candidate).items():
+                                if isinstance(config, dict):
+                                    clean_config = _parse_server_config(
+                                        name, config, f"plugin:{plugin.name}"
+                                    )
+                                    if name not in merged_servers:
+                                        merged_servers[name] = clean_config
+                                    else:
+                                        merged_servers[name] = {**merged_servers[name], **clean_config}
+
+        # 4. Project configs (lowest to highest project precedence)
+        # Note: paths.project_mcp_paths lists [.mcp.json, mcp.json, .opscloud/.mcp.json, .opscloud/mcp.json]
+        # Reversing them means .mcp.json in the project root is loaded last and wins.
+        project_candidate_paths = list(reversed(paths.project_mcp_paths(effective_project_root)))
+        for path in project_candidate_paths:
+            servers = _load_mcp_json(path)
+            for name, config in servers.items():
+                if isinstance(config, dict):
+                    clean_config = _parse_server_config(name, config, "project")
+                    if name not in merged_servers:
+                        merged_servers[name] = clean_config
+                    else:
+                        merged_servers[name] = {**merged_servers[name], **clean_config}
+
+        return merged_servers
+
+    async def discover_and_sync_async(
+        self, project_root: Path | None = None, store: Any = None
+    ) -> dict[str, MCPServerConfig]:
+        """Asynchronous discover entrypoint for compatibility.
+        
+        Discovers configs from disk and registers them with MCPSessionManager.
+        """
+        results = self.discover(project_root=project_root)
+        try:
+            from opscloud.mcp.session_manager import MCPSessionManager
+
+            MCPSessionManager.get_instance(results, purge_missing=False)
+        except Exception as e:
+            logger.debug("Failed to sync discovered configs to MCPSessionManager: %s", e)
+        return results
+
+
+def discover_mcp_configs(project_root: Path | None = None) -> dict[str, MCPServerConfig]:
+    """Discover active MCP server configs from disk."""
+    return MCPDiscovery().discover(project_root)

opscloud/mcp/mcp_info.py

@@ -0,0 +1,109 @@
+"""Data structures for MCP server and tool metadata."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+MCPServerStatus = Literal["ok", "unauthenticated", "error", "disabled", "disconnected"]
+
+
+@dataclass(frozen=True)
+class MCPToolInfo:
+    """Lightweight metadata about a single tool exposed by an MCP server."""
+
+    name: str
+    description: str = ""
+    input_schema: dict[str, Any] | None = None
+    original_name: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert MCPToolInfo to a JSON-serializable dictionary.
+
+        Returns:
+            dict[str, Any]: Dictionary containing tool name, description, and input schema.
+        """
+        res: dict[str, Any] = {
+            "name": self.name,
+            "description": self.description,
+            "input_schema": self.input_schema or {},
+        }
+        if self.original_name is not None:
+            res["original_name"] = self.original_name
+        return res
+
+
+@dataclass(frozen=True)
+class MCPServerInfo:
+    """Metadata about a configured MCP server, including probed tools."""
+
+    name: str
+    transport: str = "stdio"
+    status: MCPServerStatus = "ok"
+    error: str | None = None
+    tools: tuple[MCPToolInfo, ...] = ()
+    enabled: bool = True
+    source: str = "project"
+    url: str | None = None
+    command: str | None = None
+    args: tuple[str, ...] = ()
+    headers: dict[str, str] = field(default_factory=dict)
+    env: dict[str, str] = field(default_factory=dict)
+    disabled_tools: tuple[str, ...] = ()
+    allowed_tools: tuple[str, ...] = ()
+
+    @property
+    def is_disabled(self) -> bool:
+        """Check whether the server is disabled.
+
+        Returns:
+            bool: True if server is disabled.
+        """
+        return not self.enabled
+
+    @property
+    def tool_count(self) -> int:
+        """Count of tools exposed by this server.
+
+        Returns:
+            int: Number of exposed tools.
+        """
+        return len(self.tools)
+
+    @property
+    def display_target(self) -> str:
+        """Human-readable target URL or command line.
+
+        Returns:
+            str: URL for network servers or joined command string for stdio.
+        """
+        if self.transport in ("http", "sse", "streamable_http"):
+            return self.url or ""
+        if self.command:
+            parts = [self.command, *self.args]
+            return " ".join(parts)
+        return ""
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize server metadata to dictionary format.
+
+        Returns:
+            dict[str, Any]: JSON-compatible dictionary of server properties.
+        """
+        res: dict[str, Any] = {
+            "name": self.name,
+            "transport": self.transport,
+            "status": self.status,
+            "error": self.error,
+            "url": self.url,
+            "command": self.command,
+            "args": list(self.args),
+            "tool_count": self.tool_count,
+            "tools": [t.to_dict() for t in self.tools],
+            "enabled": self.enabled,
+        }
+        return res
+
+    def needs_attention(self) -> bool:
+        """Return whether this server requires user action."""
+        return self.status in {"unauthenticated", "error", "disconnected"}

opscloud/mcp/middleware.py

@@ -0,0 +1,102 @@
+"""MCP Discovery Middleware — discovers project-level .mcp.json and binds to domain.
+
+Registered as ``mcp_discovery`` in the middleware registry. When included
+in a coordinator's middleware list, it:
+  1. Scans project-level ``.mcp.json`` files
+  2. Merges discovered servers with ``DefaultConfig.MCP_SERVERS``
+  3. Filters by domain binding (e.g. Helm only gets helm-related servers)
+  4. Updates the runtime's MCP tool list
+
+Usage in coordinator::
+
+    custom_mws = get_middleware_registry().build_middlewares([
+        "operation_context",
+        ("mcp_discovery", {"domain": "helm-operator"}),
+    ])
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from opscloud.middleware.registry import (
+    BaseAgentMiddleware,
+    register_middleware,
+)
+from opscloud.utils.logger import AgentLogger
+
+logger = AgentLogger("MCPDiscoveryMW")
+
+
+@register_middleware(name="mcp_discovery")
+class MCPDiscoveryMiddleware(BaseAgentMiddleware):
+    """Discover project-level .mcp.json and bind MCP servers to domain.
+
+    When attached to a coordinator, this middleware runs during agent
+    initialization to discover additional MCP servers from project-level
+    config files and filter them by the coordinator's domain.
+
+    Args:
+        domain: Coordinator domain name (e.g. "helm-operator").
+            If None, no domain filtering is applied.
+        project_root: Root directory for .mcp.json scanning.
+            Defaults to the config's AGENT_PROJECT_ROOT.
+        config: Config instance for resolving defaults.
+    """
+
+    def __init__(
+        self,
+        *,
+        domain: str | None = None,
+        project_root: str | None = None,
+        config: Any = None,
+        **kwargs: Any,
+    ) -> None:
+        """Initialize MCPDiscoveryMiddleware.
+
+        Args:
+            domain: Optional coordinator domain filter.
+            project_root: Optional root directory path for discovery.
+            config: Optional configuration settings instance.
+            **kwargs: Additional keyword arguments.
+        """
+        super().__init__()
+        self._domain = domain
+        self._project_root = project_root
+        self._config = config
+        self._discovered_servers: list[dict[str, Any]] = []
+
+    def _get_config(self) -> Any:
+        """Lazy config resolution."""
+        if self._config is None:
+            from opscloud.config.settings import get_settings
+
+            self._config = get_settings()
+        return self._config
+
+    def discover_and_bind(self) -> list[dict[str, Any]]:
+        """Run discovery and domain binding, return filtered server list.
+
+        This is the main entry point. It:
+          1. Discovers project-level .mcp.json servers
+          2. Merges with defaults from config
+          3. Filters by domain binding
+
+        Returns:
+            Filtered MCP server list (dicts in DefaultConfig format).
+        """
+        from opscloud.mcp.discovery import discover_mcp_configs
+
+        discovered = discover_mcp_configs()
+        merged = [{"name": k, "config": v} for k, v in (discovered.items() if isinstance(discovered, dict) else [])]
+        self._discovered_servers = merged
+
+        if discovered:
+            logger.info(f"MCP Discovery: {len(discovered):d} servers discovered")
+
+        return merged
+
+    @property
+    def discovered_servers(self) -> list[dict[str, Any]]:
+        """Return the last discovered and bound server list."""
+        return self._discovered_servers