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 { ExactVersionType, FlowActionType, FlowOperationRequest, FlowOperationType, flowPieceUtil, flowStructureUtil, McpToolContext, McpToolDefinition, PieceActionSettings, UpdateActionRequest } from '@activepieces/shared'
import { FastifyBaseLogger } from 'fastify'
import { z } from 'zod'
import { flowService } from '../../flows/flow/flow.service'
import { pieceMetadataService } from '../../pieces/metadata/piece-metadata-service'
import { projectService } from '../../project/project-service'
import { mcpUtils } from './mcp-utils'
const updateStepInput = z.object({
flowId: z.string(),
stepName: z.string(),
displayName: z.string().optional(),
input: z.record(z.string(), z.unknown()).optional(),
auth: z.string().optional(),
actionName: z.string().optional(),
pieceVersion: z.union([z.literal('latest'), ExactVersionType]).optional(),
loopItems: z.string().optional(),
skip: z.boolean().optional(),
sourceCode: z.string().optional(),
packageJson: z.string().optional(),
continueOnFailure: z.boolean().optional(),
retryOnFailure: z.boolean().optional(),
})
export const apUpdateStepTool = ({ mcp, userId }: McpToolContext, log: FastifyBaseLogger): McpToolDefinition => {
return {
title: 'ap_update_step',
permission: Permission.WRITE_FLOW,
description: 'Update an existing step\'s settings. Provide only the fields you want to change.',
inputSchema: {
flowId: z.string().describe('The id of the flow'),
stepName: z.string().describe('The name of the step to update (e.g. "step_1"). Use ap_flow_structure to get valid values.'),
displayName: z.string().optional().describe('New display name for the step'),
input: z.record(z.string(), z.unknown()).optional().describe(`Input settings for the step (key-value pairs matching the action schema). ${mcpUtils.STEP_REFERENCE_HINT}`),
auth: z.string().optional().describe('Connection `externalId` from `ap_list_connections`. Pass the plain id, not a template.'),
actionName: z.string().optional().describe('For PIECE steps: the action to perform. Use ap_research_pieces to get valid values.'),
pieceVersion: z.union([z.literal('latest'), ExactVersionType]).optional().describe('For PIECE steps: move the step to another version of its piece. Pass "latest" or an exact version like "1.2.3". Inputs the new version no longer has are dropped, so pass the adjusted input in the same call.'),
loopItems: z.string().optional().describe('For LOOP steps: expression for the items to iterate over'),
skip: z.boolean().optional().describe('Whether to skip this step during execution'),
sourceCode: z.string().optional().describe('For CODE steps only: the JavaScript/TypeScript source code. Must export a `code` function: `export const code = async (inputs) => { ... }`.'),
packageJson: z.string().optional().describe('For CODE steps only: package.json content as a JSON string for npm dependencies. Defaults to "{}".'),
continueOnFailure: z.boolean().optional().describe('For CODE/PIECE steps: set true on the step that can fail (the one whose failure you want to react to), NOT on the recovery step. The flow keeps running on failure and the step gains On success / On failure branches — add handler steps into them with ap_add_step using stepLocationRelativeToParent INSIDE_ON_SUCCESS_BRANCH / INSIDE_ON_FAILURE_BRANCH and parentStepName = this step.'),
retryOnFailure: z.boolean().optional().describe('For CODE/PIECE steps: whether to retry this step on failure.'),
},
annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
execute: async (args) => {
const { flowId, stepName, displayName, input, auth: rawAuth, actionName, pieceVersion: requestedPieceVersion, loopItems, skip, sourceCode, packageJson, continueOnFailure, retryOnFailure } = updateStepInput.parse(args)
const auth = mcpUtils.normalizeAuth(rawAuth)
const [flow, project] = await Promise.all([
flowService(log).getOnePopulated({ id: flowId, projectId: mcp.projectId }),
projectService(log).getOneOrThrow(mcp.projectId),
])
if (isNil(flow)) {
return { content: [{ type: 'text', text: '❌ Flow not found' }] }
}
const step = flowStructureUtil.getStep(stepName, flow.version.trigger)
if (isNil(step)) {
const allSteps = flowStructureUtil.getAllSteps(flow.version.trigger).map(s => s.name).join(', ')
return {
content: [{ type: 'text', text: `❌ Step "${stepName}" not found. Available steps: ${allSteps}` }],
}
}
if (flowStructureUtil.isTrigger(step.type)) {
return {
content: [{ type: 'text', text: `❌ "${stepName}" is a trigger step. Use ap_update_trigger to configure triggers.` }],
}
}
const authError = mcpUtils.validateAuth(auth)
if (authError) {
return authError
}
const rewritten = mcpUtils.rewriteAllReferences({ input, loopItems, trigger: flow.version.trigger })
const currentSettings = step.settings as Record<string, unknown>
const updatedSettings: Record<string, unknown> = { ...currentSettings }
if (rewritten.input !== undefined || auth !== undefined) {
updatedSettings.input = {
...(currentSettings.input as Record<string, unknown> ?? {}),
...(rewritten.input ?? {}),
...(auth !== undefined && { auth: `{{connections['${auth}']}}` }),
}
}
if (actionName !== undefined) {
if (step.type === FlowActionType.PIECE) {
updatedSettings.actionName = actionName
}
else {
return { content: [{ type: 'text', text: `❌ actionName can only be set on PIECE steps, but "${stepName}" is type ${step.type}.` }] }
}
}
if (requestedPieceVersion !== undefined) {
if (step.type !== FlowActionType.PIECE) {
return { content: [{ type: 'text', text: `❌ pieceVersion can only be set on PIECE steps, but "${stepName}" is type ${step.type}.` }], isError: true }
}
if (requestedPieceVersion === 'latest') {
const versionResult = await mcpUtils.resolveLatestPieceVersion({ pieceName: step.settings.pieceName, projectId: mcp.projectId, platformId: project.platformId, log })
if (versionResult.error) {
return versionResult.error
}
updatedSettings.pieceVersion = flowPieceUtil.getExactVersion(versionResult.pieceVersion)
}
else {
const piece = await pieceMetadataService(log).get({ name: step.settings.pieceName, version: requestedPieceVersion, projectId: mcp.projectId, platformId: project.platformId })
if (isNil(piece) || piece.version !== requestedPieceVersion) {
return { content: [{ type: 'text', text: `❌ Version "${requestedPieceVersion}" of piece "${step.settings.pieceName}" not found. Pass "latest" or an exact published version like "1.2.3".` }], isError: true }
}
updatedSettings.pieceVersion = requestedPieceVersion
}
}
const pieceVersionChanged = updatedSettings.pieceVersion !== currentSettings.pieceVersion
if (rewritten.loopItems !== undefined) {
if (step.type === FlowActionType.LOOP_ON_ITEMS) {
updatedSettings.items = rewritten.loopItems
}
else {
return { content: [{ type: 'text', text: `❌ loopItems can only be set on LOOP_ON_ITEMS steps, but "${stepName}" is type ${step.type}.` }] }
}
}
if (sourceCode !== undefined || packageJson !== undefined) {
if (step.type !== FlowActionType.CODE) {
const param = sourceCode !== undefined ? 'sourceCode' : 'packageJson'
return { content: [{ type: 'text', text: `❌ ${param} can only be set on CODE steps, but "${stepName}" is type ${step.type}.` }] }
}
const existing = currentSettings.sourceCode
const isObj = typeof existing === 'object' && existing !== null
const existingCode = isObj && 'code' in existing ? String(existing.code) : ''
const existingPkg = isObj && 'packageJson' in existing ? String(existing.packageJson) : '{}'
updatedSettings.sourceCode = {
code: sourceCode ?? existingCode,
packageJson: packageJson ?? existingPkg,
}
}
if (continueOnFailure !== undefined || retryOnFailure !== undefined) {
if (step.type !== FlowActionType.CODE && step.type !== FlowActionType.PIECE) {
return { content: [{ type: 'text', text: `❌ continueOnFailure/retryOnFailure can only be set on CODE or PIECE steps, but "${stepName}" is type ${step.type}.` }] }
}
const currentErrorHandling = (currentSettings.errorHandlingOptions as { continueOnFailure?: { value?: boolean }, retryOnFailure?: { value?: boolean } }) ?? {}
updatedSettings.errorHandlingOptions = mcpUtils.buildErrorHandlingOptions({
continueOnFailure: continueOnFailure ?? currentErrorHandling.continueOnFailure?.value,
retryOnFailure: retryOnFailure ?? currentErrorHandling.retryOnFailure?.value,
})
}
if (step.type === FlowActionType.PIECE && (input !== undefined || pieceVersionChanged)) {
await mcpUtils.fillDefaultsForMissingOptionalProps({
settings: updatedSettings,
platformId: project.platformId,
log,
})
const { pieceName, pieceVersion, actionName: resolvedActionName } = updatedSettings
if (typeof pieceName === 'string' && typeof pieceVersion === 'string' && typeof resolvedActionName === 'string') {
const callerInput = {
...(rewritten.input ?? {}),
...(auth !== undefined && { auth: `{{connections['${auth}']}}` }),
}
const { input: knownInput, error: unknownPropsError } = await mcpUtils.keepKnownInputProps({ pieceName, pieceVersion, componentName: resolvedActionName, componentType: 'action', input: updatedSettings.input, callerInput, platformId: project.platformId, log })
if (unknownPropsError) {
return unknownPropsError
}
updatedSettings.input = knownInput
const changedKeys = Object.keys(pieceVersionChanged ? knownInput : callerInput)
updatedSettings.propertySettings = await mcpUtils.resolveDynamicPropertySettings({ pieceName, pieceVersion, componentName: resolvedActionName, componentType: 'action', input: knownInput, propertySettings: currentSettings.propertySettings, changedKeys, projectId: mcp.projectId, platformId: project.platformId, log })
}
}
const payload = {
type: step.type,
name: step.name,
displayName: displayName ?? step.displayName,
valid: step.valid,
settings: updatedSettings,
...(skip !== undefined && { skip }),
}
const parseResult = UpdateActionRequest.safeParse(payload)
if (!parseResult.success) {
const message = parseResult.error.issues.map(e => `${e.path.join('.')}: ${e.message}`).join('; ')
return {
content: [{ type: 'text', text: `❌ Invalid step update: ${message}` }],
}
}
const operation: FlowOperationRequest = {
type: FlowOperationType.UPDATE_ACTION,
request: parseResult.data,
}
try {
const updatedFlow = await flowService(log).update({
id: flow.id,
projectId: mcp.projectId,
userId,
previousFlow: flow,
platformId: project.platformId,
operation,
})
const updatedStep = flowStructureUtil.getStep(stepName, updatedFlow.version.trigger)
const draftWarning = mcpUtils.publishedFlowWarning(flow.publishedVersionId)
if (updatedStep && !updatedStep.valid) {
const diagnosis = updatedStep.type === FlowActionType.PIECE
? await diagnoseMissingInputs({ settings: updatedStep.settings, platformId: project.platformId, log })
: null
const hint = (diagnosis || null)
?? (step.type === FlowActionType.PIECE
? 'Use ap_research_pieces to verify pieceName, pieceVersion, actionName and required inputs, then retry.'
: 'Check the step settings and retry.')
return {
content: [{
type: 'text',
text: `⚠️ Step "${stepName}" updated but still invalid. ${hint}${draftWarning}`,
}],
}
}
return {
content: [{ type: 'text', text: `✅ Successfully updated step "${stepName}".${draftWarning}` }],
}
}
catch (err) {
return mcpUtils.mcpToolError('Step update failed', err)
}
},
}
}
async function diagnoseMissingInputs({ settings, platformId, log }: {
settings: PieceActionSettings
platformId: string
log: FastifyBaseLogger
}): Promise<string | null> {
const { pieceName, pieceVersion, actionName } = settings
if (isNil(actionName)) {
return 'Missing actionName.'
}
try {
const piece = await pieceMetadataService(log).getOrThrow({ platformId, name: pieceName, version: pieceVersion })
const action = piece.actions[actionName]
if (isNil(action)) {
return `Action "${actionName}" not found in piece "${pieceName}". Use ap_research_pieces with includeActions=true to get valid action names.`
}
const input = settings.input ?? {}
const { parts } = mcpUtils.diagnosePieceProps({ props: action.props, input, pieceAuth: piece.auth, requireAuth: action.requireAuth, componentType: 'action' })
return parts.join(' ')
}
catch (err) {
log.warn({ error: err, piece: { name: pieceName }, actionName }, 'diagnoseMissingInputs: failed to fetch piece metadata')
return null
}
}