@kjanat/paperless-mcp 2.1.2 → 2.2.0

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.
Files changed (5) hide show
  1. package/README.md +9 -1
  2. package/dist/index.js +104 -104
  3. package/package.json +5 -1
  4. package/skills/paperless-ngx/SKILL.md +8 -2
  5. package/skills/paperless-ngx/references/tools.md +32 -20
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kjanat/paperless-mcp",
3
- "version": "2.1.2",
3
+ "version": "2.2.0",
4
4
  "description": "MCP server for interacting with Paperless-ngx document management system.",
5
5
  "keywords": [
6
6
  "paperless-ngx",
@@ -32,6 +32,9 @@
32
32
  "meta": "bash scripts/meta.sh",
33
33
  "fmt": "dprint fmt",
34
34
  "fmt:check": "dprint check",
35
+ "gen": "run -s gen:schema gen:zod fmt",
36
+ "gen:schema": "python3 scripts/openapi.py extract schemas/openapi.json -o schemas/subset.json",
37
+ "gen:zod": "openapi-ts",
35
38
  "mcp": "bun src/index.ts",
36
39
  "inspect": "bunx @modelcontextprotocol/inspector run mcp",
37
40
  "prepack": "bun bd",
@@ -39,6 +42,7 @@
39
42
  "typecheck": "tsgo --noEmit"
40
43
  },
