balise-affinity-mcp

Affinity MCP Automation

Use the Affinity MCP as a live application-control surface. Work from the open document, inspect before editing, prefer small reversible commands, and verify visual results.

Standard Workflow

1. Load Affinity tools if they are not already present.
2. Read SDK documentation in this order:
   • Always read preamble first.
   • Call list_sdk_documentation.
   • Read only the topics needed for the task, such as application.js, document.js, nodes.js, commands.js, geometry.js, colours.js, fills.js, linestyle.js, storybuilder.js, glyphatts.js, paragraphatts.js, or exportconfig.js.
3. Inspect the current document before making changes.
4. Choose the narrowest edit: selected object first, current spread next, whole document only when requested.
5. Execute scripts with the Affinity MCP execute_script capability; a harness may expose a qualified tool name. Use console.log(JSON.stringify(...)) for observable output.
6. Verify with render_selection(document_session_uuid) whenever the result is visual.
7. Do not save, export, flatten, delete broad selections, or resize the spread unless the user asked for that kind of change.

Document Inspection

Use this baseline probe before editing:

const {Document} = require('/document');
const doc = Document.current;
if (!doc) {
  console.log(JSON.stringify({ok: false, reason: 'NO_CURRENT_DOCUMENT'}));
} else {
  console.log(JSON.stringify({
    ok: true,
    title: doc.title,
    path: doc.path,
    sessionUuid: doc.sessionUuid,
    isReadOnly: doc.isReadOnly,
    isDirty: doc.isDirty,
    needsSaving: doc.needsSaving,
    pageCount: doc.pageCount,
    spreadCount: doc.spreadCount,
    selectedCount: doc.selection.nodes.length,
    currentSpreadBox: doc.currentSpread.baseBox
  }, null, 2));
}

Stop cleanly if Document.current is null or doc.isReadOnly is true.

Object Operations

Use node operations for visible document objects:

• doc.selection returns the current selection.
• doc.selection.nodes gives selected nodes.
• node.userDescription = '...' is useful for naming automation-created objects.
• doc.selectAll(false) selects all document objects; use it deliberately because it changes selection.
• doc.deleteSelection(selection) deletes selected objects; only use when the user wants replacement or cleanup.
• doc.setVisible(visible, selection), doc.lockSelection(selection), and doc.unlockSelection(selection) operate through document commands.
• For new nodes, doc.addNode(def, doc.currentSpread) adds to the current spread and selects the new object.