feat(mcp): add pipeline read tools

andypalmi · andypalmi · commit 8396005ef499 · 2026-07-06T18:30:17.000+02:00
Add read-only MCP tools to list team and application pipelines and get a pipeline stage, with unit and equivalence tests. Allow-list their scopes for the expert-mcp platform token.
diff --git a/forge/ee/lib/mcp/tools/pipelines.js b/forge/ee/lib/mcp/tools/pipelines.js
@@ -0,0 +1,57 @@
+const { z } = require('zod')
+
+const { teamId, applicationId } = require('../schemas')
+
+module.exports = [
+    {
+        name: 'platform_list_team_pipelines',
+        title: 'List Team Pipelines',
+        description: `FlowFuse platform automation tool:
+            Lists the DevOps pipelines that exist for a team.
+            Results are filtered to the applications you can access, so a scoped access token
+            sees only its in-scope subset of pipelines rather than an error.
+            Use this to discover which pipelines exist before inspecting a specific pipeline's stages.`,
+        annotations: { readOnlyHint: true, destructiveHint: false },
+        inputSchema: {
+            teamId
+        },
+        handler: async (args, { inject }) => {
+            const response = await inject({ method: 'GET', url: `/api/v1/teams/${args.teamId}/pipelines` })
+            return response
+        }
+    },
+    {
+        name: 'platform_list_application_pipelines',
+        title: 'List Application Pipelines',
+        description: `FlowFuse platform automation tool:
+            Lists the DevOps pipelines belonging to a specific application.
+            Use this when you already know the application and want its pipelines,
+            rather than filtering the full team pipeline list.`,
+        annotations: { readOnlyHint: true, destructiveHint: false },
+        inputSchema: {
+            applicationId
+        },
+        handler: async (args, { inject }) => {
+            const response = await inject({ method: 'GET', url: `/api/v1/applications/${args.applicationId}/pipelines` })
+            return response
+        }
+    },
+    {
+        name: 'platform_get_pipeline_stage',
+        title: 'Get Pipeline Stage',
+        description: `FlowFuse platform automation tool:
+            Fetches the full details of a single stage within a pipeline, including what it
+            targets (hosted instance, remote instance/device, device group, or git repository)
+            and its snapshot action.
+            Use this once you have a pipeline ID and a stage ID and need to inspect that stage.`,
+        annotations: { readOnlyHint: true, destructiveHint: false },
+        inputSchema: {
+            pipelineId: z.string().describe('Pipeline hashid the stage belongs to'),
+            stageId: z.string().describe('Pipeline stage hashid to fetch')
+        },
+        handler: async (args, { inject }) => {
+            const response = await inject({ method: 'GET', url: `/api/v1/pipelines/${args.pipelineId}/stages/${args.stageId}` })
+            return response
+        }
+    }
+]
diff --git a/forge/routes/auth/permissions.js b/forge/routes/auth/permissions.js
@@ -52,7 +52,11 @@ const IMPLICIT_TOKEN_SCOPES = {
         'stack:list',
         'flow-blueprint:list',
         'project:status',
-        'template:list'
+        'template:list',
+        // pipelines
+        'team:pipeline:list', // list team pipelines
+        'application:pipeline:list', // list application pipelines
+        'pipeline:read' // get pipeline stage details
     ]
 }
 
