Skip to content

Releases

v3.2.1

Choose a tag to compare

@github-actions github-actions released this 30 Sep 20:25

Safer tag edits and fewer calls when an agent files or reads documents. Tested against Paperless-ngx 3.2.1, the latest Paperless release. No breaking changes: every new parameter is optional.

Upgrading: start a new chat after updating. A chat that was already open can keep using the old tool definitions and won't see the new parameters.

Fixed

  • update_document could silently drop tags. tags replaces the document's whole tag list, and the tool didn't say so, so adding one tag from an incomplete list removed the others. The new add_tags / remove_tags change single tags and leave the rest alone; passing tags together with either is refused. Every tag change, including a full tags replace, now returns tag_changes: { added, removed }, so a dropped tag shows up in the result.
  • An empty search_documents result looked final. Paperless updates its full-text index in the background, so the index can lag behind or miss documents and "No documents found" wasn't always true. The empty result now says so and points to list_documents search, which matches straight from the database.

Added

  • get_filing_options: every tag, correspondent, document type, storage path and custom field in one call (id and name, sorted by name; tags also show is_inbox_tag, custom fields their data_type). One call instead of five before filing a document, and it still works when a client hasn't loaded one of the list_* tools.
  • list_documents ids (Paperless id__in): read several known documents in one call.
  • fields on list_documents and get_document: return only the fields you need, e.g. ["title", "tags"]. id is always included, and correspondent, type, tag and custom-field names are still resolved.
  • get_document_content max_chars / offset: read a long document in slices. The result then adds offset, total_chars and truncated; without either parameter the output is unchanged.
  • search_documents mode: query (the default; advanced syntax with AND/OR/NOT, quoted phrases, field:value and wildcards), text (plain words, no syntax) or title (titles only).

Changed

  • Workflow trigger filters now say which trigger types use them. sources, filter_path and filter_mailrule apply only to consumption-started triggers (type 1). The tag, correspondent, document-type and storage-path filters, filter_custom_field_query and content matching apply only to added, updated and scheduled triggers (types 2–4). filter_filename applies to all four.
  • list_documents search now explains what it matches: a case-insensitive substring match on title, correspondent name and content, read straight from the database, where every word must appear. Use search_documents for ranked full-text search.
  • update_document title notes that Paperless derives the stored file name from the title and replaces characters not allowed in file names (such as /), so archived_file_name can differ from the title.
  • The server instructions point to get_filing_options for looking up everything a document can be filed under.

Full Changelog: v3.2.0...v3.2.1

v3.2.0

Choose a tag to compare

@github-actions github-actions released this 23 Sep 22:41

Aligns the tool surface with Paperless-ngx 3.2 and drops support for older Paperless versions.

Fixed

  • Workflow actions could not express 4 of the 8 action types. create_workflow_action / update_workflow_action now accept types 5 (password removal), 6 (move to trash), 7 (remote OCR) and 8 (apply AI suggestions) with their fields (passwords, ai_suggestion_fields, ai_create_missing, ai_overwrite_existing), plus assign_custom_fields_values and the per-item removal lists (remove_correspondents, remove_document_types, remove_storage_paths, remove_owners, remove_view_*, remove_change_*).
  • Workflow triggers used the legacy singular filters. Triggers now take the any/all/not forms the web UI writes (filter_has_all_tags, filter_has_not_tags, filter_has_any_* / filter_has_not_* for correspondents, document types and storage paths) and filter_custom_field_query. matching_algorithm is limited to 0–5, the range triggers support.
  • list_documents documented a custom_field_query syntax Paperless rejects. The description now gives the JSON expression syntax (["Amount", "gte", 100], ["AND", […]]).
  • Paperless error details were dropped. Validation errors ({"non_field_errors": ["password not specified"]}) and plain-text errors ("AI is required for this feature") now appear in the tool error instead of a bare "status code 400" — for every JSON API call and for version uploads; post_document uploads still report only the status. HTML error pages are still reduced to the status line.
  • A slow Paperless response could leave a tool call hanging until the MCP client gave up. Every JSON API call now has a 90-second overall deadline and fails with a message naming the endpoint. Downloads are exempt.
  • list_tasks limit above 25 returned only 25 tasks; it is now passed to the server as the page size.
  • list_trash returned the full text of every trashed document, which could overflow the model's context. Content is now left out, as in list_documents.

