Skip to content

feat(deps): show recorded Targets and declared MCPs in apm deps list - #3747

Open
ChenXingtong (xtong629) wants to merge 5 commits into
microsoft:mainfrom
xtong629:feat/2976-deps-list-targets-mcps
Open

ChenXingtong (xtong629) wants to merge 5 commits into
microsoft:mainfrom
xtong629:feat/2976-deps-list-targets-mcps

Conversation

@xtong629

@xtong629 ChenXingtong (xtong629) commented Nov 15, 2026 •

Copy link
Copy Markdown

Description

apm deps list now shows two read-only columns for each installed package:

  • MCPs: the number of MCP servers the package declares, read the way install reads them and following install's format precedence (a native Agent Plugin's MCP resource, or the package's apm.yml, including the manifest generated for Claude and marketplace plugins). 0 means inspected and none declared; ? means the package could not be inspected.
  • Targets: the deployment targets recorded for the package in the listed scope, taken from the lockfile deployment ledger only. Nothing is inferred from the configured targets or from directory names. Records that cannot be attributed to the package show as unknown, ambiguous or a * marker, and a one-line legend under the table names only the causes present in that listing.

Listing stays read-only. There are no new flags, no lockfile schema change and no new tracking file.

Issue and approved scope

Issue: Fixes #2976

Human scope-approval comment: #2976 (comment) (danielmeppiel, 2026-10-19)

Does this PR complete the issue, or what remains?

It completes the issue. Every Done-when item in the approved scope record is covered (table below) and nothing listed as out of scope is touched.

Done when -> tests

Done-when item How it is met and tested
Distinguishes package contents, recorded deployment and live runtime health Contents are the Skills/Hooks/MCPs columns and recorded deployment is Targets. No runtime health is read or claimed. test_the_package_row_and_legend_reflect_the_recorded_evidence asserts all four headers in every case, in Rich and plain.
Known, unavailable, ambiguous and partially attributable target evidence, using canonical shared-root and ownership semantics, not configured-target lists or path guesses test_package_targets_reports_what_the_recorded_rows_support (21 cases, including shared roots, co-owners and scope), test_a_legacy_lockfile_has_no_recorded_deployments_in_either_scope, test_a_package_with_nothing_to_read_has_no_attributable_target, test_a_package_missing_from_the_lockfile_has_unknown_targets, TestRecordedOwnerIndex (core: the recorded-ledger gate, None versus empty, scope, co-owners), test_targets_cell_text_for_each_evidence_level, test_the_legend_names_only_the_causes_present_in_the_listing.
Successfully inspected empty MCP content is distinguishable from unavailable inspection test_mcp_count_is_the_number_of_servers_install_would_admit (zero cases), test_an_uninspectable_package_has_an_unavailable_mcp_count (20 failure types), test_the_count_follows_the_package_format_install_selects, test_programming_errors_propagate_instead_of_reading_as_unavailable, test_mcps_cell_text_is_a_count_zero_or_a_question_mark.
Counts do not multiply by target copies or borrow unrelated package contents The case "the MCP count is not multiplied by the package's target copies" in the row test above; each package is counted from its own directory in the count table; test_a_narrow_terminal_keeps_rows_aligned_and_the_legend_intact lists three packages with different counts.
Read-only CLI coverage: differing project and user records, aliases, MCP-only packages, legacy and shared ownership, Rich and plain rendering, the existing --insecure view test_all_scope_shows_differing_project_and_user_records, test_an_aliased_package_reads_its_own_records, test_aliased_packages_with_one_owner_and_repo_on_two_hosts_keep_their_own_targets, test_a_package_materialized_with_different_letter_case_still_finds_its_targets, the MCP-only, legacy-lockfile and --insecure cases of test_the_package_row_and_legend_reflect_the_recorded_evidence (each runs in Rich and plain), the shared-ownership and shared-root cases of the targets test, test_a_manifestless_skill_package_in_the_listing_declares_no_mcp_servers, test_a_real_local_path_install_records_the_targets_the_listing_reads.
Listing remains non-mutating and does not fetch registries, connect to servers, execute package content or adopt ownership test_listing_is_read_only_and_makes_no_network_calls and test_inspecting_a_plugin_is_read_only_and_offline block sockets and assert the project tree is unchanged. test_the_ledger_is_scanned_once_per_listing_not_once_per_package pins the single read of the ledger.
Update the CLI reference and shipped command guidance, keeping ordinary output readable docs/src/content/docs/reference/cli/deps.md, packages/apm-guide/.apm/skills/apm-usage/commands.md and CHANGELOG.md are updated. The marker is a single * and the legend appears only when a cell needs it; test_a_narrow_terminal_keeps_rows_aligned_and_the_legend_intact covers an 80-column terminal.

