@baruchiro/paperless-mcp 2.0.1 → 2.1.0

package/README.md

@@ -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/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: "",

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(/^\?/, ""));
 }
@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@baruchiro/paperless-mcp",
-  "version": "2.0.1",
+  "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": {