Added

  • Workflows: list_workflows, get_workflow, create_workflow, update_workflow, delete_workflow. A workflow, with its nested triggers and actions, is what Paperless actually runs; standalone triggers and actions do nothing on their own (and Paperless deletes unattached ones whenever a workflow is updated). get_workflow output can be edited and sent straight back to update_workflow; create_workflow ignores nested ids, so copying a workflow never takes over the original's triggers. Webhook actions gain as_json and include_document.
  • Document versions: upload_document_version (reports the document's document_id and the new version_id), update_document_version, delete_document_version, merge_documents_as_versions.
  • edit_documents_bulk: method remove_password (with update_document: true the unlocked file becomes a new version), remote_ocr for method reprocess, and all + filters (+ excluded_documents) to select every matching document, e.g. to reassign all documents of a duplicate correspondent in one call. Filter keys Paperless would silently ignore (which would select every document) are refused, invalid values are caught by a preview query, and the result reports matched_documents.
  • list_documents: has_duplicates filter.
  • Mail: list/get/create/update/delete_mail_account, test_mail_account (pass a saved account's id to test it with its stored password), process_mail_account, list/get/create/update/delete_mail_rule.
  • Share link bundles: list/get/create/rebuild/delete_share_link_bundle(s).
  • System: get_system_status (includes the Paperless version), get_document_ai_suggestions, list_active_tasks, get_task_status_counts, get_task_summary. list_tasks accepts task_type: apply_ai_suggestions.
  • get_document now explains which fields follow the latest version (content, metadata) and which describe the root (page_count, file names).
  • Distribution: the release workflow now also publishes a Docker image to ghcr.io/cubinet-code/paperless-ngx-mcp (linux/amd64 and linux/arm64; stdio by default, --http for Streamable HTTP), attaches a Claude Desktop extension (paperless-ngx-mcp.mcpb) to each GitHub Release, and lists the server in the official MCP Registry as io.github.cubinet-code/paperless-ngx-mcp.

Changed (BREAKING)

  • Paperless-ngx 2.x is no longer supported. The 2.x compatibility code (task status casing fallback, flat /tasks/ arrays, related_document/result) is gone. Stay on 3.1.1 for Paperless 2.x.
  • list_tasks dropped the 2.x-only filters task_name and type. Use task_type and trigger_source.
  • update_share_link was removed. Paperless has never allowed editing a share link (the endpoint only supports GET and DELETE), so every call failed with HTTP 405. Delete and recreate the link instead.
  • Workflow triggers no longer accept filter_has_correspondent / filter_has_document_type. Use filter_has_any_correspondents / filter_has_any_document_types.
  • edit_documents_bulk documents is optional when all: true + filters is given. Exactly one of the two selection forms is required.

Security

  • Workflow PDF passwords no longer reach the model in clear text. list_workflows, get_workflow, list_workflow_actions, get_workflow_action and the create/update results show the passwords of password-removal actions as **********. Sending the masked list back to update_workflow / update_workflow_action keeps the stored passwords; creating an action from masked passwords is refused.
  • @modelcontextprotocol/sdk 1.30.0 → 1.30.1 (caps JSON-RPC batches at 100 messages) and in-range transitive bumps from npm audit fix: fast-uri 3.1.5 → 3.1.8 (high: host confusion via skipped IDN canonicalization), hono 4.13.1 → 4.13.8 and qs 6.15.3 → 6.16.0 (moderate). npm audit is clean.

Full Changelog: v3.1.1...v3.2.0

v3.1.1

Choose a tag to compare

@github-actions github-actions released this 11 Aug 04:06

Security

  • Cleared 42 Dependabot alerts (9 high, 29 moderate, 4 low) by bumping transitive and direct dependencies within their existing semver ranges — no --force, no breaking changes:
    • @modelcontextprotocol/sdk 1.29.0 → 1.30.0, pulling in patched hono (4.12.17 → 4.13.1) and @hono/node-server (1.19.14 → 2.1.0). Most of the hono advisories (JSX SSR, CORS, cookie/JWT middleware, Lambda adapters) are in code paths this server never exercises — we use Express for our own HTTP transport — but the patched versions clear them regardless.
    • express-rate-limit's ip-address 10.2.0 → 10.5.0 (SSRF/trust-boundary bypasses via octal/CIDR/IPv6-mapped address confusion).
    • axios 1.16.0 → 1.19.0 (prototype pollution, maxBodyLength bypasses, proxy handling).
    • form-data 4.0.5 → 4.0.6 (CRLF injection via unescaped multipart field names).
    • ajv's fast-uri 3.1.0 → 3.1.5 (host confusion / path traversal in URI parsing).
    • express's body-parser 2.2.2 → 2.3.0 and qs 6.15.1 → 6.15.3.
    • Dev-only: tsx 4.21.0 → 4.23.12, pulling in patched esbuild (0.27.7 → 0.28.2; arbitrary file read in esbuild's dev server on Windows — not shipped in the published package).
    • npm audit is now clean (0 vulnerabilities). Verified: tsc --noEmit, 75/75 unit tests, 15/15 e2e against paperless-ngx:2.20.15, including the full HTTP session/SSE suite against the new SDK version.

Full Changelog: v3.1.0...v3.1.1

v3.1.0

Choose a tag to compare

@github-actions github-actions released this 11 Aug 03:59

Fixed

  • The HTTP transport could only serve one client at a time. --http mode shared a single McpServer across every connection, but the MCP SDK binds one server to exactly one transport — so a second concurrent client failed with Already connected to a transport (HTTP 500). Each session now gets its own server instance. The same latent fault affected the legacy /sse endpoint, where a second connection could displace the first; it is fixed there too.
  • HTTP sessions are now durable. POST /mcp issues an Mcp-Session-Id on initialize and reuses it on later requests, instead of treating every request as a fresh stateless exchange. Clients that expect session continuity (per the Streamable HTTP spec) no longer see Session terminated.
  • GET /mcp and DELETE /mcp now work instead of always returning 405. GET opens the server-to-client stream for a session; DELETE terminates it.

Added

  • Session limits, so an unauthenticated port cannot exhaust memory. Each session pins a full server (~3.5 MB), so sessions are capped (default 50, --maxSessions / PAPERLESS_MAX_SESSIONS) and idle sessions are evicted (default 30 minutes, --sessionIdleMinutes / PAPERLESS_SESSION_IDLE_MINUTES). Past the cap, initialize is refused with HTTP 503 rather than allocating. A client that is actively connected — including one holding a GET /mcp stream open — is never evicted, however long it sits idle. /sse connections draw from the same cap, so it is refused with 503 too once the budget is spent — it was previously unbounded even after /mcp was capped.
  • SIGTERM / SIGINT now tear down live sessions before exit.

Changed (BREAKING)

  • --http mode is stateful. Clients that never call initialize, or that call it and then ignore the returned Mcp-Session-Id, previously worked against the stateless server and now receive HTTP 400. Send initialize first and echo the session id back on subsequent requests. Only --http is affected — stdio behaviour is unchanged.
  • GET/DELETE on /mcp without a session id return 400 (was 405); with an unknown or expired session id they return 404.
  • The HTTP startup log line dropped the word Stateless.

Full Changelog: v3.0.0...v3.1.0

v3.0.0

Choose a tag to compare

@github-actions github-actions released this 03 Aug 09:19

Adds support for Paperless-ngx 3.x, which reworked the task API. Paperless 2.x remains supported — the tools detect and adapt to either server.

The version jumps from 0.1.6 to 3.0.0 so the major tracks the Paperless-ngx major it targets. There are no 1.x or 2.x releases of this package.

Fixed

  • list_tasks failed outright against Paperless 3.x. 3.0 paginates /api/tasks/ ({count, next, previous, results}); 2.x returned a bare array. The tool sliced the response directly and died with response.slice is not a function. Both shapes are now accepted and the tool still returns a plain array.
  • post_document with poll: true never completed against Paperless 3.x. Two independent causes, both silent — the upload succeeded but the tool always reported a timeout with no document_id:
    • the consumer poll read /api/tasks/?task_id=… as an array, so it never found its task on 3.x;
    • terminal-state detection compared against uppercase SUCCESS/FAILURE/REVOKED, but 3.x reports lowercase success/failure/revoked. Status comparison is now case-insensitive.
  • post_document returned no document_id on Paperless 3.x even when the consumer succeeded: 3.x replaced the task's related_document with a related_document_ids array. Both are now read.

Added

  • list_tasks gained the Paperless 3.x filters task_type and trigger_source. The 2.x task_name and type filters are kept for older servers. Each server silently ignores the filters it does not know, so the correct pair applies automatically; the tool descriptions say which version each belongs to.
  • task_type covers the task kinds 3.x added: mail_fetch, llm_index, empty_trash, check_workflows, bulk_update, reprocess_document, build_share_link, bulk_delete. Note that 2.x's check_sanity is sanity_check in 3.x.

Changed (BREAKING)

  • list_tasks status values are now lowercase (success, not SUCCESS), matching the 3.x vocabulary. Paperless 2.x requires uppercase and rejects lowercase with a 400, so the tool retries with the other casing and remembers which the server accepted — callers pass lowercase either way.
  • list_tasks no longer accepts status: "RETRY" or "RECEIVED". Paperless 3.x removed both from the task status enum.
  • post_document reports the server's own status casing in its result (success on 3.x, SUCCESS on 2.x) rather than always uppercasing it.

Full Changelog: v0.1.6...v3.0.0

v0.1.6

Choose a tag to compare

@github-actions github-actions released this 29 Jun 04:52

Added

  • post_document can now wait for the consumer. New optional poll flag: when true, the tool waits for the Paperless consumer task to finish and returns the final result in a single call — the new document_id on success, or the consumer error (e.g. InputFileError) on failure — instead of just a task UUID you have to chase via list_tasks. New optional poll_timeout_seconds (default 30, max 300) caps the wait and returns the in-progress status on timeout; raise it for large scans where OCR is slow. Default behaviour is unchanged — without poll, the tool still returns the task UUID immediately.

Fixed

  • post_document no longer misleads callers about the file path option on remote deployments. The file parameter description now makes clear that base64 content is the universal method (the bytes travel over the wire) and that the absolute-path option only works when the MCP server runs on the same machine as the file (local/stdio deployments). When a path can't be read (e.g. a remote server can't see the caller's filesystem), the bare ENOENT is replaced with a message that explains why and tells the caller to pass base64 instead — so an AI client can self-correct instead of dead-ending.

Full Changelog: v0.1.5...v0.1.6

v0.1.5

Choose a tag to compare

@github-actions github-actions released this 07 May 05:48

Security

  • Bumped transitive dependency ip-address to 10.2.0 (via express-rate-limit 8.5.1) to clear GHSA-v2v4-37r5-5v8g — XSS in Address6 HTML-emitting methods. The vulnerable methods were not reachable from this codebase, so no functional change; npm audit is now clean.

Changed

  • Release workflow now extracts release notes from the matching ## [<version>] section of CHANGELOG.md and fails the release if that section is missing. Previous setup derived notes from PR titles, leaving release pages empty when work landed directly on main (as on v0.1.4).

Full Changelog: v0.1.4...v0.1.5

v0.1.4

Choose a tag to compare

@github-actions github-actions released this 07 May 04:53

Highlights: This release fixes two long-standing bugs in edit_documents_bulk (formerly bulk_edit_documents) where modify_custom_fields always returned HTTP 400 and set_permissions always 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 stale Accept: …version=5 header pin, and adds the upstream edit_pdf bulk 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_bulk method modify_custom_fields was always rejected by Paperless with HTTP 400 "add_custom_fields not specified". The wire payload now uses add_custom_fields ({field_id: value} dict, per upstream BulkEditSerializer) and remove_custom_fields (list of ids), and includes both keys whenever the method is modify_custom_fields. Previously the tool emitted assign_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_bulk method set_permissions failed with HTTP 500. set_permissions, owner, and merge are now top-level parameters on the tool (siblings of documents and method), matching the upstream _validate_parameters_set_permissions shape. The previous nested permissions: {set_permissions, owner, merge} wrapper has been removed.
  • Accept: application/json; version=5 header pin removed. The server defaults to its current API version (currently 9), so document, tag, and custom-field responses now include fields like created and user that v5 hid.

Added

  • edit_documents_bulk method edit_pdf is now exposed (added upstream in Paperless-NGX 2.16). Accepts operations: [{page, rotate?, doc?}], plus optional update_document and include_metadata flags.
  • 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 our edit_documents_bulk method enum stays in sync with upstream's MethodEnum.
    • tests/e2e/bulk_edit.e2e.test.ts — round-trips real modify_custom_fields and set_permissions payloads 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.13 to 2.20.15 (latest stable). Required for edit_pdf and 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

v0.1.3

Choose a tag to compare

@github-actions github-actions released this 06 May 02:54

v0.1.3

Internal refactor for code reuse, code quality, and efficiency, plus
a new triage_inbox prompt and a small set of efficiency wins. No
breaking changes — all existing tools accept the same arguments and
return the same response shapes as v0.1.2.

New

  • triage_inbox prompt: an MCP prompt that walks an LLM agent
    through reviewing the Paperless inbox, proposing
    correspondent / document type / tag metadata that prefers existing
    items, and gating execution on explicit user confirmation before
    any writes.

Changed

  • Heavy deduplication across tool files: shared zod field schemas
    (pagination, name filters, matching algorithm, permissions),
    shared helpers for confirmation guards / "deleted" responses /
    Content-Disposition parsing, and a registerBulkEditTool factory
    that collapses three near-identical bulk-edit registrations.
  • list_documents, search_autocomplete, and list_tasks now
    build query strings via the shared helper instead of hand-rolling
    URLSearchParams.
  • PaperlessAPI.request<T> defaults to unknown instead of any;
    bulkEditObjects gained proper type annotations; postDocument
    metadata is typed; unreachable axios status checks removed.
  • documentEnhancer.ts deduplicated against the shared
    CustomFieldInstance type, dead null-input branch removed,
    two-pass map collapsed to one.
  • post_document switched from synchronous fs.readFileSync to
    fs.promises.readFile and tightened base64 validation.
  • Section-divider and dead inline comments removed across the
    codebase; ~50 dead if (!api) throw guards deleted from tool
    handlers.

Performance

  • fetchAllPages parallelizes pages 2..N when the result set
    exceeds one page (Math.ceil(count / 100) pages issued via
    Promise.all). Sequential fallback preserved for small or
    count-less responses.
  • convertDocsWithNames now skips fetching correspondents /
    document types / tags / custom fields when no document in the
    response references that entity type. A get_document on a
    thin record can drop from 4 metadata calls to 0.

Internal

  • New shared helpers in src/tools/utils: schemas.ts,
    responses.ts, bulkEdit.ts, listFilter.ts.
  • Net diff vs v0.1.2: ~800 lines removed, ~350 added.

v0.1.2

Choose a tag to compare

@cubinet-code cubinet-code released this 06 May 02:20

Full Changelog: v0.1.1...v0.1.2