Type of change

  • Bug fix
  • New feature
  • Documentation
  • Maintenance / refactor

Testing

  • Tested locally
  • All existing tests pass
  • Added tests for new functionality (if applicable)

"All existing tests pass" is left unticked only because of the pre-existing failures below.

New tests: 137 in tests/unit/test_deps_list_targets_mcps.py and 10 in tests/unit/core/test_deployment_state.py (147 in total). _inventory.py is at 100% line and branch coverage from them.

Full unit suite: 9 failed, 27,288 passed. All 9 also fail on clean upstream/main: the two "removed plugin shortcut" tests (test_pack_cli_surface and test_plugin_init_command), three test_mcp_command install-forwarding tests, test_cli_consistency for mcp install, the test_manifest_extension_keys dry-run test (it fails there under -n auto and passes when run alone), and the two Windows test_git_env tests. ruff check and ruff format --check are clean.

Also run locally: pylint R0801, both lint scripts, the architecture ratchet and test-quality checks, and the docs build with its link and CLI-registry checks (129 pages, no broken links).

Spec conformance (OpenAPM v0.1)

If this PR changes behaviour that an OpenAPM v0.1 req-XXX covers,
confirm the three-step ritual in the
development guide:

  • Spec edit: docs/src/content/docs/specs/openapm-v0.1.md updated
    (new/changed <a id="req-XXX"></a> anchor + prose + Appendix C
    row).
  • Manifest edit: docs/src/content/docs/specs/manifests/openapm-v0.1.requirements.yml
    updated.
  • Test edit: a @pytest.mark.req("req-XXX") test under
    tests/spec_conformance/ added or extended.
  • CONFORMANCE.{md,json} regenerated via
    uv run --extra dev python -m tests.spec_conformance.gen_statement
    and committed.
  • N/A -- this PR does not change OpenAPM-observable behaviour.

