@fenfill/mcp 0.2.1 → 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 +84 -35
- package/THIRD_PARTY_NOTICES +1 -1
- package/dist/index.js +744 -158
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -127,14 +127,20 @@ 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
|
|
@@ -144,11 +150,16 @@ with their boxes (fill values still go by column id). `warnings` and `placement_
|
|
|
144
150
|
always present (`[]` = checked and clean): placement covers every box shown, so a plain preview
|
|
145
151
|
is a read-only placement audit (see the checks under `edit_template`). `crop`
|
|
146
152
|
(`{x, y, w, h}`, fractions) with `zoom` (default 2, max 8) renders just a region, magnified, and
|
|
147
|
-
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
|
|
148
155
|
preview of that page (the first time: since fenfill's version), each with only its changed
|
|
149
156
|
options/cells/columns (`members_changed` counts them, so a header edit doesn't list the whole
|
|
150
157
|
grid), plus `removed` ids and `moved_into` (ids that now sit inside a table or group), and
|
|
151
|
-
`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
|
|
152
163
|
template or analyzed version; `edited: true` / `false` in the result says which. The page is rendered on your machine by
|
|
153
164
|
PDFium (WebAssembly, shipped in the package; nothing native is installed), nothing is written to
|
|
154
165
|
disk, and the image goes only to the calling client.
|
|
@@ -161,7 +172,10 @@ disk, and the image goes only to the calling client.
|
|
|
161
172
|
`set_placeholder`, `set_autofill` (a browser autofill token such as `name` or `postal-code`,
|
|
162
173
|
or `null` to clear it);
|
|
163
174
|
- choices and combs: `group` (`kind: "choice" | "comb"`), `ungroup`, `set_options`, and
|
|
164
|
-
`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;
|
|
165
179
|
- tables: `group` with `kind: "table"` (a `cells` grid of field ids, rows × columns with `null`
|
|
166
180
|
for a gap, or `ids` laid out from their boxes; `header_cols`, `header_rows`, `orientation`,
|
|
167
181
|
`format`), `table_insert` / `table_delete` (a row or column; a new line's geometry is
|
|
@@ -172,6 +186,14 @@ disk, and the image goes only to the calling client.
|
|
|
172
186
|
- order: `reorder {page, ids}` moves those top-level entries together, in that order, to where
|
|
173
187
|
the first of them sat, and stamps an explicit `order` on every entry of the page (the web
|
|
174
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`.
|
|
175
197
|
|
|
176
198
|
Any id can be shortened to an unambiguous prefix of 6+ characters (the length of the preview
|
|
177
199
|
tags); an ambiguous prefix is rejected with the candidates. `add`, `move` and `set_box` take an
|
|
@@ -182,7 +204,8 @@ box, the box is kept and a warning says so. Snap finds printed rules with its ow
|
|
|
182
204
|
finder (one ink threshold per page, not the web editor's wand): a very faint rule on a tinted
|
|
183
205
|
scan can be missed, and an underline box is one line of handwriting tall (as tall as the clear
|
|
184
206
|
space above the rule, within about 11–16 pt). `diff_summary.ops` lists every applied op with
|
|
185
|
-
`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
|
|
186
209
|
each edit, the boxes you touched are checked for three placement problems: a value that would
|
|
187
210
|
print much larger than the page's other fields (an Auto box's text size follows its height), a
|
|
188
211
|
box over printed text (text layer only, so not on scans), and a box that runs a little past the
|
|
@@ -192,11 +215,26 @@ Coordinates are fractions of the page (0–1) with a top-left origin, the same a
|
|
|
192
215
|
`box`. Each op is checked against the rules fenfill applies when saving and is rejected with a
|
|
193
216
|
reason if it breaks them; ops apply in order, all-or-nothing each, except that a box only has to
|
|
194
217
|
lie on the page after the whole batch (so `move` then `resize` works even if the moved box
|
|
195
|
-
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,
|
|
196
220
|
placeholders, options, date formats and checkbox symbols are the form's wording, never answers:
|
|
197
221
|
an op whose new wording matches an answer given to `fill_form`, `fill_template` or
|
|
198
222
|
`preview_page` in the same session is rejected before the working copy is written (wording that
|
|
199
|
-
|
|
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.
|
|
200
238
|
Once a PDF is saved as a template, `fill_form` and `preview_page` on it use only that template's
|
|
201
239
|
working copy; an older copy of its unsaved analysis is dropped.
|
|
202
240
|
|
|
@@ -204,12 +242,22 @@ working copy; an older copy of its unsaved analysis is dropped.
|
|
|
204
242
|
from: if the template changed in fenfill meanwhile, it answers `template_conflict` and keeps your
|
|
205
243
|
local edits. Before anything is sent, it refuses wording that matches an answer given to
|
|
206
244
|
`fill_form`, `fill_template` or `preview_page` in the same session (that list lives only in
|
|
207
|
-
memory)
|
|
208
|
-
|
|
209
|
-
|
|
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
|
|
210
256
|
unsaved analysis can be edited for filling but not saved: to keep corrections,
|
|
211
257
|
analyze with `save_as_template: true` and edit that template. With nothing to save, it succeeds
|
|
212
|
-
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
|
|
213
261
|
are fenfill's saved version; `preview_page` shows the working copy) and gives `field_count`
|
|
214
262
|
(entries listed) and `field_count_total` (the whole form); `save_template`'s `field_count` is
|
|
215
263
|
the whole saved template.
|
|
@@ -288,7 +336,8 @@ fenfill web app for that workspace (for example, your logo if you have set one u
|
|
|
288
336
|
your user) holds form schemas, blank template PDFs, the workspace logo, sha256 hashes of the
|
|
289
337
|
PDFs it produced and `edit_template`'s working copies, **never the answers you fill in**. A
|
|
290
338
|
working copy holds the layout plus the wording the agent wrote with `edit_template`; the echo
|
|
291
|
-
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.
|
|
292
341
|
- **Cache cleanup:** at startup and at most once a day it deletes blank PDFs and the logo after
|
|
293
342
|
1 hour, analyses and working copies unused for 90 days, stale job records after 48 hours, and
|
|
294
343
|
output hashes after a year.
|
|
@@ -301,28 +350,28 @@ fenfill web app for that workspace (for example, your logo if you have set one u
|
|
|
301
350
|
|
|
302
351
|
## Troubleshooting
|
|
303
352
|
|
|
304
|
-
| Error | What to do
|
|
305
|
-
| ------------------------------------- |
|
|
306
|
-
| `missing_api_key` / `invalid_api_key` | Set `FENFILL_API_KEY` in the client's config and restart the client.
|
|
307
|
-
| `plan_required` | The workspace needs a paid plan (Pro and up).
|
|
308
|
-
| `insufficient_scans` | Not enough page scans left; analyze fewer `pages` or check `get_account`.
|
|
309
|
-
| `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.
|
|
310
|
-
| `pdf_password_required` | Remove the open password first; owner-password PDFs work as they are.
|
|
311
|
-
| `pdf_fill_forbidden` | The PDF's author forbids form filling; fenfill won't fill it. Use a copy that allows filling.
|
|
312
|
-
| `not_analyzed` | Run `analyze_form` on the same file (and pages) before `fill_form`.
|
|
313
|
-
| `output_exists` | Pick a new `output_path` or pass `overwrite: true`.
|
|
314
|
-
| `rate_limited` / `queue_full` | `analyze_form` already waited about a minute (`waited_s`); try again later.
|
|
315
|
-
| `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.
|
|
316
|
-
| `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.
|
|
317
|
-
| `invalid_schema` | fenfill (or the local check before it) refused the edited layout; `details` lists each item and reason. Fix them with `edit_template`.
|
|
318
|
-
| `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.
|
|
319
|
-
| `request_too_large` | The edited template is too large to save in one request.
|
|
320
|
-
| `answer_in_template` | Edited wording matches an answer from this session, so nothing was sent.
|
|
321
|
-
| `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`.
|
|
322
|
-
| `local_edits_pending` | `reanalyze_template` won't run over unsaved edits: `save_template` them first, or pass `discard: true`.
|
|
323
|
-
| `kind_required` | The pages already have fields: pass `kind` (`find`, `relabel`, `label_missing`, or `scratch` to replace them).
|
|
324
|
-
| `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).
|
|
325
|
-
| `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.
|
|
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. |
|
|
326
375
|
|
|
327
376
|
## API
|
|
328
377
|
|
package/THIRD_PARTY_NOTICES
CHANGED