@baruchiro/paperless-mcp 2.0.1 → 2.2.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/PaperlessAPI.d.ts

@@ -7,7 +7,7 @@ export declare class PaperlessAPI {
     constructor(baseUrl: string, token: string);
     request<T = any>(path: string, options?: RequestInit): Promise<T>;
     bulkEditDocuments(documents: number[], method: string, parameters?: BulkEditParameters): Promise<BulkEditDocumentsResult>;
-    postDocument(document: Buffer, filename: string, metadata?: Record<string, string | string[] | number | number[]>): Promise<string>;
+    postDocument(document: Buffer, filename: string, metadata?: Record<string, string | string[] | number | number[] | undefined>): Promise<string>;
     getDocuments(query?: string): Promise<DocumentsResponse>;
     getDocument(id: number): Promise<Document>;
     updateDocument(id: number, data: Partial<Document>): Promise<Document>;

package/build/api/types.d.ts

@@ -68,7 +68,7 @@ export interface Document {
     id: number;
     correspondent: number | null;
     document_type: number | null;
-    storage_path: string | null;
+    storage_path: number | null;
     title: string;
     content: string | null;
     tags: number[];
@@ -77,7 +77,7 @@ export interface Document {
     modified: string;
     added: string;
     deleted_at: string | null;
-    archive_serial_number: string | null;
+    archive_serial_number: number | null;
     original_file_name: string;
     archived_file_name: string;
     owner: number | null;
@@ -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/correspondents.js

@@ -22,8 +22,8 @@ var __rest = (this && this.__rest) || function (s, e) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerCorrespondentTools = registerCorrespondentTools;
 const zod_1 = require("zod");
-const types_1 = require("../api/types");
 const utils_1 = require("../api/utils");
+const matchingAlgorithm_1 = require("./utils/matchingAlgorithm");
 const middlewares_1 = require("./utils/middlewares");
 const queryString_1 = require("./utils/queryString");
 function registerCorrespondentTools(server, api) {
@@ -64,13 +64,7 @@ function registerCorrespondentTools(server, api) {
     server.tool("create_correspondent", "Create a new correspondent with optional matching pattern and algorithm for automatic document assignment.", {
         name: zod_1.z.string(),
         match: zod_1.z.string().optional(),
-        matching_algorithm: zod_1.z
-            .number()
-            .int()
-            .min(0)
-            .max(6)
-            .optional()
-            .describe(types_1.MATCHING_ALGORITHM_DESCRIPTION),
+        matching_algorithm: matchingAlgorithm_1.matchingAlgorithmSchema.optional(),
     }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
         if (!api)
             throw new Error("Please configure API connection first");
@@ -86,13 +80,7 @@ function registerCorrespondentTools(server, api) {
         id: zod_1.z.number(),
         name: zod_1.z.string(),
         match: zod_1.z.string().optional(),
-        matching_algorithm: zod_1.z
-            .number()
-            .int()
-            .min(0)
-            .max(6)
-            .optional()
-            .describe(types_1.MATCHING_ALGORITHM_DESCRIPTION),
+        matching_algorithm: matchingAlgorithm_1.matchingAlgorithmSchema.optional(),
     }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
         if (!api)
             throw new Error("Please configure API connection first");

package/build/tools/customFields.js

@@ -33,7 +33,7 @@ function registerCustomFieldTools(server, api) {
         name__iexact: zod_1.z.string().optional(),
         name__istartswith: zod_1.z.string().optional(),
         ordering: zod_1.z.string().optional(),
-    }, (0, middlewares_1.withErrorHandling)((...args_1) => __awaiter(this, [...args_1], void 0, function* (args = {}) {
+    }, (0, middlewares_1.withErrorHandling)((args) => __awaiter(this, void 0, void 0, function* () {
         if (!api)
             throw new Error("Please configure API connection first");
         const queryString = (0, queryString_1.buildQueryString)(args);
@@ -68,7 +68,7 @@ function registerCustomFieldTools(server, api) {
             "documentlink",
             "select",
         ]),
-        extra_data: zod_1.z.record(zod_1.z.unknown()).nullable().optional(),
+        extra_data: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).nullable().optional(),
     }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
         if (!api)
             throw new Error("Please configure API connection first");
@@ -93,7 +93,7 @@ function registerCustomFieldTools(server, api) {
             "select",
         ])
             .optional(),
-        extra_data: zod_1.z.record(zod_1.z.unknown()).nullable().optional(),
+        extra_data: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).nullable().optional(),
     }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
         if (!api)
             throw new Error("Please configure API connection first");

package/build/tools/documentTypes.js

@@ -22,8 +22,8 @@ var __rest = (this && this.__rest) || function (s, e) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerDocumentTypeTools = registerDocumentTypeTools;
 const zod_1 = require("zod");
-const types_1 = require("../api/types");
 const utils_1 = require("../api/utils");
+const matchingAlgorithm_1 = require("./utils/matchingAlgorithm");
 const middlewares_1 = require("./utils/middlewares");
 const queryString_1 = require("./utils/queryString");
 function registerDocumentTypeTools(server, api) {
@@ -35,7 +35,7 @@ function registerDocumentTypeTools(server, api) {
         name__iexact: zod_1.z.string().optional(),
         name__istartswith: zod_1.z.string().optional(),
         ordering: zod_1.z.string().optional(),
-    }, (0, middlewares_1.withErrorHandling)((...args_1) => __awaiter(this, [...args_1], void 0, function* (args = {}, extra) {
+    }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
         if (!api)
             throw new Error("Please configure API connection first");
         const queryString = (0, queryString_1.buildQueryString)(args);
@@ -62,13 +62,7 @@ function registerDocumentTypeTools(server, api) {
     server.tool("create_document_type", "Create a new document type with optional matching pattern and algorithm for automatic document classification.", {
         name: zod_1.z.string(),
         match: zod_1.z.string().optional(),
-        matching_algorithm: zod_1.z
-            .number()
-            .int()
-            .min(0)
-            .max(6)
-            .optional()
-            .describe(types_1.MATCHING_ALGORITHM_DESCRIPTION),
+        matching_algorithm: matchingAlgorithm_1.matchingAlgorithmSchema.optional(),
     }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
         if (!api)
             throw new Error("Please configure API connection first");
@@ -82,13 +76,7 @@ function registerDocumentTypeTools(server, api) {
         id: zod_1.z.number(),
         name: zod_1.z.string(),
         match: zod_1.z.string().optional(),
-        matching_algorithm: zod_1.z
-            .number()
-            .int()
-            .min(0)
-            .max(6)
-            .optional()
-            .describe(types_1.MATCHING_ALGORITHM_DESCRIPTION),
+        matching_algorithm: matchingAlgorithm_1.matchingAlgorithmSchema.optional(),
     }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
         if (!api)
             throw new Error("Please configure API connection first");

package/build/tools/documents.js

@@ -164,25 +164,38 @@ 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()
+            .int()
+            .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 +205,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"
@@ -272,7 +296,7 @@ function registerDocumentTools(server, api) {
             throw new Error("Please configure API connection first");
         const validationResult = postDocumentSchema.safeParse(args);
         if (!validationResult.success) {
-            throw new Error(validationResult.error.errors.map(e => e.message).join("; "));
+            throw new Error(validationResult.error.issues.map(e => e.message).join("; "));
         }
         let document;
         let filename;
@@ -378,6 +402,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 +424,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: "",
@@ -421,16 +452,19 @@ function registerDocumentTools(server, api) {
             .describe("The new title for the document (max 128 characters)"),
         correspondent: zod_1.z
             .number()
+            .int()
             .nullable()
             .optional()
             .describe("The ID of the correspondent to assign"),
         document_type: zod_1.z
             .number()
+            .int()
             .nullable()
             .optional()
             .describe("The ID of the document type to assign"),
         storage_path: zod_1.z
             .number()
+            .int()
             .nullable()
             .optional()
             .describe("The ID of the storage path to assign"),
@@ -452,6 +486,7 @@ function registerDocumentTools(server, api) {
             .describe("The archive serial number (0-4294967295)"),
         owner: zod_1.z
             .number()
+            .int()
             .nullable()
             .optional()
             .describe("The ID of the user who owns the document"),

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,178 @@ 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);
+    }));
+});
+(0, node_test_1.describe)("nullable foreign keys can still be cleared (#138)", () => {
+    (0, node_test_1.test)("update_document forwards an explicit null so a foreign key can be cleared", () => __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: "update_document",
+                arguments: { id: 42, correspondent: null, owner: null },
+            }));
+            strict_1.default.ok(!result.isError, (_a = parseToolText(result)) === null || _a === void 0 ? void 0 : _a.error);
+        }));
+        strict_1.default.equal(calls.updateDocument.length, 1);
+        const [, data] = calls.updateDocument[0];
+        strict_1.default.equal(data.correspondent, null);
+        strict_1.default.equal(data.owner, null);
+    }));
+});

