MCP tools
The authoring MCP server offers these tools to an AI assistant. The assistant picks and calls them itself; you don’t need them to work with it, but they show what it can do. This page is made from the server’s own tool list each time the site is built.
Everything is in points (1 pt = 1/72 inch, 1 mm = 2.8346 pt), from the page’s top left. Every edit answers what it did and the template’s issues as they are now; an edit that would break the template is refused, and nothing changes.
The document
Section titled “The document”new_template
Start a new template: one page of width × height points (A4 is 595.28 × 841.89; 1 mm = 2.8346 pt). Replaces the current document (save it first).
| Parameter | Type | Description |
|---|---|---|
name | string | |
width (required) | number | |
height (required) | number | |
profile | "screen" | "print" | print: CMYK PDF/X with bleed and marks |
bleed | number | points, for print |
background | string | object (cmyk) | object (swatch, tint) | "#rrggbb", { cmyk: [c, m, y, k] } (0-100), or { swatch, tint } |
open
Open a .paprika package from a path.
| Parameter | Type | Description |
|---|---|---|
path (required) | string |
save
Save the template as a .paprika package (to path, or where it was opened from).
| Parameter | Type | Description |
|---|---|---|
path | string |
describe
The template as a compact tree: pages, frames (id, type, box, text, fields, style), components with their parts and instances, fields, sample values, images, and its issues.
No parameters.
get_document
The template’s full JSON (points; see paprika://structure).
No parameters.
list_resources
The fonts (families and weights) and images at hand.
No parameters.
undo
Take back the last edit.
No parameters.
add_page
Add a page (the last page’s size unless given), after a page or at the end.
| Parameter | Type | Description |
|---|---|---|
width | number | |
height | number | |
after | string | number | page id, or number from 1 (the first by default); "component:<id>" adds a part to a component |
bleed | number | |
background | string | object (cmyk) | object (swatch, tint) | "#rrggbb", { cmyk: [c, m, y, k] } (0-100), or { swatch, tint } |
id | string |
update_page
Change a page: width, height, bleed, background (null removes), paper.
| Parameter | Type | Description |
|---|---|---|
page (required) | string | number | |
width | number | |
height | number | |
bleed | number | null | |
background | string | object (cmyk) | object (swatch, tint) | null | "#rrggbb", { cmyk: [c, m, y, k] } (0-100), or { swatch, tint } |
paper | string | null |
remove_page
Remove a page and its frames.
| Parameter | Type | Description |
|---|---|---|
page (required) | string | number |
Frames
Section titled “Frames”add_text
Add a text frame. text: lines become paragraphs, {{field}} inserts a text field’s value. Or paragraphs for mixed styles.
| Parameter | Type | Description |
|---|---|---|
page | string | number | page id, or number from 1 (the first by default); "component:<id>" adds a part to a component |
id | string | |
x (required) | number | left, in points from the page’s left |
y (required) | number | top, in points from the page’s top |
w (required) | number | width in points |
h (required) | number | height in points |
text | string | |
paragraphs | array of object (align, direction, lineSpacing, spaceBefore, spaceAfter, indentStart, indentEnd, indentFirst, list, tabs, paragraphStyle, runs) | paragraphs of runs, for mixed styles; else give text |
style | object (family, size, weight, style, stretch, tracking, color, underline, stroke, characterStyle) | a run’s style |
paragraph | object (align, direction, lineSpacing, spaceBefore, spaceAfter, indentStart, indentEnd, indentFirst, list, tabs, paragraphStyle) | a paragraph’s style |
frame | object | more frame properties: rotation, opacity, fill, stroke, mask, growth, maxH, inset, fitText, … |
set_text
Replace a text frame’s text (keeping its style unless style is given), or with only style/paragraph restyle every run/paragraph.
| Parameter | Type | Description |
|---|---|---|
id (required) | string | |
text | string | |
paragraphs | array of object (align, direction, lineSpacing, spaceBefore, spaceAfter, indentStart, indentEnd, indentFirst, list, tabs, paragraphStyle, runs) | paragraphs of runs, for mixed styles; else give text |
style | object (family, size, weight, style, stretch, tracking, color, underline, stroke, characterStyle) | a run’s style |
paragraph | object (align, direction, lineSpacing, spaceBefore, spaceAfter, indentStart, indentEnd, indentFirst, list, tabs, paragraphStyle) | a paragraph’s style |
place_image
Add an image frame showing an added image (image: its id) or an image field’s value (field).
| Parameter | Type | Description |
|---|---|---|
page | string | number | page id, or number from 1 (the first by default); "component:<id>" adds a part to a component |
id | string | |
x (required) | number | left, in points from the page’s left |
y (required) | number | top, in points from the page’s top |
w (required) | number | width in points |
h (required) | number | height in points |
image | string | |
field | string | |
fit | "fill" | "fit" | |
frame | object | more frame properties: rotation, opacity, fill, stroke, mask, growth, maxH, inset, fitText, … |
add_shape
Add a shape: rect, ellipse, rounded (radius) or path (d: SVG path data in points from the frame’s top left, every point within its w × h; M L H V C S Q T Z, absolute or relative; no arcs), with fill and/or stroke.
| Parameter | Type | Description |
|---|---|---|
page | string | number | page id, or number from 1 (the first by default); "component:<id>" adds a part to a component |
id | string | |
x (required) | number | left, in points from the page’s left |
y (required) | number | top, in points from the page’s top |
w (required) | number | width in points |
h (required) | number | height in points |
shape | "rect" | "ellipse" | "rounded" | "path" | |
radius | number | |
d | string | |
fill | string | object (cmyk) | object (swatch, tint) | "#rrggbb", { cmyk: [c, m, y, k] } (0-100), or { swatch, tint } |
stroke | object (color, width, align, style) | |
frame | object | more frame properties: rotation, opacity, fill, stroke, mask, growth, maxH, inset, fitText, … |
update_frame
Set a frame’s properties (x, y, w, h, rotation, opacity, fill, stroke, mask, growth, fitText, …); null removes one.
| Parameter | Type | Description |
|---|---|---|
id (required) | string | |
set (required) | object |
remove_frame
Remove a frame.
| Parameter | Type | Description |
|---|---|---|
id (required) | string |
arrange
Move a frame in the stacking order.
| Parameter | Type | Description |
|---|---|---|
id (required) | string | |
to (required) | "front" | "back" | "forward" | "backward" |
anchor
Tie a frame’s x and/or y to another frame (or the page), so it follows it; null removes.
| Parameter | Type | Description |
|---|---|---|
id (required) | string | |
x | object (target, at, offset) | null | |
y | any |
Components
Section titled “Components”make_component
Make a component (a reusable group, say a price badge) from frames on one page: they become its parts, where they are, and an instance of it takes their place. Edit its parts with the frame tools by id <component>/<part>; add parts with page "component:<id>". Every instance shows the same parts; "page" anchors in a part mean the instance’s box.
| Parameter | Type | Description |
|---|---|---|
name (required) | string | |
frames (required) | array of string |
place_instance
Place an instance of a component, its top left at x, y, at the component’s size (update_frame changes its box: the parts are laid out again inside it).
| Parameter | Type | Description |
|---|---|---|
component (required) | string | |
page | string | number | page id, or number from 1 (the first by default); "component:<id>" adds a part to a component |
x (required) | number | |
y (required) | number |
update_component
Change a component: its name, its box (width, height: the size of new instances), and perInstance: true gives each instance its own copy of every field the parts use, named <instance>-<field> (promo1-price); false makes them share the fields again.
| Parameter | Type | Description |
|---|---|---|
component (required) | string | |
name | string | |
width | number | |
height | number | |
perInstance | boolean |
detach_instance
Turn an instance into ordinary frames of its page, named <instance>-<part>, where they are.
| Parameter | Type | Description |
|---|---|---|
id (required) | string |
remove_component
Remove a component; its instances are detached into frames first.
| Parameter | Type | Description |
|---|---|---|
component (required) | string |
Fields and sample values
Section titled “Fields and sample values”define_field
Define (or redefine) a field: text, number (min, max, step, decimals), choice (options: [{ value, label }]), switch (true/false, for showing or hiding with conditions) or image; required with a sample value, or optional with a default; group: a field group’s id. Use {{name}} in text for text, number (shown with its decimals) and choice (shown as its label), or place_image with field.
| Parameter | Type | Description |
|---|---|---|
name (required) | string | |
type (required) | "text" | "number" | "choice" | "switch" | "image" | |
required | boolean | |
sample | string | number | boolean | the sample value: text, a number, an option’s value, true or false (an image field: an added image’s id) |
default | any | |
label | string | |
description | string | |
maxLength | integer | text only |
min | number | number only |
max | number | number only |
step | number | number only: the stepper’s increment |
decimals | integer | number only: 0-6, shown and allowed |
options | array of object (value, label) | choice only: 1-200 options, each value unique |
group | string | a field group’s id (define_field_group) |
define_field_group
Define a field group (a folder of fields for the editor and the fill-in form), or relabel one. Groups are shown in the order defined; values stay flat.
| Parameter | Type | Description |
|---|---|---|
id (required) | string | |
label (required) | string |
remove_field_group
Remove a field group; its fields stay, in no group.
| Parameter | Type | Description |
|---|---|---|
id (required) | string |
rename_field
Rename a field everywhere it is used.
| Parameter | Type | Description |
|---|---|---|
name (required) | string | |
to (required) | string |
remove_field
Remove a field no frame uses.
| Parameter | Type | Description |
|---|---|---|
name (required) | string |
set_values
Set sample values ({ field: value }; null removes).
| Parameter | Type | Description |
|---|---|---|
values (required) | object |
Styles and colours
Section titled “Styles and colours”define_style
Define a named paragraph style (paragraph settings in paragraph, its text’s look in style) or character style (style only), optionally based on another of its kind. Text takes it with paragraph.paragraphStyle or a run’s characterStyle; changing the style later changes all its text.
| Parameter | Type | Description |
|---|---|---|
kind (required) | "paragraph" | "character" | |
name (required) | string | |
id | string | made from the name by default |
basedOn | string | a style of the same kind it takes everything else from |
style | object (family, size, weight, style, stretch, tracking, color, underline, stroke) | a run’s style |
paragraph | object (align, direction, lineSpacing, spaceBefore, spaceAfter, indentStart, indentEnd, indentFirst, list, tabs) | a paragraph’s style |
update_style
Change a style: its name, basedOn (null: none) and settings (null removes one). All text using it follows.
| Parameter | Type | Description |
|---|---|---|
kind (required) | "paragraph" | "character" | |
id (required) | string | |
name | string | |
basedOn | string | null | |
style | object | character settings, as a run’s style |
paragraph | object | paragraph settings, as a paragraph’s |
remove_style
Remove a style. Its text takes style `to` of the same kind, or without it keeps its look as its own settings.
| Parameter | Type | Description |
|---|---|---|
kind (required) | "paragraph" | "character" | |
id (required) | string | |
to | string |
add_swatch
Add or replace a named colour (rgb "#rrggbb", cmyk [c,m,y,k], spot with its CMYK alternate).
| Parameter | Type | Description |
|---|---|---|
id (required) | string | |
name | string | |
kind (required) | "rgb" | "cmyk" | "spot" | |
value (required) | string | array of number | |
overprint | boolean |
Images and fonts
Section titled “Images and fonts”add_image
Add a picture file (PNG, JPEG, SVG, TIFF) as an image the template can show, or a region of it (crop, in its pixels). Answers its id. An id already there is refused unless replace: true, which puts the new picture in its place everywhere it shows.
| Parameter | Type | Description |
|---|---|---|
path (required) | string | |
id | string | |
crop | object (x, y, w, h) | |
replace | boolean |
remove_image
Remove an added image no frame or sample value uses (save leaves out unused images anyway).
| Parameter | Type | Description |
|---|---|---|
id (required) | string |
inspect_image
Look into a picture file (the one you reproduce, say) without adding it: its size, colour space and profile, a PNG of a region (in its pixels; nearest-neighbour when zoomed), and the colours at points — as shown (sRGB) and, for a CMYK picture, its inks in percent.
| Parameter | Type | Description |
|---|---|---|
path (required) | string | |
region | object (x, y, w, h) | |
points | array of array of number | [[x, y], …] in the picture’s pixels |
size | integer |
add_font
Add a font file (TTF/OTF) whose rights the user asserts: browser, backend, embed, redistribute.
| Parameter | Type | Description |
|---|---|---|
path (required) | string | |
rights (required) | object (browser, backend, embed, redistribute) | |
licence | string |
Looking at the work
Section titled “Looking at the work”render_page
A page as a PNG (longest side 1024 px by default). outlines: each frame’s box and id over it. frame: zoom into one frame; region: into any part of the page (points). The answer says which part of the page it shows. overlay: a picture (the one you reproduce) over it at half opacity, to compare. proof: a print template on its paper.
| Parameter | Type | Description |
|---|---|---|
page | string | number | page id, or number from 1 (the first by default); "component:<id>" adds a part to a component |
frame | string | |
region | object (x, y, w, h) | a part of the page, in points |
overlay | object (path, opacity, at) | a picture drawn over the page (0.5 opacity by default; at: where on the page, in points, the whole page by default), to compare with what you reproduce |
outlines | boolean | |
proof | boolean | |
size | integer |
render_all
Every page as a small PNG, for an overview.
| Parameter | Type | Description |
|---|---|---|
size | integer |
check
Everything that is wrong: layout errors and warnings, sample values against the fields, and for a print template the PDF/X preflight.
No parameters.
Output and publishing
Section titled “Output and publishing”publish is offered when the server is given a Paprika address and a key with the render and publish scopes.
set_export
The export settings: profile (screen or print), minimumDpi, output (printing condition), marks ({ crop, bleed, registration, info, colorBar }); null removes.
| Parameter | Type | Description |
|---|---|---|
profile | "screen" | "print" | |
minimumDpi | number | null | |
output | string | null | |
marks | object | null |
publish
Publish the template as the next version of the registry template of this filename (made if needed).
| Parameter | Type | Description |
|---|---|---|
filename (required) | string | e.g. "invoice.paprika" |
patch
RFC 6902 JSON Patch on the template JSON (see get_document), for what the other tools don’t cover.
| Parameter | Type | Description |
|---|---|---|
operations (required) | array of object (op, path, from, value) |