refactor(mcp): add application audit-log export and team application statuses

Author: andypalmi

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

@@ -14,6 +14,14 @@ const {
     appendQuery
 } = require('../schemas')
 
+// Audit-log routes accept cursor+limit pagination, free-text query, event
+// (single name or array) and username. scope narrows which entity levels are
+// returned and its allowed values differ per route (the device route has none);
+// includeChildren pulls in descendant entries within the chosen scope.
+const includeChildren = z.boolean().optional().describe('Also include audit entries from child entities within the chosen scope')
+const auditLogInput = { ...basePagination, ...searchQuery, ...auditLogFilters }
+const auditLogKeys = [...basePaginationKeys, ...searchQueryKeys, ...auditLogFilterKeys]
+
 module.exports = [
     {
         name: 'platform_list_applications',
@@ -163,5 +171,42 @@ module.exports = [
             const response = await inject({ method: 'GET', url })
             return response
         }
+    },
+    {
+        name: 'platform_export_application_audit_log',
+        title: 'Export Application Audit Log',
+        description: `FlowFuse platform automation tool:
+            Exports an application audit log as a CSV file.
+            Use this when the user wants a downloadable or shareable copy of the application's audit history.
+            To read audit log entries directly instead, use the application audit log read tool.`,
+        annotations: { readOnlyHint: true, destructiveHint: false },
+        inputSchema: {
+            applicationId,
+            ...auditLogInput,
+            scope: z.enum(['application', 'project', 'device']).optional().describe('Entity level to include (default application)'),
+            includeChildren
+        },
+        handler: async (args, { inject }) => {
+            const url = appendQuery(`/api/v1/applications/${args.applicationId}/audit-log/export`, args, [...auditLogKeys, 'scope', 'includeChildren'])
+            const response = await inject({ method: 'GET', url })
+            return response
+        }
+    },
+    {
+        name: 'platform_list_team_application_statuses',
+        title: 'List Team Application Statuses',
+        description: `FlowFuse platform automation tool:
+            Lists the applications in a team along with the live status of their associated hosted instances and remote instances.
+            Use this to get a status overview across an entire team without querying each application individually.`,
+        annotations: { readOnlyHint: true, destructiveHint: false },
+        inputSchema: {
+            teamId,
+            associationsLimit: z.number().optional().describe('Maximum number of associated instances and devices to include per application')
+        },
+        handler: async (args, { inject }) => {
+            const url = appendQuery(`/api/v1/teams/${args.teamId}/applications/status`, args, ['associationsLimit'])
+            const response = await inject({ method: 'GET', url })
+            return response
+        }
     }
 ]

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

@@ -114,6 +114,64 @@ describe('MCP Application Tools', function () {
         })
     })
 
+    describe('platform_export_application_audit_log', function () {
+        const tool = findTool('platform_export_application_audit_log')
+
+        it('has read-only annotations', function () {
+            tool.annotations.readOnlyHint.should.equal(true)
+            tool.annotations.destructiveHint.should.equal(false)
+        })
+
+        it('exposes the expected input fields', function () {
+            Object.keys(tool.inputSchema).should.eql(['applicationId', 'cursor', 'limit', 'query', 'event', 'username', 'scope', 'includeChildren'])
+        })
+
+        it('requests the export endpoint with no query string when no filters are given', 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/audit-log/export')
+        })
+
+        it('serialises cursor, limit, event, username, scope and includeChildren onto the query string', async function () {
+            const { calls, inject } = recordingInject()
+            await tool.handler({
+                applicationId: 'app1',
+                cursor: 'c1',
+                limit: 10,
+                event: 'application.created',
+                username: 'alice',
+                scope: 'application',
+                includeChildren: true
+            }, { inject })
+            calls.should.have.length(1)
+            calls[0].method.should.equal('GET')
+            calls[0].url.should.equal('/api/v1/applications/app1/audit-log/export?cursor=c1&limit=10&event=application.created&username=alice&scope=application&includeChildren=true')
+        })
+    })
+
+    describe('platform_list_team_application_statuses', function () {
+        const tool = findTool('platform_list_team_application_statuses')
+
+        it('has the expected input params', function () {
+            Object.keys(tool.inputSchema).should.eql(['teamId', 'associationsLimit'])
+        })
+
+        it('calls GET /api/v1/teams/:teamId/applications/status with associationsLimit', async function () {
+            const { calls, inject } = recordingInject()
+            await tool.handler({ teamId: 'team1', associationsLimit: 5 }, { inject })
+            calls[0].method.should.equal('GET')
+            calls[0].url.should.equal('/api/v1/teams/team1/applications/status?associationsLimit=5')
+        })
+
+        it('omits the query string when associationsLimit is not set', async function () {
+            const { calls, inject } = recordingInject()
+            await tool.handler({ teamId: 'team1' }, { inject })
+            calls[0].url.should.equal('/api/v1/teams/team1/applications/status')
+        })
+    })
+
     describe('Integration smoke test', function () {
         let app
         let token
@@ -229,6 +287,23 @@ describe('MCP Application Tools', function () {
                     url: `/api/v1/applications/${app.application.hashid}/snapshots`
                 })
             })
+
+            it('platform_export_application_audit_log matches GET /api/v1/applications/:applicationId/audit-log/export', async function () {
+                const tool = findTool('platform_export_application_audit_log')
+                await expectToolMatchesRoute(inject, tool, { applicationId: app.application.hashid }, {
+                    method: 'GET',
+                    url: `/api/v1/applications/${app.application.hashid}/audit-log/export`,
+                    raw: true
+                })
+            })
+
+            it('platform_list_team_application_statuses matches GET /api/v1/teams/:teamId/applications/status', async function () {
+                const tool = findTool('platform_list_team_application_statuses')
+                await expectToolMatchesRoute(inject, tool, { teamId: app.team.hashid }, {
+                    method: 'GET',
+                    url: `/api/v1/teams/${app.team.hashid}/applications/status`
+                })
+            })
         })
     })
 })