feat(mcp): add billing read tools

Add read-only MCP tools for team billing and the Stripe customer portal, wrapping the backing routes via app.inject(), with unit and equivalence tests. Allow-list their scopes for the expert-mcp platform token.

Author: andypalmi

forge/ee/lib/mcp/tools/billing.js

@@ -0,0 +1,41 @@
+const { teamId } = require('../schemas')
+
+module.exports = [
+    {
+        name: 'platform_get_team_billing',
+        title: 'Get Team Billing',
+        description: `FlowFuse platform automation tool:
+            Reads a team billing and subscription details, including the current plan items, price, and next billing date.
+            Use this when the user asks about their team plan, subscription cost, or when the next invoice is due.
+            Returns a 404-style error if the team has no active subscription, and a billing_unmanaged error if the team subscription is not managed through this platform (for example, an enterprise contract).`,
+        annotations: { readOnlyHint: true, destructiveHint: false },
+        inputSchema: {
+            teamId
+        },
+        handler: async (args, { inject }) => {
+            const response = await inject({ method: 'GET', url: `/ee/billing/teams/${args.teamId}` })
+            return response
+        }
+    },
+    {
+        name: 'platform_get_team_customer_portal',
+        title: 'Get Team Customer Portal',
+        description: `FlowFuse platform automation tool:
+            Gets a URL to the team Stripe customer portal, where the user can manage their billing details, payment methods, and subscription.
+            Use this when the user wants to update their payment method, view invoices, or change their subscription plan.`,
+        annotations: { readOnlyHint: true, destructiveHint: false },
+        inputSchema: {
+            teamId
+        },
+        handler: async (args, { inject }) => {
+            const response = await inject({ method: 'GET', url: `/ee/billing/teams/${args.teamId}/customer-portal` })
+            if (response.statusCode >= 400) {
+                return response
+            }
+            return {
+                statusCode: 200,
+                json: () => ({ url: response.headers.location })
+            }
+        }
+    }
+]

forge/routes/auth/permissions.js

