@kjanat/paperless-mcp 2.1.1 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@kjanat/paperless-mcp",
-	"version": "2.1.1",
+	"version": "2.2.0",
 	"description": "MCP server for interacting with Paperless-ngx document management system.",
 	"keywords": [
 		"paperless-ngx",
@@ -32,6 +32,9 @@
 		"meta": "bash scripts/meta.sh",
 		"fmt": "dprint fmt",
 		"fmt:check": "dprint check",
+		"gen": "run -s gen:schema gen:zod fmt",
+		"gen:schema": "python3 scripts/openapi.py extract schemas/openapi.json -o schemas/subset.json",
+		"gen:zod": "openapi-ts",
 		"mcp": "bun src/index.ts",
 		"inspect": "bunx @modelcontextprotocol/inspector run mcp",
 		"prepack": "bun bd",
@@ -39,6 +42,7 @@
 		"typecheck": "tsgo --noEmit"
 	},
 	"devDependencies": {
+		"@hey-api/openapi-ts": "^0.98.1",
 		"@modelcontextprotocol/sdk": "^1.29.0",
 		"@types/bun": "^1.3.14",
 		"@types/express": "^5.0.6",

package/skills/paperless-ngx/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: Requires a running Paperless-ngx instance with API token. MCP server must be connected with mcp_paperless_* tools available.
 metadata:
   author: kjanat
-  version: "2.0.1"
+  version: "2.2.0"
 ---
 
 # Paperless-ngx Document Management
@@ -76,7 +76,7 @@ What operation?
 ├─ Set sender      → bulk_edit_documents(method="set_correspondent", correspondent=ID)
 ├─ Merge PDFs      → bulk_edit_documents(method="merge", metadata_document_id=ID)
 ├─ Rotate pages    → bulk_edit_documents(method="rotate", degrees=90|180|270)
-├─ Delete pages    → bulk_edit_documents(method="delete_pages", pages="1,3,5-7")
+├─ Delete pages    → bulk_edit_documents(method="delete_pages", pages=[1, 3, 5])
 ├─ Reprocess OCR   → bulk_edit_documents(method="reprocess")
 └─ Delete          → bulk_edit_documents(method="delete")  !! PERMANENT !!
 ```
@@ -112,6 +112,12 @@ Need to change metadata objects?
   `4`=regex, `5`=fuzzy, `6`=auto. See [tools.md](references/tools.md).
 - **Bulk delete is permanent and irreversible.**
 - **download_document** returns base64 blob + filename from content-disposition.
+- **list_tags**, **list_correspondents**, and **list_document_types** return
+  complete paginated result sets; use IDs from `results`, not the bare `all` ID
+  list alone.
+- **bulk_edit_documents** accepts top-level MCP fields, but Paperless receives a
+  nested `parameters` object internally. The MCP tool forwards only the fields
+  relevant to the selected `method`.
 
 ## References
 

package/skills/paperless-ngx/references/tools.md

@@ -53,32 +53,44 @@ Returns `{ blob: string, filename: string }`.
 
 ### bulk_edit_documents
 
-| Param                  | Type     | Required | Notes                           |
-| ---------------------- | -------- | -------- | ------------------------------- |
-| `documents`            | number[] | yes      | Document IDs                    |
-| `method`               | enum     | yes      | See method table below          |
-| `correspondent`        | number   | no       | For `set_correspondent`         |
-| `document_type`        | number   | no       | For `set_document_type`         |
-| `storage_path`         | number   | no       | For `set_storage_path`          |
-| `tag`                  | number   | no       | For `add_tag` / `remove_tag`    |
-| `add_tags`             | number[] | no       | For `modify_tags`               |
-| `remove_tags`          | number[] | no       | For `modify_tags`               |
-| `permissions`          | object   | no       | For `set_permissions`           |
-| `metadata_document_id` | number   | no       | For `merge` -- source metadata  |
-| `delete_originals`     | boolean  | no       | For `merge`/`split`             |
-| `degrees`              | number   | no       | For `rotate`: 90, 180, 270      |
-| `pages`                | string   | no       | For `delete_pages`: `"1,3,5-7"` |
+| Param                  | Type            | Required | Notes                                               |
+| ---------------------- | --------------- | -------- | --------------------------------------------------- |
+| `documents`            | number[]        | yes      | Document IDs                                        |
+| `method`               | enum            | yes      | See method table below                              |
+| `correspondent`        | number          | no       | For `set_correspondent`                             |
+| `document_type`        | number          | no       | For `set_document_type`                             |
+| `storage_path`         | number          | no       | For `set_storage_path`                              |
+| `tag`                  | number          | no       | For `add_tag` / `remove_tag`                        |
+| `add_tags`             | number[]        | no       | For `modify_tags`                                   |
+| `remove_tags`          | number[]        | no       | For `modify_tags`                                   |
+| `add_custom_fields`    | array/object    | no       | For `modify_custom_fields`                          |
+| `remove_custom_fields` | number[]        | no       | For `modify_custom_fields`                          |
+| `permissions`          | object          | no       | For `set_permissions`                               |
+| `metadata_document_id` | number          | no       | For `merge` -- source metadata                      |
+| `delete_originals`     | boolean         | no       | For `merge`/`split`                                 |
+| `degrees`              | number          | no       | For `rotate`: 90, 180, 270                          |
+| `pages`                | string/number[] | no       | String for `split`; number array for `delete_pages` |
+| `operations`           | object[]        | no       | For `edit_pdf`                                      |
+| `password`             | string          | no       | For `remove_password`                               |
+| `update_document`      | boolean         | no       | For `edit_pdf`/`remove_password`                    |
+| `delete_original`      | boolean         | no       | For `edit_pdf`/`remove_password`                    |
+| `include_metadata`     | boolean         | no       | For `edit_pdf`/`remove_password`                    |
 
 **Method enum:**
 `set_correspondent`, `set_document_type`, `set_storage_path`, `add_tag`,
-`remove_tag`, `modify_tags`, `delete`, `reprocess`, `set_permissions`,
-`merge`, `split`, `rotate`, `delete_pages`
+`remove_tag`, `modify_tags`, `modify_custom_fields`, `delete`, `reprocess`,
+`set_permissions`, `merge`, `split`, `rotate`, `delete_pages`, `edit_pdf`,
+`remove_password`
+
+The MCP tool accepts method-specific parameters as top-level arguments and sends
+only the relevant fields to Paperless' nested `parameters` payload.
 
 ## Tag Tools
 
 ### list_tags
 
-No parameters. Returns all tags with name, color, matching rules.
+No parameters. Returns all tags with name, color, matching rules. The MCP client
+fetches all pages and combines `results`.
 
 ### create_tag
 
@@ -119,7 +131,7 @@ No parameters. Returns all tags with name, color, matching rules.
 
 ### list_correspondents
 
-No parameters.
+No parameters. The MCP client fetches all pages and combines `results`.
 
 ### create_correspondent
 
@@ -143,7 +155,7 @@ No parameters.
 
 ### list_document_types
 
-No parameters.
+No parameters. The MCP client fetches all pages and combines `results`.
 
 ### create_document_type