Skip to content

feat(mcp): hosted instance read tools#7727

Open
andypalmi wants to merge 2 commits into
feat/mcp-tools-shared-schemasfrom
feat/mcp-tools-instance-config-read
Open

feat(mcp): hosted instance read tools#7727
andypalmi wants to merge 2 commits into
feat/mcp-tools-shared-schemasfrom
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_ha - GET /projects/:id/ha
  • platform_get_instance_custom_hostname - GET /projects/:id/customHostname
  • platform_get_instance_custom_hostname_status - GET /projects/:id/customHostname/status
  • platform_get_instance_protection - GET /projects/:id/protectInstance
  • platform_get_instance_auto_update_stack - GET /projects/:id/autoUpdateStack
  • platform_list_instance_files - GET /projects/:id/files/_/:path
  • platform_list_instance_http_tokens - GET /projects/:id/httpTokens
  • platform_get_hosted_instance_audit_log - GET /projects/:id/audit-log
  • platform_export_hosted_instance_audit_log - GET /projects/:id/audit-log/export
  • platform_get_hosted_instance_history - GET /projects/:id/history
  • platform_get_hosted_instance_resources - GET /projects/:id/resources
  • platform_list_team_projects - GET /teams/:teamId/projects
  • 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_projects and platform_list_team_dashboard_instances hang off team URLs but list 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 its tool passes the response 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 (instance history)

(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.

Closes #7705

Test plan

  • eslint clean on the changed files
  • CI

@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 75.77%. Comparing base (103f9ae) to head (283ad01).

Additional details and impacted files
@@                        Coverage Diff                        @@
##           feat/mcp-tools-shared-schemas    #7727      +/-   ##
=================================================================
+ Coverage                          75.41%   75.77%   +0.36%     
=================================================================
  Files                                426      426              
  Lines                              22551    22598      +47     
  Branches                            5949     5949              
=================================================================
+ Hits                               17006    17124     +118     
+ Misses                              5545     5474      -71     
Flag Coverage Δ
backend 75.77% <100.00%> (+0.36%) ⬆️

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
Add read-only MCP tools for HA, custom hostnames, protected instance, auto-update stacks, static files and HTTP security config, with unit and equivalence tests. Allow-list their scopes for the expert-mcp platform token.
@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
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)

1 participant