Notes for reviewers

  • MCP-only packages show unknown in real installs. Their MCP rows are recorded under the root owner, not the package. Satisfying the issue's original example (an MCP-only package shown with its targets) would need guessing by server name or a ledger change, both out of scope. I'm happy to open a follow-up issue for per-package MCP attribution.
  • Behavior change: malformed plugin MCP document. A plugin whose mcp.json is malformed now shows ? instead of 0, because the whole MCP document is unreadable.
  • Behavior change: manifests that fail validation are listed. A manifest whose YAML parses but that fails validation is now listed instead of being dropped, using the same tolerant read as deps tree and deps info (_tolerant_identity). MCPs shows ? only when the MCP declarations themselves cannot be read (for example an unsupported transport); other validation failures, such as an empty version, show unknown for the version and a normal count. YAML that cannot be parsed keeps its existing warning and stays hidden, pinned by test_malformed_apm_yml_warning_excludes_path_and_hash.
  • Core change. Only DeploymentLedgerCodec.recorded_owner_index is new in core: a one-pass, scope-filtered owner-to-records map that shares a private _recorded_ledger gate with recorded_target_names, whose strict scope comparison is unchanged. Tests pin both. package_targets is a pure function of a package's resolved rows, and the listing builds the index once and maps "no recorded evidence" and "not in the lockfile" to None. If you would rather have the per-package filtering live in the deps command, it can move.
  • Owner lookup. Each listed package is matched to its lockfile owner by its materialized path (installed_package_path), so aliased packages that share an owner/repo on different hosts and mixed-case directories resolve to the right owner. A lockfile entry whose path cannot be resolved gets no owner (its Targets read unknown) and does not affect any other row.
  • Scope rule. recorded_owner_index uses locator_in_scope, so a row recorded at the scope its path implies appears in both scopes' listings. A row recorded at a different scope is exclusive. This is the existing canonical rule, pinned by characterization tests. In practice each scope has its own lockfile.
  • Shared ownership and shared roots. A record counts for every package in owners. A shared-directory row (for example .agents/skills) counts only for the target recorded on that row and is never inferred from the directory.
  • MCP counting. It asks canonical plugin admission first and then reads apm.yml, as install does, and adds a public authored_mcp_declarations wrapper in mcp_config_view.py. A package whose apm.yml declares dependencies keeps its manifest count even beside a broken plugin.json (install ignores that file). A metadata-only apm.yml beside a broken plugin.json or a disabled mcp.json shows ?: install rejects the former and admits the latter as a plugin. Skill, Claude skill and hook packages count 0; Codex compatibility manifests show ?.
  • Errors. Only inspection failures (OSError, ValueError, yaml.YAMLError) read as ?. Wrongly typed fields that the MCP parser rejects with TypeError or AttributeError are converted at the parser call only; other exceptions propagate.
  • Test strength. 34 deliberate mutations to the new logic, including the review-feedback fixes, were each caught by the suite.
  • Size. About 485 non-test lines (about 310 in the new _inventory.py); the rest is tests.
  • Width. The existing 120-column minimum for the Rich table is unchanged. The plain header grows from 94 to 107 characters (113 to 126 with --insecure), and the rule now matches the header width. Targets is the last column.
  • One existing test changed. test_pr2705_folds.py::test_deps_list_reports_the_natively_registered_plugin_with_its_version used to assert that unknown appears nowhere in the output. A native plugin's Targets cell is legitimately unknown, so it now reads the version token that follows the package name.

Add two read-only columns to `apm deps list` (Rich, plain and --insecure):

* MCPs: the number of MCP servers a package declares, read through the same
  package interpretation install uses (apm.yml, including manifests generated
  for Claude and marketplace plugins; the canonical Agent Plugin loader for
  native plugins). `0` means inspected with none declared; `?` means the
  package could not be inspected. Only inspection failures are treated that
  way; programming errors propagate.
* Targets: the deployment targets recorded for the package in the listed
  scope, from the lockfile deployment ledger via the new
  DeploymentLedgerCodec.recorded_owner_records, which shares the evidence gate
  of recorded_target_names and uses the canonical locator_in_scope test.
  Nothing is inferred from the configured targets or from directories: a
  shared-root row (for example .agents/skills) counts only for the target
  recorded on it. Records that cannot be attributed show as `unknown`,
  `ambiguous` or a `*` marker. A one-line legend under the table names only
  the causes present in that listing: legacy records, MCP servers recorded
  for the whole scope, or MCP definitions that could not be read. An MCP-only
  package shows `unknown` unless a record names it as an owner.

Listing stays read-only: no registry fetches, server connections, package
execution or ownership adoption, and no lockfile schema change. Add a public
authored_mcp_declarations wrapper for the canonical MCP declaration parser.

Refs microsoft#2976
@xtong629

Copy link
Copy Markdown
Author

@microsoft-github-policy-service agree

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Unresolved issues can miscount plugin MCPs, show incorrect package targets, hide packages with malformed MCP declarations, and add a full deployment-ledger scan for every listed package.

4 open issues
What changed in this PR

Adds read-only deployment and MCP inventory to apm deps list, helping users distinguish package contents from recorded deployment targets without implying runtime health.