package/build/tools/mail.js

@@ -35,10 +35,10 @@ const mailRuleFields = {
     account: zod_1.z.number().int().optional(),
     enabled: zod_1.z.boolean().optional(),
     folder: zod_1.z.string().optional(),
-    filter_from: zod_1.z.string().nullable().optional(),
-    filter_to: zod_1.z.string().nullable().optional(),
-    filter_subject: zod_1.z.string().nullable().optional(),
-    filter_body: zod_1.z.string().nullable().optional(),
+    filter_from: zod_1.z.string().max(256).nullable().optional(),
+    filter_to: zod_1.z.string().max(256).nullable().optional(),
+    filter_subject: zod_1.z.string().max(256).nullable().optional(),
+    filter_body: zod_1.z.string().max(256).nullable().optional(),
     filter_attachment_filename_include: zod_1.z.string().nullable().optional(),
     filter_attachment_filename_exclude: zod_1.z.string().nullable().optional(),
     maximum_age: zod_1.z.number().int().min(0).optional(),
@@ -96,7 +96,7 @@ function registerMailTools(server, api) {
     server.tool("list_mail_accounts", "List Paperless mail accounts for selecting the account ID needed by mail rules. Does not expose account passwords.", {
         page: zod_1.z.number().optional(),
         page_size: zod_1.z.number().optional(),
-    }, (0, middlewares_1.withErrorHandling)((...args_1) => __awaiter(this, [...args_1], void 0, function* (args = {}) {
+    }, (0, middlewares_1.withErrorHandling)((args) => __awaiter(this, void 0, void 0, function* () {
         if (!api)
             throw new Error("Please configure API connection first");
         const queryString = (0, queryString_1.buildQueryString)(args);
@@ -132,7 +132,7 @@ function registerMailTools(server, api) {
     server.tool("list_mail_rules", "List Paperless mail rules with optional pagination.", {
         page: zod_1.z.number().optional(),
         page_size: zod_1.z.number().optional(),
-    }, (0, middlewares_1.withErrorHandling)((...args_1) => __awaiter(this, [...args_1], void 0, function* (args = {}) {
+    }, (0, middlewares_1.withErrorHandling)((args) => __awaiter(this, void 0, void 0, function* () {
         if (!api)
             throw new Error("Please configure API connection first");
         const queryString = (0, queryString_1.buildQueryString)(args);

package/build/tools/schemaCompat.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/tools/schemaCompat.test.js

@@ -0,0 +1,59 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const strict_1 = __importDefault(require("node:assert/strict"));
+const node_test_1 = require("node:test");
+const index_js_1 = require("@modelcontextprotocol/sdk/client/index.js");
+const inMemory_js_1 = require("@modelcontextprotocol/sdk/inMemory.js");
+const server_1 = require("../server");
+// Strict MCP clients and gateways reject an array-valued `type` and silently drop
+// the whole tool (#138). A JSON Schema converter reaches that form by collapsing a
+// union of unchecked primitives: `zod-to-json-schema` (the zod v3 path) always does
+// it, and zod's own converter did it again from 4.5.0 on. The tools are only free
+// of it because the server is on the zod v4 path with zod pinned to 4.4.x, so this
+// walks every advertised schema rather than a field list: bumping that pin, moving
+// off zod v4, or adding a construct that reintroduces the form fails here.
+function arrayFormTypes(node, path = "") {
+    if (Array.isArray(node)) {
+        return node.flatMap((item, i) => arrayFormTypes(item, `${path}[${i}]`));
+    }
+    if (!node || typeof node !== "object") {
+        return [];
+    }
+    return Object.entries(node).flatMap(([key, value]) => key === "type" && Array.isArray(value)
+        ? [`${path}.type = ${JSON.stringify(value)}`]
+        : arrayFormTypes(value, `${path}.${key}`));
+}
+(0, node_test_1.test)("no tool advertises an array-form `type` (#138)", () => __awaiter(void 0, void 0, void 0, function* () {
+    const server = (0, server_1.createMcpServer)({
+        baseUrl: "http://paperless.test",
+        token: "test-token",
+        version: "0.0.0-test",
+        publicUrl: "http://paperless.test",
+    });
+    const [clientTransport, serverTransport] = inMemory_js_1.InMemoryTransport.createLinkedPair();
+    const client = new index_js_1.Client({ name: "schema-compat-test", version: "1.0.0" });
+    yield Promise.all([server.connect(serverTransport), client.connect(clientTransport)]);
+    try {
+        const { tools } = yield client.listTools();
+        const found = tools
+            .flatMap((tool) => arrayFormTypes(tool.inputSchema).map((hit) => `${tool.name} ${hit}`))
+            .sort();
+        strict_1.default.deepEqual(found, []);
+    }
+    finally {
+        yield client.close();
+        yield server.close();
+    }
+}));

package/build/tools/tags.js

@@ -11,8 +11,8 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerTagTools = registerTagTools;
 const zod_1 = require("zod");
-const types_1 = require("../api/types");
 const utils_1 = require("../api/utils");
+const matchingAlgorithm_1 = require("./utils/matchingAlgorithm");
 const middlewares_1 = require("./utils/middlewares");
 const queryString_1 = require("./utils/queryString");
 function registerTagTools(server, api) {
@@ -24,7 +24,7 @@ function registerTagTools(server, api) {
         name__iexact: zod_1.z.string().optional(),
         name__istartswith: zod_1.z.string().optional(),
         ordering: zod_1.z.string().optional(),
-    }, (0, middlewares_1.withErrorHandling)((...args_1) => __awaiter(this, [...args_1], void 0, function* (args = {}) {
+    }, (0, middlewares_1.withErrorHandling)((args) => __awaiter(this, void 0, void 0, function* () {
         if (!api)
             throw new Error("Please configure API connection first");
         const queryString = (0, queryString_1.buildQueryString)(args);
@@ -46,13 +46,7 @@ function registerTagTools(server, api) {
             .regex(/^#[0-9A-Fa-f]{6}$/)
             .optional(),
         match: zod_1.z.string().optional(),
-        matching_algorithm: zod_1.z
-            .number()
-            .int()
-            .min(0)
-            .max(6)
-            .optional()
-            .describe(types_1.MATCHING_ALGORITHM_DESCRIPTION),
+        matching_algorithm: matchingAlgorithm_1.matchingAlgorithmSchema.optional(),
     }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
         if (!api)
             throw new Error("Please configure API connection first");
@@ -75,13 +69,7 @@ function registerTagTools(server, api) {
             .regex(/^#[0-9A-Fa-f]{6}$/)
             .optional(),
         match: zod_1.z.string().optional(),
-        matching_algorithm: zod_1.z
-            .number()
-            .int()
-            .min(0)
-            .max(6)
-            .optional()
-            .describe(types_1.MATCHING_ALGORITHM_DESCRIPTION),
+        matching_algorithm: matchingAlgorithm_1.matchingAlgorithmSchema.optional(),
     }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
         if (!api)
             throw new Error("Please configure API connection first");

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

@@ -6,8 +6,8 @@ export type CustomFieldQuery = [fieldNameOrId: string | number, operator: string
     clauses: CustomFieldQuery[]
 ];
 export declare const customFieldQuerySchema: z.ZodType<CustomFieldQuery>;
-export declare const paperlessFilterValueSchema: z.ZodUnion<[z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>, z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>, "many">]>;
-export declare const paperlessFiltersSchema: z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>, z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>, "many">]>>;
+export declare const paperlessFilterValueSchema: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>]>;
+export declare const paperlessFiltersSchema: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>]>>;
 export declare const LIST_DOCUMENTS_ARGS_SHAPE: {
     custom_field_query: z.ZodOptional<z.ZodString>;
     page: z.ZodOptional<z.ZodNumber>;
@@ -27,8 +27,8 @@ export declare const LIST_DOCUMENTS_ARGS_SHAPE: {
 export declare const QUERY_DOCUMENTS_ARGS_SHAPE: {
     query: z.ZodOptional<z.ZodString>;
     more_like_id: z.ZodOptional<z.ZodNumber>;
-    custom_field_query: z.ZodOptional<z.ZodType<CustomFieldQuery, z.ZodTypeDef, CustomFieldQuery>>;
-    paperless_filters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>, z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>, "many">]>>>;
+    custom_field_query: z.ZodOptional<z.ZodType<CustomFieldQuery, unknown, z.core.$ZodTypeInternals<CustomFieldQuery, unknown>>>;
+    paperless_filters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>]>>>;
     page: z.ZodOptional<z.ZodNumber>;
     page_size: z.ZodOptional<z.ZodNumber>;
     search: z.ZodOptional<z.ZodString>;

package/build/tools/utils/documentQuery.js

@@ -68,7 +68,7 @@ exports.paperlessFilterValueSchema = zod_1.z.union([
     paperlessFilterScalarSchema,
     zod_1.z.array(paperlessFilterScalarSchema),
 ]);
-exports.paperlessFiltersSchema = zod_1.z.record(exports.paperlessFilterValueSchema);
+exports.paperlessFiltersSchema = zod_1.z.record(zod_1.z.string(), exports.paperlessFilterValueSchema);
 const DOCUMENT_QUERY_BASE_ARGS_SHAPE = {
     page: zod_1.z.number().optional(),
     page_size: zod_1.z.number().optional(),

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

@@ -0,0 +1,2 @@
+import { z } from "zod";
+export declare const matchingAlgorithmSchema: z.ZodPipe<z.ZodNumber, z.ZodTransform<0 | 1 | 2 | 3 | 4 | 5 | 6, number>>;

package/build/tools/utils/matchingAlgorithm.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.matchingAlgorithmSchema = void 0;
+const zod_1 = require("zod");
+const types_1 = require("../../api/types");
+// The 0-6 range the API declares is exactly the set `MatchingAlgorithm`
+// enumerates, so narrowing to it after the check lets the PaperlessAPI request
+// types take the parsed value without a cast at every call site.
+exports.matchingAlgorithmSchema = zod_1.z
+    .number()
+    .int()
+    .min(0)
+    .max(6)
+    .transform((value) => value)
+    .describe(types_1.MATCHING_ALGORITHM_DESCRIPTION);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@baruchiro/paperless-mcp",
-  "version": "2.0.1",
+  "version": "2.2.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": {
@@ -44,12 +44,12 @@
     "url": "https://github.com/baruchiro/paperless-mcp/issues"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.11.1",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "axios": "^1.9.0",
     "express": "^5.1.0",
     "form-data": "^4.0.2",
     "typescript": "^5.8.3",
-    "zod": "^3.24.1"
+    "zod": "~4.4.3"
   },
   "devDependencies": {
     "@anthropic-ai/dxt": "^0.2.6",