diff --git a/test/unit/forge/ee/lib/mcp/tools/pipelines_spec.js b/test/unit/forge/ee/lib/mcp/tools/pipelines_spec.js
@@ -0,0 +1,207 @@
+const should = require('should') // eslint-disable-line no-unused-vars
+
+const TestModelFactory = require('../../../../../../lib/TestModelFactory')
+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/pipelines')
+
+const findTool = toolFinder(tools)
+
+describe('MCP Platform Tools - Pipelines', function () {
+    describe('platform_list_team_pipelines', function () {
+        const tool = findTool('platform_list_team_pipelines')
+
+        it('is defined with read-only, non-destructive annotations', function () {
+            should(tool).be.an.Object()
+            tool.annotations.readOnlyHint.should.equal(true)
+            tool.annotations.destructiveHint.should.equal(false)
+        })
+
+        it('accepts a teamId input', function () {
+            Object.keys(tool.inputSchema).should.eql(['teamId'])
+        })
+
+        it('calls GET /api/v1/teams/:teamId/pipelines', async function () {
+            const { calls, inject } = recordingInject()
+            await tool.handler({ teamId: 'team1' }, { inject })
+            calls.should.have.length(1)
+            calls[0].method.should.equal('GET')
+            calls[0].url.should.equal('/api/v1/teams/team1/pipelines')
+        })
+    })
+
+    describe('platform_list_application_pipelines', function () {
+        const tool = findTool('platform_list_application_pipelines')
+
+        it('is defined with read-only, non-destructive annotations', function () {
+            should(tool).be.an.Object()
+            tool.annotations.readOnlyHint.should.equal(true)
+            tool.annotations.destructiveHint.should.equal(false)
+        })
+
+        it('accepts an applicationId input', function () {
+            Object.keys(tool.inputSchema).should.eql(['applicationId'])
+        })
+
+        it('calls GET /api/v1/applications/:applicationId/pipelines', async function () {
+            const { calls, inject } = recordingInject()
+            await tool.handler({ applicationId: 'app1' }, { inject })
+            calls.should.have.length(1)
+            calls[0].method.should.equal('GET')
+            calls[0].url.should.equal('/api/v1/applications/app1/pipelines')
+        })
+    })
+
+    describe('platform_get_pipeline_stage', function () {
+        const tool = findTool('platform_get_pipeline_stage')
+
+        it('is defined with read-only, non-destructive annotations', function () {
+            should(tool).be.an.Object()
+            tool.annotations.readOnlyHint.should.equal(true)
+            tool.annotations.destructiveHint.should.equal(false)
+        })
+
+        it('accepts pipelineId and stageId inputs', function () {
+            Object.keys(tool.inputSchema).should.eql(['pipelineId', 'stageId'])
+        })
+
+        it('calls GET /api/v1/pipelines/:pipelineId/stages/:stageId', async function () {
+            const { calls, inject } = recordingInject()
+            await tool.handler({ pipelineId: 'pipe1', stageId: 'stage1' }, { inject })
+            calls.should.have.length(1)
+            calls[0].method.should.equal('GET')
+            calls[0].url.should.equal('/api/v1/pipelines/pipe1/stages/stage1')
+        })
+    })
+
+    describe('integration smoke', function () {
+        const setup = require('../../../setup')
+
+        let app
+        let token
+
+        before(async function () {
+            app = await setup({ ai: { enabled: true }, expert: { enabled: true } })
+            token = await createExpertMcpToken(app)
+        })
+
+        after(async function () {
+            await app.close()
+        })
+
+        function inject (o) {
+            return app.inject({ ...o, headers: { ...(o.headers || {}), authorization: `Bearer ${token}` } })
+        }
+
+        it('lists pipelines for a team with none configured', async function () {
+            const response = await inject({ method: 'GET', url: `/api/v1/teams/${app.team.hashid}/pipelines` })
+            response.statusCode.should.equal(200)
+            const body = response.json()
+            body.should.have.property('count', 0)
+            body.should.have.property('pipelines')
+            body.pipelines.should.be.an.Array()
+            body.pipelines.should.have.length(0)
+        })
+    })
+
+    describe('integration equivalence (tool vs route)', function () {
+        const setup = require('../../../setup')
+        const { createSnapshot } = FF_UTIL.require('forge/services/snapshots')
+
+        let app
+        let token
+        let pipeline
+        let stageOne
+        let stageTwo
+
+        before(async function () {
+            app = await setup({ ai: { enabled: true }, expert: { enabled: true } })
+            token = await createExpertMcpToken(app)
+
+            const factory = new TestModelFactory(app)
+
+            const deviceGroup = await factory.createApplicationDeviceGroup({ name: 'device-group-a' }, app.application)
+
+            pipeline = await factory.createPipeline({ name: 'equivalence-pipeline' }, app.application)
+            stageOne = await factory.createPipelineStage({ name: 'stage-one', instanceId: app.instance.id }, pipeline)
+            stageTwo = await factory.createPipelineStage({
+                name: 'stage-two',
+                deviceGroupId: deviceGroup.id,
+                source: stageOne.hashid,
+                action: 'use_latest_snapshot'
+            }, pipeline)
+
+            await createSnapshot(app, app.instance, app.user, {
+                name: 'equivalence-snapshot',
+                description: 'snapshot seeded for tool/route equivalence checks',
+                setAsTarget: false
+            })
+        })
+
+        after(async function () {
+            await app.close()
+        })
+
+        function inject (o) {
+            return app.inject({ ...o, headers: { ...(o.headers || {}), authorization: `Bearer ${token}` } })
+        }
+
+        it('platform_list_team_pipelines matches GET /api/v1/teams/:teamId/pipelines', async function () {
+            const tool = findTool('platform_list_team_pipelines')
+            const { routeResponse } = await expectToolMatchesRoute(
+                inject,
+                tool,
+                { teamId: app.team.hashid },
+                { method: 'GET', url: `/api/v1/teams/${app.team.hashid}/pipelines` }
+            )
+            routeResponse.statusCode.should.equal(200)
+            const body = routeResponse.json()
+            body.count.should.equal(1)
+            body.pipelines.should.have.length(1)
+        })
+
+        it('platform_list_application_pipelines matches GET /api/v1/applications/:applicationId/pipelines', async function () {
+            const tool = findTool('platform_list_application_pipelines')
+            const { routeResponse } = await expectToolMatchesRoute(
+                inject,
+                tool,
+                { applicationId: app.application.hashid },
+                { method: 'GET', url: `/api/v1/applications/${app.application.hashid}/pipelines` }
+            )
+            routeResponse.statusCode.should.equal(200)
+            const body = routeResponse.json()
+            body.count.should.equal(1)
+            body.pipelines.should.have.length(1)
+        })
+
+        it('platform_get_pipeline_stage matches GET /api/v1/pipelines/:pipelineId/stages/:stageId (instance stage)', async function () {
+            const tool = findTool('platform_get_pipeline_stage')
+            const { routeResponse } = await expectToolMatchesRoute(
+                inject,
+                tool,
+                { pipelineId: pipeline.hashid, stageId: stageOne.hashid },
+                { method: 'GET', url: `/api/v1/pipelines/${pipeline.hashid}/stages/${stageOne.hashid}` }
+            )
+            routeResponse.statusCode.should.equal(200)
+            const body = routeResponse.json()
+            body.should.have.property('id', stageOne.hashid)
+            body.should.have.property('instances')
+        })
+
+        it('platform_get_pipeline_stage matches GET /api/v1/pipelines/:pipelineId/stages/:stageId (device group stage)', async function () {
+            const tool = findTool('platform_get_pipeline_stage')
+            const { routeResponse } = await expectToolMatchesRoute(
+                inject,
+                tool,
+                { pipelineId: pipeline.hashid, stageId: stageTwo.hashid },
+                { method: 'GET', url: `/api/v1/pipelines/${pipeline.hashid}/stages/${stageTwo.hashid}` }
+            )
+            routeResponse.statusCode.should.equal(200)
+            const body = routeResponse.json()
+            body.should.have.property('id', stageTwo.hashid)
+            body.should.have.property('deviceGroups')
+        })
+    })
+})

Original file line number	Diff line number	Diff line change
`@@ -52,7 +52,11 @@ const IMPLICIT_TOKEN_SCOPES = {`
`52`	`52`	`'stack:list',`
`53`	`53`	`'flow-blueprint:list',`
`54`	`54`	`'project:status',`
`55`		`- 'template:list'`
	`55`	`+ 'template:list',`
	`56`	`+ // pipelines`
	`57`	`+ 'team:pipeline:list', // list team pipelines`
	`58`	`+ 'application:pipeline:list', // list application pipelines`
	`59`	`+ 'pipeline:read' // get pipeline stage details`
`56`	`60`	`]`
`57`	`61`	`}`
`58`	`62`