@doclift/workflows-mcp 0.1.0

package/dist/tools/checks.js

@@ -0,0 +1,233 @@
+import { z } from 'zod';
+import { respond, templateId } from './shared.js';
+export const registerChecks = (server, api, base) => {
+    // ------------------------------------------------------ integrity and shape
+    server.registerTool('workflow_validate', {
+        title: 'Check a workflow without writing',
+        description: 'Runs the integrity check and answers with every anomaly, each carrying its type, whether it ' +
+            'blocks publication, and the node it points at. Optionally takes content you have NOT written ' +
+            'yet and reports what sanitising would strip from it, plus `inert_tokens` — <variable> ' +
+            'elements written without the interpolation class, which print their own name — ' +
+            '`unreachable_images`, sources the engine cannot fetch, `ejected_from_paragraph`, block ' +
+            'elements written inside a <p> that the parser moves out, and `removed_css_declarations` — ' +
+            'properties dropped from inside a `style` that survives, which is how text-transform or a ' +
+            'shadow disappears while the attribute stays and every other check reads clean. Call it ' +
+            'before publishing.',
+        inputSchema: {
+            id: templateId,
+            content: z
+                .array(z.string())
+                .optional()
+                .describe('HTML fragments to dry-run through the sanitiser before you save them.'),
+            scope: z
+                .enum(['content', 'running_title'])
+                .optional()
+                .describe('Which sanitiser to dry-run against. `content` is a section body; `running_title` is a ' +
+                'part header or footer, where script, style and iframe are removed WITH their text. ' +
+                'Defaults to content.'),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ id, content, scope }) => respond(await api.post(`${base}/templates/${id}/validate`, {
+        ...(content === undefined ? {} : { content }),
+        ...(scope === undefined ? {} : { scope }),
+    })));
+    server.registerTool('workflow_payload_contract', {
+        title: 'What a generation payload must carry',
+        description: 'The variables a generation call has to send for this workflow, which are required, which rows ' +
+            'a collection must carry, and the limits on them. Read this before calling workflow_render.',
+        inputSchema: { id: templateId },
+        annotations: { readOnlyHint: true },
+    }, async ({ id }) => respond(await api.get(`${base}/templates/${id}/payload_contract`)));
+    // ---------------------------------------------------------------- self-check
+    server.registerTool('workflow_selfcheck', {
+        title: 'Check your own work before saying it is done',
+        description: 'Answers a checklist from the workflow\'s actual state — not a reminder, a reading of the ' +
+            'database. Covers what saved cleanly and is still wrong: anomalies, tokens the interpolator ' +
+            'will never read, pictures the engine cannot fetch, variables declared and never used, and ' +
+            'whether a PDF exists that is newer than your last edit. It also names the one thing it ' +
+            'cannot check — that the document is the one that was asked for. Call it before reporting ' +
+            'a workflow as finished.',
+        inputSchema: { id: templateId },
+        annotations: { readOnlyHint: true },
+    }, async ({ id }) => {
+        const [validation, template, payload] = await Promise.all([
+            api.post(`${base}/templates/${id}/validate`),
+            api.get(`${base}/templates/${id}`),
+            api.get(`${base}/templates/${id}/payload_contract`),
+        ]);
+        if (!validation.ok)
+            return respond(validation);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(selfcheck(validation.body, template.ok ? template.body : null, payload.ok ? payload.body : null), null, 2),
+                },
+            ],
+        };
+    });
+};
+// A line whose evidence the API did not send is `unknown`, never `pass`. Reading
+// silence as success is the exact habit this tool exists to break, and it would
+// break it in the one case where the server is older than the client.
+const absent = (check, next) => ({
+    check,
+    status: 'unknown',
+    detail: 'This server did not answer with the evidence for this line.',
+    next,
+});
+const selfcheck = (validation, template, payload) => {
+    const stored = validation.stored;
+    const blocking = (validation.anomalies ?? []).filter((anomaly) => anomaly.blocking);
+    const lines = [];
+    lines.push({
+        check: 'Nothing blocks publication',
+        status: blocking.length === 0 ? 'pass' : 'todo',
+        detail: blocking.length === 0 ? 'No blocking anomaly.' : blocking,
+        ...(blocking.length === 0 ? {} : { next: 'Fix each anomaly above, then call workflow_selfcheck again.' }),
+    });
+    const listLine = (key, check, next) => {
+        if (!stored || stored[key] === undefined)
+            return absent(check, next);
+        const found = stored[key] ?? [];
+        return {
+            check,
+            status: found.length === 0 ? 'pass' : 'todo',
+            detail: found.length === 0 ? 'None found in the stored content.' : found,
+            ...(found.length === 0 ? {} : { next }),
+        };
+    };
+    lines.push(listLine('inert_tokens', 'No variable token is inert', 'Rewrite each token with the class capabilities.content.tokens gives, then section_update.'));
+    lines.push(listLine('unreachable_images', 'No picture is unreachable', 'Upload each picture with image_upload and cite the URL it answers with.'));
+    lines.push(listLine('layout_tables', 'No table is used for a column layout with its rules showing', 'Put capabilities.authoring.table.layout_row_class on the <tr>: it takes the rules away and ' +
+        'leaves the columns. A ruled table around two blocks set side by side is a shape no ' +
+        'hand-made document has.'));
+    if (!stored || stored.unused_variables === undefined) {
+        lines.push(absent('No variable is declared and never used', 'Read the stored content and compare.'));
+    }
+    else {
+        const unused = stored.unused_variables;
+        lines.push({
+            check: 'No variable is declared and never used',
+            status: unused.length === 0 ? 'pass' : 'todo',
+            detail: unused.length === 0 ? 'Every declared variable is cited.' : unused,
+            // Usually a typo: the token was written with one spelling and the variable
+            // declared with another, leaving a dead name behind rather than an error.
+            ...(unused.length === 0
+                ? {}
+                : { next: 'Either cite them, or delete them — an unused name is often a token typed differently.' }),
+        });
+    }
+    const render = stored?.last_render;
+    if (!stored || stored.last_render === undefined) {
+        lines.push(absent('A PDF exists and is newer than your last edit', 'Call workflow_render, then read the PDF.'));
+    }
+    else if (!render || !render.at) {
+        lines.push({
+            check: 'A PDF exists and is newer than your last edit',
+            status: 'todo',
+            detail: 'This workflow has never been generated.',
+            next: 'Publish it, then call workflow_render with a dataset.',
+        });
+    }
+    else {
+        lines.push({
+            check: 'A PDF exists and is newer than your last edit',
+            status: render.stale ? 'todo' : 'pass',
+            detail: render,
+            ...(render.stale
+                ? { next: 'You edited after the last generation. Render again — what you read is not what you have.' }
+                : {}),
+        });
+    }
+    // Deliberately never `pass`. No tool can compare a document to an intention it
+    // never saw, and a checklist that ticked this line would be lying about the
+    // only step that catches what the others cannot.
+    // A weight nothing carries is rounded by the engine and printed as something
+    // nobody chose — the one part of this that is a fault rather than a taste. The
+    // rest is handed over: matching the sizes of an original is a comparison only
+    // the caller can make.
+    const type = stored?.typography;
+    if (!stored || type === undefined) {
+        lines.push(absent('Sizes and weights are the ones you meant', 'Compare the PDF with the original.'));
+    }
+    else {
+        const orphaned = type.weights_no_family_carries ?? [];
+        lines.push({
+            check: 'Sizes and weights are the ones you meant',
+            status: orphaned.length > 0 ? 'todo' : 'unknown',
+            detail: {
+                sizes_pt: type.sizes_pt ?? [],
+                weights: type.weights ?? [],
+                weights_no_family_carries: orphaned,
+                off_the_editor_scale: type.sizes_off_the_editor_scale ?? [],
+                how: orphaned.length > 0
+                    ? 'No provisioned family carries these weights. The engine will round them and print a ' +
+                        'thickness nobody chose — pick one the family declares in capabilities.authoring.fonts.'
+                    : 'These are what the document asks for. Whether they match the original is a reading: ' +
+                        'put the two PDFs side by side and compare a heading, a label and a line of body text. ' +
+                        'A size off the editor scale is NOT refused and renders exactly as written — it is ' +
+                        'simply one the editor menu does not offer, which only matters when the document is ' +
+                        'meant to look hand-made. And this cannot tell whether a weight belongs to the family ' +
+                        'a passage is set in, only whether some family carries it.',
+            },
+            ...(orphaned.length > 0 ? { next: 'Replace each weight with one the chosen family declares.' } : {}),
+        });
+    }
+    // Where a break lands is only visible in the PDF, so this line is never a
+    // `pass`: what the server can say is whether anybody decided, and what they
+    // decided. The rest is a reading the caller has to do.
+    const breaks = stored?.page_breaks;
+    if (!stored || breaks === undefined) {
+        lines.push(absent('Page breaks fall where you meant them to', 'Read the PDF and check each break.'));
+    }
+    else {
+        const declared = breaks.declared ?? [];
+        const sections = breaks.sections ?? 0;
+        // Gated on how much there is to paginate, not on how many nodes it is cut
+        // into: a four-section invoice of 5 000 characters comes out on one page and
+        // needs no break at all, while a twelve-section deed of 14 500 took five.
+        // Counting sections nagged the first of those for nothing.
+        const undecided = declared.length === 0 && (breaks.content_length ?? 0) > 9000;
+        lines.push({
+            check: 'Page breaks fall where you meant them to',
+            status: undecided ? 'todo' : 'unknown',
+            detail: {
+                declared,
+                sections,
+                content_length: breaks.content_length ?? null,
+                how: undecided
+                    ? 'Not one section of this document asks for a break, so the engine paginated it wherever ' +
+                        'the text ran out. Set page_break on the sections that open a part — see ' +
+                        'capabilities.section.page_breaks — or confirm from the PDF that running on is what you want.'
+                    : 'These are the breaks you asked for. Only the PDF shows where they landed, and whether a ' +
+                        'heading was left alone at the foot of a page: fetch it and look.',
+            },
+            ...(undecided ? { next: 'Decide the breaks, or read the PDF and confirm the engine chose well.' } : {}),
+        });
+    }
+    const palette = stored?.palette;
+    lines.push({
+        check: 'The document is the one that was asked for',
+        status: 'unknown',
+        detail: {
+            how: 'Only you can check this. Fetch the URL workflow_render answers with, read the PDF, and ' +
+                'compare it to the request: the wording, the order of the sections, the values in place of ' +
+                'the tokens, the page count.',
+            // Handed over rather than judged: no tool knows what the original looked
+            // like. It is here so the one question that cannot be answered can at
+            // least be asked against something concrete — a document reproduced from
+            // a coloured original and coming back with an empty palette has lost
+            // something nobody will report.
+            colours_this_document_declares: palette ?? 'unknown',
+        },
+        next: 'Report what you could not reproduce and why, rather than presenting a partial result as complete.',
+    });
+    return {
+        workflow: template === null ? null : { id: template['id'], title: template['title'], published: template['published'] },
+        publishable: validation.publishable ?? null,
+        required_variables: payload === null ? null : payload['required'],
+        checklist: lines,
+        outstanding: lines.filter((line) => line.status === 'todo').length,
+    };
+};

