feat(mcp): snapshot read tools

[andypalmi]

Summary

Reworks the snapshot tools in forge/ee/lib/mcp/tools/snapshots.js.

Consolidates the split hosted/remote tools into single tools that take an instanceType ("hosted" or "remote"), matching the shape used by the other hosted/remote twins:

• platform_list_instance_snapshots - GET /api/v1/projects/:instanceId/snapshots or GET /api/v1/devices/:instanceId/snapshots (replaces platform_list_hosted_instance_snapshots and platform_list_remote_instance_snapshots)
• platform_create_instance_snapshot - POST to the same routes (replaces platform_create_hosted_instance_snapshot and platform_create_remote_instance_snapshot)

Adds three read tools:

• platform_get_snapshot - GET /api/v1/snapshots/:id - snapshot metadata; resolves the owner (hosted or remote) automatically
• platform_get_snapshot_full - GET /api/v1/snapshots/:id/full - full payload (flows, settings, env); hidden env values are blanked, keys kept, credentials never included
• platform_get_hosted_instance_device_target_snapshot - GET /api/v1/projects/:instanceId/devices/settings - the snapshot a hosted instance's assigned devices are set to deploy (null when none)

The read tools are annotated readOnlyHint: true, destructiveHint: false.

No permissions changes: #8185 removed the hardcoded user:expert-mcp scope allow-list, so expert MCP tokens now inherit the user's permissions gated by team role and no allow-list entries are needed.

Closes #7687

Test plan

• eslint on changed files
• mocha on changed files

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 76.35%. Comparing base (4732870) to head (6415b20).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #7720      +/-   ##
==========================================
+ Coverage   76.20%   76.35%   +0.15%     
==========================================
  Files         443      443              
  Lines       23728    23734       +6     
  Branches     6315     6315              
==========================================
+ Hits        18081    18123      +42     
+ Misses       5647     5611      -36     

