5.11-a Hosted instance read tools (phase 1)

[andypalmi]

Parent: #7680 (5.11 Instance configuration)
Tool file: forge/ee/lib/mcp/tools/instances.js (extend)

Read tools for the hosted instance resource: per-instance configuration surfaces plus instance observability and the team-scoped instance lists. Filed in instances.js alongside the existing hosted instance tools, following the one-file-per-resource convention (a tool lives in the file for the noun it is about, regardless of the URL's first path segment). The HTTP-token and history reads are generalized here to serve both hosted and remote instances via an instanceType argument, so the remote-only variants that previously sat under #7726 are not needed.

readOnlyHint: true.

Tool	Endpoint	Scope	Annotation
platform_get_instance_config	GET /projects/:id/ha, GET /projects/:id/protectInstance, GET /projects/:id/autoUpdateStack (per sections)	project:read	read
platform_get_instance_custom_hostname	GET /projects/:id/customHostname (plus /customHostname/status when includeStatus)	project:edit	read
platform_list_instance_files	GET /projects/:id/files/_/:path	project:files:list	read
platform_list_instance_http_tokens	GET /projects/:id/httpTokens (instanceType hosted or remote)	project:edit	read
platform_get_hosted_instance_audit_log	GET /projects/:id/audit-log (format: json), GET /projects/:id/audit-log/export (format: csv)	project:audit-log	read
platform_get_instance_history	GET /projects/:id/history (instanceType hosted or remote)	project:history, device:history	read
platform_get_hosted_instance_resources	GET /projects/:id/resources	project:read	read
platform_list_team_dashboard_instances	GET /teams/:teamId/dashboard-instances	team:read	read

Design notes:

• Plan-gated per team (not per user role): HA (feature key ha), custom hostnames (customHostnames), protected instance (protectedInstance), files (staticAssets), http tokens (route checks teamHttpSecurity; httpBearerTokens is the registered feature name), instance history (projectHistory, defaults to enabled), instance resources (instanceResources, default disabled). When the plan does not include the feature the route returns a 404 independent of the PAT's permissions; the tool surfaces a clear "feature not enabled for this team" message rather than a bare not-found.
• The auto-update-stack route has no feature-flag preHandler, so no plan-gate 404 applies to that section of platform_get_instance_config (only the standard project/membership checks).
• Custom-hostname GET (and its status route) and the HTTP-token list use project:edit (not project:read). These are still read tools for MCP purposes: allow-list/annotate accordingly and set readOnlyHint: true.
• GET /projects/:id/resources/stream is a WebSocket, not suited to a request/response MCP tool; only the point-in-time /resources snapshot is exposed.
• platform_list_team_dashboard_instances hangs off a team URL but lists hosted instances, so it is filed with the instance tools.

Consolidation:

• Config sections: the separate ha, protection, and autoUpdateStack getters 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: the custom-hostname read and its status read are merged into platform_get_instance_custom_hostname via an includeStatus boolean.
• Audit format: the audit read and export are merged; platform_get_hosted_instance_audit_log gains a format argument (json reads entries, csv uses the export route), and the separate export tool is dropped.
• 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 serve remote instances too, so the remote-only variants under feat(mcp): remote instance (device) read tools #7726 are removed.
• Team listing: platform_list_team_projects is dropped; its name filtering, sorting, and pagination are folded into platform_list_hosted_instances, which gained sort, dir, and orderByMostRecentFlows.
• Shared schema: platform_list_hosted_instances reuses the shared fragments (teamId, applicationId, searchQuery, sortParams.dir) from forge/ee/lib/mcp/schemas.js (basePagination, searchQuery, sortParams); its bespoke limit (max 10) and sort enum stay inline.

Scopes to allow-list (IMPLICIT_TOKEN_SCOPES['user:expert-mcp']) and access-tag (#7445):
project:edit (custom-hostname/http-token reads), project:files:list (read), project:audit-log (read), project:history (hosted history read), device:history (remote history read). project:read and team:projects:list are already present; team:read is already present from the shipped team tools.

Tests:

• Read tools allowed for read-only PAT.
• Feature-disabled instance returns the descriptive gate error per config/observability surface.