feat(asset): explore built AssetBundle contents

[haranishi]

Description

Adds 2 read-only operations to manage_asset to explore built AssetBundles through MCP. You can navigate directories from the bundle listing and inspect the asset names and scene names in a selected file.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update
• Refactoring (no functional changes)
• Test update

Changes Made

• list_asset_bundles: Returns a list of directories and files with UnityFS, UnityRaw, or UnityWeb headers. Listing does not load bundles.
• get_asset_bundle_info: Returns the selected bundle's name, size, asset count, scene count, and the names of its contents. It does not load assets or scenes and, after processing, unloads only the bundle it opened.
• Both operations restrict paths to the project and do not follow symbolic links. Results support pagination with a default page size of 25 and a maximum of 200. Empty files, named pipes, and similar entries are excluded before opening.
• The same operations are available through the CLI's asset bundles and asset bundle-info. On the Python side, these 2 operations do not trigger automatic AssetDatabase updates.
• Retrieves the AssetBundle type through reflection without adding static references to optional built-in modules.
• Updates the reference pages, usage examples, CLI descriptions, manifest descriptions, and both skill copies. The MCP tool count and groups remain unchanged.

Compatibility / Package Source

• Unity version(s) tested: 6000.3.20f1, Unity Test Framework 1.6.0.
• Package source used (#beta, #main, tag, branch, or file:): Verified this branch, created from beta, through a file: reference in a separate test project.
• Resolved commit hash from Packages/packages-lock.json (if using a Git package URL): Not applicable (file: reference). The base is 142ea0a.

Testing/Screenshots/Recordings

• Python tests (cd Server && uv run --extra dev pytest -q tests): 1,589 passed, 18 skipped.
• Unity EditMode tests: All 17 tests passed in the final run.
• Unity PlayMode tests
• Package import/compile check
• Not applicable (explain why in Additional Notes)

Verified that before the fix, the listing operation returned Unknown action and the regression test failed. After the fix, verified discovery of actual built asset and scene bundles, multiple pages, rejection of paths outside the project, rejection of symbolic links, and exclusion of named pipes with no writer. After repeated detail retrieval, none of the operation's own handles remained, and other loaded bundles, assets, and open scenes were preserved. If the selected bundle is already loaded, the operation returns an error and preserves that bundle.

Removed the AssetBundle module and the built-in modules that depend on it, confirmed that none remained in the resolved dependencies, and verified that the package still compiled. The manifest, lock file, and test source were then restored to their original state.

Also verified that the actual FastMCP schema included the 2 operations, CLI forwarding and input validation, generated documentation consistency, the site build, and consistency between the skill copies.

Ran bash tools/check-unity-versions.sh. The specified versions 2021.3.45f2, 2022.3.62f1, 6000.0.75f1, and 6000.4.8f1 were all skipped because they were not installed.

Documentation Updates

• I have added/removed/modified tools or resources
• If yes, I have updated all documentation files using:
  • The LLM prompt at tools/UPDATE_DOCS_PROMPT.md (recommended)
  • Manual review of the generated changes

Related Issues

Fixes #1129

Additional Notes

Verification was performed on macOS with the Unity version listed above. Other Unity versions and Windows and Linux machines were not verified. Detail retrieval requires the AssetBundle API available in the Editor and a bundle built for the corresponding platform.

Fork CI verification

Checked the GitHub Actions results for the same commit f25e0c21957c9caf84bcc327909eeb54e166d7a3. The Python tests succeeded, as did the harness tests that run without Unity.

C# compilation also succeeded with Unity 6000.0.75f1. Runtime and Editor were compiled for each of the Windows, macOS, and Linux configurations.

The docs build succeeded. The generated-docs drift check also succeeded.

The E2E tests and the Unity Editor tests that require a license were skipped.

The upstream GitHub Actions are waiting for a maintainer to approve the run for the current commit. The CI successes above are results from runs on the fork that verified the same commit.

Summary by CodeRabbit

• New Features

  • Browse built AssetBundles in project directories, with sorted, paginated listings of bundles and subdirectories.
  • Inspect bundle metadata and asset or scene names without loading assets or scenes. Results support page sizes of 1–200, with a default of 25.
  • Use the new asset bundles and asset bundle-info CLI commands to list and inspect bundles.

• Documentation

  • Updated CLI and tool guides with bundle-browsing examples, options, and usage details.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: f34aed85-9d44-496a-ba8d-9ff4a54bb37a

📥 Commits

Reviewing files that changed from the base of the PR and between 142ea0a and f25e0c2.

📒 Files selected for processing (15)

• .claude/skills/unity-mcp-skill/SKILL.md
• MCPForUnity/Editor/Helpers/AssetBundleExplorer.cs
• MCPForUnity/Editor/Helpers/AssetBundleExplorer.cs.meta
• MCPForUnity/Editor/Tools/ManageAsset.cs
• Server/src/cli/commands/asset.py
• Server/src/services/tools/manage_asset.py
• Server/tests/integration/test_asset_bundle_explorer.py
• Server/tests/test_asset_bundle_cli.py
• TestProjects/UnityMCPTests/Assets/Tests/EditMode/Tools/AssetBundleExplorerTests.cs
• TestProjects/UnityMCPTests/Assets/Tests/EditMode/Tools/AssetBundleExplorerTests.cs.meta
• manifest.json
• unity-mcp-skill/SKILL.md
• website/docs/guides/cli.md
• website/docs/reference/cli.md
• website/docs/reference/tools/core/manage_asset.md

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 1 remain after this review.

📝 Walkthrough

The change adds read-only AssetBundle listing and inspection through manage_asset and two CLI commands. Both operations support pagination. Inspection returns bundle metadata and asset or scene names without unloading loaded assets.

Changes: AssetBundle explorer

Layer / File(s)	Summary
Action contracts and Unity dispatch MCPForUnity/Editor/Tools/ManageAsset.cs, Server/src/services/tools/manage_asset.py, Server/tests/integration/test_asset_bundle_explorer.py, manifest.json	The server and Unity tool accept list_asset_bundles and get_asset_bundle_info. These actions skip dirty-project refresh. Integration tests cover action validation, forwarded arguments, and preflight errors.
Bundle listing and inspection MCPForUnity/Editor/Helpers/AssetBundleExplorer.cs, MCPForUnity/Editor/Helpers/AssetBundleExplorer.cs.meta, TestProjects/UnityMCPTests/Assets/Tests/EditMode/Tools/AssetBundleExplorerTests.cs*	The helper validates project-local paths and pagination. It lists directories and files with recognized Unity bundle headers, or returns paginated bundle metadata and asset or scene names. Tests cover validation, paging, and loaded-state behavior.
CLI commands and usage guidance Server/src/cli/commands/asset.py, Server/tests/test_asset_bundle_cli.py, *.md, website/docs/guides/cli.md, website/docs/reference/cli.md, website/docs/reference/tools/core/manage_asset.md, manifest.json	The CLI adds bundles and bundle-info, with a default page size of 25 and a maximum of 200. Tests check command arguments and invalid pagination. The skills and reference guides document the operations and examples.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant CLI as Asset CLI
  participant Tool as manage_asset
  participant Unity as Unity ManageAsset
  participant Explorer as AssetBundleExplorer
  participant BundleAPI as Unity AssetBundle API
  CLI->>Tool: Send bundle action, path, and pagination
  Tool->>Unity: Forward action and parameters
  Unity->>Explorer: Dispatch listing or inspection request
  Explorer->>BundleAPI: Load bundle and retrieve metadata and entries
  Explorer-->>Unity: Return paginated result
  Unity-->>Tool: Return action response
  Tool-->>CLI: Format and return result

Loading

Suggested reviewers: scriptwonder

Merge Risk: ⚪ Minimal · up to f25e0

The read-only AssetBundle commands appear ready to merge after normal checks.

Pre-merge checks · 4 · 1

Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 10.81% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 37 functions across 7 files. (8 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check		Issue #1129 requests a convenient MCP command to explore AssetBundles. The PR adds the read-only list_asset_bundles and get_asset_bundle_info actions, CLI commands, project-path and symlink safegu…
Out of Scope Changes check		The changes remain within Issue #1129. The CLI commands, documentation updates, and automated tests support AssetBundle exploration. No unrelated functional change is demonstrated.
Title check		The title clearly and concisely identifies the main change: exploring built AssetBundle contents.
Description check		The description follows the template and documents the feature, change type, implementation details, compatibility, testing, documentation updates, related issue, and limitations.

Full details: Docstring Coverage

Explanation

Docstring coverage is 10.81% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 37 functions across 7 files. (8 skipped: 8 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.