Skip to content

feat(mcp): hosted instance read tools - #7727

Open
andypalmi wants to merge 3 commits into
mainfrom
feat/mcp-tools-instance-config-read
Open

feat(mcp): hosted instance read tools#7727
andypalmi wants to merge 3 commits into
mainfrom
feat/mcp-tools-instance-config-read

Conversation

@andypalmi

@andypalmi andypalmi commented Jul 4, 2026

Copy link
Copy Markdown
Contributor

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, with a format argument: json reads entries directly, csv exports the CSV via GET /projects/:id/audit-log/export.
  • 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 gains a format argument (json reads entries, csv uses the export route).
  • 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 Bot commented Jul 4, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 76.22%. Comparing base (a8f760b) to head (dacd8f4).

Additional details and impacted files
@@            Coverage Diff             @@
##             main    #7727      +/-   ##
==========================================
+ Coverage   76.17%   76.22%   +0.05%     
==========================================
  Files         440      440              
  Lines       23604    23655      +51     
  Branches     6285     6293       +8     
==========================================
+ Hits        17981    18032      +51     
  Misses       5623     5623              
Flag Coverage Δ
backend 76.22% <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
andypalmi force-pushed the feat/mcp-tools-instance-config-read branch from 04324b4 to 6af352f Compare July 4, 2026 13:33
@andypalmi andypalmi linked an issue Jul 6, 2026 that may be closed by this pull request
@andypalmi
andypalmi force-pushed the feat/mcp-tools-shared-schemas branch from 8bfb22e to 9742987 Compare July 6, 2026 13:13
@andypalmi
andypalmi force-pushed the feat/mcp-tools-instance-config-read branch from 6af352f to fdafd47 Compare July 6, 2026 16:38
@andypalmi
andypalmi force-pushed the feat/mcp-tools-instance-config-read branch from fdafd47 to df8ad04 Compare July 6, 2026 22:01
@andypalmi andypalmi changed the title feat(mcp): instance configuration read tools feat(mcp): hosted instance read tools Jul 7, 2026
@andypalmi
andypalmi marked this pull request as draft July 30, 2026 08:22
@andypalmi
andypalmi force-pushed the feat/mcp-tools-shared-schemas branch from 103f9ae to 5773bdb Compare August 3, 2026 13:19
Add forge/ee/lib/mcp/schemas.js, a shared module of composable zod
fragments the platform read tools import instead of redefining entity-id
and pagination/search/sort/audit-log query fields in each tool file.

- entity-id params: teamId, applicationId, hostedInstanceId (UUID),
  remoteInstanceId, snapshotId
- query fragments composed per route by spreading only the params the
  backing finder honors: cursorParam/limitParam (basePagination),
  pageParam, searchQuery, sortParams, auditLogFilters
- appendQuery serialises a tool's supported params onto the request URL

The module lives one level above tools/ so the tool loader does not
register it as a tool module.

Closes #7669
@andypalmi
andypalmi force-pushed the feat/mcp-tools-shared-schemas branch from eae081f to e04360f Compare August 3, 2026 14:13
@andypalmi
andypalmi force-pushed the feat/mcp-tools-instance-config-read branch from 283ad01 to 4206424 Compare August 3, 2026 15:26
@andypalmi
andypalmi marked this pull request as ready for review August 4, 2026 10:33
@andypalmi
andypalmi requested a review from cstns August 4, 2026 10:33
@andypalmi
andypalmi force-pushed the feat/mcp-tools-instance-config-read branch from 4206424 to 526dcd3 Compare August 4, 2026 10:55
@andypalmi
andypalmi force-pushed the feat/mcp-tools-instance-config-read branch from 526dcd3 to da1f501 Compare August 4, 2026 11:04
@andypalmi andypalmi self-assigned this Aug 4, 2026
Base automatically changed from feat/mcp-tools-shared-schemas to main August 5, 2026 08:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5.11-a Hosted instance read tools (phase 1)

2 participants