Flag	Coverage Δ
backend	76.35% <100.00%> (+0.15%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[andypalmi]

@cstns reworked the snapshot read tools in 49a1cad based on your review, taking a slightly different route than the literal suggestions:

• Consolidated the get and list tools so hosted and remote are no longer split. platform_get_hosted_instance_snapshot and platform_get_remote_instance_snapshot are gone; platform_get_snapshot (the owner-agnostic /snapshots/:id route) is now the single get tool, since it resolves the owner from the snapshot itself. The two list tools are merged into platform_list_instance_snapshots with an instanceType ('hosted' | 'remote') discriminator, matching how platform_get_team_instance_counts and the other twins are shaped.
• On the rename note: I kept platform_get_snapshot rather than renaming it to hosted, because /snapshots/:id serves both hosted and device snapshots, so a "hosted" name would be misleading. Clarified the description instead.
• On the env exposure: only platform_get_snapshot_full returns env values (the metadata tools do not). It now blanks the values of hidden env vars while keeping visible ones, mirroring the template endpoint's behaviour, so secrets are not handed over while the keys stay visible.

Let me know if you'd prefer different naming.

[andypalmi]

Follow-up in 6d7de1a, continuing the consolidation and picking up your last comment:

• Merged the two create tools into platform_create_instance_snapshot, same instanceType ('hosted' | 'remote') shape as the list tool. The remote reachability note (device must be online, check status first) is now conditional in the description.
• Renamed platform_get_instance_device_settings to platform_get_hosted_instance_device_target_snapshot. The route only returns { targetSnapshot } (the snapshot the instance's assigned devices are set to deploy), so the old "device settings" name read as settings of a device. Title and description now name what it actually returns.
• Updated the one reference to the old create tool name in platform_get_remote_instance_status so it stays consistent.

Snapshot read/create tools are now: platform_list_instance_snapshots, platform_create_instance_snapshot, platform_get_snapshot, platform_get_snapshot_full, platform_get_hosted_instance_device_target_snapshot.

[andypalmi]

Testing results of new/edited tools

Local platform context these calls ran against:

• A team with 10 hosted instances (one holds 35 snapshots including several with hidden/secret environment variables) and no devices.
• A second team with 10 remote instances (devices), one online (in developer mode), and 9 hosted instances.

This PR reworks snapshots.js: 3 new tools and 2 edited tools.

• New (3 read tools): platform_get_snapshot, platform_get_snapshot_full, platform_get_hosted_instance_device_target_snapshot.
• Edited (2 consolidated tools): platform_list_instance_snapshots merges the former hosted/remote list tools, and platform_create_instance_snapshot merges the former hosted/remote create tools; both now take an instanceType of "hosted" or "remote".

All five are exercised below. Hashids and instance UUIDs are redacted; counts, states, and env keys are verbatim.

platform_list_instance_snapshots

Lists the snapshots of a hosted instance or a remote instance (device), selected by instanceType. Honors limit (page size) and cursor (pages from a given snapshot id).

Case	Input params	Verdict	Returned payload (overview, redacted)
hosted, limit	{instanceType:"hosted", instanceId, limit:3}	PASS	{count:35, snapshots:[{id, name, ownerType:"instance", user}, ... x3]}
hosted, cursor	{instanceType:"hosted", instanceId, limit:3, cursor:<1st id>}	PASS	returns the 3 snapshots that follow the given id (paging works from a supplied cursor)
remote	{instanceType:"remote", instanceId, limit:5}	PASS	{count:1, snapshots:[{id, name, ownerType:"device"}]} (remote branch hits the devices route; lists the device-owned snapshot)
bad instance id	{instanceType:"hosted", instanceId:"not-a-uuid", limit:3}	PASS	{content:{code:not_found}, code:404, isError:true}

platform_create_instance_snapshot

Creates a snapshot from a hosted or remote instance. Consolidated from the two former create tools; the instanceType selects the route.

Case	Input params	Verdict	Returned payload (overview, redacted)
hosted create	{instanceType:"hosted", instanceId, name, description}	PASS	{id, name, ownerType:"instance"} - snapshot created; confirmed readable via platform_get_snapshot, then removed
remote create	{instanceType:"remote", instanceId, name, description}	PASS	{id, name, ownerType:"device", device} - captured from an online device; confirmed readable via platform_get_snapshot and platform_list_instance_snapshots, then removed

platform_get_snapshot

Gets a single snapshot's metadata by id; resolves the owner (hosted or remote) automatically.

Case	Input params	Verdict	Returned payload (overview, redacted)
hosted-owned	{snapshotId}	PASS	{id, name, description, ownerType:"instance", projectId, project, modules, createdAt, updatedAt} - metadata only, no flows
remote-owned	{snapshotId}	PASS	{id, name, ownerType:"device", deviceId, device} - owner resolved to the device automatically
not found	{snapshotId:"zzzzzzzzzz"}	PASS	{content:{code:not_found}, code:404, isError:true}

platform_get_snapshot_full

Gets the full payload (flows, settings, environment variables). Hidden (secret) env values are blanked; keys and the hidden flag are kept. Credentials are not included.

Case	Input params	Verdict	Returned payload (overview, redacted)
hosted-owned, with hidden env	{snapshotId}	PASS	{flows, settings:{env, modules, settings}, ...}; visible env vars pass through (FF_INSTANCE_ID, OPENAI_ORG, OPENAI_API_KEY_NAME), hidden ones returned as {value:"", hidden:true} (OPENAI_API_KEY, STAGING_ACCESS_KEY, PRODUCTION_ACCESS_KEY, DEV_ACCESS_KEY)
remote-owned	{snapshotId}	PASS	{flows, settings:{env, modules, settings}, ownerType:"device", ...} - full payload returned for a device snapshot
not found	{snapshotId:"zzzzzzzzzz"}	PASS	{content:{code:not_found}, code:404, isError:true}

platform_get_hosted_instance_device_target_snapshot

Gets the target snapshot that a hosted instance's assigned devices are set to deploy. Returns null when none is set.

Case	Input params	Verdict	Returned payload (overview, redacted)
target set	{hostedInstanceId}	PASS	{targetSnapshot:} - the id resolves via platform_get_snapshot to the snapshot the instance's devices will deploy
no target set	{hostedInstanceId}	PASS	{targetSnapshot:null} - no target snapshot assigned

Conclusion

All five new/edited tools in snapshots.js are verified against their descriptions, on both the hosted and remote branches. The consolidated platform_list_instance_snapshots lists hosted and remote instances via instanceType, with working limit and cursor paging; platform_create_instance_snapshot creates on both a hosted instance and an online device, and each result is immediately readable via platform_get_snapshot and platform_list_instance_snapshots. platform_get_snapshot returns metadata only and resolves the owner (instance or device) automatically, platform_get_snapshot_full returns flows and settings for both owner types with hidden environment values blanked to {value:"", hidden:true} while visible ones pass through, and platform_get_hosted_instance_device_target_snapshot returns the target snapshot or null. Not-found ids return a 404 on every read path. The four backing read scopes (project:snapshot:read, device:snapshot:read, snapshot:meta, snapshot:full) are added to the allow-list in this PR.