apm-cli 0.27.0__tar.gz → 0.29.0__tar.gz

{apm_cli-0.27.0/src/apm_cli.egg-info → apm_cli-0.29.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: apm-cli
-Version: 0.27.0
+Version: 0.29.0
 Summary: MCP configuration tool
 Author-email: Daniel Meppiel <user@example.com>
 License: MIT License
@@ -76,9 +76,9 @@ 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 · Kiro
+GitHub Copilot | Claude Code | Grok Build | 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)**
+**[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/)** · **[v0.29 Roadmap](https://github.com/microsoft/apm/milestone/17)**
 
 ---
 
@@ -139,7 +139,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, Kiro
+- **[One manifest for everything](https://microsoft.github.io/apm/reference/primitive-types/)** -- declared once, deployed across Copilot, Claude, Grok Build, 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`
@@ -239,7 +239,8 @@ Use agentrc to author high-quality instructions, then package them with APM to s
 
 Created by [@danielmeppiel](https://github.com/danielmeppiel). Maintained by [@danielmeppiel](https://github.com/danielmeppiel) and [@sergio-sisternes-epam](https://github.com/sergio-sisternes-epam).
 
-- [Roadmap & Discussions](https://github.com/microsoft/apm/discussions/116)
+- [v0.29 Roadmap](https://github.com/microsoft/apm/milestone/17)
+- [Discussions](https://github.com/microsoft/apm/discussions)
 - [Contributing](CONTRIBUTING.md)
 - [AI Native Development guide](https://danielmeppiel.github.io/awesome-ai-native) — a practical learning path for AI-native development
 

{apm_cli-0.27.0 → apm_cli-0.29.0}/README.md

@@ -4,9 +4,9 @@
 
 Think `package.json`, `requirements.txt`, or `Cargo.toml` — but for AI agent configuration.
 
-GitHub Copilot · Claude Code · Cursor · OpenCode · Codex · Gemini · Windsurf · Kiro
+GitHub Copilot | Claude Code | Grok Build | 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)**
+**[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/)** · **[v0.29 Roadmap](https://github.com/microsoft/apm/milestone/17)**
 
 ---
 
@@ -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, Kiro
+- **[One manifest for everything](https://microsoft.github.io/apm/reference/primitive-types/)** -- declared once, deployed across Copilot, Claude, Grok Build, 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`
@@ -167,7 +167,8 @@ Use agentrc to author high-quality instructions, then package them with APM to s
 
 Created by [@danielmeppiel](https://github.com/danielmeppiel). Maintained by [@danielmeppiel](https://github.com/danielmeppiel) and [@sergio-sisternes-epam](https://github.com/sergio-sisternes-epam).
 
-- [Roadmap & Discussions](https://github.com/microsoft/apm/discussions/116)
+- [v0.29 Roadmap](https://github.com/microsoft/apm/milestone/17)
+- [Discussions](https://github.com/microsoft/apm/discussions)
 - [Contributing](CONTRIBUTING.md)
 - [AI Native Development guide](https://danielmeppiel.github.io/awesome-ai-native) — a practical learning path for AI-native development
 

{apm_cli-0.27.0 → apm_cli-0.29.0}/pyproject.toml

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

{apm_cli-0.27.0 → apm_cli-0.29.0}/src/apm_cli/adapters/client/base.py

@@ -7,7 +7,7 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, ClassVar
 
-from ...models.dependency.mcp import _RESERVED_EXTRA_KEYS
+from ...models.dependency.mcp import _RESERVED_EXTRA_KEYS, TrustedEnvLiteral
 from ...utils.console import _rich_error, _rich_warning
 
 _INPUT_VAR_RE = re.compile(r"\$\{input:([^}]+)\}")
@@ -29,6 +29,7 @@ _ENV_PLACEHOLDER_RE = re.compile(r"<([A-Z_][A-Z0-9_]*)>|" + _ENV_VAR_RE.pattern)
 # Detects the legacy ``<VAR>`` placeholder syntax only. Used to aggregate
 # deprecation warnings across all servers in a single install run.
 _LEGACY_ANGLE_VAR_RE = re.compile(r"<([A-Z_][A-Z0-9_]*)>")
+_RUNTIME_TEMPLATE_VARIABLE_RE = re.compile(r"(?<!\$)\{([a-zA-Z_][a-zA-Z0-9_]*)\}")
 
 # MCP Registry v0.1 names the container registry type ``oci``; the adapters
 # below key their launcher dispatch on ``docker`` (the vocabulary the legacy
@@ -656,6 +657,94 @@ class MCPClientAdapter(ABC):
             None,
         )
 
+    @staticmethod
+    def _package_runtime_variable_metadata(
+        package: dict[str, Any] | None,
+    ) -> dict[str, dict] | None:
+        """Return one validated runtime-variable declaration map for a package.
+
+        Registry metadata may declare a variable on one argument and reference it
+        later without repeating the declaration. Keeping this map package-scoped
+        makes those references resolve consistently while rejecting malformed
+        secret metadata before an adapter can render a collected value.
+        """
+        metadata_by_name: dict[str, dict] = {}
+        for field_name in ("runtime_arguments", "package_arguments"):
+            for argument in (package or {}).get(field_name) or []:
+                if not isinstance(argument, dict):
+                    continue
+                variables = argument.get("variables")
+                if variables is None:
+                    continue
+                if not isinstance(variables, dict):
+                    return None
+                for name, metadata in variables.items():
+                    if not isinstance(name, str) or not isinstance(metadata, dict):
+                        return None
+                    secret_marker = metadata.get("isSecret", metadata.get("is_secret", False))
+                    if not isinstance(secret_marker, bool):
+                        return None
+                    existing = metadata_by_name.get(name)
+                    if existing is not None and existing != metadata:
+                        return None
+                    metadata_by_name[name] = metadata
+        return metadata_by_name
+
+    @staticmethod
+    def _substitute_runtime_variables(
+        template: str,
+        variables: dict[object, object] | None,
+        runtime_vars: dict[str, object] | None,
+        runtime_variable_fallbacks: dict[str, str] | None = None,
+        secret_variable_fallbacks: dict[str, str] | None = None,
+    ) -> str | None:
+        """Resolve every APM runtime variable in one registry argument template.
+
+        Variable metadata may appear on an earlier argument while later
+        arguments reference the same value. Collected values therefore apply to
+        every template, not only the metadata-bearing entry. Target-specific
+        fallbacks are used only for declared variables with no collected value.
+        """
+        secret_fallbacks = secret_variable_fallbacks or {}
+        values: dict[str, str] = dict(secret_fallbacks)
+        for name, value in (runtime_vars or {}).items():
+            if (
+                isinstance(name, str)
+                and name not in secret_fallbacks
+                and value is not None
+                and str(value) != ""
+            ):
+                values[name] = str(value)
+
+        fallbacks = runtime_variable_fallbacks or {}
+        for name, metadata in (variables or {}).items():
+            if not isinstance(name, str) or not isinstance(metadata, dict):
+                return None
+            placeholder = f"{{{name}}}"
+            if placeholder not in template or name in values:
+                continue
+            secret_marker = metadata.get("isSecret", metadata.get("is_secret", False))
+            if not isinstance(secret_marker, bool):
+                return None
+            if secret_marker is True:
+                return None
+            fallback = fallbacks.get(name)
+            if fallback is not None:
+                values[name] = fallback
+                continue
+            configured = metadata.get("value", metadata.get("default"))
+            if isinstance(configured, str) and configured:
+                values[name] = configured
+            elif configured is not None:
+                return None
+
+        for name, value in values.items():
+            template = template.replace(f"{{{name}}}", value)
+
+        if _RUNTIME_TEMPLATE_VARIABLE_RE.search(template):
+            return None
+        return template
+
     @staticmethod
     def _processed_non_container_argument_groups(
         arguments: list[object],
@@ -998,7 +1087,9 @@ class MCPClientAdapter(ABC):
                 if not isinstance(raw_value, str):
                     translated[name] = raw_value
                     continue
-                if _has_env_placeholder(raw_value):
+                if isinstance(raw_value, TrustedEnvLiteral):
+                    translated[name] = raw_value
+                elif _has_env_placeholder(raw_value):
                     self._last_legacy_angle_vars.update(_extract_legacy_angle_vars(raw_value))
                     translated[name] = self._translate_env_placeholder_for_runtime(raw_value)
                     placeholder_keys.extend(

{apm_cli-0.27.0 → apm_cli-0.29.0}/src/apm_cli/adapters/client/codex.py

@@ -12,6 +12,7 @@ from ...registry.client import SimpleRegistryClient
 from ...registry.integration import RegistryIntegration
 from ...utils.atomic_io import atomic_write_text
 from ...utils.console import _rich_success, _rich_warning
+from ...utils.net import is_loopback_host
 from ...utils.path_security import PathTraversalError
 from ._mcp_runtime_args import process_v01_value_hint_arg
 from .base import MCPClientAdapter
@@ -216,6 +217,8 @@ class CodexClientAdapter(MCPClientAdapter):
         raw = server_info.get("_raw_stdio")
         if raw:
             config["command"] = raw["command"]
+            if raw.get("cwd") is not None:
+                config["cwd"] = raw["cwd"]
             resolved_env_for_args: dict = {}
             if raw.get("env"):
                 resolved_env_for_args = self._resolve_environment_variables(
@@ -239,7 +242,8 @@ class CodexClientAdapter(MCPClientAdapter):
         # Precedence on Codex when a server publishes BOTH a remote and a stdio
         # package: prefer the stdio package (falls through to the packages branch
         # below). The remote-only branch here handles the streamable-http path
-        # and rejects SSE / non-https / empty-url remotes with explicit warnings.
+        # and rejects SSE / non-https (except loopback http) / empty-url remotes
+        # with explicit warnings.
         remotes = server_info.get("remotes", [])
         packages = server_info.get("packages", [])
         if remotes and not packages:
@@ -263,11 +267,22 @@ class CodexClientAdapter(MCPClientAdapter):
                 )
                 return None
 
-            scheme = urlparse(remote_url).scheme.lower()
-            if scheme != "https":
+            try:
+                parsed_remote = urlparse(remote_url)
+                scheme = parsed_remote.scheme.lower()
+                insecure_loopback = scheme == "http" and is_loopback_host(parsed_remote.hostname)
+            except ValueError:
+                scheme = ""
+                insecure_loopback = False
+            # Codex CLI itself accepts plain-http loopback URLs (its docs use
+            # http://localhost examples), and local dev servers rarely carry
+            # certs -- so loopback http is allowed. Any other non-https host is
+            # still rejected to avoid cleartext bearer tokens in transit.
+            if scheme != "https" and not insecure_loopback:
                 _rich_warning(
                     f"Skipping MCP server '{server_name}' for Codex CLI: remote URL "
-                    f"must use https:// (got {scheme or 'no scheme'}).",
+                    f"must use https:// (got {scheme or 'no scheme'}). "
+                    "Plain http is allowed for loopback addresses only.",
                     symbol="warning",
                 )
                 return None

{apm_cli-0.27.0 → apm_cli-0.29.0}/src/apm_cli/adapters/client/copilot.py

@@ -1,8 +1,8 @@
 """GitHub Copilot CLI implementation of MCP client adapter.
 
-This adapter implements the Copilot CLI-specific handling of MCP server configuration,
-targeting the global ~/.copilot/mcp-config.json file as specified in the MCP installation
-architecture specification.
+This adapter implements the Copilot-specific handling of MCP server configuration.
+At project scope it targets .github/mcp.json (read by Copilot CLI); at user scope
+it targets the global ~/.copilot/mcp-config.json file.
 """
 
 import json
@@ -13,6 +13,7 @@ from typing import ClassVar
 import click
 
 from ...core.token_manager import GitHubTokenManager
+from ...models.dependency.mcp import TrustedEnvLiteral
 from ...registry.client import SimpleRegistryClient
 from ...registry.integration import RegistryIntegration
 from ...utils.console import _rich_warning
@@ -103,13 +104,23 @@ class CopilotClientAdapter(MCPClientAdapter):
         self.registry_integration = RegistryIntegration(registry_url)
 
     def get_config_path(self):
-        """Get the path to the Copilot CLI MCP configuration file.
+        """Get the path to the Copilot MCP configuration file.
+
+        At user scope returns the global Copilot CLI config so MCP servers are
+        available across all projects. At project scope returns the per-repo
+        .github/mcp.json path that Copilot CLI reads since deprecating
+        .vscode/mcp.json.
 
         Returns:
-            str: Path to ~/.copilot/mcp-config.json
+            str: Path to the MCP configuration file.
         """
-        copilot_dir = Path.home() / ".copilot"
-        return str(copilot_dir / "mcp-config.json")
+        if self.user_scope:
+            configured_home = os.environ.get("COPILOT_HOME", "").strip()
+            copilot_home = (
+                Path(configured_home).expanduser() if configured_home else Path.home() / ".copilot"
+            )
+            return str(copilot_home / "mcp-config.json")
+        return str(self.project_root / ".github" / "mcp.json")
 
     def update_config(self, config_updates):
         """Update the Copilot CLI MCP configuration.
@@ -423,6 +434,8 @@ class CopilotClientAdapter(MCPClientAdapter):
         raw = server_info.get("_raw_stdio")
         if raw:
             config["command"] = raw["command"]
+            if raw.get("cwd") is not None:
+                config["cwd"] = raw["cwd"]
             resolved_env_for_args = {}
             if raw.get("env"):
                 resolved_env_for_args = self._resolve_environment_variables(
@@ -723,7 +736,9 @@ class CopilotClientAdapter(MCPClientAdapter):
                 if not isinstance(raw_value, str):
                     translated[name] = _stringify_env_literal(raw_value)
                     continue
-                if _has_env_placeholder(raw_value):
+                if isinstance(raw_value, TrustedEnvLiteral):
+                    translated[name] = raw_value
+                elif _has_env_placeholder(raw_value):
                     self._last_legacy_angle_vars.update(_extract_legacy_angle_vars(raw_value))
                     translated[name] = self._translate_env_placeholder_for_runtime(raw_value)
                     for match in _ENV_VAR_RE.finditer(translated[name]):

{apm_cli-0.27.0 → apm_cli-0.29.0}/src/apm_cli/adapters/client/cursor.py

@@ -134,6 +134,8 @@ class CursorClientAdapter(CopilotClientAdapter):
         if raw:
             config["type"] = "stdio"
             config["command"] = raw["command"]
+            if raw.get("cwd") is not None:
+                config["cwd"] = raw["cwd"]
             resolved_env_for_args: dict = {}
             if raw.get("env"):
                 resolved_env_for_args = self._resolve_environment_variables(

{apm_cli-0.27.0 → apm_cli-0.29.0}/src/apm_cli/adapters/client/gemini.py

@@ -148,6 +148,8 @@ class GeminiClientAdapter(CopilotClientAdapter):
         raw = server_info.get("_raw_stdio")
         if raw:
             config["command"] = raw["command"]
+            if raw.get("cwd") is not None:
+                config["cwd"] = raw["cwd"]
             resolved_env_for_args: dict = {}
             if raw.get("env"):
                 resolved_env_for_args = self._resolve_environment_variables(

{apm_cli-0.27.0 → apm_cli-0.29.0}/src/apm_cli/adapters/client/kiro.py

@@ -116,6 +116,8 @@ class KiroClientAdapter(CopilotClientAdapter):
         raw = server_info.get("_raw_stdio")
         if raw:
             config: dict[str, Any] = {"command": raw["command"]}
+            if raw.get("cwd") is not None:
+                config["cwd"] = raw["cwd"]
             resolved_env_for_args: dict[str, Any] = {}
             if raw.get("env"):
                 resolved_env_for_args = self._resolve_environment_variables(

{apm_cli-0.27.0 → apm_cli-0.29.0}/src/apm_cli/adapters/client/vscode.py

@@ -5,6 +5,7 @@ following the official documentation at:
 https://code.visualstudio.com/docs/copilot/chat/mcp-servers
 """
 
+import hashlib
 import json
 import re
 from pathlib import Path
@@ -13,7 +14,13 @@ from ...core.docker_args import DockerArgsProcessor
 from ...registry.client import SimpleRegistryClient
 from ...registry.integration import RegistryIntegration
 from ...utils.console import _rich_warning
-from .base import _ENV_VAR_RE, _INPUT_VAR_RE, MCPClientAdapter, registry_field_is_required
+from .base import (
+    _ENV_VAR_RE,
+    _INPUT_VAR_RE,
+    _RUNTIME_TEMPLATE_VARIABLE_RE,
+    MCPClientAdapter,
+    registry_field_is_required,
+)
 
 # Legacy ``<VAR>`` placeholder (Copilot CLI / Codex only). VS Code does not
 # resolve angle-bracket placeholders, so emitting them produces literal
@@ -270,6 +277,8 @@ class VSCodeClientAdapter(MCPClientAdapter):
                 "command": raw["command"],
                 "args": raw["args"],
             }
+            if raw.get("cwd") is not None:
+                server_config["cwd"] = raw["cwd"]
             if raw.get("env"):
                 # Translate bare ${VAR} -> ${env:VAR} so VS Code's runtime env
                 # interpolation resolves them at server-start. ${input:...}
@@ -298,7 +307,8 @@ class VSCodeClientAdapter(MCPClientAdapter):
                 existing_server_config=existing_server_config,
             )
             secret_fallbacks, argument_inputs = self._declared_vscode_argument_secret_inputs(
-                package
+                package,
+                server_name=server_info.get("name", ""),
             )
             seen_input_ids = {item.get("id") for item in input_vars}
             for input_definition in (*declared_inputs, *argument_inputs):
@@ -342,19 +352,29 @@ class VSCodeClientAdapter(MCPClientAdapter):
 
             # Handle docker packages
             elif is_docker:
-                args = self._docker_run_args(package, runtime_vars)
+                docker_kwargs = (
+                    {"secret_variable_fallbacks": secret_fallbacks} if secret_fallbacks else {}
+                )
+                unresolved_variables: list[str] = []
+                args = self._docker_run_args(
+                    package,
+                    runtime_vars,
+                    unresolved_variables=unresolved_variables,
+                    **docker_kwargs,
+                )
                 if args is None:
                     if package.get("runtime_arguments") or package.get("package_arguments"):
+                        variable_name = (
+                            unresolved_variables[0] if unresolved_variables else "unknown"
+                        )
                         _rich_warning(
-                            "Could not resolve container run options for "
-                            f"'{package.get('name', '')}'; using the default launcher. "
-                            "Set the required registry runtime variables and rerun "
-                            "'apm install'."
+                            "Could not resolve required container run option "
+                            f"'{variable_name}' for '{package.get('name', '')}'; "
+                            "target configuration was not changed. Set the required "
+                            "registry runtime variables and rerun 'apm install'."
                         )
-                    args = self._ensure_docker_image_arg(
-                        ["run", "-i", "--rm"],
-                        package.get("name"),
-                    )
+                        return {}, []
+                    args = self._ensure_docker_image_arg(["run", "-i", "--rm"], package.get("name"))
 
                 server_config = {"type": "stdio", "command": "docker", "args": args}
 
@@ -547,50 +567,50 @@ class VSCodeClientAdapter(MCPClientAdapter):
         return env_config, input_vars
 
     @staticmethod
-    def _declared_vscode_argument_secret_inputs(package):
+    def _vscode_argument_secret_input_id(server_name: str, variable_name: str) -> str:
+        """Return a collision-safe VS Code input ID for one server variable."""
+        server_digest = hashlib.sha256(server_name.encode("utf-8")).hexdigest()[:12]
+        return f"mcp-{server_digest}-{variable_name.encode('utf-8').hex()}"
+
+    @classmethod
+    def _declared_vscode_argument_secret_inputs(cls, package, *, server_name: str):
         """Return VS Code input indirections for secret argument variables."""
         if not package:
             return {}, []
+        package_variables = cls._package_runtime_variable_metadata(package)
+        if package_variables is None:
+            raise ValueError("MCP package argument variable metadata must be valid")
         fallbacks = {}
         input_vars = []
+        templates = []
         for field_name in ("runtime_arguments", "package_arguments"):
             for argument in package.get(field_name) or []:
                 if not isinstance(argument, dict):
                     continue
-                variables = argument.get("variables")
-                if not isinstance(variables, dict):
-                    continue
                 template = argument.get(
                     "value",
                     argument.get("default", argument.get("value_hint", "")),
                 )
-                for variable_name, variable_info in variables.items():
-                    if not isinstance(variable_name, str) or not isinstance(
-                        variable_info,
-                        dict,
-                    ):
-                        continue
-                    if not isinstance(template, str) or f"{{{variable_name}}}" not in template:
-                        continue
-                    is_secret = variable_info.get(
-                        "isSecret",
-                        variable_info.get("is_secret", False),
-                    )
-                    if is_secret is not True or variable_name in fallbacks:
-                        continue
-                    input_id = variable_name.lower().replace("_", "-")
-                    fallbacks[variable_name] = f"${{input:{input_id}}}"
-                    input_vars.append(
-                        {
-                            "type": "promptString",
-                            "id": input_id,
-                            "description": variable_info.get(
-                                "description",
-                                f"{variable_name} for MCP server",
-                            ),
-                            "password": True,
-                        }
-                    )
+                if isinstance(template, str):
+                    templates.append(template)
+        for variable_name, variable_info in package_variables.items():
+            if not any(f"{{{variable_name}}}" in template for template in templates):
+                continue
+            if not variable_info.get("isSecret", variable_info.get("is_secret", False)):
+                continue
+            input_id = cls._vscode_argument_secret_input_id(server_name, variable_name)
+            fallbacks[variable_name] = f"${{input:{input_id}}}"
+            input_vars.append(
+                {
+                    "type": "promptString",
+                    "id": input_id,
+                    "description": variable_info.get(
+                        "description",
+                        f"{variable_name} for MCP server",
+                    ),
+                    "password": True,
+                }
+            )
         return fallbacks, input_vars
 
     @staticmethod
@@ -776,7 +796,14 @@ class VSCodeClientAdapter(MCPClientAdapter):
         return extracted
 
     @classmethod
-    def _docker_run_args(cls, package: dict, runtime_vars: dict | None = None) -> list[str] | None:
+    def _docker_run_args(
+        cls,
+        package: dict,
+        runtime_vars: dict | None = None,
+        *,
+        secret_variable_fallbacks: dict[str, str] | None = None,
+        unresolved_variables: list[str] | None = None,
+    ) -> list[str] | None:
         """Build ``docker run`` arguments from a container package's metadata.
 
         Container packages retain a dedicated assembler because Docker requires
@@ -813,10 +840,27 @@ class VSCodeClientAdapter(MCPClientAdapter):
         """
         if not package:
             return None
-        run_options = cls._docker_arg_values(package.get("runtime_arguments"), runtime_vars)
+        package_variables = cls._package_runtime_variable_metadata(package)
+        if package_variables is None:
+            if unresolved_variables is not None:
+                unresolved_variables.append("invalid metadata")
+            return None
+        run_options = cls._docker_arg_values(
+            package.get("runtime_arguments"),
+            runtime_vars,
+            secret_variable_fallbacks,
+            package_variables,
+            unresolved_variables,
+        )
         if run_options is None:
             return None
-        package_args = cls._docker_arg_values(package.get("package_arguments"), runtime_vars)
+        package_args = cls._docker_arg_values(
+            package.get("package_arguments"),
+            runtime_vars,
+            secret_variable_fallbacks,
+            package_variables,
+            unresolved_variables,
+        )
         if package_args is None:
             return None
         if not run_options and package_args and package_args[0] == "run":
@@ -855,7 +899,12 @@ class VSCodeClientAdapter(MCPClientAdapter):
 
     @classmethod
     def _docker_arg_values(
-        cls, entries: list | None, runtime_vars: dict | None
+        cls,
+        entries: list | None,
+        runtime_vars: dict | None,
+        secret_variable_fallbacks: dict[str, str] | None,
+        package_variables: dict[str, dict],
+        unresolved_variables: list[str] | None,
     ) -> list[str] | None:
         """Resolve one registry argument list into CLI argument strings.
 
@@ -903,47 +952,26 @@ class VSCodeClientAdapter(MCPClientAdapter):
                 continue
 
             template = str(raw)
-            variables = arg.get("variables")
-            if isinstance(variables, dict) and variables:
-                substituted = cls._substitute_runtime_variables(template, variables, runtime_vars)
-                if substituted is None:
-                    if required:
-                        return None
-                    continue
-                template = substituted
+            substituted = cls._substitute_runtime_variables(
+                template,
+                package_variables,
+                runtime_vars,
+                {"workspaceFolder": "${workspaceFolder}"},
+                secret_variable_fallbacks,
+            )
+            if substituted is None:
+                if required:
+                    if unresolved_variables is not None:
+                        match = _RUNTIME_TEMPLATE_VARIABLE_RE.search(template)
+                        unresolved_variables.append(match.group(1) if match else "unknown")
+                    return None
+                continue
+            template = substituted
             if arg_type == "named" and arg.get("name"):
                 args.append(str(arg["name"]))
             args.append(template)
         return args
 
-    @staticmethod
-    def _substitute_runtime_variables(
-        template: str, variables: dict, runtime_vars: dict | None
-    ) -> str | None:
-        """Substitute ``{var}`` placeholders, or return None if unresolvable.
-
-        ``workspaceFolder`` resolves to VS Code's own ``${workspaceFolder}``
-        token, which the editor expands at server start. Any other name that
-        this install did not collect a value for has no such fallback, so the
-        caller is told to decline rather than write a literal ``${name}`` into
-        a mount path.
-        """
-        for var_name in variables:
-            placeholder = f"{{{var_name}}}"
-            # A descriptor the template never references cannot make it
-            # unresolvable; declining on one would drop a usable argument.
-            if placeholder not in template:
-                continue
-            supplied = (runtime_vars or {}).get(var_name)
-            if supplied is not None and str(supplied) != "":
-                replacement = str(supplied)
-            elif var_name == "workspaceFolder":
-                replacement = "${workspaceFolder}"
-            else:
-                return None
-            template = template.replace(placeholder, replacement)
-        return template
-
     @staticmethod
     def _select_remote_with_url(remotes):
         """Return the first remote entry that has a non-empty URL.