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

{apm_cli-0.18.0 → apm_cli-0.20.0}/AUTHORS

@@ -4,6 +4,7 @@
 
 * Daniel Meppiel (@danielmeppiel) — Microsoft
 * Sergio Sisternes (@sergio-sisternes-epam) — EPAM Systems
+* Nadav Yogev (@nadav-y) — JFrog
 
 Maintainers' work on APM is supported by their employers. Project
 decisions are made in the interest of APM and its users, independent

{apm_cli-0.18.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.18.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.18.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.18.0 → apm_cli-0.20.0}/pyproject.toml

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

{apm_cli-0.18.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:
@@ -633,22 +638,25 @@ class MCPClientAdapter(ABC):
         return server_info
 
     @staticmethod
-    def _determine_config_key(server_url: str, server_name: str) -> str:
+    def _determine_config_key(server_url: str, server_name: str | None) -> str:
         """Return the configuration key to use for *server_url*/*server_name*.
 
-        The caller-supplied *server_name* takes precedence; if empty the last
-        path segment of *server_url* is used as a fallback, which mirrors the
-        convention ``owner/repo -> repo``.
+        The caller-supplied *server_name* takes precedence. If it is absent,
+        preserve npm-style scoped names such as ``@scope/name`` (one slash by
+        npm convention) while keeping the historical ``owner/repo -> repo``
+        fallback for registry paths.
 
         Args:
             server_url: Registry reference used as fallback source.
-            server_name: Explicit caller-supplied name (may be empty string).
+            server_name: Explicit caller-supplied name, if any.
 
         Returns:
             Non-empty configuration key string.
         """
         if server_name:
             return server_name
+        if server_url.startswith("@") and server_url.count("/") == 1:
+            return server_url
         if "/" in server_url:
             return server_url.split("/")[-1]
         return server_url
@@ -794,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:
@@ -834,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", "")
@@ -856,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.18.0 → apm_cli-0.20.0}/src/apm_cli/adapters/client/claude.py

@@ -239,12 +239,7 @@ class ClaudeClientAdapter(CopilotClientAdapter):
                 _rich_error(f"MCP server '{server_url}' not found in registry")
                 return False
 
-            if server_name:
-                config_key = server_name
-            elif "/" in server_url:
-                config_key = server_url.split("/")[-1]
-            else:
-                config_key = server_url
+            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})

{apm_cli-0.18.0 → apm_cli-0.20.0}/src/apm_cli/adapters/client/codex.py

@@ -150,19 +150,7 @@ class CodexClientAdapter(MCPClientAdapter):
             if server_info is None:
                 return False
 
-            # Determine the server name for configuration key
-            if server_name:
-                # Use explicitly provided server name
-                config_key = server_name
-            else:  # noqa: PLR5501
-                # Extract name from server_url (part after last slash)
-                # For URLs like "microsoft/azure-devops-mcp" -> "azure-devops-mcp"
-                # For URLs like "github/github-mcp-server" -> "github-mcp-server"
-                if "/" in server_url:  # noqa: SIM108
-                    config_key = server_url.split("/")[-1]
-                else:
-                    # Fallback to full server_url if no slash
-                    config_key = server_url
+            config_key = self._determine_config_key(server_url, server_name)
 
             # Generate server configuration with environment variable resolution
             server_config = self._format_server_config(server_info, env_overrides, runtime_vars)

{apm_cli-0.18.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,
@@ -206,19 +207,7 @@ class CopilotClientAdapter(MCPClientAdapter):
             # Generate server configuration with environment and runtime variable resolution
             server_config = self._format_server_config(server_info, env_overrides, runtime_vars)
 
-            # Determine the server name for configuration key
-            if server_name:
-                # Use explicitly provided server name
-                config_key = server_name
-            else:  # noqa: PLR5501
-                # Extract name from server_url (part after last slash)
-                # For URLs like "microsoft/azure-devops-mcp" -> "azure-devops-mcp"
-                # For URLs like "github/github-mcp-server" -> "github-mcp-server"
-                if "/" in server_url:  # noqa: SIM108
-                    config_key = server_url.split("/")[-1]
-                else:
-                    # Fallback to full server_url if no slash
-                    config_key = server_url
+            config_key = self._determine_config_key(server_url, server_name)
 
             # Update configuration using the chosen key
             self.update_config({config_key: server_config})
@@ -710,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:
@@ -718,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