@axonity-ai/mcp 0.1.0 → 0.3.2

package/dist/tools/workflowMutations.js

@@ -5,41 +5,136 @@
  * backend-authoritative model the Studio uses), never by replacing the whole
  * document. The backend applies and validates the commands and returns the new
  * authoritative document + version.
+ *
+ * The backend route applies exactly ONE mutation per call — `POST
+ * /workflows/{id}/mutations` takes `{ type, payload, expectedVersion }` and there
+ * is no batch route. This tool keeps a batch-shaped signature (an agent thinks in
+ * whole edits, not round-trips) and sequences the calls itself, threading the
+ * version returned by call N into call N+1.
+ *
+ * Because the sequence is not a transaction, a failure at index k leaves the
+ * mutations before it applied. The error says how many landed and which one
+ * failed so the caller can re-read and resume rather than blindly retry — a
+ * retry from the top would re-apply the successful prefix.
  */
 import { z } from "zod";
 import { AxonityApiError } from "../errors.js";
+import { guard, jsonResult } from "./result.js";
+/** A required literal — an agent cannot satisfy it by filling in a default. */
+const CONFIRM = z
+    .literal(true)
+    .describe("Must be true. Acknowledges you understand this is destructive.");
+/**
+ * Split one command into the `{ type, payload }` pair the backend expects.
+ *
+ * Accepts both the explicit form (`{ type, payload: {...} }`) and the flat form
+ * (`{ type, ...args }`), because an agent writing these by hand produces either
+ * and the difference is not meaningful to it.
+ */
+export function toMutationBody(mutation, index) {
+    const { type, payload, ...rest } = mutation;
+    if (typeof type !== "string" || type.length === 0) {
+        throw new Error(`mutations[${index}] is missing a \`type\` (e.g. "add_step", "add_edge").`);
+    }
+    if (payload !== undefined) {
+        if (typeof payload !== "object" || payload === null || Array.isArray(payload)) {
+            throw new Error(`mutations[${index}].payload must be a JSON object.`);
+        }
+        return { type, payload: payload };
+    }
+    return { type, payload: rest };
+}
+/** Compose the error for a mutation that failed part-way through a sequence. */
+function sequenceError(index, total, type, version, cause) {
+    const reason = cause instanceof AxonityApiError || cause instanceof Error
+        ? cause.message
+        : String(cause);
+    const applied = index;
+    const summary = JSON.stringify({ appliedCount: applied, failedIndex: index, failedType: type, currentVersion: version }, null, 2);
+    return new Error(`Mutation ${index + 1} of ${total} (\`${type}\`) failed: ${reason}\n\n` +
+        `${applied} of ${total} mutations were already applied and were NOT rolled back — ` +
+        `this sequence is not a transaction. Do not retry the whole list: re-read the ` +
+        `workflow, confirm which edits landed, and resume from index ${index}.\n\n` +
+        summary);
+}
 export function registerWorkflowMutations(server, client) {
     server.tool("apply_workflow_mutations", "Apply structural mutation commands to a workflow draft (add/remove steps, " +
         "connect edges, set conditions). Read the workflow first for its version. " +
-        "Returns the new authoritative document + version. On a 409 conflict, " +
-        "re-read and retry.", {
+        "Commands are applied IN ORDER, one backend call each, with the version " +
+        "threaded automatically — pass the version you read, not one per command. " +
+        "Returns the new authoritative document, version, and validation state. " +
+        "Not transactional: if command N fails, commands before it stay applied and " +
+        "the error reports how many landed. On a 409 conflict, re-read and retry. " +
+        'Each command is `{ "type": "add_step", "payload": { … } }`; the flat form ' +
+        '`{ "type": "add_step", … }` is accepted too. Valid types: update_workflow, ' +
+        "add_trigger, update_trigger, remove_trigger, update_trigger_operator, " +
+        "group_triggers, ungroup_triggers, move_trigger, add_step, add_loop, " +
+        "update_step, remove_step, move_step, add_edge, update_edge, remove_edge, " +
+        "convert_to_loop, setup_loop_decision, advanced_edit.", {
         id: z.string().describe("The workflow's id."),
         expectedVersion: z
             .number()
             .int()
-            .describe("The version you last read — rejected with 409 if stale."),
+            .describe("The version you last read. Only the FIRST command uses it; later " +
+            "commands use the version returned by the previous one."),
         mutations: z
             .array(z.record(z.unknown()))
-            .describe("A list of mutation commands, each a JSON object with a command name " +
-            "and its arguments (camelCase)."),
-    }, async ({ id, expectedVersion, mutations }) => {
-        try {
-            const data = await client.post(`/api/v1/workflows/${id}/mutations`, {
-                expectedVersion,
-                mutations,
-            });
-            return {
-                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
-            };
-        }
-        catch (err) {
-            const message = err instanceof AxonityApiError
-                ? err.message
-                : err instanceof Error
-                    ? err.message
-                    : String(err);
-            return { content: [{ type: "text", text: message }], isError: true };
+            .min(1)
+            .describe("Mutation commands to apply in order, each a JSON object with a " +
+            "`type` and its arguments (camelCase), either nested under " +
+            "`payload` or inline."),
+    }, async ({ id, expectedVersion, mutations }) => guard(async () => {
+        // Reject the whole batch on a malformed command before applying any of
+        // it — a shape error is the agent's mistake, not a partial failure.
+        const bodies = mutations.map((m, i) => toMutationBody(m, i));
+        let version = expectedVersion;
+        let last;
+        for (const [index, body] of bodies.entries()) {
+            try {
+                last = await client.post(`/api/v1/workflows/${id}/mutations`, { type: body.type, payload: body.payload, expectedVersion: version });
+            }
+            catch (cause) {
+                throw sequenceError(index, bodies.length, body.type, version, cause);
+            }
+            version = last.version;
         }
-    });
+        return jsonResult({ ...last, appliedCount: bodies.length });
+    }));
+    server.tool("replace_workflow_document", "Replace the ENTIRE workflow document in one atomic call. Read the workflow first to " +
+        "get the current version, then call this again only after rereading on a stale " +
+        "`409`.\n" +
+        "Unlike `apply_workflow_mutations`, this is a single PUT request and treats the " +
+        "payload as the complete editable document.", {
+        id: z.string().describe("The workflow's id."),
+        expectedVersion: z
+            .number()
+            .int()
+            .describe("The version you read before replacing the document."),
+        document: z
+            .record(z.unknown())
+            .describe("The complete workflow document object to persist."),
+    }, async ({ id, expectedVersion, document }) => guard(async () => jsonResult(await client.put(`/api/v1/workflows/${id}`, {
+        expectedVersion,
+        document,
+    }))));
+    server.tool("read_workflow_trigger_parameters", "Read the input parameters a workflow's triggers expect — what a caller must " +
+        "supply to start it. Use this before authoring a webhook/cron/conditional " +
+        "trigger, or before start_workflow_run, so the trigger input matches. Read-only.", { workflowId: z.string().describe("The workflow's id.") }, async ({ workflowId }) => guard(async () => jsonResult(await client.get(`/api/v1/workflows/${workflowId}/trigger-parameters`))));
+    server.tool("bulk_delete_workflows", "Soft-delete several workflows at once (each recoverable with " +
+        "restore_workflow, like single delete_workflow). Each target needs its own " +
+        "current version for optimistic locking — read each first. Returns a " +
+        "per-workflow success/error result; a partial failure is possible.", {
+        workflows: z
+            .array(z.object({
+            id: z.string().describe("The workflow's id."),
+            expectedVersion: z
+                .number()
+                .int()
+                .describe("That workflow's last-read version — 409 if stale."),
+        }))
+            .min(1)
+            .describe("The workflows to delete, each with its expectedVersion."),
+        confirm: CONFIRM,
+    }, async ({ workflows }) => guard(async () => jsonResult(await client.post("/api/v1/workflows/bulk-delete", { workflows }))));
 }
 //# sourceMappingURL=workflowMutations.js.map

