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.
Context: Surfaced via #122 and the followup conversation with @lirantal -- users sometimes write
command: "npx mcp-server-foo"(single shell-string) instead of the canonicalcommand: 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:commandMUST be a single binary path (no whitespace, no args)argsis the list of argumentsToday APM accepts the shell-string shape with no warning, hiding the mistake until something breaks.
Proposed change
Parse-time validation that detects:
transport == "stdio", ANDcommandis a string containing whitespace, ANDargsis empty or missingThen emit a structured warning with a concrete fix-it suggestion:
Scope
src/apm_cli/deps/aggregator.pynear_install_inline_mcp_depsor wherever the inline MCP shape is normalized)[!]STATUS_SYMBOLOpen 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 --mcpCLI extension.