package/dist/tools/datasets.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ApiClient } from '../client.js';
+export declare const registerDatasets: (server: McpServer, api: ApiClient, base: string) => void;

package/dist/tools/datasets.js

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+import { respond, templateId } from './shared.js';
+export const registerDatasets = (server, api, base) => {
+    // -------------------------------------------------------------- the datasets
+    server.registerTool('dataset_list', {
+        title: 'List the preview datasets',
+        description: 'The sets of values the preview injects in place of a real payload.',
+        inputSchema: { template_id: templateId },
+        annotations: { readOnlyHint: true },
+    }, async ({ template_id }) => respond(await api.get(`${base}/templates/${template_id}/datasets`)));
+    server.registerTool('dataset_create', {
+        title: 'Create a preview dataset',
+        description: '`values` is a FLAT map of variable name to value. A collection appears as an array of flat ' +
+            'objects, exactly as in a generation payload. Anything more nested is refused.',
+        inputSchema: {
+            template_id: templateId,
+            name: z.string().min(1),
+            values: z.record(z.unknown()),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, async ({ template_id, ...dataset }) => respond(await api.post(`${base}/templates/${template_id}/datasets`, { dataset })));
+    server.registerTool('dataset_update', {
+        title: 'Change a preview dataset',
+        inputSchema: {
+            template_id: templateId,
+            id: z.number().int(),
+            name: z.string().min(1).optional(),
+            values: z.record(z.unknown()).optional(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, async ({ template_id, id, ...dataset }) => respond(await api.patch(`${base}/templates/${template_id}/datasets/${id}`, { dataset })));
+    server.registerTool('dataset_delete', {
+        title: 'Delete a preview dataset',
+        inputSchema: { template_id: templateId, id: z.number().int() },
+        annotations: { readOnlyHint: false, destructiveHint: true },
+    }, async ({ template_id, id }) => respond(await api.delete(`${base}/templates/${template_id}/datasets/${id}`)));
+};

package/dist/tools/documents.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ApiClient } from '../client.js';
+export declare const registerDocuments: (server: McpServer, api: ApiClient, base: string) => void;

package/dist/tools/documents.js

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+import { respond, templateId } from './shared.js';
+export const registerDocuments = (server, api, base) => {
+    // ------------------------------------------------------------- the document
+    server.registerTool('workflow_document_get', {
+        title: 'Export the whole workflow',
+        description: 'The entire workflow as one manifest — tree, variables, datasets, theme, page setup. Useful to ' +
+            'copy a workflow, or to read one you did not build.',
+        inputSchema: { id: templateId },
+        annotations: { readOnlyHint: true },
+    }, async ({ id }) => respond(await api.get(`${base}/templates/${id}/document`)));
+    server.registerTool('workflow_document_put', {
+        title: 'Replace the whole workflow',
+        description: 'Wipes the tree, the variables and the datasets and rebuilds them from the manifest. This is a ' +
+            'replacement, not a merge: anything absent from the document is gone. Prefer the section tools ' +
+            'for incremental work.',
+        inputSchema: {
+            id: templateId,
+            document: z.record(z.unknown()).describe('A manifest in the shape workflow_document_get returns.'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true },
+    }, async ({ id, document }) => respond(await api.put(`${base}/templates/${id}/document`, { document })));
+};

package/dist/tools/images.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ApiClient } from '../client.js';
+export declare const registerImages: (server: McpServer, api: ApiClient, base: string) => void;

package/dist/tools/images.js

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+import { respond, templateId } from './shared.js';
+export const registerImages = (server, api, base) => {
+    // ---------------------------------------------------------------- the images
+    server.registerTool('image_upload', {
+        title: 'Store a picture for use inside content',
+        description: 'Answers with the URL to put in an <img src>. The renderer makes no network request, so a ' +
+            'picture cited by an external URL prints an empty frame and nothing refuses it: every ' +
+            'picture in a section has to come through here. workflow_validate reports the ones that ' +
+            'would not resolve, under `unreachable_images`.',
+        inputSchema: {
+            template_id: templateId,
+            filename: z.string().min(1),
+            content_type: z.string().min(1),
+            data: z.string().min(1).describe('Base64 of the file, without a data: prefix.'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, async ({ template_id, ...image }) => respond(await api.post(`${base}/templates/${template_id}/images`, { image })));
+    server.registerTool('image_list', {
+        title: 'List the pictures of a workflow',
+        inputSchema: { template_id: templateId },
+        annotations: { readOnlyHint: true },
+    }, async ({ template_id }) => respond(await api.get(`${base}/templates/${template_id}/images`)));
+};

package/dist/tools/index.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ApiClient } from '../client.js';
+export declare const registerTools: (server: McpServer, api: ApiClient) => void;

package/dist/tools/index.js

@@ -0,0 +1,28 @@
+// The registrations, in the order the tools were declared. `base` is computed
+// once here and handed down: repeating it in each module is the duplication the
+// rest of this package avoids.
+import { registerCapabilities } from './capabilities.js';
+import { registerWorkflows } from './workflows.js';
+import { registerChecks } from './checks.js';
+import { registerPublication } from './publication.js';
+import { registerDocuments } from './documents.js';
+import { registerTheme } from './theme.js';
+import { registerSections } from './sections.js';
+import { registerVariables } from './variables.js';
+import { registerDatasets } from './datasets.js';
+import { registerImages } from './images.js';
+import { registerRender } from './render.js';
+export const registerTools = (server, api) => {
+    const base = '/api/v1/workflows';
+    registerCapabilities(server, api, base);
+    registerWorkflows(server, api, base);
+    registerChecks(server, api, base);
+    registerPublication(server, api, base);
+    registerDocuments(server, api, base);
+    registerTheme(server, api, base);
+    registerSections(server, api, base);
+    registerVariables(server, api, base);
+    registerDatasets(server, api, base);
+    registerImages(server, api, base);
+    registerRender(server, api);
+};

package/dist/tools/publication.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ApiClient } from '../client.js';
+export declare const registerPublication: (server: McpServer, api: ApiClient, base: string) => void;

package/dist/tools/publication.js

@@ -0,0 +1,17 @@
+import { respond, templateId } from './shared.js';
+export const registerPublication = (server, api, base) => {
+    server.registerTool('workflow_publish', {
+        title: 'Publish a workflow',
+        description: 'Publishing is refused while a blocking anomaly stands — run workflow_validate first. Only a ' +
+            'published workflow can be generated from.',
+        inputSchema: { id: templateId },
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, async ({ id }) => respond(await api.post(`${base}/templates/${id}/publication`)));
+    server.registerTool('workflow_unpublish', {
+        title: 'Withdraw a workflow',
+        description: 'Never gated on integrity: a workflow whose references broke after publication is exactly one ' +
+            'that has to be withdrawable.',
+        inputSchema: { id: templateId },
+        annotations: { readOnlyHint: false, destructiveHint: true },
+    }, async ({ id }) => respond(await api.delete(`${base}/templates/${id}/publication`)));
+};

package/dist/tools/render.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ApiClient } from '../client.js';
+export declare const registerRender: (server: McpServer, api: ApiClient) => void;

package/dist/tools/render.js

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+import { respond, templateId } from './shared.js';
+export const registerRender = (server, api) => {
+    // --------------------------------------------------------------- generation
+    server.registerTool('workflow_render', {
+        title: 'Generate a PDF',
+        description: 'Runs the real generation pipeline and answers with the document. The workflow must be ' +
+            'published. `variables` has to satisfy workflow_payload_contract — a required variable whose ' +
+            'KEY is absent is refused, while a key sent empty is accepted. This is the only honest way to ' +
+            'check that a reproduction matches its original. A sandbox key stamps a watermark across every ' +
+            'page: letters that appear in the PDF and in no content you wrote.',
+        inputSchema: {
+            id: templateId,
+            variables: z.record(z.unknown()).describe('Flat map, collections as arrays of flat objects.'),
+            tag: z.string().optional().describe('Free label carried back on the request.'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, async ({ id, variables, tag }) => respond(await api.post('/api/v1/document_requests', {
+        document_request: {
+            type: 'synchrone',
+            document_generations: [{ template_id: id, variables }],
+            ...(tag === undefined ? {} : { tag }),
+        },
+    })));
+};

package/dist/tools/sections.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ApiClient } from '../client.js';
+export declare const registerSections: (server: McpServer, api: ApiClient, base: string) => void;

package/dist/tools/sections.js

@@ -0,0 +1,118 @@
+import { z } from 'zod';
+import { condition, placements, respond, runningTitles, sectionId, templateId } from './shared.js';
+export const registerSections = (server, api, base) => {
+    // ---------------------------------------------------------------- the tree
+    server.registerTool('section_tree', {
+        title: 'Read the whole tree',
+        description: 'Every section of the workflow, nested as it prints.',
+        inputSchema: { template_id: templateId },
+        annotations: { readOnlyHint: true },
+    }, async ({ template_id }) => respond(await api.get(`${base}/templates/${template_id}/sections`)));
+    server.registerTool('section_get', {
+        title: 'Read one section',
+        inputSchema: { template_id: templateId, id: sectionId },
+        annotations: { readOnlyHint: true },
+    }, async ({ template_id, id }) => respond(await api.get(`${base}/templates/${template_id}/sections/${id}`)));
+    server.registerTool('section_create', {
+        title: 'Add a section',
+        description: 'A node is EITHER a group — a title, a condition and children — OR a content section. Never ' +
+            'both: a group refuses content, and only an image_with_variable section carries placements. ' +
+            'The tree is three levels deep at most (group → group → section). A group may carry its whole ' +
+            'subtree in this one call, through `children`.',
+        inputSchema: {
+            template_id: templateId,
+            kind: z.string().describe('See capabilities.section.kinds and the `carries` matrix.'),
+            title: z.string().min(1),
+            content: z
+                .string()
+                .optional()
+                .describe('HTML, sanitised on write. Anything off the allow-list is removed WITHOUT AN ERROR — ' +
+                'dry-run it through workflow_validate first. A variable token is recognised by its ' +
+                'CLASS, not by its tag: <variable class="editor-text-variable non-editable-content editor-parsed">name</variable>, the name being ' +
+                'the inner text. Take the exact string from capabilities.content.tokens — a token ' +
+                'without the editor-parsed class prints the name instead of the value, and every ' +
+                'other check passes.'),
+            parent_id: z.number().int().nullable().optional().describe('Must name a group of the same workflow.'),
+            position: z
+                .number()
+                .int()
+                .optional()
+                .describe('Rank among siblings, zero-based and renumbered on write — read the answer for what it became.'),
+            layout: z.string().optional(),
+            page_break: z.string().optional(),
+            repeat_over: z
+                .string()
+                .nullable()
+                .optional()
+                .describe('Name of a collection variable: the whole node prints once per row. Nesting one repetition ' +
+                'inside another is refused in both directions.'),
+            condition: condition.optional(),
+            placements: placements.optional(),
+            running_titles: runningTitles.optional(),
+            children: z.array(z.record(z.unknown())).optional().describe('Nested sections, same shape, recursive.'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, async ({ template_id, ...section }) => respond(await api.post(`${base}/templates/${template_id}/sections`, { section })));
+    server.registerTool('section_update', {
+        title: 'Change a section',
+        description: 'Only the keys you send are written. `kind` is fixed at creation. Answers with the whole tree, ' +
+            'so you see what the database made of the change rather than guessing.',
+        inputSchema: {
+            template_id: templateId,
+            id: sectionId,
+            title: z.string().min(1).optional(),
+            content: z.string().optional(),
+            layout: z.string().optional(),
+            page_break: z.string().optional(),
+            repeat_over: z.string().nullable().optional(),
+            condition: condition.optional(),
+            placements: placements.optional(),
+            running_titles: runningTitles.optional(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, async ({ template_id, id, ...section }) => respond(await api.patch(`${base}/templates/${template_id}/sections/${id}`, { section })));
+    server.registerTool('section_move', {
+        title: 'Move a section',
+        description: 'Changes a section\'s parent and rank. A group that already holds a group cannot enter another ' +
+            'group — that is how a fourth level would appear by drift.',
+        inputSchema: {
+            template_id: templateId,
+            id: sectionId,
+            parent_id: z.number().int().nullable().describe('null moves it to the root.'),
+            position: z.number().int(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, async ({ template_id, id, parent_id, position }) => respond(await api.patch(`${base}/templates/${template_id}/sections/${id}/move`, {
+        section: { parent_id, position },
+    })));
+    server.registerTool('section_duplicate', {
+        title: 'Duplicate a section',
+        description: 'Deep copy of the section and its subtree, in the same workflow, backdrops included.',
+        inputSchema: { template_id: templateId, id: sectionId },
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, async ({ template_id, id }) => respond(await api.post(`${base}/templates/${template_id}/sections/${id}/duplicate`)));
+    server.registerTool('section_delete', {
+        title: 'Delete a section',
+        description: 'Deleting a group takes its whole subtree with it.',
+        inputSchema: { template_id: templateId, id: sectionId },
+        annotations: { readOnlyHint: false, destructiveHint: true },
+    }, async ({ template_id, id }) => respond(await api.delete(`${base}/templates/${template_id}/sections/${id}`)));
+    server.registerTool('section_background_set', {
+        title: 'Lay a backdrop under an image section',
+        description: 'The picture an `image_with_variable` section places its labels over. Sent as base64. Refused ' +
+            'on any other kind of section, and bounded by capabilities.limits.image_bytes.',
+        inputSchema: {
+            template_id: templateId,
+            id: sectionId,
+            filename: z.string().min(1),
+            content_type: z.string().min(1),
+            data: z.string().min(1).describe('Base64 of the file, without a data: prefix.'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, async ({ template_id, id, ...background }) => respond(await api.patch(`${base}/templates/${template_id}/sections/${id}/background`, { background })));
+    server.registerTool('section_background_remove', {
+        title: 'Remove a backdrop',
+        inputSchema: { template_id: templateId, id: sectionId },
+        annotations: { readOnlyHint: false, destructiveHint: true },
+    }, async ({ template_id, id }) => respond(await api.delete(`${base}/templates/${template_id}/sections/${id}/background`)));
+};

package/dist/tools/shared.d.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import type { ApiResult } from '../client.js';
+export declare const respond: <T>(result: ApiResult<T>) => {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: never;
+} | {
+    isError: boolean;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+export declare const templateId: z.ZodNumber;
+export declare const sectionId: z.ZodNumber;
+export declare const condition: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const placements: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>, "many">;
+export declare const runningTitles: z.ZodRecord<z.ZodString, z.ZodUnknown>;

package/dist/tools/shared.js

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+// Every tool answers with JSON text. A tool that formatted prose would be
+// guessing what the caller wants to read, and the caller is a model that will do
+// better with the payload than with a summary of it.
+export const respond = (result) => {
+    if (result.ok) {
+        return { content: [{ type: 'text', text: JSON.stringify(result.body, null, 2) }] };
+    }
+    return {
+        isError: true,
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({ status: result.status, errors: result.messages }, null, 2),
+            },
+        ],
+    };
+};
+export const templateId = z.number().int().describe('Identifier of the workflow.');
+export const sectionId = z.number().int().describe('Identifier of the section.');
+// Left as a free-form object on purpose. The shape a rule takes depends on its
+// operator, and `capabilities.condition.operators` is where that is decided; a
+// schema written here would be a second catalogue, wrong the day an operator
+// moves.
+export const condition = z
+    .record(z.unknown())
+    .describe('Flat condition: {"match": "all"|"any", "rules": [...]}. The key a rule carries depends on its ' +
+    'operator — see workflow_capabilities.condition.operators. An unknown "match" is read as "all".');
+export const placements = z
+    .array(z.record(z.unknown()))
+    .describe('Labels laid over the backdrop, in percent of the image box. `image_with_variable` sections only. ' +
+    'Key names are exact — see workflow_capabilities.placement.keys_by_kind. A misspelled key is ' +
+    'dropped silently and the label renders as nothing.');
+export const runningTitles = z
+    .record(z.unknown())
+    .describe('Root groups only: {"header": html, "footer": html, "numbering": {"start": n}}. Header and footer ' +
+    'are sanitised like content, and script/style/iframe are removed with their text. Unknown keys ' +
+    'are discarded, never refused.');

package/dist/tools/theme.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ApiClient } from '../client.js';
+export declare const registerTheme: (server: McpServer, api: ApiClient, base: string) => void;

package/dist/tools/theme.js

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+import { respond, templateId } from './shared.js';
+export const registerTheme = (server, api, base) => {
+    // ---------------------------------------------------------------- the theme
+    server.registerTool('theme_get', {
+        title: 'Read the document defaults',
+        description: 'The face, size, ink and leading a paragraph and each of the three heading levels take when a ' +
+            'section says nothing.',
+        inputSchema: { id: templateId },
+        annotations: { readOnlyHint: true },
+    }, async ({ id }) => respond(await api.get(`${base}/templates/${id}/theme`)));
+    server.registerTool('theme_update', {
+        title: 'Set the document defaults',
+        description: 'Blocks are paragraph, h1, h2 and h3. Each takes font_family, font_size, color and line_height. ' +
+            'A declaration that will not parse is DROPPED and the call still answers 200, so the shape ' +
+            'matters: font_size is a STRING carrying its unit ("11pt", never 11), line_height is unitless ' +
+            '("1.4" or 1.4 — a value carrying a unit is dropped, not converted), color is hex. font-weight ' +
+            'is not settable: headings take their weight from the engine. Set the theme BEFORE writing ' +
+            'sections — content that declares inline what the theme already says looks identical today and ' +
+            'stops following the theme forever. Read it back to confirm what was kept.',
+        inputSchema: {
+            id: templateId,
+            theme: z.record(z.unknown()).describe('{"paragraph": {"font_family": …}, "h1": {…}, …}'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, async ({ id, theme }) => respond(await api.patch(`${base}/templates/${id}/theme`, { theme })));
+};