Skip to content

feat(validation): warn or error on shell-string command in MCP stdio entries #806

@danielmeppiel

Description

@danielmeppiel

Context: Surfaced via #122 and the followup conversation with @lirantal -- users sometimes write command: "npx mcp-server-foo" (single shell-string) instead of the canonical command: npx, args: ["mcp-server-foo"]. The current loose acceptance is a UX trap: it either silently mis-parses or silently relies on whitespace-splitting somewhere downstream, both of which are wrong per the schema.

Problem

Per manifest-schema.md, for self-defined stdio MCP entries:

  • command MUST be a single binary path (no whitespace, no args)
  • args is the list of arguments

Today APM accepts the shell-string shape with no warning, hiding the mistake until something breaks.

Proposed change

Parse-time validation that detects:

  • transport == "stdio", AND
  • command is a string containing whitespace, AND
  • args is empty or missing

Then emit a structured warning with a concrete fix-it suggestion:

[!] MCP server 'NAME': command "npx mcp-server-foo" looks like a shell line.
    APM does not split commands by whitespace. Did you mean:
        command: npx
        args: ["mcp-server-foo"]
    See <link to consolidated MCP guide once W2 lands>

Scope

  • Validator added to MCP entry parser (likely src/apm_cli/deps/aggregator.py near _install_inline_mcp_deps or wherever the inline MCP shape is normalized)
  • ASCII-only output per repo encoding rule, uses [!] STATUS_SYMBOL
  • Unit tests covering: clean path, whitespace-in-command path, single-token command (no warn), explicit args list with whitespace command (no warn since args present)
  • CHANGELOG entry under Unreleased -> Changed

Open question for the panel (apm-review-panel skill activates on this): warn vs. error in v1. Maintainer steer is "move fast, breaking changes OK if they make sense, adoption base small enough." Likely outcome: error in v1 with a clear fix-it message, since the loose shape was never specified and silently mis-parsing user input is worse than hard-failing.

Workstream: Part of #122 followup, alongside docs consolidation and apm install --mcp CLI extension.

Metadata

Metadata

Assignees

No one assigned

    Labels

    clidxenhancementNew feature or requestneeds-designNeeds discussion or design before implementation

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions