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
TypeScript ai-agentai-agent-toolsai-agentsai-agents-frameworkmcpmcp-servermcp-toolsmcpsn8n-alternativeno-code-automationworkflowworkflow-automationworkflows
import { isNil, Permission } from '@activepieces/core-utils'
import { BranchCondition, BranchExecutionType, FlowActionType, flowCanvasUtils, flowStructureUtil, FlowTrigger, FlowTriggerType, McpToolDefinition, Note, ProjectScopedMcpServer, StepLocationRelativeToParent } from '@activepieces/shared'
import type { Step } from '@activepieces/shared'
import { FastifyBaseLogger } from 'fastify'
import { z } from 'zod'
import { flowService } from '../../flows/flow/flow.service'
import { mcpUtils } from './mcp-utils'
type StepInfo = {
name: string
type: string
displayName: string
parentName: string | null
relationship: 'trigger' | 'next' | 'first_loop_action' | 'branch' | 'on_success_branch' | 'on_failure_branch'
branchIndex?: number
branchName?: string
valid: boolean
skip?: boolean
configStatus: string
}
function getConfigStatus({ step, skippedStepNames }: { step: Step, skippedStepNames: Set<string> }): string {
if (skippedStepNames.has(step.name)) return 'skipped'
if (step.valid) return 'configured'
const s = step.settings as { triggerName?: string, actionName?: string }
switch (step.type) {
case FlowTriggerType.EMPTY:
return 'unconfigured (no trigger set — use ap_update_trigger)'
case FlowTriggerType.PIECE:
return s.triggerName ? 'invalid (use ap_update_trigger to fix — check required inputs)' : 'unconfigured (triggerName missing)'
case FlowActionType.PIECE:
return s.actionName ? 'invalid (use ap_update_step to fix — check required inputs)' : 'unconfigured (actionName missing)'
case FlowActionType.CODE:
return 'invalid (check sourceCode/input)'
case FlowActionType.LOOP_ON_ITEMS:
return 'invalid (loopItems expression missing or invalid)'
case FlowActionType.ROUTER:
return 'invalid (check branch conditions)'
case FlowActionType.AI_ROUTER:
return 'invalid (check the input, question and route descriptions)'
default:
return 'invalid'
}
}
function hasSampleData(step: Step): boolean {
if (!('sampleData' in step.settings)) {
return false
}
const sampleData = step.settings.sampleData
return typeof sampleData === 'object' && sampleData !== null && 'sampleDataFileId' in sampleData && sampleData.sampleDataFileId != null
}
function formatStepSettings(step: Step): string[] {
const lines: string[] = []
const settings = step.settings as Record<string, unknown>
if (step.type === FlowTriggerType.PIECE || step.type === FlowActionType.PIECE) {
const input = settings.input as Record<string, unknown> | undefined
if (input && Object.keys(input).length > 0) {
lines.push(` input: ${mcpUtils.truncate(JSON.stringify(input), 500)}`)
}
}
else if (step.type === FlowActionType.CODE) {
const sourceCode = settings.sourceCode as { code?: string, packageJson?: string } | undefined
if (sourceCode?.code) {
lines.push(` sourceCode: ${mcpUtils.truncate(sourceCode.code, 300)}`)
}
if (sourceCode?.packageJson && sourceCode.packageJson !== '{}') {
lines.push(` packageJson: ${mcpUtils.truncate(sourceCode.packageJson, 200)}`)
}
const input = settings.input as Record<string, unknown> | undefined
if (input && Object.keys(input).length > 0) {
lines.push(` input: ${mcpUtils.truncate(JSON.stringify(input), 300)}`)
}
}
else if (step.type === FlowActionType.LOOP_ON_ITEMS) {
const items = settings.items as string | undefined
if (items) {
lines.push(` loopItems: ${items}`)
}
}
return lines
}
function formatRelationshipLabel(step: StepInfo): string {
switch (step.relationship) {
case 'trigger':
return 'trigger'
case 'next':
return 'after parent'
case 'first_loop_action':
return 'inside_loop'
case 'on_success_branch':
return 'on_success_branch'
case 'on_failure_branch':
return 'on_failure_branch'
case 'branch':
return `branch ${step.branchIndex}${step.branchName ? ` "${step.branchName}"` : ''}`
}
}
function formatBranchConditions(conditions: BranchCondition[][]): string {
const groups = conditions.map((andGroup) => {
const parts = andGroup.map((c) => {
const op = c.operator ?? '?'
const caseSensitive = 'caseSensitive' in c && c.caseSensitive ? ' [case-sensitive]' : ''
return 'secondValue' in c
? `${c.firstValue} ${op} ${c.secondValue}${caseSensitive}`
: `${c.firstValue} ${op}${caseSensitive}`
})
return parts.join(' AND ')
})
return groups.join(' OR ')
}
function buildFlowStructure(trigger: FlowTrigger): { structure: StepInfo[], stepByName: Map<string, Step> } {
const allSteps = flowStructureUtil.getAllSteps(trigger)
const skippedStepNames = flowStructureUtil.getSkippedStepNames({ trigger })
const stepByName = new Map(allSteps.map(s => [s.name, s]))
const structure = allSteps.map((step): StepInfo => {
if (flowStructureUtil.isTrigger(step.type)) {
return {
name: step.name,
type: step.type,
displayName: step.displayName,
parentName: null,
relationship: 'trigger',
valid: step.valid,
skip: skippedStepNames.has(step.name),
configStatus: getConfigStatus({ step, skippedStepNames }),
}
}
let parentName: string | null = null
let relationship: StepInfo['relationship'] = 'next'
let branchIndex: number | undefined
let branchName: string | undefined
for (const parent of allSteps) {
if (parent.nextAction?.name === step.name) {
parentName = parent.name
relationship = 'next'
break
}
if (parent.type === FlowActionType.LOOP_ON_ITEMS && (parent as { firstLoopAction?: { name: string } }).firstLoopAction?.name === step.name) {
parentName = parent.name
relationship = 'first_loop_action'
break
}
if (flowStructureUtil.isBranchedAction(parent)) {
const idx = parent.children.findIndex((c) => c?.name === step.name)
if (idx >= 0) {
parentName = parent.name
relationship = 'branch'
branchIndex = idx
branchName = parent.settings.branches[idx]?.branchName
break
}
}
if (parent.type === FlowActionType.CODE || parent.type === FlowActionType.PIECE) {
const branches = parent.continueOnFailureBranches
if (branches?.onSuccess?.name === step.name) {
parentName = parent.name
relationship = 'on_success_branch'
break
}
if (branches?.onFailure?.name === step.name) {
parentName = parent.name
relationship = 'on_failure_branch'
break
}
}
}
return {
name: step.name,
type: step.type,
displayName: step.displayName,
parentName,
relationship,
...(relationship === 'branch' && { branchIndex, branchName }),
valid: step.valid,
skip: skippedStepNames.has(step.name),
configStatus: getConfigStatus({ step, skippedStepNames }),
}
})
return { structure, stepByName }
}
function formatFlowStructure(
flowDisplayName: string,
flowId: string,
structure: StepInfo[],
stepByName: Map<string, Step>,
positions: Map<string, { x: number, y: number }>,
notes: Note[],
): string {
const lines: string[] = []
lines.push(`# Flow: ${flowDisplayName} (id: ${flowId})`)
lines.push('')
lines.push('## Steps (DFS order: trigger first, then each step with parent and relationship)')
lines.push('Format: name | type | displayName | parent | relationship | configStatus | canvas')
lines.push('')
for (const step of structure) {
const skipLabel = step.skip ? ' [SKIPPED]' : ''
const pos = positions.get(step.name)
const canvasLabel = pos ? ` | canvas: (${Math.round(pos.x)}, ${Math.round(pos.y)})` : ''
const fullStep = stepByName.get(step.name)
const sampleLabel = fullStep && hasSampleData(fullStep) ? ' | has sample data' : ''
if (step.relationship === 'trigger') {
let triggerDetail = ''
if (fullStep && fullStep.type === FlowTriggerType.PIECE) {
triggerDetail = ` (piece: ${fullStep.settings.pieceName}, trigger: ${fullStep.settings.triggerName ?? 'not set'})`
}
lines.push(`- [TRIGGER] ${step.name} | ${step.type} | "${step.displayName}"${triggerDetail} | parent: — | ${step.configStatus}${sampleLabel}${skipLabel}${canvasLabel}`)
if (fullStep) {
lines.push(...formatStepSettings(fullStep))
}
continue
}
const rel = formatRelationshipLabel(step)
let stepDetail = ''
if (step.type === FlowActionType.PIECE) {
const s = fullStep?.settings as { pieceName?: string, actionName?: string } | undefined
if (s?.pieceName) stepDetail = ` (piece: ${s.pieceName}, action: ${s.actionName ?? 'not set'})`
}
lines.push(`- ${step.name} | ${step.type} | "${step.displayName}"${stepDetail} | parent: ${step.parentName} | ${rel} | ${step.configStatus}${sampleLabel}${skipLabel}${canvasLabel}`)
if (fullStep) {
lines.push(...formatStepSettings(fullStep))
}
if (step.type === FlowActionType.ROUTER && fullStep) {
const branches = (fullStep.settings as { branches?: { branchName?: string, branchType?: string, conditions?: BranchCondition[][] }[] })?.branches ?? []
branches.forEach((b, i) => {
const btype = b.branchType === BranchExecutionType.FALLBACK ? 'fallback' : 'condition'
if (btype === 'condition' && b.conditions && b.conditions.length > 0) {
const condStr = formatBranchConditions(b.conditions)
lines.push(` branch[${i}]: "${b.branchName ?? ''}" (${btype}) | conditions: ${condStr}`)
}
else {
lines.push(` branch[${i}]: "${b.branchName ?? ''}" (${btype})`)
}
})
}
if (fullStep?.type === FlowActionType.AI_ROUTER) {
lines.push(` question: "${fullStep.settings.question}"`)
fullStep.settings.branches.forEach((b, i) => {
const btype = b.branchType === BranchExecutionType.FALLBACK ? 'fallback' : 'route'
const when = isNil(b.description) || b.description.length === 0 ? '' : ` | when: ${b.description}`
lines.push(` branch[${i}]: "${b.branchName}" (${btype})${when}`)
})
}
}
lines.push('')
lines.push('## Valid insert locations for ap_add_step')
lines.push('Use parentStepName + stepLocationRelativeToParent (and branchIndex when INSIDE_BRANCH).')
lines.push('')
const triggerStep = structure[0]
if (triggerStep) {
lines.push(`- After trigger: parentStepName="${triggerStep.name}", stepLocationRelativeToParent="${StepLocationRelativeToParent.AFTER}"`)
}
for (const step of structure) {
if (step.relationship === 'trigger') continue
lines.push(`- After "${step.name}": parentStepName="${step.name}", stepLocationRelativeToParent="${StepLocationRelativeToParent.AFTER}"`)
if (step.type === FlowActionType.LOOP_ON_ITEMS) {
lines.push(` Inside loop of "${step.name}": parentStepName="${step.name}", stepLocationRelativeToParent="${StepLocationRelativeToParent.INSIDE_LOOP}"`)
}
const branchedStep = stepByName.get(step.name)
if (!isNil(branchedStep) && flowStructureUtil.isBranchedAction(branchedStep)) {
branchedStep.settings.branches.forEach((b, i) => {
lines.push(` Branch ${i} of "${step.name}"${b.branchName ? ` ("${b.branchName}")` : ''}: parentStepName="${step.name}", stepLocationRelativeToParent="${StepLocationRelativeToParent.INSIDE_BRANCH}", branchIndex=${i}`)
})
}
if (step.type === FlowActionType.CODE || step.type === FlowActionType.PIECE) {
const fullStep = stepByName.get(step.name)
const isFullStepCodeOrPiece = fullStep?.type === FlowActionType.CODE || fullStep?.type === FlowActionType.PIECE
const cofEnabled = isFullStepCodeOrPiece && fullStep?.settings.errorHandlingOptions?.continueOnFailure?.value
if (cofEnabled) {
lines.push(` On success branch of "${step.name}": parentStepName="${step.name}", stepLocationRelativeToParent="${StepLocationRelativeToParent.INSIDE_ON_SUCCESS_BRANCH}"`)
lines.push(` On failure branch of "${step.name}": parentStepName="${step.name}", stepLocationRelativeToParent="${StepLocationRelativeToParent.INSIDE_ON_FAILURE_BRANCH}"`)
}
}
}
lines.push('')
lines.push('Step types: trigger = EMPTY | PIECE_TRIGGER; action = CODE | PIECE | LOOP_ON_ITEMS | ROUTER')
lines.push('')
lines.push('## Referencing step outputs')
lines.push(mcpUtils.STEP_REFERENCE_HINT)
lines.push('Use ap_test_step or ap_test_flow to generate sample data and see available output fields.')
lines.push('')
lines.push('## Canvas Notes')
if (notes.length === 0) {
lines.push('No canvas notes.')
}
else {
for (const note of notes) {
const content = note.content.replace(/<[^>]*>/g, '').slice(0, 80)
lines.push(`- id: ${note.id} | "${content}" | color: ${note.color} | pos: (${Math.round(note.position.x)}, ${Math.round(note.position.y)}) | size: ${note.size.width}×${note.size.height}`)
}
}
return lines.join('\n')
}
export const apFlowStructureTool = (mcp: ProjectScopedMcpServer, log: FastifyBaseLogger): McpToolDefinition => {
return {
title: 'ap_flow_structure',
permission: Permission.READ_FLOW,
description: 'Get the structure of a flow: step tree (parent/child), each step type, configuration status (configured/unconfigured/invalid), and valid insert locations for ap_add_step.',
inputSchema: {
flowId: z.string().describe('The id of the flow'),
},
annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
execute: async ({ flowId }) => {
try {
const flow = await flowService(log).getOnePopulated({
id: String(flowId),
projectId: mcp.projectId,
})
if (isNil(flow)) {
return { content: [{ type: 'text', text: '❌ Flow not found' }] }
}
const { structure, stepByName } = buildFlowStructure(flow.version.trigger)
const positions = flowCanvasUtils.computeStepPositions(flow.version.trigger)
const text = formatFlowStructure(flow.version.displayName, flow.id, structure, stepByName, positions, flow.version.notes ?? [])
return {
content: [{ type: 'text', text }],
structuredContent: {
flowId: flow.id,
displayName: flow.version.displayName,
steps: structure.map(s => ({
name: s.name,
type: s.type,
displayName: s.displayName,
parentName: s.parentName,
relationship: s.relationship,
...(s.branchIndex !== undefined ? { branchIndex: s.branchIndex } : {}),
...(s.branchName !== undefined ? { branchName: s.branchName } : {}),
valid: s.valid,
configStatus: s.configStatus,
})),
stepCount: structure.length,
},
}
}
catch (err) {
return mcpUtils.mcpToolError('Failed to get flow structure', err)
}
},
}
}