[AdamSelene]

Description

Adds an optional pieceVersion parameter to the ap_update_step MCP tool so an AI client can move a PIECE step onto a different version of its piece:

• "latest" — resolves to the newest available version (reuses resolveLatestPieceVersion, the same helper ap_update_trigger already uses to keep triggers on the latest version).
• an exact version like "1.2.3" — validated against the piece registry (friendly error if it doesn't exist) and pinned as ~1.2.3, matching how step versions are stored everywhere else.
• non-PIECE step — rejected with a clear message.

After the version is set, the existing flow-update path re-validates the step against the new action schema and diagnoses missing/unknown inputs, so the LLM can pass an adjusted input in the same call to handle properties that were removed, renamed, or added between versions.

Previously ap_update_step always copied the existing pieceVersion and had no way to upgrade an action step — triggers already auto-bumped, actions did not.

How was this tested?

npx turbo run lint --filter=api — 0 errors. Change is confined to ap_update_step; no new tool registration, disabledTools schema, or web settings wiring needed.

Breaking change? (required — CI fails if this is left unedited)

• no — reviewed, not breaking

Security impact? (required — CI fails if this is left unedited)

• no — reviewed, no security impact

🤖 Generated with Claude Code

[github-actions]

Hey — thanks so much for taking the time to open this! 🙏

We've temporarily paused unsolicited pull requests from outside the core team. This isn't about you or the quality of your change — an open PR is a promise from us to review it carefully, and right now the volume (a lot of it AI-generated) means we can't keep that promise for every PR without it becoming unfair to contributors who wait weeks for a reply. So instead of leaving PRs hanging, we close them and point you to a faster path.

Already working with us? If you're an existing customer and we've already discussed this change over Slack, ping us there and we'll add the keep-open label and reopen this PR for review.

You can still build and publish your own piece — just outside this repo, as your own package rather than a PR here. See CONTRIBUTING.md for the full policy. Thanks again for caring about the project. 💜

[hopper-prod]

Hopper review

Review completed for 6095054.

Open Hopper session

---

This PR touches only packages/server/api/src/app/mcp/tools/ap-update-step.ts and its test file — entirely inside the Activepieces server/MCP core, with no changes under packages/pieces/. There is no piece contribution here at all.

Per the stated scope, this is out of scope for the piece-contribution review this pass is meant for: it's an engine/MCP-tooling change, not a piece, and needs regular engineer review (correctness of resolveLatestPieceVersion reuse, the ~-prefix stripping/pinning logic, error-handling paths, and the new integration test), not the pre-upstream piece checklist (auth definition, action schema, upstream fit for packages/pieces/community/, etc.) this pass checks.

I did not deep-review the MCP tool logic itself, consistent with the scope boundary — flagging it for engineer review instead.

[linear-code]

Q-3192