feat(mcp): hosted instance read tools

[andypalmi]

Summary

Phase 1 read-only MCP tools for the hosted instance resource, added to forge/ee/lib/mcp/tools/instances.js. This covers per-instance configuration surfaces, instance observability, and the team-scoped instance lists:

• platform_get_instance_config - one configuration reader taking a sections array (any subset of ha, protection, autoUpdateStack; defaults to all). Backed by GET /projects/:id/ha, GET /projects/:id/protectInstance, and GET /projects/:id/autoUpdateStack, returning each requested section independently.
• platform_get_instance_custom_hostname - GET /projects/:id/customHostname, with an includeStatus boolean that additionally fetches the live verification status from GET /projects/:id/customHostname/status.
• platform_list_instance_files - GET /projects/:id/files/_/:path
• platform_list_instance_http_tokens - takes instanceType (hosted or remote); lists the HTTP bearer tokens for a hosted or remote instance.
• platform_get_hosted_instance_audit_log - GET /projects/:id/audit-log, returning audit entries as JSON.
• platform_get_instance_history - takes instanceType (hosted or remote); returns the timeline for a hosted or remote instance.
• platform_get_hosted_instance_resources - GET /projects/:id/resources
• platform_list_team_dashboard_instances - GET /teams/:teamId/dashboard-instances

Each tool describes the hosted instance resource, so all are filed with the existing hosted instance tools, following the one-file-per-resource convention. platform_list_team_dashboard_instances hangs off a team URL but lists hosted instances.

All tools are annotated readOnlyHint: true, destructiveHint: false. Several backing routes are plan-gated per team (High Availability, custom hostnames, protected instance, static file storage, HTTP bearer tokens, instance history, instance resources); since a disabled feature and a genuine not-found both return a 404, the affected tools turn that 404 into a descriptive "feature not enabled for this team" message. The auto-update-stack route has no feature gate, so that section passes through unchanged. The /resources/stream WebSocket route is intentionally not exposed; only the point-in-time /resources snapshot is implemented.

Scopes allow-listed for user:expert-mcp in forge/routes/auth/permissions.js:

• project:edit (custom-hostname and HTTP-token reads)
• project:files:list (instance file listing)
• project:audit-log (instance audit log)
• project:history (hosted instance history)
• device:history (remote instance history, via the generalized history tool)

(project:read and team:projects:list were already present.)

Write, delete and admin-only tools for this resource are out of scope for this PR.

Consolidation notes

• Config sections: platform_get_instance_ha, platform_get_instance_protection, and platform_get_instance_auto_update_stack are merged into platform_get_instance_config, which takes a sections array (subset of ha / protection / autoUpdateStack, defaults to all) and returns each requested section independently.
• Hostname plus status: platform_get_instance_custom_hostname and platform_get_instance_custom_hostname_status are merged into platform_get_instance_custom_hostname, with an includeStatus boolean that also fetches the live verification status.
• Audit format: the separate platform_export_hosted_instance_audit_log is removed; platform_get_hosted_instance_audit_log returns audit entries as JSON.
• Instance-type twins: platform_list_instance_http_tokens and platform_get_instance_history (renamed from platform_get_hosted_instance_history) take an instanceType (hosted or remote) and now also serve remote instances, replacing the remote-only variants dropped from feat(mcp): remote instance (device) read tools #7726.
• Team listing: platform_list_team_projects is dropped; its capability is folded into platform_list_hosted_instances, which gained sort, dir, and orderByMostRecentFlows for the team-wide listing.
• Shared schema: platform_list_hosted_instances reuses the shared fragments (teamId, applicationId, searchQuery, sortParams.dir) from forge/ee/lib/mcp/schemas.js instead of re-declaring them inline; its bespoke limit (max 10) and sort enum stay inline.

Closes #7705

Test plan

• eslint clean on the changed files
• mocha unit tests

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 76.24%. Comparing base (d33b229) to head (14e791e).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #7727      +/-   ##
==========================================
+ Coverage   76.19%   76.24%   +0.05%     
==========================================
  Files         443      443              
  Lines       23726    23776      +50     
  Branches     6314     6321       +7     
==========================================
+ Hits        18079    18129      +50     
  Misses       5647     5647              

Flag	Coverage Δ
backend	76.24% <100.00%> (+0.05%)	⬆️

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]

Testing results of new/edited tools

@cstns for visibility

Every tool below was invoked against a running local platform (team DEV, 10 hosted instances, primary instance INSTANCE-NAME-3). Payloads show the shape of what came back, with ids/urls/cursors/timestamps redacted as INSTANCE_ID URL CURSOR TS HASH; structural values (counts, states, statusCodes, enum echoes) are verbatim.

platform_list_hosted_instances

Returns a list of hosted instances.

• Team-wide (no applicationId): paginated, each item = {id, name, url, application:{id,name}, projectType:{id,name}, stack:{id,name,label}, template:{id,name}, state}, plus {count, meta:{page,pageSize,total,pageCount}}.
• Application-scoped: unpaginated, each item = {id, name, url, state}, plus {count}.

