feat(validation): reject shell-string command in MCP stdio entries

[danielmeppiel]

Summary

Reject self-defined stdio MCP entries with whitespace-containing command and no args at parse time. Surfaces with a fix-it error pointing at the canonical shape.

Why

Surfaced via #122 (thanks @lirantal). Users coming from the universal mcp.json / Claude Desktop / Cursor mental model write:

- name: nodejs-api-docs
  registry: false
  transport: stdio
  command: "npx mcp-server-nodejs-api-docs"   # WRONG: shell line in `command`

and get confused when nothing works. APM never whitespace-split command; per schema, command is a single binary path and args is the list of arguments. Silently accepting the loose shape was a UX trap.

What changes

MCPDependency.validate() now raises ValueError when:

• registry: false, AND
• transport == "stdio", AND
• command is a string containing whitespace, AND
• args is empty/missing

Error message includes a fix-it that splits the offending command at the first whitespace boundary and shows the corrected command: / args: shape.

Self-defined MCP dependency 'nodejs-api-docs': 'command' must be a single binary
path, not a shell line. APM does not split 'command' on whitespace.
Got: command='npx -y mcp-server-nodejs-api-docs'.
Did you mean: command: npx, args: ["-y", "mcp-server-nodejs-api-docs"] ?
See https://microsoft.github.io/apm/guides/mcp-servers/ for the canonical stdio shape.

Why error, not warn

Per maintainer steer (issue #806 thread): "move fast, breaking changes OK if they make sense, adoption base small enough." Panel ratified:

• devx-ux: npm/cargo error on bad manifests; warn-then-mis-execute is worse UX.
• supply-chain-security: Silently passing a whitespace string to a runtime that doesn't split = broken or surprising. Fail closed.
• CEO: The loose shape was never specified; CHANGELOG (BREAKING) entry covers the comms.

If user feedback shows broader migration friction, downgrading to a warn is a one-line change.

Edge cases covered (tests)

• Canonical shape (command: npx, args: [...]) keeps working
• Whitespace command + empty args -> rejected with fix-it
• Whitespace command + explicit args -> accepted (paths with spaces, e.g. /opt/My App/server, are legal when author has owned shape)
• Tabs in command -> also rejected (covers \t, not just spaces)
• Error message includes the suggested command: and args: tokens

Tests

tests/unit/test_mcp_overlays.py: 46 passed
tests/unit tests/test_console.py: 4069 passed

CHANGELOG

Added under ## [Unreleased] / Changed (BREAKING).

Followups

• feat(cli): extend 'apm install --mcp' for declarative MCP server addition #807 -- apm install --mcp will use this validator path; entries built from -- boundary on the CLI cannot trigger this error by construction
• docs: consolidate MCP coverage into a single canonical guide #808 -- new guides/mcp-servers.md will be the canonical home of the URL referenced in the error message; the link is already correct (URL pattern matches the existing site routing)

Closes #806
Refs #122

[Copilot]

Pull request overview

Adds stricter parse-time validation for self-defined stdio MCP dependencies to prevent the common “shell string in command” misconfiguration, and also updates package-type detection/observability to address plugin-vs-hooks classification edge cases.

Changes:

• Reject self-defined stdio MCP entries where command contains whitespace and args is missing/empty, with a fix-it suggestion in the error.
• Introduce richer package-type detection evidence and reorder the detection cascade to classify plugin-shaped packages before hook-only packages.
• Add/extend unit tests and update CHANGELOG.md entries for the behavior changes.

Show a summary per file

File	Description
src/apm_cli/models/dependency/mcp.py	Adds the new stdio shell-string command validation and fix-it error text.
tests/unit/test_mcp_overlays.py	Adds unit tests covering the new MCP validation behavior and error contents.
src/apm_cli/models/validation.py	Adds DetectionEvidence + gather_detection_evidence() and changes detection order to prefer plugin evidence over hooks.
tests/test_apm_package_models.py	Adds regression tests for plugin-vs-hooks classification and new evidence-gathering helper.
src/apm_cli/install/sources.py	Centralizes package-type label formatting and ensures hook packages get a label.
tests/unit/install/test_sources_classification.py	New tests ensuring every classifiable PackageType has a human-readable label.
CHANGELOG.md	Adds entries describing the new MCP validation breaking change and the plugin classification fix.

Copilot's findings

Comments suppressed due to low confidence (1)

src/apm_cli/models/dependency/mcp.py:142

• This validation rejects any whitespace in command when args is empty, but per the schema command is a binary path and valid paths can contain spaces (notably on Windows, e.g. under Program Files). Consider narrowing the check to the specific "shell line" anti-pattern (e.g. multiple tokens and command doesn't look like a path) so you don't block legitimate single-binary paths that contain spaces but have no arguments.

            if (
                self.transport == 'stdio'
                and isinstance(self.command, str)
                and any(ch.isspace() for ch in self.command)
                and not self.args
            ):

• Files reviewed: 7/7 changed files
• Comments generated: 7

[Copilot]

This changelog entry ends with (#122), but #122 is an issue (already referenced via Closes #806/Refs #122) and cannot also be the PR number. Per the repo changelog convention, the trailing parenthetical should be the PR number for this change.

[Copilot]

This entry appears to be a normal code change but does not end with a PR number, and (#780) reads like an issue reference rather than the required (#PR_NUMBER) suffix. Please adjust to Keep-a-Changelog format: one line per PR, ending with this PR's number (issue refs can stay in the sentence body).

[Copilot]

This PR's title/description are focused on MCP stdio validation (#806/#122), but this diff also adds new package-type detection behavior (gather_detection_evidence, .claude-plugin evidence, and a reordered detection cascade) tied to #780. If this extra scope is intentional, it should be called out explicitly in the PR description; otherwise consider splitting to keep review/rollback risk isolated.

[Copilot]

The fix-it suggestion splits command using .partition(' '), which only handles a literal space. For inputs containing other whitespace (e.g. tabs, multiple whitespace), the validation still triggers but the suggested command/args shape will be incorrect (e.g. npx\t-y\tpkg produces command: npx\t-y\tpkg, args: []). Split on any whitespace with a single pass (e.g. split(maxsplit=1) / regex \s+) so the suggestion matches the validation condition (isspace()).

This issue also appears on line 137 of the same file.

Suggested change

	first, _, rest = self.command.strip().partition(' ')
	command_parts = self.command.strip().split(maxsplit=1)
	first = command_parts[0] if command_parts else ''
	rest = command_parts[1] if len(command_parts) > 1 else ''

[Copilot]

The error message links to https://microsoft.github.io/apm/guides/mcp-servers/, but there is no mcp-servers guide in the current docs tree, so users will hit a 404 from the fix-it error. Either add the page in this PR or point to an existing canonical section (e.g. the current MCP dependency docs) until the new guide lands.

Suggested change

	f"See https://microsoft.github.io/apm/guides/mcp-servers/ "
	f"See https://microsoft.github.io/apm/reference/dependencies/ "

[Copilot]

These tests mix src.apm_cli... and apm_cli... imports for the same module. That can import the same source file twice under different module names, leading to duplicated class/enum singletons (e.g. PackageType identity mismatches) and flaky isinstance / equality behavior. Please standardize on a single import style within this file (preferably the existing src.apm_cli... used at the top).

[Copilot]

MARKETPLACE_PLUGIN classification now also triggers on a bare .claude-plugin/ directory (see detect_package_type), but this label only mentions plugin.json or agents/skills/commands. That makes the install-time classification log misleading for the manifest-less plugin case. Update the wording (or make it more generic) so it matches the actual detection signals.