41
44
  "devDependencies": {
45
+ "@hey-api/openapi-ts": "^0.98.1",
42
46
  "@modelcontextprotocol/sdk": "^1.29.0",
43
47
  "@types/bun": "^1.3.14",
44
48
  "@types/express": "^5.0.6",
package/skills/paperless-ngx/SKILL.md CHANGED
@@ -5,7 +5,7 @@ license: MIT
5
5
  compatibility: Requires a running Paperless-ngx instance with API token. MCP server must be connected with mcp_paperless_* tools available.
6
6
  metadata:
7
7
  author: kjanat
8
- version: "2.0.1"
8
+ version: "2.2.0"
9
9
  ---
10
10
 
11
11
  # Paperless-ngx Document Management
@@ -76,7 +76,7 @@ What operation?
76
76
  ├─ Set sender → bulk_edit_documents(method="set_correspondent", correspondent=ID)
77
77
  ├─ Merge PDFs → bulk_edit_documents(method="merge", metadata_document_id=ID)
78
78
  ├─ Rotate pages → bulk_edit_documents(method="rotate", degrees=90|180|270)
79
- ├─ Delete pages → bulk_edit_documents(method="delete_pages", pages="1,3,5-7")
79
+ ├─ Delete pages → bulk_edit_documents(method="delete_pages", pages=[1, 3, 5])
80
80
  ├─ Reprocess OCR → bulk_edit_documents(method="reprocess")
81
81
  └─ Delete → bulk_edit_documents(method="delete") !! PERMANENT !!
82
82
  ```
@@ -112,6 +112,12 @@ Need to change metadata objects?
112
112
  `4`=regex, `5`=fuzzy, `6`=auto. See [tools.md](references/tools.md).
113
113
  - **Bulk delete is permanent and irreversible.**
114
114
  - **download_document** returns base64 blob + filename from content-disposition.
115
+ - **list_tags**, **list_correspondents**, and **list_document_types** return
116
+ complete paginated result sets; use IDs from `results`, not the bare `all` ID
117
+ list alone.
118
+ - **bulk_edit_documents** accepts top-level MCP fields, but Paperless receives a
119
+ nested `parameters` object internally. The MCP tool forwards only the fields
120
+ relevant to the selected `method`.
115
121
 
116
122
  ## References
117
123
 
package/skills/paperless-ngx/references/tools.md CHANGED
@@ -53,32 +53,44 @@ Returns `{ blob: string, filename: string }`.
53
53
 
54
54
  ### bulk_edit_documents
55
55
 
56
- | Param | Type | Required | Notes |
57
- | ---------------------- | -------- | -------- | ------------------------------- |
58
- | `documents` | number[] | yes | Document IDs |
59
- | `method` | enum | yes | See method table below |
60
- | `correspondent` | number | no | For `set_correspondent` |
61
- | `document_type` | number | no | For `set_document_type` |
62
- | `storage_path` | number | no | For `set_storage_path` |
63
- | `tag` | number | no | For `add_tag` / `remove_tag` |
64
- | `add_tags` | number[] | no | For `modify_tags` |
65
- | `remove_tags` | number[] | no | For `modify_tags` |
66
- | `permissions` | object | no | For `set_permissions` |
67
- | `metadata_document_id` | number | no | For `merge` -- source metadata |
68
- | `delete_originals` | boolean | no | For `merge`/`split` |
69
- | `degrees` | number | no | For `rotate`: 90, 180, 270 |
70
- | `pages` | string | no | For `delete_pages`: `"1,3,5-7"` |
56
+ | Param | Type | Required | Notes |
57
+ | ---------------------- | --------------- | -------- | --------------------------------------------------- |
58
+ | `documents` | number[] | yes | Document IDs |
59
+ | `method` | enum | yes | See method table below |
60
+ | `correspondent` | number | no | For `set_correspondent` |
61
+ | `document_type` | number | no | For `set_document_type` |
62
+ | `storage_path` | number | no | For `set_storage_path` |
63
+ | `tag` | number | no | For `add_tag` / `remove_tag` |
64
+ | `add_tags` | number[] | no | For `modify_tags` |
65
+ | `remove_tags` | number[] | no | For `modify_tags` |
66
+ | `add_custom_fields` | array/object | no | For `modify_custom_fields` |
67
+ | `remove_custom_fields` | number[] | no | For `modify_custom_fields` |
68
+ | `permissions` | object | no | For `set_permissions` |
69
+ | `metadata_document_id` | number | no | For `merge` -- source metadata |
70
+ | `delete_originals` | boolean | no | For `merge`/`split` |
71
+ | `degrees` | number | no | For `rotate`: 90, 180, 270 |
72
+ | `pages` | string/number[] | no | String for `split`; number array for `delete_pages` |
73
+ | `operations` | object[] | no | For `edit_pdf` |
74
+ | `password` | string | no | For `remove_password` |
75
+ | `update_document` | boolean | no | For `edit_pdf`/`remove_password` |
76
+ | `delete_original` | boolean | no | For `edit_pdf`/`remove_password` |
77
+ | `include_metadata` | boolean | no | For `edit_pdf`/`remove_password` |
71
78
 
72
79
  **Method enum:**
73
80
  `set_correspondent`, `set_document_type`, `set_storage_path`, `add_tag`,
74
- `remove_tag`, `modify_tags`, `delete`, `reprocess`, `set_permissions`,
75
- `merge`, `split`, `rotate`, `delete_pages`
81
+ `remove_tag`, `modify_tags`, `modify_custom_fields`, `delete`, `reprocess`,
82
+ `set_permissions`, `merge`, `split`, `rotate`, `delete_pages`, `edit_pdf`,
83
+ `remove_password`
84
+
85
+ The MCP tool accepts method-specific parameters as top-level arguments and sends
86
+ only the relevant fields to Paperless' nested `parameters` payload.
76
87
 
77
88
  ## Tag Tools
78
89
 
79
90
  ### list_tags
80
91
 
81
- No parameters. Returns all tags with name, color, matching rules.
92
+ No parameters. Returns all tags with name, color, matching rules. The MCP client
93
+ fetches all pages and combines `results`.
82
94
 
83
95
  ### create_tag
84
96
 
@@ -119,7 +131,7 @@ No parameters. Returns all tags with name, color, matching rules.
119
131
 
120
132
  ### list_correspondents
121
133
 
122
- No parameters.
134
+ No parameters. The MCP client fetches all pages and combines `results`.
123
135
 
124
136
  ### create_correspondent
125
137
 
@@ -143,7 +155,7 @@ No parameters.
143
155
 
144
156
  ### list_document_types
145
157
 
146
- No parameters.
158
+ No parameters. The MCP client fetches all pages and combines `results`.
147
159
 
148
160
  ### create_document_type
149
161