Changes:

  • Adds MCPs and Targets columns to Rich and plain listings, with markers for unavailable or ambiguous evidence.
  • Reuses deployment-ledger ownership and MCP declaration parsing without new flags or tracking files.
  • Adds regression coverage and updates CLI documentation and shipped guidance.
File Description
tests/​unit/​test_deps_list_targets_mcps.py Tests counts, target attribution, rendering, scopes, and read-only behavior.
tests/​unit/​core/​test_deployment_state.py Tests recorded-owner filtering and scope semantics.
tests/​unit/​copilot_plugins/​test_pr2705_folds.py Makes the version assertion independent of unknown target values.
src/​apm_cli/​integration/​mcp_config_view.py Exposes the canonical MCP declaration parser.
src/​apm_cli/​core/​deployment_ledger.py Adds a recorded per-owner deployment view.
src/​apm_cli/​commands/​deps/​cli.py Collects and renders the new inventory columns.
src/​apm_cli/​commands/​deps/​_inventory.py Implements MCP counts, target evidence, and legends.
packages/​apm-guide/​.apm/​skills/​apm-usage/​commands.md Updates shipped dependency-list guidance.
docs/​src/​content/​docs/​reference/​cli/​deps.md Documents column meanings and evidence limits.
CHANGELOG.md Records the new inventory feature.

Review effort: Balanced

Comment thread src/apm_cli/commands/deps/_inventory.py Resolved
Comment thread src/apm_cli/commands/deps/cli.py Resolved
Comment thread src/apm_cli/commands/deps/cli.py Resolved
Comment thread src/apm_cli/core/deployment_ledger.py Resolved
* Count a native Agent Plugin's MCP servers through canonical plugin
  admission before reading apm.yml, so a metadata-only apm.yml no longer
  hides them. An apm.yml that declares dependencies still wins, as install
  selects it; a metadata-only apm.yml beside a broken plugin.json or a
  disabled mcp.json reads as unavailable, matching what install does.
* Look up each package's lockfile owner by its materialized path through
  installed_package_path instead of the host-blind canonical key, so aliased
  packages that share an owner/repo on different hosts keep their own
  targets and mixed-case materializations are found.
* Keep a package listed with MCPs `?` when its apm.yml parses as YAML but the
  strict parser rejects it (for example an unsupported MCP transport).
  YAML that cannot be parsed keeps the existing read-failure warning.
* Build the scope-filtered owner-to-records index once per listing with
  DeploymentLedgerCodec.recorded_owner_index, the only new core method.
  package_targets is now a pure function of the owner's resolved records;
  the listing maps "no recorded evidence" and "not in the lockfile" to None.
  The recorded-ledger gate, None versus empty semantics and co-owner credit
  are unchanged.

Refs microsoft#2976
@danielmeppiel

Copy link
Copy Markdown
Collaborator

Docs re-sweep (#3800) coordination: packages/apm-guide/.apm/skills/apm-usage/commands.md had about 25 duplicated table rows (merge leftovers). #3849 removes the ones outside your hunk. Three duplicates sit inside your hunk, so they're yours to resolve, not mine:

Could you fold this into this PR? Depending on which merges first, #3849 may need a rebase; I'll handle that on my side.

@danielmeppiel

Copy link
Copy Markdown
Collaborator

Update: #3849 and #3850 are folded into #3848. The coordination notes above still apply. Where they reference #3849 or #3850, read #3848.

@xtong629

Copy link
Copy Markdown
Author

Folded in (993358d): removed the two duplicate apm uninstall PKGS... rows in my hunk, keeping the merged #3672 row, and kept a single apm deps list row with the MCPs/Targets sentence and the non-default-hosts text. I also merged upstream/main (2b192e5) to resolve a CHANGELOG conflict. Since #3848 has already landed, nothing should need rebasing on your side.

…-targets-mcps

# Conflicts:
#	CHANGELOG.md
#	packages/apm-guide/.apm/skills/apm-usage/commands.md
#	src/apm_cli/commands/deps/cli.py

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[FEATURE] Show deployment targets and MCP counts in deps list

3 participants