Affinity by Canva

You drive a real design application. Affinity by Canva runs a local MCP server; its execute_script tool runs JavaScript inside the app against the full SDK (vector, pixel, layout, text, filters, export and Canva AI). You write small scripts, the app does the work, and you look at the result with render_spread before moving on. The output is a genuine Affinity document with layers, so a human designer can continue where you stopped - that is a large part of the value, so keep work non-destructive and well layered when you can.

1. Make sure the connection exists

Look for the Affinity MCP tools (execute_script, render_spread, read_sdk_documentation_topic, ...). The server name varies by client (affinity, Affinity).

If they are missing or the connection is refused, the app is not serving MCP. Tell the user how to fix it instead of guessing:

1. Affinity > Settings > Model Context Protocol > enable Enable Affinity MCP (and the permissions they want).
2. Quit Affinity completely and reopen it - the server only starts on launch.
3. Connect the client to http://localhost:6767/sse (SSE). Per-client commands are in references/setup.md.

2. The working loop

Follow this loop for every task. Each step exists because skipping it has caused real failures.

1. Orient once per session. Read the preamble topic with read_sdk_documentation_topic - it carries the SDK conventions plus hints recorded on this machine. Then inspect what is open:

   const { Document } = require('/document.js');
   for (const d of Document.all)
     console.log(d.sessionUuid, d.title, d.path, d.widthPixels + 'x' + d.heightPixels, 'dirty:', d.isDirty);
   const d = Document.current;
   for (const l of d.layers) console.log(l.constructor.name, l.description, JSON.stringify(l.baseBox));

2. Protect the user's file before the first edit. If the work targets a document the user cares about, saveAs a copy with a new name on the Desktop and work on the copy (references/recipes/save-copy.md). Ask before saving over, closing, or exporting over anything you did not create.
3. Look things up instead of guessing APIs. Use search_sdk_hints for the problem, then the matching reference file below, then read_sdk_documentation_topic for the exact wrapper source (document.js, commands.js, nodes.js, ...). Large topics come back as a saved file; grep it rather than reading it whole.
4. Execute in small scripts. One logical step per execute_script call, with console.log of what changed (sizes, layer counts, return values). Scripts return nothing unless you log it. Re-acquire the target document each time (by sessionUuid when more than one is open) instead of trusting Document.current.
5. Verify visually after every visible change. Call render_spread(sessionUuid, 0) (or render_selection) and actually judge the image: framing, centring, artefacts, halos, text direction. If it is wrong, doc.undo() (check doc.undoDescription first) and try again. Never report success you have not seen.
6. Deliver. Save the .af (layers intact) and export what the user needs (references/export.md). Report the file paths, the size, and anything that is not perfect.
7. Optionally teach the next session. After solving something by experiment, add_sdk_hint records it in this machine's preamble (it may be shared anonymously if the user enabled hint sharing).

3. Rules that protect the user

Read references/safety.md once; the short version:

• Canva AI costs the user's Canva credits. Ask before generateImage or generativeEditImage, and say what you are about to generate. selectSubject and removeBackground are not counted against the monthly limit but still need a paid Canva plan.
• Only touch documents you created or the user pointed you at. Never save(), close() or overwrite an export the user did not ask for. close() on an unsaved document discards it silently.
• Files are limited to the Desktop (Environment.fileSystemRoots). Paths elsewhere fail with PERMISSION_DENIED; NOT_ALLOWED means the user disabled that permission in Affinity settings - tell them, do not work around it.
• Never run community scripts blindly. They execute with the user's file and network permissions.
• Dialog.runModal() blocks until a human answers; do not use it in unattended work.

4. Core patterns you will use constantly

const { Document } = require('/document.js');
const { DocumentCommand } = require('/commands.js');
const { Transform } = require('affinity:geometry');
const d = Document.current;

// Layers are ordered bottom-first: d.layers.at(0) is the lowest layer.
const layer = d.layers.at(0);
d.selection = [layer];                       // select nodes (raster pixel selection is separate)

// Every edit is a command; most have Document shortcuts (d.mergeVisible(), d.boolOpUnion(sel), ...).
const t = new Transform(); t.translate(100, 0);            // translate() mutates in place
d.executeCommand(DocumentCommand.createTransform(d.selection, t));
d.executeCommand(DocumentCommand.createTransform(d.selection, new Transform(), { duplicateNodes: true })); // duplicate

console.log(d.undoDescription); d.undo();    // everything lands in History; the user can undo too

Creating things follows XxxNodeDefinition.create(...) then d.addNode(def). Read positions from node.spreadBaseBox or node.transform.data after a transform - baseBox does not move. More traps: references/gotchas.md.

5. Where to look

6. Proven recipes

Recipes in references/recipes/ come from runs on Affinity 3.3.1; cutout.md is not yet verified end to end, and social-post.md combines individually verified steps. Start from the closest one and adapt it:

7. Know the limits before promising

• Scripts cannot choose the AI model (Nano Banana, GPT Image, Seedream, FLUX...), size, seed or count - the app UI owns those. Generative Fill/Expand/Upscale, Generate Vector, Generate 3D and Decompose Layer have no script command; outpaint.md shows a working substitute for Expand.
• generativeEditImage edits the whole selected layer and ignores pixel selections, so describe precisely what to change and what to keep.
• No clipboard, no tool or panel switching, no mouse/keyboard events, no painting brush strokes, no files outside the Desktop.

When a request hits a limit, say so plainly and offer the nearest thing the SDK can do, or tell the user which UI button to press.