@fenfill/mcp 0.2.0 → 0.2.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +86 -35
- package/THIRD_PARTY_NOTICES +1 -1
- package/dist/index.js +916 -210
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -127,27 +127,39 @@ cancelling the call ends the wait. `too_many_active_jobs` counts every running a
|
|
|
127
127
|
workspace, free native-field (AcroForm) ones included.
|
|
128
128
|
|
|
129
129
|
`fill_form` and `fill_template` take `values`, `output_path` (a new `.pdf`) and optional
|
|
130
|
-
`overwrite`. They never overwrite the input PDF.
|
|
130
|
+
`overwrite`. They never overwrite the input PDF. In `values` (here and in `preview_page`), an id
|
|
131
|
+
may be shortened to an unambiguous prefix of 6+ characters, the length of the preview tags; that
|
|
132
|
+
goes for a table's cell or column ids inside its value too. A key that matches nothing is listed
|
|
133
|
+
in `skipped`.
|
|
131
134
|
|
|
132
135
|
### Previews and corrections
|
|
133
136
|
|
|
134
137
|
`preview_page` takes `path` (an analyzed PDF) or `template_id`, a 1-based `page`, optional
|
|
135
138
|
`values` (to see them stamped; the same shapes as `fill_form`, e.g. `table_rows` =
|
|
136
139
|
`[{columnId: value}, …]`, `multiselect` = an array of option ids or labels) and `dpi` (default
|
|
137
|
-
110, max 200).
|
|
140
|
+
110, max 200). The image's longest side is capped at 2,000 px, the size clients show without
|
|
141
|
+
shrinking it, so the `width` and `height` in the result are the image the agent sees; the
|
|
142
|
+
result's `dpi` is the resolution actually rendered (a whole A4 page tops out near 171, and
|
|
143
|
+
`crop` + `zoom` give more detail). It returns a PNG image plus a legend: each box's tag, id, type, label and `box`;
|
|
138
144
|
a text/date field's stored `format` and `font_pt` (the size its value starts at; `font_auto`
|
|
139
145
|
when that follows the box height); a choice's options with their own boxes; a table's cells by
|
|
140
146
|
`(row, col)`, its `orientation` and headers (also printed on the image inside, or beside, the
|
|
141
|
-
first cell of each line as `R: …` / `C:
|
|
147
|
+
first cell of each line as `R: …` / `C: …`; a character the bundled fonts lack is shown as `?`
|
|
148
|
+
there, with a warning, and the legend keeps the full text); a `table_rows` table's columns and printed cells
|
|
142
149
|
with their boxes (fill values still go by column id). `warnings` and `placement_warnings` are
|
|
143
150
|
always present (`[]` = checked and clean): placement covers every box shown, so a plain preview
|
|
144
151
|
is a read-only placement audit (see the checks under `edit_template`). `crop`
|
|
145
152
|
(`{x, y, w, h}`, fractions) with `zoom` (default 2, max 8) renders just a region, magnified, and
|
|
146
|
-
lists only what it shows
|
|
153
|
+
lists only what it shows (convert a position read off a crop by proportion: `x = crop.x + crop.w ×
|
|
154
|
+
pixel x / image width`); `legend: "changed"` returns only the rows that changed since your last
|
|
147
155
|
preview of that page (the first time: since fenfill's version), each with only its changed
|
|
148
156
|
options/cells/columns (`members_changed` counts them, so a header edit doesn't list the whole
|
|
149
157
|
grid), plus `removed` ids and `moved_into` (ids that now sit inside a table or group), and
|
|
150
|
-
`legend: "none"` omits the legend.
|
|
158
|
+
`legend: "none"` omits the legend. `overlay` says what is drawn over the page: `"full"` (the
|
|
159
|
+
default), `"outline"` (the boxes without id tags and table header texts) or `"none"` (nothing:
|
|
160
|
+
the page as a fill stamps it). Use the last two when a tag covers a caption, a tick box or a
|
|
161
|
+
stamped value; `"none"` needs no outlined copy, so it also renders after `check_copy_failed`.
|
|
162
|
+
The legend and `placement_warnings` are the same in all three. It renders the local working copy (`edit_template`) when there is one, otherwise the saved
|
|
151
163
|
template or analyzed version; `edited: true` / `false` in the result says which. The page is rendered on your machine by
|
|
152
164
|
PDFium (WebAssembly, shipped in the package; nothing native is installed), nothing is written to
|
|
153
165
|
disk, and the image goes only to the calling client.
|
|
@@ -160,7 +172,10 @@ disk, and the image goes only to the calling client.
|
|
|
160
172
|
`set_placeholder`, `set_autofill` (a browser autofill token such as `name` or `postal-code`,
|
|
161
173
|
or `null` to clear it);
|
|
162
174
|
- choices and combs: `group` (`kind: "choice" | "comb"`), `ungroup`, `set_options`, and
|
|
163
|
-
`add_option` / `remove_option`, which keep the group's id;
|
|
175
|
+
`add_option` / `remove_option`, which keep the group's id; `set_format` on a comb group takes
|
|
176
|
+
`cell_type` (`char`, `integer` or `date`) and `date_format` (one `D`, `M` or `Y` per cell, e.g.
|
|
177
|
+
`DDMMYYYY`). Giving a `date_format` makes it a date comb, and `diff_summary.ops` echoes the
|
|
178
|
+
comb's `cell_type`, `date_format` and `max_length` as a fill will read them;
|
|
164
179
|
- tables: `group` with `kind: "table"` (a `cells` grid of field ids, rows × columns with `null`
|
|
165
180
|
for a gap, or `ids` laid out from their boxes; `header_cols`, `header_rows`, `orientation`,
|
|
166
181
|
`format`), `table_insert` / `table_delete` (a row or column; a new line's geometry is
|
|
@@ -171,6 +186,14 @@ disk, and the image goes only to the calling client.
|
|
|
171
186
|
- order: `reorder {page, ids}` moves those top-level entries together, in that order, to where
|
|
172
187
|
the first of them sat, and stamps an explicit `order` on every entry of the page (the web
|
|
173
188
|
editor's layer-panel convention), so a later sub-pixel move no longer reshuffles questions.
|
|
189
|
+
`diff_summary.ops` shows the `order` the page is now listed in. fenfill lists each section as
|
|
190
|
+
one run, standing where its first entry stands, so entries of different sections never stand
|
|
191
|
+
together whatever their ranks: `reorder` warns, naming the sections, when the ids did not all
|
|
192
|
+
come out as asked, and rejects such an order when it would change nothing in the listing;
|
|
193
|
+
- sections: `set_section {ids, section_id}` moves fields or groups of one page to another of
|
|
194
|
+
that page's sections (`null`: out of every section; a group moves with all its members), and
|
|
195
|
+
`set_section_title {page, section_id, title}` renames one. `get_template` and `analyze_form`
|
|
196
|
+
show each section's `section_id`.
|
|
174
197
|
|
|
175
198
|
Any id can be shortened to an unambiguous prefix of 6+ characters (the length of the preview
|
|
176
199
|
tags); an ambiguous prefix is rejected with the candidates. `add`, `move` and `set_box` take an
|
|
@@ -181,7 +204,8 @@ box, the box is kept and a warning says so. Snap finds printed rules with its ow
|
|
|
181
204
|
finder (one ink threshold per page, not the web editor's wand): a very faint rule on a tinted
|
|
182
205
|
scan can be missed, and an underline box is one line of handwriting tall (as tall as the clear
|
|
183
206
|
space above the rule, within about 11–16 pt). `diff_summary.ops` lists every applied op with
|
|
184
|
-
`snapped: true/false` (when it asked for a snap) and `noop: true` when it changed nothing
|
|
207
|
+
`snapped: true/false` (when it asked for a snap) and `noop: true` when it changed nothing; a
|
|
208
|
+
batch that leaves the form as it was writes no working copy (`has_edits` stays `false`). After
|
|
185
209
|
each edit, the boxes you touched are checked for three placement problems: a value that would
|
|
186
210
|
print much larger than the page's other fields (an Auto box's text size follows its height), a
|
|
187
211
|
box over printed text (text layer only, so not on scans), and a box that runs a little past the
|
|
@@ -191,11 +215,26 @@ Coordinates are fractions of the page (0–1) with a top-left origin, the same a
|
|
|
191
215
|
`box`. Each op is checked against the rules fenfill applies when saving and is rejected with a
|
|
192
216
|
reason if it breaks them; ops apply in order, all-or-nothing each, except that a box only has to
|
|
193
217
|
lie on the page after the whole batch (so `move` then `resize` works even if the moved box
|
|
194
|
-
overhangs the page in between). `discard: true` drops the working copy
|
|
218
|
+
overhangs the page in between). `discard: true` drops the working copy (`ops` may then be left
|
|
219
|
+
out). Labels, descriptions,
|
|
195
220
|
placeholders, options, date formats and checkbox symbols are the form's wording, never answers:
|
|
196
221
|
an op whose new wording matches an answer given to `fill_form`, `fill_template` or
|
|
197
222
|
`preview_page` in the same session is rejected before the working copy is written (wording that
|
|
198
|
-
|
|
223
|
+
holds an answer of 6+ characters, or equals one of 4–5; equal to a shorter one only warns). A
|
|
224
|
+
one-word answer is held only as a whole word, so the test value `exempt` does not flag the
|
|
225
|
+
caption `exemption`; an answer of several words, or one without letters (a number, a phone
|
|
226
|
+
number, a date), is caught wherever it occurs. An answer is known as you passed it and as the
|
|
227
|
+
page shows it: a date in its field's printed format (`1990-05-17` as `17.05.1990`), a comb's
|
|
228
|
+
characters without the separators typed between them, an answer of several lines also line by
|
|
229
|
+
line. A date written a third way (`17/05/1990`) is not recognised. The values of a fill or
|
|
230
|
+
preview that failed before the form was read (an output file that already exists, a failed
|
|
231
|
+
download) count as answers too. The reason names the entry and the property (a section with
|
|
232
|
+
its page), never the text. A printed caption can share a word with a test value (`Middle name` after
|
|
233
|
+
previewing `Middle`): when the rejected wording is the form's own, send the op again with
|
|
234
|
+
`confirm_wording: true`. That lets through only wording a rejection has already named (that
|
|
235
|
+
text in that property), and what you confirmed is the wording: it is not asked about again in
|
|
236
|
+
that session, on any entry. Previewing with values that are not words printed on the form
|
|
237
|
+
avoids the round trip.
|
|
199
238
|
Once a PDF is saved as a template, `fill_form` and `preview_page` on it use only that template's
|
|
200
239
|
working copy; an older copy of its unsaved analysis is dropped.
|
|
201
240
|
|
|
@@ -203,12 +242,22 @@ working copy; an older copy of its unsaved analysis is dropped.
|
|
|
203
242
|
from: if the template changed in fenfill meanwhile, it answers `template_conflict` and keeps your
|
|
204
243
|
local edits. Before anything is sent, it refuses wording that matches an answer given to
|
|
205
244
|
`fill_form`, `fill_template` or `preview_page` in the same session (that list lives only in
|
|
206
|
-
memory)
|
|
207
|
-
|
|
208
|
-
|
|
245
|
+
memory): `answer_in_template` lists the matched ids and properties in `matched`, never their
|
|
246
|
+
text (a section comes with its `page`, since section ids repeat from page to page). Fix an
|
|
247
|
+
answer with `edit_template`; when the wording is the form's own, call again with
|
|
248
|
+
`confirm_wording: true`, and the save names what it sent on your confirmation in `warnings`.
|
|
249
|
+
An entry no error has listed yet is refused and listed first, even with the flag set; an entry
|
|
250
|
+
listed for one template is not thereby listed for another. A working
|
|
251
|
+
copy edited in an earlier session can't be checked against that session's answers:
|
|
252
|
+
`save_template` then answers `confirm_wording_needed` with the changed ids and properties (never
|
|
253
|
+
their text); review them and call again with `confirm_wording: true` (the flag on the first
|
|
254
|
+
call gets the list first, too, and so does a copy whose wording changed after the list was
|
|
255
|
+
sent). An
|
|
209
256
|
unsaved analysis can be edited for filling but not saved: to keep corrections,
|
|
210
257
|
analyze with `save_as_template: true` and edit that template. With nothing to save, it succeeds
|
|
211
|
-
with `saved: false, nothing_to_save: true`. `get_template`
|
|
258
|
+
with `saved: false, nothing_to_save: true`. `get_template` lists the fields in `sections`, in fenfill's order: one
|
|
259
|
+
block per section (with its `section_id` and `title`), and fields in no section as blocks of
|
|
260
|
+
their own where they stand. It says `has_local_edits` (its fields
|
|
212
261
|
are fenfill's saved version; `preview_page` shows the working copy) and gives `field_count`
|
|
213
262
|
(entries listed) and `field_count_total` (the whole form); `save_template`'s `field_count` is
|
|
214
263
|
the whole saved template.
|
|
@@ -287,7 +336,8 @@ fenfill web app for that workspace (for example, your logo if you have set one u
|
|
|
287
336
|
your user) holds form schemas, blank template PDFs, the workspace logo, sha256 hashes of the
|
|
288
337
|
PDFs it produced and `edit_template`'s working copies, **never the answers you fill in**. A
|
|
289
338
|
working copy holds the layout plus the wording the agent wrote with `edit_template`; the echo
|
|
290
|
-
guard refuses wording that repeats an answer seen in the same session before it is written
|
|
339
|
+
guard refuses wording that repeats an answer seen in the same session before it is written,
|
|
340
|
+
unless the agent, told which property matched, confirms that it is the form's own wording.
|
|
291
341
|
- **Cache cleanup:** at startup and at most once a day it deletes blank PDFs and the logo after
|
|
292
342
|
1 hour, analyses and working copies unused for 90 days, stale job records after 48 hours, and
|
|
293
343
|
output hashes after a year.
|
|
@@ -300,27 +350,28 @@ fenfill web app for that workspace (for example, your logo if you have set one u
|
|
|
300
350
|
|
|
301
351
|
## Troubleshooting
|
|
302
352
|
|
|
303
|
-
| Error | What to do
|
|
304
|
-
| ------------------------------------- |
|
|
305
|
-
| `missing_api_key` / `invalid_api_key` | Set `FENFILL_API_KEY` in the client's config and restart the client.
|
|
306
|
-
| `plan_required` | The workspace needs a paid plan (Pro and up).
|
|
307
|
-
| `insufficient_scans` | Not enough page scans left; analyze fewer `pages` or check `get_account`.
|
|
308
|
-
| `prefilled_form` / `filled_output` | Only blank forms can be analyzed; use the original, empty PDF. If it is the blank form (some ship with default text in their fields), use the fenfill web app.
|
|
309
|
-
| `pdf_password_required` | Remove the open password first; owner-password PDFs work as they are.
|
|
310
|
-
| `pdf_fill_forbidden` | The PDF's author forbids form filling; fenfill won't fill it. Use a copy that allows filling.
|
|
311
|
-
| `not_analyzed` | Run `analyze_form` on the same file (and pages) before `fill_form`.
|
|
312
|
-
| `output_exists` | Pick a new `output_path` or pass `overwrite: true`.
|
|
313
|
-
| `rate_limited` / `queue_full` | `analyze_form` already waited about a minute (`waited_s`); try again later.
|
|
314
|
-
| `too_many_active_jobs` | Other analyses in the workspace (free native-field ones too) are still running; try again in a minute, or analyze fewer at once.
|
|
315
|
-
| `template_conflict` | The template changed in fenfill since your edits began. Your local edits are kept: `edit_template` with `discard: true`, re-apply the ops, save again.
|
|
316
|
-
| `invalid_schema` | fenfill (or the local check before it) refused the edited layout; `details` lists each item and reason. Fix them with `edit_template`.
|
|
317
|
-
| `
|
|
318
|
-
| `
|
|
319
|
-
| `
|
|
320
|
-
| `
|
|
321
|
-
| `
|
|
322
|
-
| `
|
|
323
|
-
| `
|
|
353
|
+
| Error | What to do |
|
|
354
|
+
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
355
|
+
| `missing_api_key` / `invalid_api_key` | Set `FENFILL_API_KEY` in the client's config and restart the client. |
|
|
356
|
+
| `plan_required` | The workspace needs a paid plan (Pro and up). |
|
|
357
|
+
| `insufficient_scans` | Not enough page scans left; analyze fewer `pages` or check `get_account`. |
|
|
358
|
+
| `prefilled_form` / `filled_output` | Only blank forms can be analyzed; use the original, empty PDF. If it is the blank form (some ship with default text in their fields), use the fenfill web app. |
|
|
359
|
+
| `pdf_password_required` | Remove the open password first; owner-password PDFs work as they are. |
|
|
360
|
+
| `pdf_fill_forbidden` | The PDF's author forbids form filling; fenfill won't fill it. Use a copy that allows filling. |
|
|
361
|
+
| `not_analyzed` | Run `analyze_form` on the same file (and pages) before `fill_form`. |
|
|
362
|
+
| `output_exists` | Pick a new `output_path` or pass `overwrite: true`. |
|
|
363
|
+
| `rate_limited` / `queue_full` | `analyze_form` already waited about a minute (`waited_s`); try again later. |
|
|
364
|
+
| `too_many_active_jobs` | Other analyses in the workspace (free native-field ones too) are still running; try again in a minute, or analyze fewer at once. |
|
|
365
|
+
| `template_conflict` | The template changed in fenfill since your edits began. Your local edits are kept: `edit_template` with `discard: true`, re-apply the ops, save again. |
|
|
366
|
+
| `invalid_schema` | fenfill (or the local check before it) refused the edited layout; `details` lists each item and reason. Fix them with `edit_template`. |
|
|
367
|
+
| `check_copy_failed` | `preview_page` could not build its outlined copy; `stage` and `id` say where. Fix or remove that field or group with `edit_template`, then preview again; `overlay: "none"` still shows the page meanwhile. |
|
|
368
|
+
| `request_too_large` | The edited template is too large to save in one request. |
|
|
369
|
+
| `answer_in_template` | Edited wording matches an answer from this session, so nothing was sent; `matched` lists the ids and properties. An answer: put the form's own wording back with `edit_template`. The form's own wording: `save_template` again with `confirm_wording: true`. |
|
|
370
|
+
| `confirm_wording_needed` | The working copy has wording edited in an earlier session. Review the ids and properties in `changed`, then `save_template` with `confirm_wording: true`. |
|
|
371
|
+
| `local_edits_pending` | `reanalyze_template` won't run over unsaved edits: `save_template` them first, or pass `discard: true`. |
|
|
372
|
+
| `kind_required` | The pages already have fields: pass `kind` (`find`, `relabel`, `label_missing`, or `scratch` to replace them). |
|
|
373
|
+
| `job_in_progress` | A job is already running on the template; wait and retry (call `reanalyze_template` again with the same arguments if you started it). |
|
|
374
|
+
| `upload_outcome_unknown` | An earlier upload was interrupted. To avoid charging twice, the same file isn't re-uploaded for about 10 minutes; check `get_account` meanwhile. |
|
|
324
375
|
|
|
325
376
|
## API
|
|
326
377
|
|
package/THIRD_PARTY_NOTICES
CHANGED