@formfeed/mcp 0.3.20 → 0.3.21

package/README.md

@@ -3,12 +3,13 @@
 [![formfeed MCP server – quality and maintenance score on Glama](https://glama.ai/mcp/servers/formfeed-dev/formfeed/badges/score.svg)](https://glama.ai/mcp/servers/formfeed-dev/formfeed)
 
 Model Context Protocol server for [Formfeed](https://formfeed.dev/?utm_source=npm&utm_content=mcp).
-Gives Claude, Cursor and other agents eight tools: `list_templates`, `get_template_schema`,
+Gives Claude, Cursor and other agents ten tools: `list_templates`, `get_template_schema`,
 `validate_template` (free: the data against the template's schema, ad-hoc HTML offline), `check_invoice` (free and offline: the
 `_invoice` block of a ZUGFeRD / Factur-X e-invoice against EN 16931), `render` (with `einvoice`, the PDF becomes that e-invoice; an
 image comes back as a picture the agent can look at),
-`convert_to_pdf` (Word, Excel, PowerPoint and OpenDocument to PDF), `get_render` and `get_workspace` (which workspace the
-server works in, and the units left).
+`convert_to_pdf` (Word, Excel, PowerPoint and OpenDocument to PDF), `get_render`, `get_workspace` (which workspace the
+server works in, and the units left), `get_template_source` and `save_template` (a new template or a change as a draft,
+which a person publishes in Formfeed; needs `template:write` on the key, or the person's permission for a signed-in agent).
 
 ## stdio (Claude Desktop, Cursor, Claude Code)
 

package/bin/formfeed-mcp.mjs

@@ -83878,7 +83878,7 @@ function base64(bytes) {
     binary += String.fromCharCode(...bytes.subarray(i, i + 32768));
   return btoa(binary);
 }
-var SERVER_INFO = { name: "formfeed", version: "0.3.20" };
+var SERVER_INFO = { name: "formfeed", version: "0.3.21" };
 var READS = {
   readOnlyHint: true,
   destructiveHint: false,
@@ -83951,10 +83951,52 @@ var renderSummary = (r) => ({
   // the report of an e-invoice (spec 17): valid, the findings, the XML's link, the hashes it checked
   ...r.einvoice ? { einvoice: r.einvoice } : {}
 });
+var diagnosticOf = (d) => ({
+  severity: d.severity,
+  code: d.code,
+  message: d.message,
+  ...d.path ? { path: d.path } : {},
+  ...d.location ? { line: d.location.line, column: d.location.column } : {},
+  ...d.part ? { part: d.part, paragraph: d.paragraph } : {}
+});
+var slugSchema = z3.string().regex(/^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/).describe(
+  "New in the workspace: lowercase letters, digits and dashes, e.g. invoice-de"
+);
+var sourceParts = {
+  html: z3.string().max(2 * 1024 * 1024).optional().describe(
+    "The body markup in the template language, without <html>, <head> or <body>; up to 2 MB"
+  ),
+  css: z3.string().max(1024 * 1024).optional().describe("The stylesheet; up to 1 MB"),
+  head: z3.string().max(256 * 1024).optional().describe("Extra markup for <head>, such as font links"),
+  settings: z3.record(z3.string(), z3.unknown()).optional().describe(
+    "Paper, margins, header, footer, fonts and the other settings, as get_template_source returns them; replaces the stored settings as a whole"
+  ),
+  sample_data: z3.record(z3.string(), z3.unknown()).optional().describe(
+    "The data the editor previews with and the draft is checked with; never used by a render"
+  ),
+  data_sets: z3.record(z3.string(), z3.unknown()).optional().describe("Named sample data sets besides sample_data (name \u2192 data)"),
+  data_schema: z3.record(z3.string(), z3.unknown()).nullable().optional().describe("JSON Schema of data; null removes the stored one"),
+  i18n: z3.record(z3.string(), z3.unknown()).nullable().optional().describe("Translations: locale \u2192 key \u2192 text, read by the t helper"),
+  partials: z3.record(z3.string(), z3.string()).optional().describe("Partials the template includes (name \u2192 source)")
+};
+function appOrigin(baseUrl2) {
+  if (!baseUrl2) return "https://app.formfeed.dev";
+  try {
+    return /^api(-[a-z]+)?\.formfeed\.dev$/.test(new URL(baseUrl2).hostname) ? "https://app.formfeed.dev" : null;
+  } catch {
+    return null;
+  }
+}
+function slugIn(account, part) {
+  const value = account?.[part];
+  const slug = typeof value === "object" && value !== null ? value["slug"] : null;
+  return typeof slug === "string" ? slug : null;
+}
 var EINVOICE_PROBLEMS = /* @__PURE__ */ new Set([
   "einvoice_data_invalid",
   "einvoice_display_mismatch",
-  "pdfa_conversion_failed"
+  "pdfa_conversion_failed",
+  "einvoice_validator_error"
 ]);
 function text3(data) {
   return {
@@ -84000,7 +84042,7 @@ function createFormfeedServer(options) {
   };
   const fetchImpl = options.fetch ?? ((input, init) => fetch(input, init));
   const server = new McpServer(SERVER_INFO, {
-    instructions: (client ? "" : `${NO_KEY_INSTRUCTION} `) + "Formfeed renders PDFs and images from HTML templates, and fills Word and PowerPoint templates (as DOCX, PPTX or PDF). Start with list_templates, read the data shape with get_template_schema, check data with validate_template, then call render and hand the download_url to the user. An image render also returns the picture itself, so look at it before handing it on. For an e-invoice (ZUGFeRD / Factur-X), put the invoice into data._invoice, check it with check_invoice, and call render with einvoice set; the template prints the same block. convert_to_pdf turns office documents into PDFs. get_workspace says which workspace this server works in and what the period has left."
+    instructions: (client ? "" : `${NO_KEY_INSTRUCTION} `) + "Formfeed renders PDFs and images from HTML templates, and fills Word and PowerPoint templates (as DOCX, PPTX or PDF). Start with list_templates, read the data shape with get_template_schema, check data with validate_template, then call render and hand the download_url to the user. An image render also returns the picture itself, so look at it before handing it on. For an e-invoice (ZUGFeRD / Factur-X), put the invoice into data._invoice, check it with check_invoice, and call render with einvoice set; the template prints the same block. convert_to_pdf turns office documents into PDFs. To change a template or write a new one, read it with get_template_source and save it with save_template: it stays a draft until a person publishes it in Formfeed. get_workspace says which workspace this server works in and what the period has left."
   });
   const picture = async (render) => {
     const mimeType = IMAGE_TYPES[render.output];
@@ -84103,13 +84145,92 @@ function createFormfeedServer(options) {
       }
     }
   );
+  server.registerTool(
+    "get_template_source",
+    {
+      title: "Read the source of a template",
+      description: "Returns what a template version is made of: the body markup (html), css, head, settings (paper, margins, header, footer, fonts), sample data, data sets, data schema, translations and partials, with the version's checksum. Call it before save_template to change a template the user named, and save what you edited with that checksum as base_checksum. Reads the latest version by default, the newest draft a change builds on; published reads what renders use. Word and PowerPoint templates are documents: for them it returns the settings and data, not the document. Read-only and free.",
+      inputSchema: {
+        template: z3.string().describe(
+          "Slug (e.g. invoice) or tpl_ id, as list_templates returns them"
+        ),
+        version: z3.union([z3.string().min(1).max(32), z3.number().int().positive()]).optional().describe(
+          "latest (default), published, a version number or a channel name"
+        )
+      },
+      outputSchema: {
+        template: z3.object({
+          id: z3.string().describe("tpl_ id"),
+          slug: z3.string(),
+          name: z3.string(),
+          kind: z3.string().describe("pdf, image, docx (Word) or pptx (PowerPoint)"),
+          engine: z3.string().describe("jinja2, liquid or handlebars"),
+          published_version: z3.number().nullable()
+        }),
+        version: z3.object({
+          number: z3.number(),
+          status: z3.string().describe("draft, published or archived"),
+          checksum: z3.string().describe("Pass it to save_template as base_checksum"),
+          change_note: z3.string().nullable()
+        }),
+        html: z3.string(),
+        css: z3.string(),
+        head: z3.string(),
+        settings: z3.record(z3.string(), z3.unknown()),
+        sample_data: z3.record(z3.string(), z3.unknown()),
+        data_sets: z3.record(z3.string(), z3.unknown()),
+        data_schema: z3.record(z3.string(), z3.unknown()).nullable(),
+        i18n: z3.record(z3.string(), z3.unknown()).nullable(),
+        partials: z3.record(z3.string(), z3.string())
+      },
+      annotations: READS
+    },
+    async ({ template, version }) => {
+      try {
+        const [tpl, row] = await Promise.all([
+          api().templates.get(template),
+          api().templates.versions.get(template, version ?? "latest")
+        ]);
+        return text3({
+          template: {
+            id: tpl.id,
+            slug: tpl.slug,
+            name: tpl.name,
+            kind: tpl.kind,
+            engine: tpl.engine,
+            published_version: tpl.published_version
+          },
+          version: {
+            number: row.number,
+            status: row.status,
+            checksum: row.checksum,
+            change_note: row.change_note
+          },
+          html: row.html ?? "",
+          css: row.css ?? "",
+          head: row.head ?? "",
+          settings: row.settings ?? {},
+          sample_data: row.sample_data ?? {},
+          data_sets: row.data_sets ?? {},
+          data_schema: row.data_schema ?? null,
+          i18n: row.i18n ?? null,
+          partials: row.partials ?? {}
+        });
+      } catch (e) {
+        return failure(e);
+      }
+    }
+  );
   server.registerTool(
     "validate_template",
     {
       title: "Validate a template with data",
-      description: "Checks a template and its data without rendering: free, no units, nothing stored, no document produced. Call it before render when you assembled the data yourself, or after writing ad-hoc html. With template, the API checks the published version (else the latest) as a render would: syntax, header and footer, errors only this data triggers, and the data against the stored JSON Schema (a wrong type or a missing required field is an error). With html and engine it compiles offline and reports syntax errors, unknown filters and variables missing from data. Returns ok and diagnostics (severity, code, message, plus path, line and column, or part and paragraph for Word and PowerPoint). Warnings leave ok true: settle each before rendering.",
+      description: "Checks a template and its data without rendering: free, no units, nothing stored, no document produced. Call it before render when you assembled the data yourself, or after writing ad-hoc html. With template, the API checks the published version (else the latest, or the version you name) as a render would: syntax, header and footer, errors only this data triggers, and the data against the stored JSON Schema (a wrong type or a missing required field is an error). With html and engine it compiles offline and reports syntax errors, unknown filters and variables missing from data. Returns ok and diagnostics (severity, code, message, plus path, line and column, or part and paragraph for Word and PowerPoint). Warnings leave ok true: settle each before rendering.",
       inputSchema: {
         template: z3.string().optional().describe("Slug or tpl_ id of a stored template; pass this or html"),
+        version: z3.union([z3.string().min(1).max(32), z3.number().int().positive()]).optional().describe(
+          "With template: the version to check, such as latest for the newest draft or a number; left out, the published one, else the latest"
+        ),
         html: z3.string().optional().describe(
           "Template source to check offline, when there is no stored template; pass this or template"
         ),
@@ -84125,28 +84246,21 @@ function createFormfeedServer(options) {
       },
       annotations: READS
     },
-    async ({ template, html, engine, data }) => {
+    async ({ template, version, html, engine, data }) => {
       try {
         if (template) {
-          const check = (version) => api().templates.validate(template, {
-            version,
+          const check = (which) => api().templates.validate(template, {
+            version: which,
             ...data ? { data } : {}
           });
-          const result = await check("published").catch((e) => {
+          const result = version !== void 0 ? await check(String(version)) : await check("published").catch((e) => {
             if (e.status === 404) return check("latest");
             throw e;
           });
           return text3({
             ok: result.ok,
             template: result.template,
-            diagnostics: result.diagnostics.map((d) => ({
-              severity: d.severity,
-              code: d.code,
-              message: d.message,
-              ...d.path ? { path: d.path } : {},
-              ...d.location ? { line: d.location.line, column: d.location.column } : {},
-              ...d.part ? { part: d.part, paragraph: d.paragraph } : {}
-            }))
+            diagnostics: result.diagnostics.map(diagnosticOf)
           });
         }
         if (!html || !engine)
@@ -84184,6 +84298,166 @@ function createFormfeedServer(options) {
       }
     }
   );
+  server.registerTool(
+    "save_template",
+    {
+      title: "Save a template as a draft",
+      description: "Saves a template as a draft, never published: renders keep using the published version until a person publishes the draft in Formfeed. With template and base_checksum it saves a new version of that template: read it with get_template_source first, change what the user asked for, and pass only the parts you changed (the others are kept from the version you read). With new_template and html it creates a template whose version 1 is the draft. change_note says what changed; the person reads it before publishing. Returns the saved version, the check of the draft with its sample data (fix every error and save again) and review_url, the page where the person reviews and publishes it: hand that to the user. Needs an API key with template:write, or, for a signed-in agent, the person's permission under Account \u2192 Connected agents in Formfeed. Word and PowerPoint templates cannot be saved here. Free; a new template counts towards the plan's template limit.",
+      inputSchema: {
+        template: z3.string().optional().describe(
+          "Slug or tpl_ id of the template to save a new draft of; pass this or new_template"
+        ),
+        base_checksum: z3.string().max(80).optional().describe(
+          "With template: the checksum get_template_source returned. When someone saved a newer version since, nothing is saved: read the source again and redo the change on it"
+        ),
+        new_template: z3.object({
+          slug: slugSchema,
+          name: z3.string().min(1).max(200),
+          kind: z3.enum(["pdf", "image"]).describe("pdf for documents, image for pictures"),
+          engine: engineSchema.describe("The template language of html"),
+          description: z3.string().max(2e3).optional(),
+          tags: z3.array(z3.string().max(40)).max(20).optional().describe("Lowercase with dashes, e.g. billing")
+        }).optional().describe(
+          "Creates a template whose version 1 is this draft; pass this and html, or template"
+        ),
+        ...sourceParts,
+        change_note: z3.string().min(1).max(500).describe(
+          "What the draft changes, in one sentence, shown in the version history"
+        )
+      },
+      outputSchema: {
+        template: z3.object({
+          id: z3.string().describe("tpl_ id"),
+          slug: z3.string(),
+          name: z3.string(),
+          published_version: z3.number().nullable().describe(
+            "The version renders still use; null when nothing is published yet"
+          )
+        }),
+        version: z3.object({
+          number: z3.number(),
+          status: z3.string().describe("draft"),
+          checksum: z3.string().describe("base_checksum for a further change to this draft")
+        }),
+        ok: z3.boolean().nullable().describe(
+          "false when the check of the draft found an error; null when the check could not run"
+        ),
+        diagnostics: z3.array(diagnosticOutput),
+        review_url: z3.string().optional().describe(
+          "The page in Formfeed where the person reviews and publishes the draft"
+        ),
+        next: z3.string()
+      },
+      annotations: CREATES
+    },
+    async (args2) => {
+      const { template, base_checksum, new_template, change_note } = args2;
+      try {
+        if (!template === !new_template)
+          return failure(
+            new Error(
+              "Pass template with base_checksum to save a new draft of a template, or new_template with html to create one"
+            )
+          );
+        let saved;
+        let slug;
+        if (template) {
+          if (!base_checksum)
+            return failure(
+              new Error(
+                "Pass base_checksum: read the template with get_template_source, change it, and save it with the checksum you read"
+              )
+            );
+          const [tpl2, base] = await Promise.all([
+            api().templates.get(template),
+            api().templates.versions.get(template, "latest")
+          ]);
+          if (tpl2.kind === "docx" || tpl2.kind === "pptx")
+            return failure(
+              new Error(
+                `${tpl2.slug} is a ${tpl2.kind === "docx" ? "Word" : "PowerPoint"} template: its document is changed in ${tpl2.kind === "docx" ? "Word" : "PowerPoint"} and uploaded in Formfeed, not saved here`
+              )
+            );
+          if (base.checksum !== base_checksum)
+            return failure(
+              new Error(
+                "conflict: someone saved a newer version of this template since you read it. Read it again with get_template_source and make the change on that version"
+              )
+            );
+          saved = await api().templates.versions.create(template, {
+            html: args2.html ?? base.html ?? "",
+            css: args2.css ?? base.css,
+            head: args2.head ?? base.head,
+            settings: args2.settings ?? base.settings,
+            sample_data: args2.sample_data ?? base.sample_data,
+            data_sets: args2.data_sets ?? base.data_sets,
+            data_schema: args2.data_schema !== void 0 ? args2.data_schema : base.data_schema,
+            i18n: args2.i18n !== void 0 ? args2.i18n : base.i18n,
+            partials: args2.partials ?? base.partials,
+            change_note,
+            base_checksum,
+            publish: false
+          });
+          slug = tpl2.slug;
+        } else {
+          if (!new_template || args2.html === void 0)
+            return failure(new Error("html is required for a new template"));
+          const created = await api().templates.create({
+            ...new_template,
+            html: args2.html,
+            css: args2.css,
+            head: args2.head,
+            settings: args2.settings,
+            sample_data: args2.sample_data,
+            data_sets: args2.data_sets,
+            data_schema: args2.data_schema,
+            i18n: args2.i18n,
+            partials: args2.partials,
+            change_note,
+            publish: false
+          });
+          slug = created.slug;
+          saved = await api().templates.versions.get(slug, "latest");
+        }
+        const origin = appOrigin(options.baseUrl);
+        const [tpl, check, account] = await Promise.all([
+          api().templates.get(slug),
+          // the check of the draft itself, with its sample data; a check that cannot run leaves the draft saved
+          api().templates.validate(slug, { version: String(saved.number) }).then(
+            (result) => ({ result, error: null }),
+            (e) => ({
+              result: null,
+              error: e instanceof Error ? e.message : String(e)
+            })
+          ),
+          origin ? api().account.get().catch(() => null) : Promise.resolve(null)
+        ]);
+        const org = slugIn(account, "organization");
+        const workspace = slugIn(account, "workspace");
+        return text3({
+          template: {
+            id: tpl.id,
+            slug: tpl.slug,
+            name: tpl.name,
+            published_version: tpl.published_version
+          },
+          version: {
+            number: saved.number,
+            status: saved.status,
+            checksum: saved.checksum
+          },
+          ok: check.result ? check.result.ok : null,
+          diagnostics: check.result ? check.result.diagnostics.map(diagnosticOf) : [],
+          ...origin && org && workspace ? {
+            review_url: `${origin}/o/${org}/w/${workspace}/templates/${tpl.slug}`
+          } : {},
+          next: check.result ? `Saved as draft version ${saved.number}; nothing is published. Ask the person to review it in Formfeed and publish it there.` : `Saved as draft version ${saved.number}; nothing is published. The check could not run (${check.error}): call validate_template with version ${saved.number} before asking the person to publish it.`
+        });
+      } catch (e) {
+        return failure(e);
+      }
+    }
+  );
   server.registerTool(
     "check_invoice",
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@formfeed/mcp",
-  "version": "0.3.20",
+  "version": "0.3.21",
   "mcpName": "io.github.formfeed-dev/formfeed",
   "description": "Model Context Protocol server for Formfeed: list templates, read data schemas, validate and render documents from AI agents.",
   "license": "MIT",