@baruchiro/paperless-mcp 2.0.0 → 2.0.1

package/README.md

@@ -66,7 +66,7 @@ Add these to your MCP config file:
 | `PAPERLESS_URL` | Yes | — | Base URL of your Paperless-NGX instance |
 | `PAPERLESS_API_KEY` | Yes | — | API token from your Paperless-NGX profile |
 | `PAPERLESS_PUBLIC_URL` | No | `PAPERLESS_URL` | Public-facing URL for document links |
-| `PAPERLESS_API_VERSION` | No | `5` | Paperless-ngx REST API version. Use `10` for Paperless-ngx v3+. If you see HTTP 406 errors, set this to `10`. |
+| `PAPERLESS_API_VERSION` | No | `9` | Paperless-ngx REST API version. `9` works on Paperless-ngx v2.x (recent) and v3.x. Paperless-ngx v3.0.0 dropped support for versions below `9`, so older defaults now return HTTP 406. If you see HTTP 406 errors, set this to a version your server supports. |
 | `PAPERLESS_MCP_UPLOAD_PATHS` | No | — | Colon-separated list of allowed directories for `file_path` uploads. **Recommended for security.** Example: `/var/uploads:/tmp/scans` |
 
 That's it! Now you can ask Claude to help you manage your Paperless-NGX documents.

package/build/api/PaperlessAPI.js

@@ -22,7 +22,7 @@ class PaperlessAPI {
         this.token = token;
         this.baseUrl = baseUrl;
         this.token = token;
-        this.apiVersion = process.env.PAPERLESS_API_VERSION || "5";
+        this.apiVersion = process.env.PAPERLESS_API_VERSION || "9";
     }
     request(path_1) {
         return __awaiter(this, arguments, void 0, function* (path, options = {}) {
@@ -57,7 +57,7 @@ class PaperlessAPI {
             catch (error) {
                 if (axios_1.default.isAxiosError(error) && ((_a = error.response) === null || _a === void 0 ? void 0 : _a.status) === 406) {
                     throw new Error(`HTTP 406: Paperless-ngx rejected API version ${this.apiVersion}. ` +
-                        `Set the PAPERLESS_API_VERSION environment variable to match your server's API version (e.g., "10" for Paperless-ngx v3+).`);
+                        `Set the PAPERLESS_API_VERSION environment variable to a version your server supports (e.g., "9" or "10" for Paperless-ngx v3+, or a lower value for older servers).`);
                 }
                 console.error({
                     error: "Error executing request",
@@ -121,7 +121,7 @@ class PaperlessAPI {
             catch (error) {
                 if (axios_1.default.isAxiosError(error) && ((_a = error.response) === null || _a === void 0 ? void 0 : _a.status) === 406) {
                     throw new Error(`HTTP 406: Paperless-ngx rejected API version ${this.apiVersion}. ` +
-                        `Set the PAPERLESS_API_VERSION environment variable to match your server's API version (e.g., "10" for Paperless-ngx v3+).`);
+                        `Set the PAPERLESS_API_VERSION environment variable to a version your server supports (e.g., "9" or "10" for Paperless-ngx v3+, or a lower value for older servers).`);
                 }
                 throw error;
             }

package/build/tools/documents.js

@@ -412,7 +412,7 @@ function registerDocumentTools(server, api) {
             ],
         };
     })));
-    server.tool("update_document", "Update a specific document with new values. This tool allows you to modify any document field including title, correspondent, document type, storage path, tags, custom fields, and more. Only the fields you specify will be updated.", {
+    server.tool("update_document", "Update a specific document with new values (title, correspondent, document type, storage path, tags, custom fields, and more). Top-level fields you omit are left unchanged. IMPORTANT: custom_fields is the exception — see its parameter description; it replaces the document's entire custom-field set.", {
         id: zod_1.z.number().describe("The ID of the document to update"),
         title: zod_1.z
             .string()
@@ -469,13 +469,13 @@ function registerDocumentTools(server, api) {
                 .describe(descriptions_1.CUSTOM_FIELD_VALUE_DESCRIPTION),
         }))
             .optional()
-            .describe("Array of custom field values to assign"),
+            .describe("Custom field values for the document. ⚠️ REPLACES the document's entire custom-field set — any field not included here will be CLEARED. To update or add a single field without losing the others, first call get_document to read the existing custom_fields, then pass the full merged array. To add/set fields additively without fetching, use bulk_edit_documents with method 'modify_custom_fields' instead."),
     }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
         if (!api)
             throw new Error("Please configure API connection first");
         const { id } = args, updateData = __rest(args, ["id"]);
         (0, monetary_1.validateCustomFields)(updateData.custom_fields);
-        updateData.custom_fields = yield (0, selectFields_1.resolveSelectCustomFieldValues)(api, updateData.custom_fields, "index");
+        updateData.custom_fields = yield (0, selectFields_1.resolveSelectCustomFieldValues)(api, updateData.custom_fields, "stored");
         const response = yield api.updateDocument(id, updateData);
         return (0, documentEnhancer_1.convertDocsWithNames)(response, api);
     })));

