Repository navigation
v0.1.4
Highlights: This release fixes two long-standing bugs in
edit_documents_bulk(formerlybulk_edit_documents) wheremodify_custom_fieldsalways returned HTTP 400 andset_permissionsalways returned HTTP 500. It also renames every bulk operation to a verb-first naming scheme so that wildcard permission allowlists group cleanly by operation, drops a staleAccept: …version=5header pin, and adds the upstreamedit_pdfbulk method. New schema-driven e2e tests now run against a live Paperless 2.20.15 container and will fail when upstream changes its API.
Fixed
edit_documents_bulkmethodmodify_custom_fieldswas always rejected by Paperless with HTTP 400"add_custom_fields not specified". The wire payload now usesadd_custom_fields({field_id: value}dict, per upstreamBulkEditSerializer) andremove_custom_fields(list of ids), and includes both keys whenever the method ismodify_custom_fields. Previously the tool emittedassign_custom_fields/assign_custom_fields_values, neither of which the upstream serializer recognises. Tool input shape is unchanged —add_custom_fields: [{field, value}, …]still works and is now translated to the dict form on the wire.edit_documents_bulkmethodset_permissionsfailed with HTTP 500.set_permissions,owner, andmergeare now top-level parameters on the tool (siblings ofdocumentsandmethod), matching the upstream_validate_parameters_set_permissionsshape. The previous nestedpermissions: {set_permissions, owner, merge}wrapper has been removed.Accept: application/json; version=5header pin removed. The server defaults to its current API version (currently 9), so document, tag, and custom-field responses now include fields likecreatedanduserthat v5 hid.
Added
edit_documents_bulkmethodedit_pdfis now exposed (added upstream in Paperless-NGX 2.16). Acceptsoperations: [{page, rotate?, doc?}], plus optionalupdate_documentandinclude_metadataflags.- Schema-driven e2e tests that fetch the live
/api/schema/from a running Paperless container:tests/e2e/schema_coverage.e2e.test.ts— fails when upstream adds, removes, or renames an endpoint, forcing a triage decision (wrap the new endpoint, or document the skip). Also verifies ouredit_documents_bulkmethod enum stays in sync with upstream'sMethodEnum.tests/e2e/bulk_edit.e2e.test.ts— round-trips realmodify_custom_fieldsandset_permissionspayloads against a real container, asserting observable side effects (custom-field value applied, owner changed, etc.).
- E2e harness now applies each tool's Zod schema before invoking the body, so e2e tests exercise the full input pipeline (schema validation + body + API), the same way the real MCP SDK does.
Changed
- E2e Paperless container bumped from
2.13to2.20.15(latest stable). Required foredit_pdfand current OpenAPI schema coverage.
Changed (BREAKING)
If you upgrade and your AI agent or hand-written client makes bulk operations, read this section.
1. Bulk-operation tool names are now verb-first
Tool names changed so that wildcard-based permission allowlists group cleanly by operation. Migrate any client config (Claude Code permissions, Codex allowlists, Cursor rules, hand-written allowlists) that references the old names:
| Old name | New name |
|---|---|
bulk_download |
download_documents_bulk |
bulk_edit_documents |
edit_documents_bulk |
bulk_edit_tags |
edit_tags_bulk |
bulk_edit_correspondents |
edit_correspondents_bulk |
bulk_edit_document_types |
edit_document_types_bulk |
bulk_edit_custom_fields |
edit_custom_fields_bulk |
Behaviour and parameters are unchanged — only the names. After upgrading, download_* covers single + bulk downloads and edit_*_bulk covers every bulk-edit family. See the README's "Tool naming convention" table for the recommended allowlist patterns.
2. edit_documents_bulk set_permissions parameter shape
If you build set_permissions payloads by hand (vs. letting the LLM produce them), the wrapping permissions: object is gone and set_permissions / owner / merge are siblings at the top level.
edit_documents_bulk({
documents: [1, 2],
method: "set_permissions",
- permissions: {
- set_permissions: { view: { users: [1] }, change: { users: [2] } },
- owner: 1,
- merge: false,
- },
+ set_permissions: { view: { users: [1] }, change: { users: [2] } },
+ owner: 1,
+ merge: false,
})3. edit_documents_bulk modify_custom_fields
The tool's input shape is unchanged (add_custom_fields: [{field, value}, …], remove_custom_fields: [id, …]). What changed is the wire format: it used to silently fail with HTTP 400 on every call, and now succeeds. Anyone who had this method "working" against their server is on a custom fork.
Full Changelog: v0.1.3...v0.1.4