Repository navigation
feat(deps): show recorded Targets and declared MCPs in apm deps list - #3747
ChenXingtong (xtong629) wants to merge 5 commits into
Conversation
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
e41b6ae to
f2d0005
Compare
|
@microsoft-github-policy-service agree |
There was a problem hiding this comment.
🟡 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
MCPsandTargetscolumns 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
* 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
|
Docs re-sweep (#3800) coordination:
Could you fold this into this PR? Depending on which merges first, #3849 may need a rebase; I'll handle that on my side. |
…-targets-mcps # Conflicts: # CHANGELOG.md
|
Folded in (993358d): removed the two duplicate |
…-targets-mcps # Conflicts: # CHANGELOG.md # packages/apm-guide/.apm/skills/apm-usage/commands.md # src/apm_cli/commands/deps/cli.py

Description
apm deps listnow shows two read-only columns for each installed package:apm.yml, including the manifest generated for Claude and marketplace plugins).0means inspected and none declared;?means the package could not be inspected.unknown,ambiguousor 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
Skills/Hooks/MCPscolumns and recorded deployment isTargets. No runtime health is read or claimed.test_the_package_row_and_legend_reflect_the_recorded_evidenceasserts all four headers in every case, in Rich and plain.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,Noneversus empty, scope, co-owners),test_targets_cell_text_for_each_evidence_level,test_the_legend_names_only_the_causes_present_in_the_listing.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.test_a_narrow_terminal_keeps_rows_aligned_and_the_legend_intactlists three packages with different counts.--insecureviewtest_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--insecurecases oftest_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.test_listing_is_read_only_and_makes_no_network_callsandtest_inspecting_a_plugin_is_read_only_and_offlineblock sockets and assert the project tree is unchanged.test_the_ledger_is_scanned_once_per_listing_not_once_per_packagepins the single read of the ledger.docs/src/content/docs/reference/cli/deps.md,packages/apm-guide/.apm/skills/apm-usage/commands.mdandCHANGELOG.mdare 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_intactcovers an 80-column terminal.Type of change
Testing
"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.pyand 10 intests/unit/core/test_deployment_state.py(147 in total)._inventory.pyis 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_surfaceandtest_plugin_init_command), threetest_mcp_commandinstall-forwarding tests,test_cli_consistencyformcp install, thetest_manifest_extension_keysdry-run test (it fails there under-n autoand passes when run alone), and the two Windowstest_git_envtests.ruff checkandruff format --checkare 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-XXXcovers,confirm the three-step ritual in the
development guide:
docs/src/content/docs/specs/openapm-v0.1.mdupdated(new/changed
<a id="req-XXX"></a>anchor + prose + Appendix Crow).
docs/src/content/docs/specs/manifests/openapm-v0.1.requirements.ymlupdated.
@pytest.mark.req("req-XXX")test undertests/spec_conformance/added or extended.CONFORMANCE.{md,json}regenerated viauv run --extra dev python -m tests.spec_conformance.gen_statementand committed.
Notes for reviewers
unknownin 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.mcp.jsonis malformed now shows?instead of0, because the whole MCP document is unreadable.deps treeanddeps info(_tolerant_identity).MCPsshows?only when the MCP declarations themselves cannot be read (for example an unsupported transport); other validation failures, such as an empty version, showunknownfor the version and a normal count. YAML that cannot be parsed keeps its existing warning and stays hidden, pinned bytest_malformed_apm_yml_warning_excludes_path_and_hash.DeploymentLedgerCodec.recorded_owner_indexis new in core: a one-pass, scope-filtered owner-to-records map that shares a private_recorded_ledgergate withrecorded_target_names, whose strict scope comparison is unchanged. Tests pin both.package_targetsis 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" toNone. If you would rather have the per-package filtering live in the deps command, it can move.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 (itsTargetsreadunknown) and does not affect any other row.recorded_owner_indexuseslocator_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.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.apm.yml, as install does, and adds a publicauthored_mcp_declarationswrapper inmcp_config_view.py. A package whoseapm.ymldeclares dependencies keeps its manifest count even beside a brokenplugin.json(install ignores that file). A metadata-onlyapm.ymlbeside a brokenplugin.jsonor a disabledmcp.jsonshows?: install rejects the former and admits the latter as a plugin. Skill, Claude skill and hook packages count0; Codex compatibility manifests show?.OSError,ValueError,yaml.YAMLError) read as?. Wrongly typed fields that the MCP parser rejects withTypeErrororAttributeErrorare converted at the parser call only; other exceptions propagate._inventory.py); the rest is tests.--insecure), and the rule now matches the header width.Targetsis the last column.test_pr2705_folds.py::test_deps_list_reports_the_natively_registered_plugin_with_its_versionused to assert thatunknownappears nowhere in the output. A native plugin'sTargetscell is legitimatelyunknown, so it now reads the version token that follows the package name.