Skip to content

feat(mcp): team read tools - #7722

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

feat(mcp): team read tools#7722
andypalmi wants to merge 3 commits into
mainfrom
feat/mcp-tools-teams-read

Conversation

@andypalmi

@andypalmi andypalmi commented Jul 4, 2026

Copy link
Copy Markdown
Contributor

Summary

Phase 1 read-only MCP tools for the team resource, added to forge/ee/lib/mcp/tools/teams.js. This covers team lookups, membership, the team audit log, and team-scoped data and packages:

  • platform_get_team_by_slug - GET /teams/slug/:teamSlug
  • platform_get_team_instance_counts - GET /teams/:teamId/instance-counts
  • platform_check_team_slug_availability - POST /teams/check-slug
  • platform_get_team_membership - GET /teams/:teamId/user
  • platform_list_team_members - GET /teams/:teamId/members
  • platform_list_team_invitations - GET /teams/:teamId/invitations
  • platform_get_team_audit_log - GET /teams/:teamId/audit-log
  • platform_export_team_audit_log - GET /teams/:teamId/audit-log/export
  • platform_list_team_npm_packages - GET /teams/:teamId/npm/packages
  • platform_list_team_git_tokens - GET /teams/:teamId/git/tokens
  • platform_list_library_entries - GET /storage/library/:libraryId/*

Each tool describes the team resource, so the membership tools and the team-data tools all fold into teams.js, following the one-file-per-resource convention (rather than separate members.js/teamData.js files). All tools are annotated readOnlyHint: true, destructiveHint: false. platform_check_team_slug_availability uses POST but performs no mutation, so it is annotated read as well.

The team-data surfaces (npm, gitIntegration, shared-library) are plan-gated; the tools turn a feature-disabled 404 into a clear "feature not enabled" message.

Scopes allow-listed on IMPLICIT_TOKEN_SCOPES['user:expert-mcp'] in forge/routes/auth/permissions.js:

  • team:user:list
  • team:user:invite
  • team:audit-log
  • team:packages:read
  • team:git:tokens:list
  • library:entry:list
  • team:create

(team:read was already present.)

Tools that describe a different resource are filed elsewhere: instance lists in instances.js, application statuses in applications.js, provisioning tokens in devices.js, and team types in platform.js. Their backing scopes move with them.

FlowFuse Tables tools (platform_list_team_databases, platform_get_team_database, platform_list_database_tables, platform_get_database_table, platform_query_database_table_data) are split out to #7990, tracked by #7989.

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

Closes #7693

Test plan

  • eslint on changed files passes
  • Tool modules load and export the expected tool definitions (verified with a local require smoke check)
  • CI

@codecov

codecov Bot commented Jul 4, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 97.61905% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 76.21%. Comparing base (a8f760b) to head (903947d).

Files with missing lines Patch % Lines
forge/ee/routes/sharedLibrary/index.js 0.00% 1 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main    #7722      +/-   ##
==========================================
+ Coverage   76.17%   76.21%   +0.04%     
==========================================
  Files         440      440              
  Lines       23604    23645      +41     
  Branches     6285     6286       +1     
==========================================
+ Hits        17981    18022      +41     
  Misses       5623     5623              
Flag Coverage Δ
backend 76.21% <97.61%> (+0.04%) ⬆️

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-teams-read branch from 8721ef6 to a6ff64d 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-teams-read branch from a6ff64d to 9f4845e Compare July 6, 2026 16:39
@andypalmi
andypalmi force-pushed the feat/mcp-tools-teams-read branch from 9f4845e to aff2226 Compare July 6, 2026 22:01
@andypalmi andypalmi changed the title feat(mcp): teams and membership read tools feat(mcp): team read tools Jul 7, 2026
@andypalmi
andypalmi marked this pull request as draft July 30, 2026 08:21
@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
Expose read-only team, membership, audit-log, and shared-data tools on the platform automation MCP surface.
@andypalmi
andypalmi force-pushed the feat/mcp-tools-teams-read branch from b675d3f to 516c3cb Compare August 3, 2026 15:30
@andypalmi
andypalmi requested a review from cstns August 3, 2026 15:48
@andypalmi
andypalmi marked this pull request as ready for review August 3, 2026 15:48
@andypalmi andypalmi self-assigned this Aug 4, 2026
Base automatically changed from feat/mcp-tools-shared-schemas to main August 5, 2026 08:48
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.4-a Team read tools (phase 1)

2 participants