@@ -48,6 +48,8 @@ const IMPLICIT_TOKEN_SCOPES = {
         // teams
         'user:team:list', // list teams
         'team:read', // get team details
+        // billing
+        'team:edit', // get team billing details, get team customer-portal link
         // platform
         'stack:list',
         'flow-blueprint:list',

test/unit/forge/ee/lib/mcp/tools/billing_spec.js

@@ -0,0 +1,134 @@
+const should = require('should') // eslint-disable-line no-unused-vars
+
+const { expectToolMatchesRoute, createExpertMcpToken, toolFinder, recordingInject } = require('../../../../../../lib/mcpToolEquivalence')
+
+const FF_UTIL = require('flowforge-test-utils')
+
+const tools = FF_UTIL.require('forge/ee/lib/mcp/tools/billing')
+const findTool = toolFinder(tools)
+
+describe('MCP Billing Tools', function () {
+    describe('platform_get_team_billing', function () {
+        const tool = findTool('platform_get_team_billing')
+
+        it('has read-only, non-destructive annotations', function () {
+            tool.annotations.readOnlyHint.should.equal(true)
+            tool.annotations.destructiveHint.should.equal(false)
+        })
+
+        it('exposes the expected input schema keys', function () {
+            Object.keys(tool.inputSchema).should.eql(['teamId'])
+        })
+
+        it('requests the team billing endpoint', async function () {
+            const { calls, inject } = recordingInject()
+            await tool.handler({ teamId: 'team123' }, { inject })
+            calls.should.have.length(1)
+            calls[0].method.should.equal('GET')
+            calls[0].url.should.equal('/ee/billing/teams/team123')
+        })
+    })
+
+    describe('platform_get_team_customer_portal', function () {
+        const tool = findTool('platform_get_team_customer_portal')
+
+        it('has read-only, non-destructive annotations', function () {
+            tool.annotations.readOnlyHint.should.equal(true)
+            tool.annotations.destructiveHint.should.equal(false)
+        })
+
+        it('exposes the expected input schema keys', function () {
+            Object.keys(tool.inputSchema).should.eql(['teamId'])
+        })
+
+        it('requests the team customer-portal endpoint', async function () {
+            const { calls, inject } = recordingInject()
+            await tool.handler({ teamId: 'team123' }, { inject })
+            calls.should.have.length(1)
+            calls[0].method.should.equal('GET')
+            calls[0].url.should.equal('/ee/billing/teams/team123/customer-portal')
+        })
+
+        it('surfaces the portal URL from the response location header', async function () {
+            const inject = async () => ({ statusCode: 200, headers: { location: 'https://billing.stripe.com/session/abc' } })
+            const response = await tool.handler({ teamId: 'team123' }, { inject })
+            response.statusCode.should.equal(200)
+            response.json().should.eql({ url: 'https://billing.stripe.com/session/abc' })
+        })
+
+        it('returns the error response unchanged when the route fails', async function () {
+            const errorResponse = { statusCode: 404, json: () => ({ error: 'not found' }) }
+            const inject = async () => errorResponse
+            const response = await tool.handler({ teamId: 'team123' }, { inject })
+            response.should.equal(errorResponse)
+        })
+    })
+
+    describe('Integration smoke', function () {
+        const setup = require('../../../setup')
+
+        let app
+        let stripe
+        let token
+
+        before(async function () {
+            stripe = setup.setupStripe({
+                billingPortal: {
+                    sessions: {
+                        create: async () => ({ url: 'https://billing.stripe.com/p/session/test_123' })
+                    }
+                }
+            })
+            app = await setup({
+                ai: { enabled: true },
+                expert: { enabled: true }
+            })
+            token = await createExpertMcpToken(app)
+        })
+
+        after(async function () {
+            await app.close()
+            setup.resetStripe()
+        })
+
+        it('platform_get_team_billing returns the team subscription details', async function () {
+            const inject = (o) => app.inject({ ...o, headers: { ...(o.headers || {}), authorization: `Bearer ${token}` } })
+            const tool = findTool('platform_get_team_billing')
+
+            const response = await tool.handler({ teamId: app.team.hashid }, { inject })
+
+            // app.team has an active subscription via the Stripe mock
+            response.statusCode.should.equal(200)
+            const body = response.json()
+            body.should.have.property('items').which.is.an.Array()
+            body.should.have.property('customer')
+            should.equal(stripe.subscriptions.retrieve.called, true)
+        })
+
+        it('platform_get_team_billing matches the team billing route response exactly', async function () {
+            const inject = (o) => app.inject({ ...o, headers: { ...(o.headers || {}), authorization: `Bearer ${token}` } })
+            const tool = findTool('platform_get_team_billing')
+
+            await expectToolMatchesRoute(inject, tool, { teamId: app.team.hashid }, {
+                method: 'GET',
+                url: `/ee/billing/teams/${app.team.hashid}`
+            })
+        })
+
+        it('platform_get_team_customer_portal matches the customer-portal route redirect location', async function () {
+            const inject = (o) => app.inject({ ...o, headers: { ...(o.headers || {}), authorization: `Bearer ${token}` } })
+            const tool = findTool('platform_get_team_customer_portal')
+
+            const { routeResponse } = await expectToolMatchesRoute(inject, tool, { teamId: app.team.hashid }, {
+                method: 'GET',
+                url: `/ee/billing/teams/${app.team.hashid}/customer-portal`,
+                transform: (r) => (r.statusCode >= 400
+                    ? { statusCode: r.statusCode, body: r.json() }
+                    : { statusCode: 200, body: { url: r.headers.location } })
+            })
+
+            // Stripe mock's billing portal session is wired to a fixed URL
+            routeResponse.headers.location.should.equal('https://billing.stripe.com/p/session/test_123')
+        })
+    })
+})