package/build/tools/documents.test.js

@@ -416,7 +416,7 @@ const OBJECT_SELECT_FIELD = {
         const [, data] = calls.updateDocument[0];
         strict_1.default.deepEqual(data.custom_fields, [{ field: 2, value: 0 }]);
     }));
-    (0, node_test_1.test)("update_document translates a select label to its option index (Paperless 2.17+)", () => __awaiter(void 0, void 0, void 0, function* () {
+    (0, node_test_1.test)("update_document sends the option id for 2.17+ select fields (stored form)", () => __awaiter(void 0, void 0, void 0, function* () {
         const { api, calls } = createDocumentApi([OBJECT_SELECT_FIELD]);
         yield withDocumentClient(api, (client) => __awaiter(void 0, void 0, void 0, function* () {
             var _a;
@@ -427,7 +427,7 @@ const OBJECT_SELECT_FIELD = {
             strict_1.default.ok(!result.isError, (_a = parseToolText(result)) === null || _a === void 0 ? void 0 : _a.error);
         }));
         const [, data] = calls.updateDocument[0];
-        strict_1.default.deepEqual(data.custom_fields, [{ field: 3, value: 1 }]);
+        strict_1.default.deepEqual(data.custom_fields, [{ field: 3, value: "def456" }]);
     }));
     (0, node_test_1.test)("bulk_edit_documents translates a select label in add_custom_fields", () => __awaiter(void 0, void 0, void 0, function* () {
         const { api, calls } = createDocumentApi([LEGACY_SELECT_FIELD]);

package/build/tools/utils/selectFields.d.ts

@@ -1,9 +1,11 @@
 import { PaperlessAPI } from "../../api/PaperlessAPI";
 import { CustomField, CustomFieldInstanceRequest, CustomFieldValue } from "../../api/types";
 /**
- * Encoding Paperless expects for a select value: `update_document` takes the
- * option index; `bulk_edit` writes `value_select` directly so it needs the
- * stored form (option id on 2.17+, index on pre-2.17 string options).
+ * Encoding Paperless expects for a select value. On the supported API versions
+ * (v9+) both `update_document` and `bulk_edit` take the option's stored form:
+ * the option id on 2.17+ fields, or the index on pre-2.17 string-option fields.
+ * The bare `index` form is retained for older API versions whose document
+ * endpoint accepted the option index directly.
  */
 export type SelectValueEncoding = "index" | "stored";
 /** Translates a select value (label, option id, or index) to the `encoding` Paperless expects; throws on no match. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@baruchiro/paperless-mcp",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Model Context Protocol (MCP) server for interacting with Paperless-NGX document management system. Enables AI assistants to manage documents, tags, correspondents, and document types through the Paperless-NGX API.",
   "main": "build/index.js",
   "bin": {