apm-cli 0.19.0__tar.gz → 0.20.0__tar.gz

{apm_cli-0.19.0/src/apm_cli.egg-info → apm_cli-0.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: apm-cli
-Version: 0.19.0
+Version: 0.20.0
 Summary: MCP configuration tool
 Author-email: Daniel Meppiel <user@example.com>
 License: MIT License
@@ -72,7 +72,7 @@ Dynamic: license-file
 
 Think `package.json`, `requirements.txt`, or `Cargo.toml` — but for AI agent configuration.
 
-GitHub Copilot · Claude Code · Cursor · OpenCode · Codex · Gemini · Windsurf
+GitHub Copilot · Claude Code · Cursor · OpenCode · Codex · Gemini · Windsurf · Kiro
 
 **[Documentation](https://microsoft.github.io/apm/)** · **[Quick Start](https://microsoft.github.io/apm/getting-started/quick-start/)** · **[CLI Reference](https://microsoft.github.io/apm/reference/cli-commands/)** · **[Roadmap](https://github.com/orgs/microsoft/projects/2304)**
 
@@ -135,7 +135,7 @@ One command, no configuration -- VS Code and GitHub Copilot read the file automa
 
 One `apm.yml` describes every primitive your agents need — instructions, skills, prompts, agents, hooks, plugins, MCP servers — and `apm install` reproduces the exact same setup across every client on every machine. `apm.lock.yaml` pins the resolved tree the way `package-lock.json` does for npm.
 
-- **[One manifest for everything](https://microsoft.github.io/apm/reference/primitive-types/)** — declared once, deployed across Copilot, Claude, Cursor, OpenCode, Codex, Gemini, Windsurf
+- **[One manifest for everything](https://microsoft.github.io/apm/reference/primitive-types/)** — declared once, deployed across Copilot, Claude, Cursor, OpenCode, Codex, Gemini, Windsurf, Kiro
 - **[Install from anywhere](https://microsoft.github.io/apm/guides/dependencies/)** — GitHub, GitLab, Bitbucket, Azure DevOps, GitHub Enterprise, Gitea, Gogs, any git host
 - **[Transitive dependencies](https://microsoft.github.io/apm/guides/dependencies/)** — packages can depend on packages; APM resolves the full tree
 - **[Author plugins](https://microsoft.github.io/apm/guides/plugins/)** — build Copilot, Claude, and Cursor plugins with dependency management, then export standard `plugin.json`
@@ -214,7 +214,7 @@ apm marketplace add github/awesome-copilot
 apm install azure-cloud-development@awesome-copilot
 ```
 
-Or add an MCP server (wired into Copilot, Claude, Cursor, Codex, OpenCode, Gemini, and Windsurf):
+Or add an MCP server (wired into Copilot, Claude, Cursor, Codex, OpenCode, Gemini, Windsurf, and Kiro):
 
 ```bash
 apm install --mcp io.github.github/github-mcp-server --transport http   # connects over HTTPS

{apm_cli-0.19.0 → apm_cli-0.20.0}/README.md

@@ -4,7 +4,7 @@
 
 Think `package.json`, `requirements.txt`, or `Cargo.toml` — but for AI agent configuration.
 
-GitHub Copilot · Claude Code · Cursor · OpenCode · Codex · Gemini · Windsurf
+GitHub Copilot · Claude Code · Cursor · OpenCode · Codex · Gemini · Windsurf · Kiro
 
 **[Documentation](https://microsoft.github.io/apm/)** · **[Quick Start](https://microsoft.github.io/apm/getting-started/quick-start/)** · **[CLI Reference](https://microsoft.github.io/apm/reference/cli-commands/)** · **[Roadmap](https://github.com/orgs/microsoft/projects/2304)**
 
@@ -67,7 +67,7 @@ One command, no configuration -- VS Code and GitHub Copilot read the file automa
 
 One `apm.yml` describes every primitive your agents need — instructions, skills, prompts, agents, hooks, plugins, MCP servers — and `apm install` reproduces the exact same setup across every client on every machine. `apm.lock.yaml` pins the resolved tree the way `package-lock.json` does for npm.
 
-- **[One manifest for everything](https://microsoft.github.io/apm/reference/primitive-types/)** — declared once, deployed across Copilot, Claude, Cursor, OpenCode, Codex, Gemini, Windsurf
+- **[One manifest for everything](https://microsoft.github.io/apm/reference/primitive-types/)** — declared once, deployed across Copilot, Claude, Cursor, OpenCode, Codex, Gemini, Windsurf, Kiro
 - **[Install from anywhere](https://microsoft.github.io/apm/guides/dependencies/)** — GitHub, GitLab, Bitbucket, Azure DevOps, GitHub Enterprise, Gitea, Gogs, any git host
 - **[Transitive dependencies](https://microsoft.github.io/apm/guides/dependencies/)** — packages can depend on packages; APM resolves the full tree
 - **[Author plugins](https://microsoft.github.io/apm/guides/plugins/)** — build Copilot, Claude, and Cursor plugins with dependency management, then export standard `plugin.json`
@@ -146,7 +146,7 @@ apm marketplace add github/awesome-copilot
 apm install azure-cloud-development@awesome-copilot
 ```
 
-Or add an MCP server (wired into Copilot, Claude, Cursor, Codex, OpenCode, Gemini, and Windsurf):
+Or add an MCP server (wired into Copilot, Claude, Cursor, Codex, OpenCode, Gemini, Windsurf, and Kiro):
 
 ```bash
 apm install --mcp io.github.github/github-mcp-server --transport http   # connects over HTTPS

{apm_cli-0.19.0 → apm_cli-0.20.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "apm-cli"
-version = "0.19.0"
+version = "0.20.0"
 description = "MCP configuration tool"
 readme = "README.md"
 requires-python = ">=3.10"

{apm_cli-0.19.0 → apm_cli-0.20.0}/src/apm_cli/adapters/client/base.py

@@ -4,7 +4,7 @@ import os
 import re
 from abc import ABC, abstractmethod
 from pathlib import Path
-from typing import ClassVar
+from typing import Any, ClassVar
 
 from ...utils.console import _rich_error, _rich_warning
 
@@ -29,6 +29,11 @@ _ENV_PLACEHOLDER_RE = re.compile(r"<([A-Z_][A-Z0-9_]*)>|" + _ENV_VAR_RE.pattern)
 _LEGACY_ANGLE_VAR_RE = re.compile(r"<([A-Z_][A-Z0-9_]*)>")
 
 
+def registry_field_is_required(field: dict[str, Any]) -> bool:
+    """Return True unless registry metadata explicitly marks a field optional."""
+    return field.get("required", field.get("is_required", True)) is not False
+
+
 def _translate_env_placeholder(value):
     """Pure-textual translation of env-var placeholders to the canonical
     ``${VAR}`` runtime-substitution syntax.
@@ -481,7 +486,7 @@ class MCPClientAdapter(ABC):
             name = env_var.get("name", "")
             if not name:
                 continue
-            required = env_var.get("required", True)
+            required = registry_field_is_required(env_var)
 
             value = env_overrides.get(name) or os.getenv(name)
             if not value and required and not skip_prompting:
@@ -797,12 +802,15 @@ class MCPClientAdapter(ABC):
         )
 
         # First pass: identify variables with empty values to warn the user.
-        empty_value_vars = [ev for ev in env_vars if ev.get("required") and not ev.get("value")]
+        empty_value_vars = [
+            ev for ev in env_vars if registry_field_is_required(ev) and not ev.get("value")
+        ]
         if empty_value_vars and skip_prompting:
             var_names = [ev.get("name") for ev in empty_value_vars]
             _rich_warning(
-                f"Warning: The following required environment variables have no default "
-                f"value and cannot be prompted in non-interactive mode: {var_names}"
+                f"Required environment variables have no default value and cannot be "
+                f"prompted in non-interactive mode: {var_names}. Set them in your "
+                "environment and rerun `apm install`."
             )
 
         for env_var in env_vars:
@@ -837,9 +845,9 @@ class MCPClientAdapter(ABC):
 
             # Priority 4: interactive prompt
             default_value = env_var.get("value", "")
-            required = env_var.get("required", False)
+            required = registry_field_is_required(env_var)
 
-            if not skip_prompting:
+            if not skip_prompting and required:
                 from rich.prompt import Prompt
 
                 description = env_var.get("description", "")
@@ -859,11 +867,10 @@ class MCPClientAdapter(ABC):
                 resolved[name] = default_value
             elif required:
                 _rich_warning(
-                    f"Warning: Required environment variable '{name}' could not be resolved. "
-                    f"The MCP server may not function correctly."
+                    f"Required environment variable '{name}' could not be resolved. "
+                    f"The MCP server may not function correctly. Set {name} in your "
+                    "environment and rerun `apm install`."
                 )
                 resolved[name] = ""
-            else:
-                resolved[name] = default_value
 
         return resolved

{apm_cli-0.19.0 → apm_cli-0.20.0}/src/apm_cli/adapters/client/copilot.py

@@ -26,6 +26,7 @@ from .base import (
     _extract_legacy_angle_vars,
     _has_env_placeholder,
     _stringify_env_literal,
+    registry_field_is_required,
 )
 from .base import (
     _translate_env_placeholder as _translate_env_placeholder,
@@ -698,6 +699,7 @@ class CopilotClientAdapter(MCPClientAdapter):
             return translated
 
         if self._supports_runtime_env_substitution:
+            env_overrides = env_overrides or {}
             resolved = {}
             placeholder_keys = []
             for env_var in env_vars:
@@ -706,12 +708,18 @@ class CopilotClientAdapter(MCPClientAdapter):
                 name = env_var.get("name", "")
                 if not name:
                     continue
+                required = registry_field_is_required(env_var)
+                override_value = env_overrides.get(name)
+                has_override = bool(
+                    override_value.strip() if isinstance(override_value, str) else override_value
+                )
                 if name in default_github_env:
                     # Non-secret literal default -- preserve as-is.
                     resolved[name] = default_github_env[name]
-                else:
+                elif required or has_override:
                     # Emit a runtime-substitution placeholder; APM never reads
-                    # or stores the value.
+                    # or stores the value. Optional variables are included only
+                    # when install-time collection observed a value.
                     resolved[name] = self._format_runtime_env_placeholder(name)
                     placeholder_keys.append(name)
             # Record for the post-install summary line and the

apm_cli-0.20.0/src/apm_cli/adapters/client/hermes.py

@@ -0,0 +1,210 @@
+"""Hermes agent MCP client adapter.
+
+Hermes (Nous Research) reads MCP servers from a YAML ``mcp_servers:`` block
+in ``~/.hermes/config.yaml`` (snake_case key -- distinct from the JSON
+``mcpServers`` schema used by Claude/Copilot).  ``$HERMES_HOME`` overrides
+the home directory (default ``~/.hermes``).
+
+Scope: Hermes has a single home-directory config, so MCP writes are always
+user-scope -- ``config.yaml`` is the same file regardless of whether the
+install was triggered at project or user scope.  Unrelated top-level config
+keys (model provider, telegram settings, ...) are preserved on every write;
+a malformed existing file is left untouched rather than overwritten.
+
+Per-server shape:
+  * stdio  -> ``command`` / ``args`` / ``env`` (+ ``enabled``)
+  * http   -> ``url`` / ``headers`` (+ ``enabled``)
+
+YAML serialization goes through ``utils.yaml_io`` (lint forbids raw
+``yaml.dump``); the document is written atomically with ``0o600`` perms via
+``utils.atomic_io`` because ``config.yaml`` carries literal credentials.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+from pathlib import Path
+
+import yaml
+
+from ...utils.atomic_io import atomic_write_text
+from ...utils.console import _rich_error, _rich_success
+from ...utils.yaml_io import load_yaml, yaml_to_str
+from .copilot import CopilotClientAdapter
+
+# Credential-bearing config file mode: owner read/write only. Hermes' config.yaml
+# holds literal MCP env values plus native model-provider keys / messaging tokens,
+# so it must never be group/world-readable (parity with claude/codex/gemini/cursor).
+_CONFIG_FILE_MODE = 0o600
+
+
+class _MalformedHermesConfig(Exception):
+    """Raised when ``config.yaml`` exists but is not a YAML mapping.
+
+    Signals write paths to refuse the overwrite so a user's native Hermes
+    credentials (model-provider keys, Telegram tokens) are never discarded.
+    """
+
+
+class HermesClientAdapter(CopilotClientAdapter):
+    """MCP configuration for the Hermes agent (YAML ``mcp_servers`` schema).
+
+    Registry formatting reuses :class:`CopilotClientAdapter`, then entries are
+    converted to Hermes' on-disk shape via :meth:`_to_hermes_format`.
+    """
+
+    supports_user_scope: bool = True
+    target_name: str = "hermes"
+    mcp_servers_key: str = "mcp_servers"
+
+    # Hermes' config.yaml does NOT support runtime env-var substitution; the
+    # value in ``env`` must be a literal string, so install-time resolution
+    # is kept (mirrors Claude -- see #1152 supply-chain analysis).
+    _supports_runtime_env_substitution: bool = False
+
+    def _config_path(self) -> Path:
+        """Resolve ``<hermes-home>/config.yaml`` honouring ``$HERMES_HOME``."""
+        from ...integration.targets import resolve_hermes_root
+
+        return resolve_hermes_root() / "config.yaml"
+
+    @staticmethod
+    def _to_hermes_format(copilot_entry: dict, *, enabled: bool = True) -> dict:
+        """Convert a Copilot-format server entry to Hermes' on-disk shape.
+
+        Drops Copilot-CLI-only fields (``type: "local"``, default
+        ``tools: ["*"]``, empty ``id``) and stamps an explicit ``enabled``.
+        Required transport fields (``url`` for remote, ``command`` for stdio)
+        are only emitted when truthy so a malformed entry never serializes as
+        ``url: null`` / ``command: null`` into Hermes' config.
+        """
+        if not isinstance(copilot_entry, dict):
+            return copilot_entry
+
+        url = copilot_entry.get("url")
+        t = copilot_entry.get("type")
+        is_remote = bool(url) or t in ("http", "sse", "streamable-http")
+
+        out: dict = {}
+        if is_remote:
+            if url:
+                out["url"] = url
+            headers = copilot_entry.get("headers")
+            if headers:
+                out["headers"] = headers
+        else:
+            command = copilot_entry.get("command")
+            if command:
+                out["command"] = command
+            args = copilot_entry.get("args")
+            if args:
+                out["args"] = list(args)
+            env = copilot_entry.get("env")
+            if env:
+                out["env"] = dict(env)
+        out["enabled"] = enabled
+        return out
+
+    def get_config_path(self):
+        """Path to the Hermes config file (``<hermes-home>/config.yaml``)."""
+        return str(self._config_path())
+
+    def _load_document(self) -> dict:
+        """Load the full ``config.yaml`` document (preserving siblings).
+
+        Returns ``{}`` when the file is absent or empty.  Raises
+        :class:`_MalformedHermesConfig` when the file exists but is not a YAML
+        mapping (parse error or non-dict root) so write paths can refuse to
+        overwrite and silently discard the user's native Hermes credentials.
+        """
+        path = self._config_path()
+        if not path.is_file():
+            return {}
+        try:
+            data = load_yaml(path)
+        except (OSError, yaml.YAMLError) as exc:
+            raise _MalformedHermesConfig(str(path)) from exc
+        if data is None:
+            return {}
+        if not isinstance(data, dict):
+            raise _MalformedHermesConfig(str(path))
+        return data
+
+    def get_current_config(self):
+        """Return ``{"mcp_servers": {...}}`` for the on-disk config."""
+        try:
+            data = self._load_document()
+        except _MalformedHermesConfig:
+            return {self.mcp_servers_key: {}}
+        servers = data.get(self.mcp_servers_key)
+        return {self.mcp_servers_key: dict(servers) if isinstance(servers, dict) else {}}
+
+    def update_config(self, config_updates, enabled=True):
+        """Merge *config_updates* into the ``mcp_servers:`` block.
+
+        Entries are normalized to Hermes' shape.  Per-server entries are
+        replaced on key conflict; unrelated servers and all other top-level
+        config keys are preserved.  The file is written atomically with
+        ``0o600`` permissions so the credential-bearing config is never left
+        group/world-readable.  A malformed existing ``config.yaml`` is left
+        untouched (returns ``False``) rather than overwritten.
+        """
+        path = self._config_path()
+        try:
+            data = self._load_document()
+        except _MalformedHermesConfig:
+            _rich_error(
+                f"{path} is malformed YAML; refusing to overwrite. "
+                "Fix or remove the file manually, then retry."
+            )
+            return False
+        try:
+            servers = data.get(self.mcp_servers_key)
+            if not isinstance(servers, dict):
+                servers = {}
+            for name, cfg in config_updates.items():
+                servers[name] = self._to_hermes_format(cfg, enabled=enabled)
+            data[self.mcp_servers_key] = servers
+            path.parent.mkdir(parents=True, exist_ok=True)
+            atomic_write_text(path, yaml_to_str(data), new_file_mode=_CONFIG_FILE_MODE)
+            # Tighten perms even when the file pre-existed with a looser mode
+            # (atomic_write_text only applies new_file_mode on first create).
+            with contextlib.suppress(OSError, NotImplementedError):
+                os.chmod(path, _CONFIG_FILE_MODE)
+            return True
+        except OSError:
+            return False
+
+    def configure_mcp_server(
+        self,
+        server_url,
+        server_name=None,
+        enabled=True,
+        env_overrides=None,
+        server_info_cache=None,
+        runtime_vars=None,
+    ):
+        if not server_url:
+            _rich_error("server_url cannot be empty")
+            return False
+
+        try:
+            server_info = self._fetch_server_info(server_url, server_info_cache)
+            if server_info is None:
+                return False
+
+            config_key = self._determine_config_key(server_url, server_name)
+            server_config = self._format_server_config(server_info, env_overrides, runtime_vars)
+            ok = self.update_config({config_key: server_config}, enabled=enabled)
+            if not ok:
+                _rich_error(f"Failed to write MCP config for '{config_key}' to Hermes")
+                return False
+
+            _rich_success(f"Successfully configured MCP server '{config_key}' for Hermes")
+            return True
+        except Exception:
+            # Do not interpolate the exception message: registry URLs and
+            # other inputs may carry embedded credentials.
+            _rich_error("Error configuring MCP server")
+            return False

apm_cli-0.20.0/src/apm_cli/adapters/client/kiro.py

@@ -0,0 +1,226 @@
+"""Kiro IDE implementation of MCP client adapter.
+
+Kiro reads MCP configuration from ``.kiro/settings/mcp.json`` at project
+scope and ``~/.kiro/settings/mcp.json`` at user scope. The schema uses a
+``mcpServers`` object whose server entries support stdio ``command`` /
+``args`` / ``env`` and remote ``url`` / ``headers`` entries. Kiro resolves
+``${VAR}`` environment placeholders at runtime, so this adapter preserves
+placeholders instead of writing host secrets to disk.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from pathlib import Path
+from typing import Any
+
+from ...utils.atomic_io import atomic_write_text
+from ...utils.console import _rich_error, _rich_success
+from .copilot import CopilotClientAdapter
+
+logger = logging.getLogger(__name__)
+
+
+class KiroClientAdapter(CopilotClientAdapter):
+    """Kiro IDE MCP client adapter."""
+
+    supports_user_scope: bool = True
+    _client_label: str = "Kiro"
+    target_name: str = "kiro"
+    mcp_servers_key: str = "mcpServers"
+    _supports_runtime_env_substitution: bool = True
+
+    def _get_kiro_root(self) -> Path:
+        """Return the ``.kiro`` directory for the active scope."""
+        if self.user_scope:
+            return Path.home() / ".kiro"
+        return self.project_root / ".kiro"
+
+    def get_config_path(self) -> str:
+        """Return the Kiro MCP config path for the active scope."""
+        return str(self._get_kiro_root() / "settings" / "mcp.json")
+
+    def get_current_config(self) -> dict[str, Any]:
+        """Read the current Kiro MCP config."""
+        config_path = Path(self.get_config_path())
+        if not config_path.exists():
+            return {}
+        try:
+            with open(config_path, encoding="utf-8") as f:
+                data = json.load(f)
+            return data if isinstance(data, dict) else {}
+        except (OSError, json.JSONDecodeError) as exc:
+            logger.warning("Could not read %s: %s", config_path, exc)
+            return {}
+
+    def update_config(self, config_updates: dict[str, dict[str, Any]]) -> bool | None:
+        """Merge *config_updates* into Kiro's ``mcpServers`` object.
+
+        Project scope is opt-in: the workspace must already contain ``.kiro/``.
+        User scope creates ``~/.kiro/settings/`` on demand.
+        """
+        kiro_root = self._get_kiro_root()
+        if not self.user_scope and not kiro_root.is_dir():
+            logger.debug("Skipping Kiro project-scope write -- %s does not exist", kiro_root)
+            return None
+
+        config_path = Path(self.get_config_path())
+        current_config = self.get_current_config()
+        if not isinstance(current_config.get(self.mcp_servers_key), dict):
+            current_config[self.mcp_servers_key] = {}
+        current_config[self.mcp_servers_key].update(config_updates)
+
+        config_path.parent.mkdir(parents=True, exist_ok=True)
+        atomic_write_text(
+            config_path,
+            json.dumps(current_config, indent=2),
+            new_file_mode=0o600,
+        )
+        # Keep existing config files private after updates too.
+        os.chmod(config_path, 0o600)
+        return True
+
+    @staticmethod
+    def _header_mapping(remote: dict[str, Any]) -> dict[str, str]:
+        """Return registry remote headers as string key-value pairs."""
+        headers = remote.get("headers", {})
+        if isinstance(headers, list):
+            return {
+                str(h["name"]): str(h["value"])
+                for h in headers
+                if isinstance(h, dict) and "name" in h and "value" in h
+            }
+        if isinstance(headers, dict):
+            return {str(name): str(value) for name, value in headers.items()}
+        return {}
+
+    @staticmethod
+    def _copy_kiro_extensions(config: dict[str, Any], server_info: dict[str, Any]) -> None:
+        """Carry Kiro-specific MCP fields when the registry supplies them."""
+        for key in ("autoApprove", "disabledTools", "disabled"):
+            if key in server_info and server_info[key] is not None:
+                config[key] = server_info[key]
+
+    def _format_server_config(
+        self,
+        server_info: dict[str, Any],
+        env_overrides: dict[str, str] | None = None,
+        runtime_vars: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        """Format registry or self-defined server info for Kiro."""
+        if runtime_vars is None:
+            runtime_vars = {}
+
+        raw = server_info.get("_raw_stdio")
+        if raw:
+            config: dict[str, Any] = {"command": raw["command"]}
+            resolved_env_for_args: dict[str, Any] = {}
+            if raw.get("env"):
+                resolved_env_for_args = self._resolve_environment_variables(
+                    raw["env"], env_overrides=env_overrides
+                )
+                config["env"] = resolved_env_for_args
+                self._warn_input_variables(raw["env"], server_info.get("name", ""), "Kiro")
+            config["args"] = [
+                self._resolve_variable_placeholders(arg, resolved_env_for_args, runtime_vars)
+                if isinstance(arg, str)
+                else arg
+                for arg in raw.get("args") or []
+            ]
+            self._copy_kiro_extensions(config, server_info)
+            return config
+
+        remotes = server_info.get("remotes", [])
+        if remotes:
+            remote = self._select_remote_with_url(remotes) or remotes[0]
+            transport = (remote.get("transport_type") or "").strip()
+            if not transport:
+                transport = "http"
+            elif transport not in ("sse", "http", "streamable-http"):
+                raise ValueError(
+                    f"Unsupported remote transport '{transport}' for Kiro. "
+                    f"Server: {server_info.get('name', 'unknown')}. "
+                    "Supported transports: http, sse, streamable-http."
+                )
+
+            config = {"url": (remote.get("url") or "").strip()}
+            headers = {
+                name: self._resolve_env_variable(name, value, env_overrides)
+                if isinstance(value, str)
+                else value
+                for name, value in self._header_mapping(remote).items()
+                if name
+            }
+            if headers:
+                config["headers"] = headers
+                self._warn_input_variables(headers, server_info.get("name", ""), "Kiro")
+            self._copy_kiro_extensions(config, server_info)
+            return config
+
+        packages = server_info.get("packages", [])
+        if not packages:
+            raise ValueError(
+                "MCP server has incomplete configuration in registry - "
+                "no package information or remote endpoints available. "
+                f"Server: {server_info.get('name', 'unknown')}"
+            )
+
+        config = {}
+        package = self._select_and_dispatch_best_package(
+            config,
+            packages,
+            env_overrides,
+            runtime_vars,
+        )
+        if not package:
+            raise ValueError(
+                f"No supported package type found for Kiro. "
+                f"Server: {server_info.get('name', 'unknown')}."
+            )
+        self._copy_kiro_extensions(config, server_info)
+        return config
+
+    def configure_mcp_server(
+        self,
+        server_url: str,
+        server_name: str | None = None,
+        enabled: bool = True,
+        env_overrides: dict[str, str] | None = None,
+        server_info_cache: dict[str, Any] | None = None,
+        runtime_vars: dict[str, str] | None = None,
+    ) -> bool:
+        """Configure an MCP server in Kiro's MCP config."""
+        if not server_url:
+            _rich_error("server_url cannot be empty", symbol="error")
+            return False
+
+        if not self.user_scope and not self._get_kiro_root().is_dir():
+            logger.debug(
+                "Kiro opt-in gate: %s absent, skipping configure_mcp_server",
+                self._get_kiro_root(),
+            )
+            return True
+
+        config_key = self._determine_config_key(server_url, server_name)
+
+        try:
+            server_info = self._fetch_server_info(server_url, server_info_cache)
+            if server_info is None:
+                return False
+
+            self._last_env_placeholder_keys = set()
+            self._last_legacy_angle_vars = set()
+
+            server_config = self._format_server_config(server_info, env_overrides, runtime_vars)
+            if not enabled:
+                server_config["disabled"] = True
+            self.update_config({config_key: server_config})
+
+            _rich_success(f"Configured MCP server '{config_key}' for Kiro", symbol="success")
+            return True
+        except Exception as exc:
+            logger.debug("Kiro MCP configuration failed: %s", exc)
+            _rich_error(f"Failed to configure MCP server '{config_key}' for Kiro", symbol="error")
+            return False