Skip to content

AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents

feat(mcp): list folders and move a flow into one (#16327)

Alexandru Andronic03e0f4deb847
diff --git a/bun.lock b/bun.lock
index 6e91ac206b9..09a9669f11c 100644
--- a/bun.lock
+++ b/bun.lock
@@ -166,7 +166,7 @@
},
"packages/core/shared": {
"name": "@activepieces/shared",
- "version": "0.201.0",
+ "version": "0.201.1",
"dependencies": {
"@activepieces/core-execution": "workspace:*",
"@activepieces/core-formula": "workspace:*",
diff --git a/docs/mcp/tools.mdx b/docs/mcp/tools.mdx
index ede274fafa1..e39dd3d967b 100644
--- a/docs/mcp/tools.mdx
+++ b/docs/mcp/tools.mdx
@@ -186,6 +186,14 @@ List all tables in the project with their fields (name, type, id) and row counts
|-------|------|----------|-------------|
| — | — | — | No inputs required |
+### ap_list_folders
+
+List the folders in the project with how many flows and tables each holds.
+
+| Input | Type | Required | Description |
+|-------|------|----------|-------------|
+| — | — | — | No inputs required |
+
### ap_find_records
Query records from a table with optional filtering.
@@ -269,6 +277,18 @@ Rename an existing flow.
| `flowId` | string | Yes | The flow ID |
| `displayName` | string | Yes | New name |
+### ap_move_flow_to_folder
+
+Move a flow into a folder, or take it out of its folder. A folder name is matched case-insensitively, and a new folder is created when no folder has that name.
+
+| Input | Type | Required | Description |
+|-------|------|----------|-------------|
+| `flowId` | string | Yes | The flow ID |
+| `folderName` | string | No | The folder to move the flow into |
+| `uncategorized` | boolean | No | `true` to take the flow out of its folder |
+
+Pass exactly one of `folderName` or `uncategorized`.
+
### ap_change_flow_status
Enable or disable a flow.
diff --git a/packages/core/shared/package.json b/packages/core/shared/package.json
index 42de9a917a6..01b0bccc3a5 100644
--- a/packages/core/shared/package.json
+++ b/packages/core/shared/package.json
@@ -1,6 +1,6 @@
{
"name": "@activepieces/shared",
- "version": "0.201.0",
+ "version": "0.201.1",
"type": "commonjs",
"sideEffects": false,
"main": "./dist/src/index.js",
diff --git a/packages/core/shared/src/lib/ee/agent/tool-phases.ts b/packages/core/shared/src/lib/ee/agent/tool-phases.ts
index efdeee8da1c..efa65984b7f 100644
--- a/packages/core/shared/src/lib/ee/agent/tool-phases.ts
+++ b/packages/core/shared/src/lib/ee/agent/tool-phases.ts
@@ -25,6 +25,7 @@ const BUILD_ONLY_TOOL_NAMES = new Set<string>([
'ap_change_flow_status',
'ap_delete_flow',
'ap_rename_flow',
+ 'ap_move_flow_to_folder',
'ap_duplicate_flow',
'ap_manage_notes',
'ap_retry_run',
diff --git a/packages/core/shared/src/lib/ee/agent/tool-skills.ts b/packages/core/shared/src/lib/ee/agent/tool-skills.ts
index 744945a0f96..f689230154d 100644
--- a/packages/core/shared/src/lib/ee/agent/tool-skills.ts
+++ b/packages/core/shared/src/lib/ee/agent/tool-skills.ts
@@ -134,11 +134,12 @@ const AGENT_SKILLS: readonly AgentSkill[] = [
},
{
name: 'flow_management',
- loadWhen: 'before inspecting, renaming, duplicating, deleting, pausing or annotating an existing flow',
+ loadWhen: 'before inspecting, renaming, duplicating, moving to a folder, deleting, pausing or annotating an existing flow',
entersBuildPhase: false,
toolNames: [
'ap_flow_structure', 'ap_read_step_code', 'ap_read_step_settings',
'ap_rename_flow', 'ap_duplicate_flow', 'ap_delete_flow', 'ap_change_flow_status', 'ap_manage_notes',
+ 'ap_list_folders', 'ap_move_flow_to_folder',
],
},
{
diff --git a/packages/server/api/src/app/mcp/tools/ap-list-folders.ts b/packages/server/api/src/app/mcp/tools/ap-list-folders.ts
new file mode 100644
index 00000000000..58880a42a58
--- /dev/null
+++ b/packages/server/api/src/app/mcp/tools/ap-list-folders.ts
@@ -0,0 +1,56 @@
+import { Cursor, Permission } from '@activepieces/core-utils'
+import { FolderDto, McpToolDefinition, ProjectScopedMcpServer } from '@activepieces/shared'
+import { FastifyBaseLogger } from 'fastify'
+import { flowFolderService } from '../../flows/folder/folder.service'
+import { mcpUtils } from './mcp-utils'
+
+export const apListFoldersTool = (mcp: ProjectScopedMcpServer, log: FastifyBaseLogger): McpToolDefinition => {
+ return {
+ title: 'ap_list_folders',
+ permission: Permission.READ_FLOW,
+ description: 'List the folders in the current project with how many flows and tables each holds. Use it to reuse an existing folder name instead of creating a near-duplicate.',
+ inputSchema: {},
+ annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+ execute: async () => {
+ try {
+ const folders = (await listAllFolders({ projectId: mcp.projectId, log })).map((folder) => ({
+ id: folder.id,
+ displayName: folder.displayName,
+ numberOfFlows: folder.numberOfFlows,
+ numberOfTables: folder.numberOfTables,
+ }))
+ if (folders.length === 0) {
+ return {
+ content: [{ type: 'text', text: 'No folders in this project. Create one with ap_create_folder, or move a flow into a new one with ap_move_flow_to_folder.' }],
+ structuredContent: { folders, count: 0 },
+ }
+ }
+ const lines = folders.map((f) => `- ${f.displayName} (id: ${f.id}): ${plural({ count: f.numberOfFlows, noun: 'flow' })}, ${plural({ count: f.numberOfTables, noun: 'table' })}`)
+ return {
+ content: [{ type: 'text', text: `✅ ${plural({ count: folders.length, noun: 'folder' })}:\n${lines.join('\n')}` }],
+ structuredContent: { folders, count: folders.length },
+ }
+ }
+ catch (err) {
+ return mcpUtils.mcpToolError('Folder listing failed', err)
+ }
+ },
+ }
+}
+
+async function listAllFolders({ projectId, log }: { projectId: string, log: FastifyBaseLogger }): Promise<FolderDto[]> {
+ const folders: FolderDto[] = []
+ let cursor: Cursor | null = null
+ do {
+ const page = await flowFolderService(log).list({ projectId, cursorRequest: cursor, limit: PAGE_SIZE })
+ folders.push(...page.data)
+ cursor = page.next
+ } while (cursor !== null)
+ return folders
+}
+
+function plural({ count, noun }: { count: number, noun: string }): string {
+ return `${count} ${noun}${count === 1 ? '' : 's'}`
+}
+
+const PAGE_SIZE = 100
diff --git a/packages/server/api/src/app/mcp/tools/ap-move-flow-to-folder.ts b/packages/server/api/src/app/mcp/tools/ap-move-flow-to-folder.ts
new file mode 100644
index 00000000000..9d27e4bb588
--- /dev/null
+++ b/packages/server/api/src/app/mcp/tools/ap-move-flow-to-folder.ts
@@ -0,0 +1,65 @@
+import { isNil, Permission } from '@activepieces/core-utils'
+import { FlowOperationRequest, FlowOperationType, Folder, McpToolContext, McpToolDefinition } from '@activepieces/shared'
+import { FastifyBaseLogger } from 'fastify'
+import { z } from 'zod'
+import { flowService } from '../../flows/flow/flow.service'
+import { flowFolderService } from '../../flows/folder/folder.service'
+import { projectService } from '../../project/project-service'
+import { mcpUtils } from './mcp-utils'
+
+const moveFlowToFolderInput = z.object({
+ flowId: z.string().describe('The id of the flow to move'),
+ folderName: mcpUtils.FOLDER_NAME_SCHEMA.describe('The folder to move the flow into. An existing folder is matched case-insensitively; a new one is created when no folder has this name.'),
+ uncategorized: z.boolean().optional().describe('true to take the flow out of its folder'),
+})
+
+export const apMoveFlowToFolderTool = ({ mcp, userId }: McpToolContext, log: FastifyBaseLogger): McpToolDefinition => {
+ return {
+ title: 'ap_move_flow_to_folder',
+ permission: Permission.WRITE_FLOW,
+ description: 'Move a flow into a folder, creating the folder when no folder has that name, or take it out of its folder with uncategorized=true. Pass exactly one of folderName or uncategorized.',
+ inputSchema: moveFlowToFolderInput.shape,
+ annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+ execute: async (args) => {
+ try {
+ const { flowId, folderName, uncategorized } = moveFlowToFolderInput.parse(args)
+ const toFolder = !isNil(folderName)
+ const toUncategorized = uncategorized === true
+ if (toFolder === toUncategorized) {
+ return { content: [{ type: 'text', text: '❌ Pass exactly one of folderName or uncategorized=true.' }], isError: true }
+ }
+ const flow = await flowService(log).getOnePopulated({ id: flowId, projectId: mcp.projectId })
+ if (isNil(flow)) {
+ return { content: [{ type: 'text', text: '❌ Flow not found' }], isError: true }
+ }
+ const folder = isNil(folderName) ? null : await getOrCreateFolder({ projectId: mcp.projectId, folderName, log })
+ const folderId = folder?.id ?? null
+ const moved = flow.folderId !== folderId
+ if (moved) {
+ const platformId = await projectService(log).getPlatformId(mcp.projectId)
+ const operation: FlowOperationRequest = { type: FlowOperationType.CHANGE_FOLDER, request: { folderId } }
+ await flowService(log).update({ id: flow.id, projectId: mcp.projectId, userId, previousFlow: flow, platformId, operation })
+ }
+ return {
+ content: [{ type: 'text', text: `✅ Flow "${flow.version.displayName}" ${describeOutcome({ moved, folderName: folder?.displayName })}.` }],
+ structuredContent: { flowId: flow.id, folderId, folderName: folder?.displayName ?? null, moved },
+ }
+ }
+ catch (err) {
+ return mcpUtils.mcpToolError('Flow move failed', err)
+ }
+ },
+ }
+}
+
+async function getOrCreateFolder({ projectId, folderName, log }: { projectId: string, folderName: string, log: FastifyBaseLogger }): Promise<Pick<Folder, 'id' | 'displayName'>> {
+ const existing = await flowFolderService(log).getOneByDisplayNameCaseInsensitive({ projectId, displayName: folderName })
+ return existing ?? flowFolderService(log).upsert({ projectId, request: { projectId, displayName: folderName } })
+}
+
+function describeOutcome({ moved, folderName }: { moved: boolean, folderName: string | undefined }): string {
+ if (isNil(folderName)) {
+ return moved ? 'moved out of its folder' : 'is already in no folder'
+ }
+ return moved ? `moved to folder "${folderName}"` : `is already in folder "${folderName}"`
+}
diff --git a/packages/server/api/src/app/mcp/tools/index.ts b/packages/server/api/src/app/mcp/tools/index.ts
index f19c02cd59d..d8a5fae3a61 100644
--- a/packages/server/api/src/app/mcp/tools/index.ts
+++ b/packages/server/api/src/app/mcp/tools/index.ts
@@ -22,11 +22,13 @@ import { apInsertRecordsTool } from './ap-insert-records'
import { apListAiModelsTool } from './ap-list-ai-models'
import { apListConnectionsTool } from './ap-list-connections'
import { apListFlowsTool } from './ap-list-flows'
+import { apListFoldersTool } from './ap-list-folders'
import { apListRunsTool } from './ap-list-runs'
import { apListTablesTool } from './ap-list-tables'
import { apLockAndPublishTool } from './ap-lock-and-publish'
import { apManageFieldsTool } from './ap-manage-fields'
import { apManageNotesTool } from './ap-manage-notes'
+import { apMoveFlowToFolderTool } from './ap-move-flow-to-folder'
import { apReadStepCodeTool } from './ap-read-step-code'
import { apReadStepSettingsTool } from './ap-read-step-settings'
import { apRenameFlowTool } from './ap-rename-flow'
@@ -67,6 +69,7 @@ export const LOCKED_TOOL_NAMES: string[] = [
'ap_list_connections',
'ap_list_ai_models',
'ap_list_tables',
+ 'ap_list_folders',
'ap_find_records',
'ap_list_runs',
'ap_get_run',
@@ -89,6 +92,7 @@ export const ALL_CONTROLLABLE_TOOL_NAMES = [
'ap_create_folder',
'ap_duplicate_flow',
'ap_rename_flow',
+ 'ap_move_flow_to_folder',
'ap_update_trigger',
'ap_add_step',
'ap_update_step',
@@ -118,7 +122,9 @@ export const activepiecesTools = (mcp: ProjectScopedMcpServer, userId: string |
apCreateFolderTool(mcp, log),
apDuplicateFlowTool({ mcp, userId }, log),
apRenameFlowTool({ mcp, userId }, log),
+ apMoveFlowToFolderTool({ mcp, userId }, log),
apListFlowsTool(mcp, log),
+ apListFoldersTool(mcp, log),
apFlowStructureTool(mcp, log),
apReadStepCodeTool(mcp, log),
apReadStepSettingsTool(mcp, log),
diff --git a/packages/server/api/test/integration/ce/mcp/mcp-tools.test.ts b/packages/server/api/test/integration/ce/mcp/mcp-tools.test.ts
index 7d750887f7d..d58ea2dfcfd 100644
--- a/packages/server/api/test/integration/ce/mcp/mcp-tools.test.ts
+++ b/packages/server/api/test/integration/ce/mcp/mcp-tools.test.ts
@@ -30,6 +30,8 @@ import { apUpdateBranchTool } from '../../../../src/app/mcp/tools/ap-update-bran
import { apListRunsTool } from '../../../../src/app/mcp/tools/ap-list-runs'
import { apGetRunTool } from '../../../../src/app/mcp/tools/ap-get-run'
import { apListFlowsTool } from '../../../../src/app/mcp/tools/ap-list-flows'
+import { apListFoldersTool } from '../../../../src/app/mcp/tools/ap-list-folders'
+import { apMoveFlowToFolderTool } from '../../../../src/app/mcp/tools/ap-move-flow-to-folder'
import { apReadStepSettingsTool } from '../../../../src/app/mcp/tools/ap-read-step-settings'
import { apRunActionTool } from '../../../../src/app/mcp/tools/ap-run-action'
import { mcpUtils } from '../../../../src/app/mcp/tools/mcp-utils'
@@ -2938,6 +2940,79 @@ describe('MCP Tools integration', () => {
expect(new Set(folderIds).size).toBe(1)
})
+ it('ap_move_flow_to_folder creates a folder by name, reuses it in any case, and takes the flow back out', async () => {
+ const ctx = await createTestContext(app)
+ const mcp = makeMcp(ctx.project.id)
+ const flowId = await createFlowAndGetId(mcp, 'Folder flow')
+ const otherFlowId = await createFlowAndGetId(mcp, 'Folder flow 2')
+ const moveSchema = z.object({ folderId: z.string().nullable(), folderName: z.string().nullable(), moved: z.boolean() })
+ const move = apMoveFlowToFolderTool({ mcp }, mockLog).execute
+
+ const created = await move({ flowId, folderName: 'Order intake' })
+ const reused = await move({ flowId: otherFlowId, folderName: 'order INTAKE' })
+ const again = await move({ flowId, folderName: 'Order intake' })
+ const listed = await apListFoldersTool(mcp, mockLog).execute({})
+ const out = await move({ flowId, uncategorized: true })
+
+ const createdContent = structured({ result: created, schema: moveSchema })
+ const otherFlow = await flowService(mockLog).getOneOrThrow({ id: otherFlowId, projectId: ctx.project.id })
+ const flow = await flowService(mockLog).getOneOrThrow({ id: flowId, projectId: ctx.project.id })
+ expect(createdContent).toMatchObject({ folderName: 'Order intake', moved: true })
+ expect(text(created)).toContain('to folder "Order intake"')
+ expect(structured({ result: reused, schema: moveSchema })).toMatchObject({ folderId: createdContent.folderId, folderName: 'Order intake' })
+ expect(otherFlow.folderId).toBe(createdContent.folderId)
+ expect(structured({ result: again, schema: moveSchema }).moved).toBe(false)
+ expect(text(listed)).toContain('Order intake')
+ expect(text(listed)).toContain('2 flows')
+ expect(text(out)).toContain('out of its folder')
+ expect(flow.folderId).toBeNull()
+ })
+
+ it('ap_move_flow_to_folder called concurrently into a new name in different casing files both flows into one folder', async () => {
+ const ctx = await createTestContext(app)
+ const mcp = makeMcp(ctx.project.id)
+ const flowIds = await Promise.all([createFlowAndGetId(mcp, 'Parallel move 1'), createFlowAndGetId(mcp, 'Parallel move 2')])
+
+ const results = await Promise.all([
+ apMoveFlowToFolderTool({ mcp }, mockLog).execute({ flowId: flowIds[0], folderName: 'Parallel move' }),
+ apMoveFlowToFolderTool({ mcp }, mockLog).execute({ flowId: flowIds[1], folderName: 'PARALLEL move' }),
+ ])
+
+ const folderIds = results.map((result) => structured({ result, schema: z.object({ folderId: z.string() }) }).folderId)
+ const flows = await Promise.all(flowIds.map((id) => flowService(mockLog).getOneOrThrow({ id, projectId: ctx.project.id })))
+ expect(new Set(folderIds).size).toBe(1)
+ expect(flows.map((flow) => flow.folderId)).toEqual([folderIds[0], folderIds[0]])
+ })
+
+ it('ap_move_flow_to_folder needs exactly one target and only moves flows in its own project', async () => {
+ const ctx = await createTestContext(app)
+ const other = await createTestContext(app)
+ const mcp = makeMcp(ctx.project.id)
+ const flowId = await createFlowAndGetId(mcp, 'Guarded flow')
+ const foreignFlowId = await createFlowAndGetId(makeMcp(other.project.id), 'Other project flow')
+ const move = apMoveFlowToFolderTool({ mcp }, mockLog).execute
+
+ const none = await move({ flowId })
+ const both = await move({ flowId, folderName: 'A', uncategorized: true })
+ const foreign = await move({ flowId: foreignFlowId, folderName: 'Mine' })
+
+ const foreignFlow = await flowService(mockLog).getOneOrThrow({ id: foreignFlowId, projectId: other.project.id })
+ expect(text(none)).toContain('exactly one')
+ expect(text(both)).toContain('exactly one')
+ expect(text(foreign)).toContain('Flow not found')
+ expect(foreignFlow.folderId).toBeNull()
+ })
+
+ it('ap_list_folders returns every folder past the first page', async () => {
+ const ctx = await createTestContext(app)
+ const mcp = makeMcp(ctx.project.id)
+ await Promise.all(Array.from({ length: 105 }, (_, i) => flowFolderService(mockLog).upsert({ projectId: ctx.project.id, request: { projectId: ctx.project.id, displayName: `Folder ${i}` } })))
+
+ const listed = await apListFoldersTool(mcp, mockLog).execute({})
+
+ expect(structured({ result: listed, schema: z.object({ count: z.number() }) }).count).toBe(105)
+ })
+
it('ap_create_flow without a folder leaves the flow unfiled', async () => {
const ctx = await createTestContext(app)
const mcp = makeMcp(ctx.project.id)
diff --git a/packages/web/src/app/components/project-settings/mcp-server/tool-tiers/mcp-tool-tiers.ts b/packages/web/src/app/components/project-settings/mcp-server/tool-tiers/mcp-tool-tiers.ts
index e959c534966..91be3e1b673 100644
--- a/packages/web/src/app/components/project-settings/mcp-server/tool-tiers/mcp-tool-tiers.ts
+++ b/packages/web/src/app/components/project-settings/mcp-server/tool-tiers/mcp-tool-tiers.ts
@@ -9,6 +9,7 @@ const DRAFT_TOOLS = new Set([
'ap_create_flow',
'ap_duplicate_flow',
'ap_rename_flow',
+ 'ap_move_flow_to_folder',
'ap_build_flow',
'ap_update_trigger',
'ap_add_step',
diff --git a/packages/web/src/app/components/project-settings/mcp-server/utils/mcp-tools-metadata.ts b/packages/web/src/app/components/project-settings/mcp-server/utils/mcp-tools-metadata.ts
index 68a88288cd4..d383bd8d5c4 100644
--- a/packages/web/src/app/components/project-settings/mcp-server/utils/mcp-tools-metadata.ts
+++ b/packages/web/src/app/components/project-settings/mcp-server/utils/mcp-tools-metadata.ts
@@ -19,6 +19,11 @@ const TOOL_CATEGORIES: ToolCategory[] = [
name: 'ap_list_flows',
description: 'List all flows in the current project',
},
+ {
+ name: 'ap_list_folders',
+ description:
+ 'List the folders in the current project with their flow and table counts',
+ },
{
name: 'ap_flow_structure',
description:
@@ -127,6 +132,10 @@ const TOOL_CATEGORIES: ToolCategory[] = [
name: 'ap_rename_flow',
description: 'Rename an existing flow',
},
+ {
+ name: 'ap_move_flow_to_folder',
+ description: 'Move a flow into a folder, creating the folder if needed',
+ },
{
name: 'ap_change_flow_status',
description: 'Enable or disable a flow',
diff --git a/packages/web/src/features/chat/lib/tool-icons.ts b/packages/web/src/features/chat/lib/tool-icons.ts
index 4b03663be80..e3737be3d52 100644
--- a/packages/web/src/features/chat/lib/tool-icons.ts
+++ b/packages/web/src/features/chat/lib/tool-icons.ts
@@ -5,7 +5,9 @@ import {
Columns3,
Copy,
FlaskConical,
+ FolderInput,
FolderPlus,
+ Folders,
GitBranch,
Globe,
Image,
@@ -51,6 +53,7 @@ const TOOL_ICONS: Record<string, LucideIcon> = {
ap_find_records: Search,
ap_list_across_projects: List,
ap_list_flows: List,
+ ap_list_folders: Folders,
ap_list_runs: List,
ap_list_tables: List,
ap_list_connections: Plug,
@@ -70,6 +73,7 @@ const TOOL_ICONS: Record<string, LucideIcon> = {
ap_update_branch: GitBranch,
ap_delete_branch: GitBranch,
ap_rename_flow: Pencil,
+ ap_move_flow_to_folder: FolderInput,
ap_duplicate_flow: Copy,
ap_delete_flow: Trash2,
ap_flow_structure: Network,
diff --git a/packages/web/test/app/components/project-settings/mcp-server/tool-tiers/mcp-tool-tiers.test.ts b/packages/web/test/app/components/project-settings/mcp-server/tool-tiers/mcp-tool-tiers.test.ts
index 014aef9c422..9fe2ef1ac10 100644
--- a/packages/web/test/app/components/project-settings/mcp-server/tool-tiers/mcp-tool-tiers.test.ts
+++ b/packages/web/test/app/components/project-settings/mcp-server/tool-tiers/mcp-tool-tiers.test.ts
@@ -40,6 +40,7 @@ describe('mcpToolTiers.groupByTier', () => {
'ap_create_flow',
'ap_duplicate_flow',
'ap_rename_flow',
+ 'ap_move_flow_to_folder',
'ap_build_flow',
'ap_update_trigger',
'ap_add_step',