[brandonkelly]

Summary

asset_folders_list couldn't find a volume's root folder by query, because criteria.parentId only accepted integers. Agents need that folder's ID to list a volume's top-level folders, or to create one with asset_folders_create, which requires parentId.

 asset_folders_list criteria
-  parentId: integer                 // null -> -32602 "Expected `integer`, but received `null`"
+  parentId: integer | null          // null -> volumes' root folders

FolderCriteria ignores a null parentId, so findFolders() would have returned every folder. null is therefore mapped to :empty:, the same match that Assets::getRootFolderByVolumeId() uses:

list(criteria)
  if criteria has parentId: null
    criteria.parentId = ":empty:"
  findFolders(criteria), filtered by viewContents

Combine it with volumeId to get one volume's root folder. Then pass that folder's ID as parentId to list the volume's top-level folders. The parentId description says this.

Craft 6: craftcms/cms 6.x has the same integer-only parentId in src/Mcp/Capabilities/AssetFolders.php, so this should be ported.

Evidence

• Before: asset_folders_list {criteria: {parentId: null}} →
  Invalid parameters for tool 'asset_folders_list': Property '/criteria/parentId': Invalid type. Expected 'integer', but received 'null'.
  After: it returns only root folders 1000 and 1001 from the volume folder fixtures. The subfolder under 1000 is left out.

New AssetFoldersCapabilityTest::testListFiltersToRootFoldersForNullParentId calls the tool through tools/call on the authenticated server, so the input schema applies:

store subfolder (parentId 1000)
tools/call asset_folders_list {criteria: {parentId: null}} -> ids == [1000, 1001]

• Before (schema integer-only): -32602 Invalid parameters … Expected 'integer', but received 'null'
  Before (without the :empty: mapping): Failed asserting that two arrays are equal. The subfolder was included.
  After: OK (1 test, 2 assertions)

ECS and Rector are clean. PHPStan passes (pre-commit hook).

[Copilot]

🟡 Changes recommended

The regression test bypasses MCP schema validation, so it would miss a regression that rejects null parentId values and restores the client invalid-parameters error.

1 open issue

• Test null parentId through MCP schema validation · New

What changed in this PR

This PR lets MCP clients query volume root folders with asset_folders_list, providing the parent IDs needed to list or create top-level folders.

Changes:

• Accepts null for criteria.parentId and maps it to the explicit root-folder filter.
• Adds a regression test confirming that root-folder queries exclude subfolders.
• Documents the behavior in the tool schema and changelog.

File	Description
tests/​unit/​mcp/​AssetFoldersCapabilityTest.php	Tests root-folder filtering with a null parent ID.
src/​mcp/​capabilities/​AssetFolders.php	Allows null parent IDs and translates them into root-folder queries.
CHANGELOG.md	Announces support for querying root folders.

_{Review effort: Balanced}

[brandonkelly]

Fixed in 52b6968: the test now calls asset_folders_list through tools/call on the authenticated server, so the input schema applies. It fails both when parentId reverts to integer-only (-32602 … Expected 'integer', but received 'null') and when the :empty: mapping is removed (the subfolder is included).