Case	Input params	Verdict	Returned payload (overview, redacted)
team default	{teamId}	PASS	{count:10, meta:{page:1,pageSize:10,total:10,pageCount:1}, instances:[10 items as above]}
paging limit=2 page=1	{teamId,limit:2,page:1}	PASS	first 2 [INSTANCE-NAME-1,INSTANCE-NAME-2], meta:{page:1,pageSize:2,total:10,pageCount:5}
paging page=2	{teamId,limit:2,page:2}	PASS	next 2 [INSTANCE-NAME-3,INSTANCE-NAME-4], meta.page:2
name search	{teamId,query:""}	PASS	{count:2, instances:[INSTANCE-NAME-2,INSTANCE-NAME-4]} (substring filter applied)
state=running	{teamId,state:[running]}	PASS	{count:9} (server-side filter on cached state; per-item state field null unless includeLiveStatus)
state=notRunning	{teamId,state:[notRunning]}	PASS	{count:1}
includeLiveStatus	{teamId,includeLiveStatus:true,limit:3}	PASS	per-item state populated [running,running,running]
sort name asc	{teamId,sort:name,dir:asc,limit:5}	PASS	[INSTANCE-NAME-9,INSTANCE-NAME-10,INSTANCE-NAME-1,INSTANCE-NAME-2,INSTANCE-NAME-4] (alphabetical)
sort name desc	{teamId,sort:name,dir:desc,limit:5}	PASS	reverse of asc [INSTANCE-NAME-8,INSTANCE-NAME-7,INSTANCE-NAME-6,INSTANCE-NAME-5,INSTANCE-NAME-3]
sort=flowLastUpdatedAt WITHOUT includeLiveStatus	{teamId,sort:flowLastUpdatedAt,limit:5}	PASS	default order (no effect, per description)
sort=flowLastUpdatedAt WITH includeLiveStatus	{teamId,sort:flowLastUpdatedAt,includeLiveStatus:true,limit:5}	PASS	reordered vs default [INSTANCE-NAME-3,INSTANCE-NAME-2,INSTANCE-NAME-1,INSTANCE-NAME-4,INSTANCE-NAME-5]
orderByMostRecentFlows WITHOUT includeLiveStatus	{teamId,orderByMostRecentFlows:true,limit:5}	PASS	default order (no effect, per description)
orderByMostRecentFlows WITH includeLiveStatus	{teamId,orderByMostRecentFlows:true,includeLiveStatus:true,limit:5}	PASS	reordered vs default [INSTANCE-NAME-4,INSTANCE-NAME-1,INSTANCE-NAME-2,INSTANCE-NAME-3,INSTANCE-NAME-6]
app-scoped default	{teamId,applicationId}	PASS	{count:11, instances:[each {id,name,url,state}]} (unpaginated)
app-scoped state filter (implies live)	{teamId,applicationId,state:[running]}	PASS	{count:9, all state:running}

platform_get_hosted_instance

Returns the full settings/metadata of one instance: id, name, url, its application and team, current state, and specification (instance type, stack, template).

Case	Input params	Verdict	Returned payload (overview, redacted)
valid id	{hostedInstanceId}	PASS	{id:INSTANCE_ID, name:INSTANCE-NAME-3, state:running, projectType:Large, stack:node-red-4-1-7, ...full settings}

platform_get_hosted_instance_status

Returns the live runtime status only.

Case	Input params	Verdict	Returned payload (overview, redacted)
valid id	{hostedInstanceId}	PASS	{name, id, meta:{state:running, lastStartTime:TS, versions:{node,launcher,node-red}, isDeploying:false}}
nonexistent id	{hostedInstanceId:"does-not-exist"}	PASS	{content:{code:not_found}, code:404, isError:true}

platform_get_hosted_instance_logs

Returns Node-RED console log entries, newest first, with cursor pagination.

Case	Input params	Verdict	Returned payload (overview, redacted)
limit=3	{hostedInstanceId,limit:3}	PASS	{log:[3 entries, each {ts:TS,level,msg,src:HASH}], meta:{next_cursor:CURSOR,previous_cursor,first_entry,last_entry}}

platform_check_hosted_instance_name_availability

Returns whether a proposed instance name is free.

Case	Input params	Verdict	Returned payload (overview, redacted)
free name	{name:"a-brand-new-unique-name-xyz"}	PASS	{available:true}
taken name	{name:"INSTANCE-NAME-2"} (an existing instance name)	PASS	{content:{code:invalid_project_name,error:"name in use"}, code:409, isError:true}

platform_get_instance_config

Returns the requested config sections, each independently as {statusCode, data}. data is an object for ha/protection and an array of weekly restart windows for autoUpdateStack.

