@baruchiro/paperless-mcp 2.0.0 → 2.1.0

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.
@@ -252,7 +252,9 @@ Parameters:
   - tag: ID for add_tag/remove_tag
   - add_tags: Array of tag IDs for modify_tags
   - remove_tags: Array of tag IDs for modify_tags
-  - permissions: Object for set_permissions with owner, permissions, merge flag
+  - set_permissions: Object for set_permissions with view/change users and groups (`{"view": {"users": [], "groups": []}, "change": {...}}`). Omitted actions/lists are left untouched
+  - owner: User ID (or null to remove) for set_permissions. Unless merge is true, omitting owner clears the current owner
+  - merge: Boolean for set_permissions — true adds to existing permissions and keeps the owner; false (default) replaces the listed users/groups
   - metadata_document_id: ID for merge to specify metadata source
   - delete_originals: Boolean for merge/split
   - pages: String for split "[1,2-3,4,5-7]" or delete_pages "[2,3,4]"

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/api/types.d.ts

@@ -188,18 +188,16 @@ export interface BulkEditParameters {
     document_type?: number;
     storage_path?: number;
     tag?: number;
-    permissions?: {
-        owner?: number | null;
-        set_permissions?: {
-            view: {
-                users: number[];
-                groups: number[];
-            };
-            change: {
-                users: number[];
-                groups: number[];
-            };
+    set_permissions?: {
+        view?: {
+            users?: number[];
+            groups?: number[];
+        };
+        change?: {
+            users?: number[];
+            groups?: number[];
         };
-        merge?: boolean;
     };
+    owner?: number | null;
+    merge?: boolean;
 }

package/build/tools/documents.js

@@ -164,25 +164,37 @@ function registerDocumentTools(server, api) {
             .array(zod_1.z.number())
             .optional()
             .transform(empty_1.arrayNotEmpty),
-        permissions: zod_1.z
+        set_permissions: zod_1.z
             .object({
-            owner: zod_1.z.number().nullable().optional(),
-            set_permissions: zod_1.z
+            view: zod_1.z
                 .object({
-                view: zod_1.z.object({
-                    users: zod_1.z.array(zod_1.z.number()),
-                    groups: zod_1.z.array(zod_1.z.number()),
-                }),
-                change: zod_1.z.object({
-                    users: zod_1.z.array(zod_1.z.number()),
-                    groups: zod_1.z.array(zod_1.z.number()),
-                }),
+                users: zod_1.z.array(zod_1.z.number()).optional(),
+                groups: zod_1.z.array(zod_1.z.number()).optional(),
             })
+                .strict()
+                .optional(),
+            change: zod_1.z
+                .object({
+                users: zod_1.z.array(zod_1.z.number()).optional(),
+                groups: zod_1.z.array(zod_1.z.number()).optional(),
+            })
+                .strict()
                 .optional(),
-            merge: zod_1.z.boolean().optional(),
         })
+            // strict: a misspelled action ("read") must not silently collapse
+            // into {} and clear permissions/ownership.
+            .strict()
+            .optional()
+            .describe("For set_permissions: view/change permissions to apply. Omitted actions (view/change) and omitted users/groups lists are left untouched; an empty list [] removes all (unless merge is true). Omit entirely for owner-only changes."),
+        owner: zod_1.z
+            .number()
+            .nullable()
+            .optional()
+            .describe("For set_permissions: new owner user ID, or null to remove the owner. Unless merge is true, omitting owner also clears the current owner."),
+        merge: zod_1.z
+            .boolean()
             .optional()
-            .transform(empty_1.objectNotEmpty),
+            .describe("For set_permissions: true adds to existing permissions and keeps the current owner; false (default) replaces the listed users/groups"),
         metadata_document_id: zod_1.z.number().optional(),
         delete_originals: zod_1.z.boolean().optional(),
         pages: zod_1.z.string().optional(),
@@ -192,12 +204,23 @@ function registerDocumentTools(server, api) {
             .optional()
             .describe("Must be true when method is 'delete' to confirm destructive operation"),
     }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
+        var _a;
         if (!api)
             throw new Error("Please configure API connection first");
         if (args.method === "delete" && !args.confirm) {
             throw new Error("Confirmation required for destructive operation. Set confirm: true to proceed.");
         }
+        if (args.method === "set_permissions" &&
+            !args.set_permissions &&
+            args.owner === undefined) {
+            throw new Error("Method 'set_permissions' requires set_permissions and/or owner.");
+        }
         const { documents, method, add_custom_fields, confirm } = args, parameters = __rest(args, ["documents", "method", "add_custom_fields", "confirm"]);
+        if (method === "set_permissions") {
+            // Paperless rejects (Paperless <= 3.0.5: crashes with a 500 on) a missing
+            // set_permissions key even for owner-only changes.
+            (_a = parameters.set_permissions) !== null && _a !== void 0 ? _a : (parameters.set_permissions = {});
+        }
         (0, monetary_1.validateCustomFields)(add_custom_fields);
         const resolvedCustomFields = yield (0, selectFields_1.resolveSelectCustomFieldValues)(api, add_custom_fields, "stored");
         const response = yield api.bulkEditDocuments(documents, method, method === "delete"
@@ -378,6 +401,9 @@ function registerDocumentTools(server, api) {
         });
         return {
             content: [
+                // Legacy clients surface only content[].text and drop resource blocks
+                // entirely, so the URI is repeated here to stay reachable (issue #134).
+                { type: "text", text: uri },
                 {
                     type: "resource",
                     resource: {
@@ -397,12 +423,16 @@ function registerDocumentTools(server, api) {
     }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
         if (!api)
             throw new Error("Please configure API connection first");
+        const uri = (0, resourceUri_1.buildThumbnailResourceUri)(args.id);
         return {
             content: [
+                // See download_document above: the URI is repeated as text for legacy
+                // clients that drop resource blocks.
+                { type: "text", text: uri },
                 {
                     type: "resource",
                     resource: {
-                        uri: (0, resourceUri_1.buildThumbnailResourceUri)(args.id),
+                        uri,
                         // See download_document above: the binary thumbnail is fetched
                         // lazily through resources/read instead of embedded here.
                         text: "",
@@ -412,7 +442,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 +499,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

@@ -21,6 +21,7 @@ const index_js_1 = require("@modelcontextprotocol/sdk/client/index.js");
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const documents_1 = require("./documents");
 const documentQuery_1 = require("./utils/documentQuery");
+const resourceUri_1 = require("./utils/resourceUri");
 function getQueryParams(queryString) {
     return new URLSearchParams(queryString.replace(/^\?/, ""));
 }
@@ -416,7 +417,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 +428,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]);
@@ -480,3 +481,161 @@ const OBJECT_SELECT_FIELD = {
         strict_1.default.equal(calls.updateDocument.length, 0, "no document update should be sent when the option is invalid");
     }));
 });
+(0, node_test_1.describe)("document resource reference tools", () => {
+    // Expected URIs come from the builders rather than literals: their exact
+    // format is already pinned by utils/resourceUri.test.ts, and what matters
+    // here is that the handler surfaces that URI in both content blocks.
+    const cases = [
+        {
+            tool: "download_document",
+            args: { id: 4 },
+            uri: (0, resourceUri_1.buildDocumentResourceUri)(4),
+            mimeType: "application/octet-stream",
+        },
+        {
+            tool: "download_document",
+            args: { id: 4, original: true },
+            uri: (0, resourceUri_1.buildDocumentResourceUri)(4, { original: true }),
+            mimeType: "application/octet-stream",
+        },
+        {
+            tool: "get_document_thumbnail",
+            args: { id: 123 },
+            uri: (0, resourceUri_1.buildThumbnailResourceUri)(123),
+            mimeType: "image/webp",
+        },
+    ];
+    for (const { tool, args, uri, mimeType } of cases) {
+        (0, node_test_1.test)(`${tool} ${JSON.stringify(args)} returns the URI as text beside the resource`, () => __awaiter(void 0, void 0, void 0, function* () {
+            const { api } = createDocumentApi([]);
+            let result;
+            yield withDocumentClient(api, (client) => __awaiter(void 0, void 0, void 0, function* () {
+                result = (yield client.callTool({
+                    name: tool,
+                    arguments: args,
+                }));
+            }));
+            strict_1.default.ok(result && !result.isError, `${tool} failed`);
+            const [text, embedded] = result.content;
+            // Legacy clients read only content[].text (issue #134).
+            strict_1.default.equal(text.type, "text");
+            strict_1.default.equal(text.text, uri);
+            strict_1.default.equal(embedded.type, "resource");
+            const { resource } = embedded;
+            strict_1.default.equal(resource.uri, uri, "both blocks must reference the same URI");
+            strict_1.default.equal(resource.mimeType, mimeType);
+        }));
+    }
+});
+(0, node_test_1.describe)("bulk_edit_documents set_permissions", () => {
+    (0, node_test_1.test)("sends set_permissions, owner and merge at the top level of parameters", () => __awaiter(void 0, void 0, void 0, function* () {
+        const { api, calls } = createDocumentApi([]);
+        yield withDocumentClient(api, (client) => __awaiter(void 0, void 0, void 0, function* () {
+            var _a;
+            const result = (yield client.callTool({
+                name: "bulk_edit_documents",
+                arguments: {
+                    documents: [4103],
+                    method: "set_permissions",
+                    set_permissions: {
+                        view: { users: [], groups: [10] },
+                        change: { users: [], groups: [10] },
+                    },
+                    owner: 3,
+                    merge: true,
+                },
+            }));
+            strict_1.default.ok(!result.isError, (_a = parseToolText(result)) === null || _a === void 0 ? void 0 : _a.error);
+        }));
+        strict_1.default.equal(calls.bulkEditDocuments.length, 1);
+        const [documents, method, parameters] = calls.bulkEditDocuments[0];
+        strict_1.default.deepEqual(documents, [4103]);
+        strict_1.default.equal(method, "set_permissions");
+        // Paperless reads parameters["set_permissions"] directly; nesting it under
+        // another key makes the server crash with a KeyError (HTTP 500).
+        strict_1.default.deepEqual(parameters, {
+            set_permissions: {
+                view: { users: [], groups: [10] },
+                change: { users: [], groups: [10] },
+            },
+            owner: 3,
+            merge: true,
+        });
+    }));
+    (0, node_test_1.test)("forwards partial permissions without filling in omitted actions or lists", () => __awaiter(void 0, void 0, void 0, function* () {
+        const { api, calls } = createDocumentApi([]);
+        yield withDocumentClient(api, (client) => __awaiter(void 0, void 0, void 0, function* () {
+            var _a;
+            const result = (yield client.callTool({
+                name: "bulk_edit_documents",
+                arguments: {
+                    documents: [1],
+                    method: "set_permissions",
+                    set_permissions: { view: { groups: [10] } },
+                },
+            }));
+            strict_1.default.ok(!result.isError, (_a = parseToolText(result)) === null || _a === void 0 ? void 0 : _a.error);
+        }));
+        // Paperless only touches the actions/lists that are present, and clears
+        // the owner when it is omitted without merge — so nothing may be added.
+        const [, , parameters] = calls.bulkEditDocuments[0];
+        strict_1.default.deepEqual(parameters, { set_permissions: { view: { groups: [10] } } });
+    }));
+    (0, node_test_1.test)("owner-only changes send an empty set_permissions object", () => __awaiter(void 0, void 0, void 0, function* () {
+        const { api, calls } = createDocumentApi([]);
+        yield withDocumentClient(api, (client) => __awaiter(void 0, void 0, void 0, function* () {
+            var _a;
+            for (const owner of [3, null]) {
+                const result = (yield client.callTool({
+                    name: "bulk_edit_documents",
+                    arguments: { documents: [1], method: "set_permissions", owner },
+                }));
+                strict_1.default.ok(!result.isError, (_a = parseToolText(result)) === null || _a === void 0 ? void 0 : _a.error);
+            }
+        }));
+        strict_1.default.deepEqual(calls.bulkEditDocuments.map(([, , parameters]) => parameters), [
+            { set_permissions: {}, owner: 3 },
+            { set_permissions: {}, owner: null },
+        ]);
+    }));
+    (0, node_test_1.test)("rejects method set_permissions with neither set_permissions nor owner", () => __awaiter(void 0, void 0, void 0, function* () {
+        const { api, calls } = createDocumentApi([]);
+        yield withDocumentClient(api, (client) => __awaiter(void 0, void 0, void 0, function* () {
+            var _a, _b;
+            const result = (yield client.callTool({
+                name: "bulk_edit_documents",
+                arguments: { documents: [1], method: "set_permissions", merge: true },
+            }));
+            strict_1.default.ok(result.isError, "expected an error when both are missing");
+            strict_1.default.match((_b = (_a = parseToolText(result)) === null || _a === void 0 ? void 0 : _a.error) !== null && _b !== void 0 ? _b : "", /set_permissions and\/or owner/);
+        }));
+        strict_1.default.equal(calls.bulkEditDocuments.length, 0);
+    }));
+    (0, node_test_1.test)("rejects malformed set_permissions input before calling Paperless", () => __awaiter(void 0, void 0, void 0, function* () {
+        const { api, calls } = createDocumentApi([]);
+        yield withDocumentClient(api, (client) => __awaiter(void 0, void 0, void 0, function* () {
+            for (const set_permissions of [
+                { view: { groups: ["ai-agents"] } },
+                { read: { groups: [10] } },
+                { view: [10] },
+            ]) {
+                // Depending on the installed MCP SDK version, an input-schema (zod)
+                // violation either rejects with a protocol error (-32602) or resolves
+                // with a CallToolResult carrying isError: true.
+                let rejected = false;
+                let result;
+                try {
+                    result = (yield client.callTool({
+                        name: "bulk_edit_documents",
+                        arguments: { documents: [1], method: "set_permissions", set_permissions },
+                    }));
+                }
+                catch (_a) {
+                    rejected = true;
+                }
+                strict_1.default.ok(rejected || (result === null || result === void 0 ? void 0 : result.isError), `expected ${JSON.stringify(set_permissions)} to be rejected`);
+            }
+        }));
+        strict_1.default.equal(calls.bulkEditDocuments.length, 0);
+    }));
+});

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.1.0",
   "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": {