package/dist/tools/workflowMutations.js.map

@@ -1 +1 @@
-{"version":3,"file":"workflowMutations.js","sourceRoot":"","sources":["../../src/tools/workflowMutations.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C,MAAM,UAAU,yBAAyB,CACvC,MAAiB,EACjB,MAAqB;IAErB,MAAM,CAAC,IAAI,CACT,0BAA0B,EAC1B,4EAA4E;QAC1E,2EAA2E;QAC3E,uEAAuE;QACvE,oBAAoB,EACtB;QACE,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,oBAAoB,CAAC;QAC7C,eAAe,EAAE,CAAC;aACf,MAAM,EAAE;aACR,GAAG,EAAE;aACL,QAAQ,CAAC,yDAAyD,CAAC;QACtE,SAAS,EAAE,CAAC;aACT,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;aAC5B,QAAQ,CACP,sEAAsE;YACpE,gCAAgC,CACnC;KACJ,EACD,KAAK,EAAE,EAAE,EAAE,EAAE,eAAe,EAAE,SAAS,EAAE,EAAE,EAAE;QAC3C,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,qBAAqB,EAAE,YAAY,EAAE;gBAClE,eAAe;gBACf,SAAS;aACV,CAAC,CAAC;YACH,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;aAC1E,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,OAAO,GACX,GAAG,YAAY,eAAe;gBAC5B,CAAC,CAAC,GAAG,CAAC,OAAO;gBACb,CAAC,CAAC,GAAG,YAAY,KAAK;oBACpB,CAAC,CAAC,GAAG,CAAC,OAAO;oBACb,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACpB,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QAChF,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"workflowMutations.js","sourceRoot":"","sources":["../../src/tools/workflowMutations.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axonity-ai/mcp",
-  "version": "0.1.0",
+  "version": "0.3.2",
   "description": "Model Context Protocol server for Axonity Flow — lets an external agent (e.g. Claude Code) read, draft, and update workflows, agents and tools in an Axonity tenant.",
   "license": "MIT",
   "repository": {
@@ -47,6 +47,6 @@
     "@types/node": "^20.14.0",
     "tsx": "^4.16.0",
     "typescript": "^5.5.0",
-    "vitest": "^2.0.0"
+    "vitest": "^4.1.10"
   }
 }