Case	Input params	Verdict	Returned payload (overview, redacted)
default (all)	{hostedInstanceId}	PASS	{ha:{statusCode:404,data:{code:not_found}}, protection:{statusCode:200,data:{}}, autoUpdateStack:{statusCode:200,data:[]}}
subset autoUpdateStack	{hostedInstanceId,sections:[autoUpdateStack]}	PASS	{autoUpdateStack:{statusCode:200,data:[]}} (data is an array)
subset ha+protection	{hostedInstanceId,sections:[ha,protection]}	PASS	{ha:{statusCode:404,...}, protection:{statusCode:200,data:{}}}
nonexistent instance	{hostedInstanceId:"does-not-exist",sections:[autoUpdateStack]}	PASS	{autoUpdateStack:{statusCode:404,data:{code:not_found}}} (404 = instance missing)

Confirms both fixes shipped in this PR: per-section {statusCode, data} and the autoUpdateStack array shape (no array-spread corruption).

platform_get_instance_custom_hostname

Returns the configured custom hostname; with includeStatus, also the live CNAME verification status.

Case	Input params	Verdict	Returned payload (overview, redacted)
no status	{hostedInstanceId}	PASS	{content:{code:not_found}, code:404, isError:true} (plan-gated / none set)
includeStatus	{hostedInstanceId,includeStatus:true}	PASS	{content:{hostname:{...},status:{...}}, code:404, isError:true} (both sub-objects present)

platform_list_instance_files

Returns the files/directories at a path in the instance file store.

Tested on INSTANCE-NAME-1 (which has a populated file store).

Case	Input params	Verdict	Returned payload (overview, redacted)
root	{hostedInstanceId,path:""}	PASS	{count:6, files:[mix of files and directories, each {name, type: "file" or "directory"}], meta:{}, folder:null}
nested subdir	{hostedInstanceId,path:"ff-logs"}	PASS	{count:5, files:[5 log files, each {name,type:"file"}]}
bogus nested path	{hostedInstanceId,path:"does/not/exist"}	PASS	{content:{code:invalid_request}, code:400, isError:true}

platform_list_instance_http_tokens

Returns the HTTP bearer tokens for a hosted or remote instance (token secrets not included).

Case	Input params	Verdict	Returned payload (overview, redacted)
hosted	{instanceId,instanceType:hosted}	PASS	{tokens:[], count:0}
remote (bogus)	{instanceId:"nonexistent",instanceType:remote}	PASS	{content:{code:not_found}, code:404, isError:true}

platform_get_hosted_instance_audit_log

Returns audit entries (paginated), each = {id, createdAt, username, event, scope, trigger, source, body}, plus {meta:{next_cursor}, count, associations:{applications,instances,devices}}. The tool always returns JSON entries (the former format="csv" option was removed in this pass).

Case	Input params	Verdict	Returned payload (overview, redacted)
json default	{hostedInstanceId,limit:3}	PASS	{log:[3 entries], meta:{next_cursor:CURSOR}, count, associations:{...}}
event single	{hostedInstanceId,limit:10,event:"auth.login"}	PASS	10 entries, all event=auth.login (filter applied)
event array	{hostedInstanceId,limit:10,event:[flows.set,project.snapshot.created]}	PASS	entries only of those two events
query text	{hostedInstanceId,limit:5,query:"login"}	PASS	entries matching, all auth.login
scope+includeChildren	{hostedInstanceId,limit:3,scope:project,includeChildren:true}	PASS	3 entries
cursor paging	page1 next_cursor then {...,cursor:CURSOR}	PASS	page2 distinct entries
former csv arg	{hostedInstanceId,format:"csv"}	PASS	format no longer in schema; arg ignored, returns JSON entries

platform_get_instance_history

Returns a chronological timeline for a hosted or remote instance, cursor-paginated.

Case	Input params	Verdict	Returned payload (overview, redacted)
hosted	{instanceId,instanceType:hosted}	PASS	{timeline:[39 entries], meta:{}}
hosted limit=2	{instanceId,instanceType:hosted,limit:2}	PASS	{timeline:[2], meta:{next_cursor:CURSOR}}
hosted cursor walk	{...,limit:2,cursor:CURSOR}	PASS	next 2 entries
remote (bogus)	{instanceId:"nonexistent",instanceType:remote}	PASS	{content:{code:not_found}, code:404, isError:true}

platform_get_hosted_instance_resources

Returns stored CPU/memory usage as a time-series (a list of samples over time), not a live feed.

Case	Input params	Verdict	Returned payload (overview, redacted)
valid id	{hostedInstanceId}	PASS	{count:17, meta:{}, resources:[17 samples, each {src:HASH, ps, ts:TS}]}

platform_list_team_dashboard_instances

Returns the team's hosted instances that have the Node-RED dashboard installed.

Case	Input params	Verdict	Returned payload (overview, redacted)
team id	{teamId}	PASS	{count:1, projects:[{id,name:INSTANCE-NAME-3,url,settings:{dashboard2UI:"/dashboard"}}]}

Conclusion

All 13 tools verified against their descriptions, including the fixes shipped in this PR (get_instance_config {statusCode, data} + autoUpdateStack array shape; flowLastUpdatedAt / orderByMostRecentFlows requiring includeLiveStatus). No open defects.