@baruchiro/paperless-mcp 1.0.0 → 2.0.1

package/build/tools/documents.test.js

@@ -1,11 +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_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
 const node_test_1 = require("node:test");
+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");
+function getQueryParams(queryString) {
+    return new URLSearchParams(queryString.replace(/^\?/, ""));
+}
+function getDocumentQueryParamsFromOpenApi() {
+    const openApiPath = (0, node_path_1.join)(process.cwd(), "Paperless_ngx_REST_API.yaml");
+    const text = (0, node_fs_1.readFileSync)(openApiPath, "utf8");
+    const start = text.indexOf("  /api/documents/:");
+    const end = text.indexOf("  /api/documents/{id}/:");
+    strict_1.default.ok(start >= 0, "OpenAPI docs marker '/api/documents/' not found");
+    strict_1.default.ok(end > start, "OpenAPI docs marker '/api/documents/{id}/' not found or out of order");
+    const section = text.slice(start, end);
+    return Array.from(section.matchAll(/^\s*-?\s*name:\s+(.+)$/gm), (match) => match[1]).sort();
+}
+// ALLOWED_UPLOAD_PATHS is read from the environment at module load, so the
+// allowlist can only be exercised by re-importing the module with the env set.
+function validateFilePathWithAllowlist(allowedPaths) {
+    const modulePath = require.resolve("./documents");
+    const previous = process.env.PAPERLESS_MCP_UPLOAD_PATHS;
+    process.env.PAPERLESS_MCP_UPLOAD_PATHS = allowedPaths;
+    delete require.cache[modulePath];
+    try {
+        return require("./documents").validateFilePath;
+    }
+    finally {
+        delete require.cache[modulePath];
+        if (previous === undefined) {
+            delete process.env.PAPERLESS_MCP_UPLOAD_PATHS;
+        }
+        else {
+            process.env.PAPERLESS_MCP_UPLOAD_PATHS = previous;
+        }
+    }
+}
 (0, node_test_1.test)("buildBulkEditParameters sends Paperless bulk custom fields as id:value map", () => {
     const parameters = (0, documents_1.buildBulkEditParameters)({ remove_custom_fields: [] }, [
         { field: 9, value: "" },
@@ -76,3 +124,359 @@ const documents_1 = require("./documents");
         "5": [123, 456],
     });
 });
+(0, node_test_1.test)("paperless filter allowlist stays in sync with the document OpenAPI section", () => {
+    const documentedParams = getDocumentQueryParamsFromOpenApi();
+    const allowedParams = [...documentQuery_1.DOCUMENT_QUERY_PAPERLESS_FILTER_KEYS].sort();
+    strict_1.default.deepEqual(allowedParams, documentedParams);
+});
+(0, node_test_1.test)("serializes full-text query_documents arguments", () => {
+    const query = getQueryParams((0, documentQuery_1.buildDocumentQueryString)({
+        query: "invoice 2024",
+        search: "jan",
+        more_like_id: 42,
+    }));
+    strict_1.default.equal(query.get("query"), "invoice 2024");
+    strict_1.default.equal(query.get("search"), "jan");
+    strict_1.default.equal(query.get("more_like_id"), "42");
+});
+(0, node_test_1.test)("serializes first-class document filters using Paperless parameter names", () => {
+    const query = getQueryParams((0, documentQuery_1.buildDocumentQueryString)({
+        page: 2,
+        page_size: 50,
+        ordering: "-created",
+        correspondent: 3,
+        document_type: 4,
+        tag: 5,
+        storage_path: 6,
+        created__date__gte: "2024-01-01",
+        created__date__lte: "2024-12-31",
+        archive_serial_number: 99,
+        archive_serial_number__isnull: false,
+        custom_fields__icontains: "invoice",
+    }));
+    strict_1.default.equal(query.get("page"), "2");
+    strict_1.default.equal(query.get("page_size"), "50");
+    strict_1.default.equal(query.get("ordering"), "-created");
+    strict_1.default.equal(query.get("correspondent__id"), "3");
+    strict_1.default.equal(query.get("document_type__id"), "4");
+    strict_1.default.equal(query.get("tags__id"), "5");
+    strict_1.default.equal(query.get("storage_path__id"), "6");
+    strict_1.default.equal(query.get("created__date__gte"), "2024-01-01");
+    strict_1.default.equal(query.get("created__date__lte"), "2024-12-31");
+    strict_1.default.equal(query.get("archive_serial_number"), "99");
+    strict_1.default.equal(query.get("archive_serial_number__isnull"), "false");
+    strict_1.default.equal(query.get("custom_fields__icontains"), "invoice");
+});
+(0, node_test_1.test)("serializes paperless_filters arrays as comma-separated values", () => {
+    const query = getQueryParams((0, documentQuery_1.buildDocumentQueryString)({
+        paperless_filters: {
+            fields: ["title", "tags"],
+            id__in: [1, 2, 3],
+        },
+    }));
+    strict_1.default.equal(query.get("fields"), "title,tags");
+    strict_1.default.equal(query.get("id__in"), "1,2,3");
+});
+(0, node_test_1.test)("serializes raw list custom_field_query strings without JSON encoding", () => {
+    const rawCustomFieldQuery = '[7, "icontains", "value"]';
+    const query = getQueryParams((0, documentQuery_1.buildDocumentQueryString)({
+        custom_field_query: rawCustomFieldQuery,
+    }));
+    strict_1.default.equal(query.get("custom_field_query"), rawCustomFieldQuery);
+});
+(0, node_test_1.test)("serializes leaf custom_field_query values as JSON", () => {
+    const query = getQueryParams((0, documentQuery_1.buildDocumentQueryString)({
+        custom_field_query: ["Invoice Number", "exact", "12345"],
+    }));
+    strict_1.default.equal(query.get("custom_field_query"), JSON.stringify(["Invoice Number", "exact", "12345"]));
+});
+(0, node_test_1.test)("serializes numeric custom_field_query field IDs as JSON", () => {
+    const query = getQueryParams((0, documentQuery_1.buildDocumentQueryString)({
+        custom_field_query: [7, "exact", "12345"],
+    }));
+    strict_1.default.equal(query.get("custom_field_query"), JSON.stringify([7, "exact", "12345"]));
+});
+(0, node_test_1.test)("serializes grouped custom_field_query values as JSON", () => {
+    const groupedQuery = [
+        "OR",
+        [
+            ["Invoice Number", "isnull", true],
+            ["Invoice Number", "exact", ""],
+        ],
+    ];
+    const query = getQueryParams((0, documentQuery_1.buildDocumentQueryString)({
+        custom_field_query: groupedQuery,
+    }));
+    strict_1.default.equal(query.get("custom_field_query"), JSON.stringify(groupedQuery));
+});
+(0, node_test_1.test)("rejects unsupported paperless_filters keys", () => {
+    strict_1.default.throws(() => (0, documentQuery_1.buildDocumentQueryString)({
+        paperless_filters: {
+            not_a_real_filter: "value",
+        },
+    }), /Unsupported paperless_filters key/);
+});
+(0, node_test_1.test)("rejects duplicate first-class and paperless_filters definitions", () => {
+    strict_1.default.throws(() => (0, documentQuery_1.buildDocumentQueryString)({
+        correspondent: 7,
+        paperless_filters: {
+            correspondent__id: 7,
+        },
+    }), /Duplicate filter 'correspondent__id'/);
+});
+(0, node_test_1.test)("rejects invalid custom_field_query shapes", () => {
+    strict_1.default.equal(documentQuery_1.customFieldQuerySchema.safeParse(["field", "exact"]).success, false);
+    strict_1.default.equal(documentQuery_1.customFieldQuerySchema.safeParse(["AND", []]).success, false);
+    strict_1.default.equal(documentQuery_1.customFieldQuerySchema.safeParse(["AND", [["field"]]]).success, false);
+    strict_1.default.equal(documentQuery_1.customFieldQuerySchema.safeParse(["AND", "iexact", "foo"]).success, false);
+});
+(0, node_test_1.describe)("validateFilePath", () => {
+    let testDir;
+    let testFile;
+    let emptyFile;
+    let symlinkPath;
+    (0, node_test_1.before)(() => {
+        testDir = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "paperless-mcp-test-"));
+        testFile = (0, node_path_1.join)(testDir, "test.pdf");
+        (0, node_fs_1.writeFileSync)(testFile, "%PDF-1.4\ntest content");
+        emptyFile = (0, node_path_1.join)(testDir, "empty.pdf");
+        (0, node_fs_1.writeFileSync)(emptyFile, "");
+        symlinkPath = (0, node_path_1.join)(testDir, "link.pdf");
+        try {
+            (0, node_fs_1.symlinkSync)(testFile, symlinkPath);
+        }
+        catch (_a) {
+            // Skip if unsupported.
+        }
+    });
+    (0, node_test_1.after)(() => {
+        (0, node_fs_1.rmSync)(testDir, { recursive: true, force: true });
+    });
+    (0, node_test_1.test)("accepts a valid absolute file path", () => __awaiter(void 0, void 0, void 0, function* () {
+        yield strict_1.default.doesNotReject(() => (0, documents_1.validateFilePath)(testFile));
+    }));
+    (0, node_test_1.test)("rejects relative paths", () => __awaiter(void 0, void 0, void 0, function* () {
+        yield strict_1.default.rejects(() => (0, documents_1.validateFilePath)("relative/path.pdf"), {
+            message: "file_path must be an absolute path",
+        });
+    }));
+    (0, node_test_1.test)("rejects non-existent files", () => __awaiter(void 0, void 0, void 0, function* () {
+        yield strict_1.default.rejects(() => (0, documents_1.validateFilePath)((0, node_path_1.join)(testDir, "missing.pdf")), { message: "File not found" });
+    }));
+    (0, node_test_1.test)("rejects directories", () => __awaiter(void 0, void 0, void 0, function* () {
+        yield strict_1.default.rejects(() => (0, documents_1.validateFilePath)(testDir), {
+            message: "Path must point to a regular file",
+        });
+    }));
+    (0, node_test_1.test)("rejects empty files", () => __awaiter(void 0, void 0, void 0, function* () {
+        yield strict_1.default.rejects(() => (0, documents_1.validateFilePath)(emptyFile), {
+            message: "File is empty",
+        });
+    }));
+    (0, node_test_1.test)("resolves symlinks to the real file", () => __awaiter(void 0, void 0, void 0, function* () {
+        try {
+            yield strict_1.default.doesNotReject(() => (0, documents_1.validateFilePath)(symlinkPath));
+        }
+        catch (_a) {
+            // Skip on systems without symlink support.
+        }
+    }));
+    (0, node_test_1.test)("rejects files exceeding the maximum size", () => __awaiter(void 0, void 0, void 0, function* () {
+        const largeFile = (0, node_path_1.join)(testDir, "large.pdf");
+        (0, node_fs_1.writeFileSync)(largeFile, "%PDF-1.4\n");
+        (0, node_fs_1.truncateSync)(largeFile, 101 * 1024 * 1024);
+        yield strict_1.default.rejects(() => (0, documents_1.validateFilePath)(largeFile), {
+            message: /exceeds maximum allowed size/,
+        });
+    }));
+    (0, node_test_1.test)("accepts files within allowed upload paths", () => __awaiter(void 0, void 0, void 0, function* () {
+        const validate = validateFilePathWithAllowlist((0, node_fs_1.realpathSync)(testDir));
+        yield strict_1.default.doesNotReject(() => validate(testFile));
+    }));
+    (0, node_test_1.test)("rejects files outside allowed upload paths", () => __awaiter(void 0, void 0, void 0, function* () {
+        const validate = validateFilePathWithAllowlist("/some/other/path");
+        yield strict_1.default.rejects(() => validate(testFile), {
+            message: /outside allowed upload directories/,
+        });
+    }));
+});
+class TestTransport {
+    start() {
+        return __awaiter(this, void 0, void 0, function* () { });
+    }
+    send(message) {
+        return __awaiter(this, void 0, void 0, function* () {
+            queueMicrotask(() => { var _a, _b; return (_b = (_a = this.peer) === null || _a === void 0 ? void 0 : _a.onmessage) === null || _b === void 0 ? void 0 : _b.call(_a, message); });
+        });
+    }
+    close() {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            (_a = this.onclose) === null || _a === void 0 ? void 0 : _a.call(this);
+        });
+    }
+}
+function createTransportPair() {
+    const clientTransport = new TestTransport();
+    const serverTransport = new TestTransport();
+    clientTransport.peer = serverTransport;
+    serverTransport.peer = clientTransport;
+    return { clientTransport, serverTransport };
+}
+function parseToolText(result) {
+    var _a;
+    const item = (_a = result.content) === null || _a === void 0 ? void 0 : _a[0];
+    if (!item || item.type !== "text") {
+        throw new Error("Expected text tool response");
+    }
+    return JSON.parse(item.text);
+}
+function withDocumentClient(api, run) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const server = new mcp_js_1.McpServer({ name: "paperless-doc-test", version: "1.0.0" });
+        (0, documents_1.registerDocumentTools)(server, api);
+        const client = new index_js_1.Client({
+            name: "paperless-doc-test-client",
+            version: "1.0.0",
+        });
+        const { clientTransport, serverTransport } = createTransportPair();
+        yield server.connect(serverTransport);
+        yield client.connect(clientTransport);
+        try {
+            yield run(client);
+        }
+        finally {
+            yield client.close();
+            yield server.close();
+        }
+    });
+}
+function createDocumentApi(fields) {
+    const calls = {
+        updateDocument: [],
+        bulkEditDocuments: [],
+        getCustomField: [],
+    };
+    const fieldMap = new Map(fields.map((field) => [field.id, field]));
+    const api = {
+        getCustomField: (id) => __awaiter(this, void 0, void 0, function* () {
+            calls.getCustomField.push(id);
+            const field = fieldMap.get(id);
+            if (!field)
+                throw new Error(`custom field ${id} not found`);
+            return field;
+        }),
+        updateDocument: (id, data) => __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            calls.updateDocument.push([id, data]);
+            return { id, custom_fields: (_a = data.custom_fields) !== null && _a !== void 0 ? _a : [] };
+        }),
+        bulkEditDocuments: (documents, method, parameters) => __awaiter(this, void 0, void 0, function* () {
+            calls.bulkEditDocuments.push([documents, method, parameters]);
+            return { result: "OK" };
+        }),
+        getCorrespondents: () => __awaiter(this, void 0, void 0, function* () { return ({ results: [] }); }),
+        getDocumentTypes: () => __awaiter(this, void 0, void 0, function* () { return ({ results: [] }); }),
+        getTags: () => __awaiter(this, void 0, void 0, function* () { return ({ results: [] }); }),
+        getCustomFields: () => __awaiter(this, void 0, void 0, function* () { return ({ results: [] }); }),
+    };
+    return { api, calls };
+}
+const LEGACY_SELECT_FIELD = {
+    id: 2,
+    name: "Retention period",
+    data_type: "select",
+    extra_data: { select_options: ["1 year", "7 years", "2 years"], default_currency: null },
+    document_count: 10,
+};
+const OBJECT_SELECT_FIELD = {
+    id: 3,
+    name: "Priority",
+    data_type: "select",
+    extra_data: {
+        select_options: [
+            { id: "abc123", label: "Low" },
+            { id: "def456", label: "High" },
+        ],
+    },
+    document_count: 5,
+};
+(0, node_test_1.describe)("select custom field value resolution in document handlers", () => {
+    (0, node_test_1.test)("update_document translates a select label to its zero-based index", () => __awaiter(void 0, void 0, void 0, function* () {
+        const { api, calls } = createDocumentApi([LEGACY_SELECT_FIELD]);
+        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, custom_fields: [{ field: 2, value: "1 year" }] },
+            }));
+            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.deepEqual(data.custom_fields, [{ field: 2, value: 0 }]);
+    }));
+    (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;
+            const result = (yield client.callTool({
+                name: "update_document",
+                arguments: { id: 7, custom_fields: [{ field: 3, value: "High" }] },
+            }));
+            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: "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]);
+        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, 2],
+                    method: "modify_custom_fields",
+                    add_custom_fields: [{ field: 2, value: "7 years" }],
+                },
+            }));
+            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 [, , parameters] = calls.bulkEditDocuments[0];
+        strict_1.default.deepEqual(parameters.add_custom_fields, { "2": 1 });
+    }));
+    (0, node_test_1.test)("bulk_edit_documents 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;
+            const result = (yield client.callTool({
+                name: "bulk_edit_documents",
+                arguments: {
+                    documents: [1],
+                    method: "modify_custom_fields",
+                    add_custom_fields: [{ field: 3, value: "High" }],
+                },
+            }));
+            strict_1.default.ok(!result.isError, (_a = parseToolText(result)) === null || _a === void 0 ? void 0 : _a.error);
+        }));
+        const [, , parameters] = calls.bulkEditDocuments[0];
+        strict_1.default.deepEqual(parameters.add_custom_fields, { "3": "def456" });
+    }));
+    (0, node_test_1.test)("update_document rejects an unknown select option with a helpful error", () => __awaiter(void 0, void 0, void 0, function* () {
+        const { api, calls } = createDocumentApi([LEGACY_SELECT_FIELD]);
+        yield withDocumentClient(api, (client) => __awaiter(void 0, void 0, void 0, function* () {
+            var _a, _b;
+            const result = (yield client.callTool({
+                name: "update_document",
+                arguments: { id: 42, custom_fields: [{ field: 2, value: "forever" }] },
+            }));
+            strict_1.default.ok(result.isError, "expected an error for an unknown select option");
+            const message = (_b = (_a = parseToolText(result)) === null || _a === void 0 ? void 0 : _a.error) !== null && _b !== void 0 ? _b : "";
+            strict_1.default.match(message, /forever/);
+            strict_1.default.match(message, /1 year/);
+        }));
+        strict_1.default.equal(calls.updateDocument.length, 0, "no document update should be sent when the option is invalid");
+    }));
+});

package/build/tools/mail.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp";
+import { PaperlessAPI } from "../api/PaperlessAPI";
+export declare function registerMailTools(server: McpServer, api: PaperlessAPI): void;

package/build/tools/mail.js

@@ -0,0 +1,187 @@
+"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 __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerMailTools = registerMailTools;
+const zod_1 = require("zod");
+const middlewares_1 = require("./utils/middlewares");
+const queryString_1 = require("./utils/queryString");
+const MAIL_RULE_ACTION_DESCRIPTION = "Mail rule action: 1=Delete, 2=Move to specified folder, 3=Mark as read/don't process read mails, 4=Flag/don't process flagged mails, 5=Tag/don't process tagged mails";
+const ASSIGN_TITLE_FROM_DESCRIPTION = "Title assignment: 1=Use subject as title, 2=Use attachment filename as title, 3=Do not assign title from rule";
+const ASSIGN_CORRESPONDENT_FROM_DESCRIPTION = "Correspondent assignment: 1=Do not assign, 2=Use mail address, 3=Use sender name or address, 4=Use assign_correspondent";
+const ATTACHMENT_TYPE_DESCRIPTION = "Attachment type: 1=Only process attachments, 2=Process all files including inline attachments";
+const CONSUMPTION_SCOPE_DESCRIPTION = "Consumption scope: 1=Only process attachments, 2=Process full mail as .eml, 3=Process full mail and attachments separately";
+const PDF_LAYOUT_DESCRIPTION = "PDF layout for full-mail consumption: 0=System default, 1=Text then HTML, 2=HTML then text, 3=HTML only, 4=Text only";
+const mailRuleFields = {
+    name: zod_1.z.string().optional(),
+    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_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(),
+    action: zod_1.z
+        .number()
+        .int()
+        .min(1)
+        .max(5)
+        .optional()
+        .describe(MAIL_RULE_ACTION_DESCRIPTION),
+    action_parameter: zod_1.z.string().nullable().optional(),
+    assign_title_from: zod_1.z
+        .number()
+        .int()
+        .min(1)
+        .max(3)
+        .optional()
+        .describe(ASSIGN_TITLE_FROM_DESCRIPTION),
+    assign_tags: zod_1.z.array(zod_1.z.number().int().nullable()).optional(),
+    assign_correspondent_from: zod_1.z
+        .number()
+        .int()
+        .min(1)
+        .max(4)
+        .optional()
+        .describe(ASSIGN_CORRESPONDENT_FROM_DESCRIPTION),
+    assign_correspondent: zod_1.z.number().int().nullable().optional(),
+    assign_document_type: zod_1.z.number().int().nullable().optional(),
+    assign_owner_from_rule: zod_1.z.boolean().optional(),
+    order: zod_1.z.number().int().optional(),
+    attachment_type: zod_1.z
+        .number()
+        .int()
+        .min(1)
+        .max(2)
+        .optional()
+        .describe(ATTACHMENT_TYPE_DESCRIPTION),
+    consumption_scope: zod_1.z
+        .number()
+        .int()
+        .min(1)
+        .max(3)
+        .optional()
+        .describe(CONSUMPTION_SCOPE_DESCRIPTION),
+    pdf_layout: zod_1.z
+        .number()
+        .int()
+        .min(0)
+        .max(4)
+        .optional()
+        .describe(PDF_LAYOUT_DESCRIPTION),
+    owner: zod_1.z.number().int().nullable().optional(),
+};
+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 = {}) {
+        if (!api)
+            throw new Error("Please configure API connection first");
+        const queryString = (0, queryString_1.buildQueryString)(args);
+        const response = yield api.getMailAccounts(queryString);
+        const sanitizedResults = (response.results || []).map((account) => (Object.assign(Object.assign({}, account), { password: undefined })));
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(Object.assign(Object.assign({}, response), { results: sanitizedResults })),
+                },
+            ],
+        };
+    })));
+    server.tool("get_mail_account", "Get one Paperless mail account by ID. Password/token fields are redacted if the server returns them.", { id: zod_1.z.number().int() }, (0, middlewares_1.withErrorHandling)((args) => __awaiter(this, void 0, void 0, function* () {
+        if (!api)
+            throw new Error("Please configure API connection first");
+        const _a = yield api.getMailAccount(args.id), { password } = _a, account = __rest(_a, ["password"]);
+        return {
+            content: [{ type: "text", text: JSON.stringify(account) }],
+        };
+    })));
+    server.tool("process_mail_account", "Manually run Paperless mail processing for one account. This can consume matching mails according to enabled Paperless mail rules.", { id: zod_1.z.number().int() }, (0, middlewares_1.withErrorHandling)((args) => __awaiter(this, void 0, void 0, function* () {
+        if (!api)
+            throw new Error("Please configure API connection first");
+        yield api.processMailAccount(args.id);
+        return {
+            content: [
+                { type: "text", text: JSON.stringify({ status: "processed" }) },
+            ],
+        };
+    })));
+    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 = {}) {
+        if (!api)
+            throw new Error("Please configure API connection first");
+        const queryString = (0, queryString_1.buildQueryString)(args);
+        const response = yield api.getMailRules(queryString);
+        return {
+            content: [{ type: "text", text: JSON.stringify(response) }],
+        };
+    })));
+    server.tool("get_mail_rule", "Get one Paperless mail rule by ID.", { id: zod_1.z.number().int() }, (0, middlewares_1.withErrorHandling)((args) => __awaiter(this, void 0, void 0, function* () {
+        if (!api)
+            throw new Error("Please configure API connection first");
+        const response = yield api.getMailRule(args.id);
+        return {
+            content: [{ type: "text", text: JSON.stringify(response) }],
+        };
+    })));
+    server.tool("create_mail_rule", "Create a Paperless mail rule. Use list_mail_accounts first to choose account. Prefer attachment-only rules for invoices unless the full mail must be archived.", Object.assign(Object.assign({}, mailRuleFields), { name: zod_1.z.string(), account: zod_1.z.number().int(), folder: zod_1.z.string() }), (0, middlewares_1.withErrorHandling)((args) => __awaiter(this, void 0, void 0, function* () {
+        if (!api)
+            throw new Error("Please configure API connection first");
+        const response = yield api.createMailRule(args);
+        return {
+            content: [{ type: "text", text: JSON.stringify(response) }],
+        };
+    })));
+    server.tool("update_mail_rule", "Patch an existing Paperless mail rule. Only supplied fields are changed.", Object.assign({ id: zod_1.z.number().int() }, mailRuleFields), (0, middlewares_1.withErrorHandling)((args) => __awaiter(this, void 0, void 0, function* () {
+        if (!api)
+            throw new Error("Please configure API connection first");
+        const { id } = args, data = __rest(args, ["id"]);
+        const response = yield api.updateMailRule(id, data);
+        return {
+            content: [{ type: "text", text: JSON.stringify(response) }],
+        };
+    })));
+    server.tool("delete_mail_rule", "Delete one Paperless mail rule. This changes future mail ingestion behavior but does not delete documents.", {
+        id: zod_1.z.number().int(),
+        confirm: zod_1.z
+            .boolean()
+            .describe("Must be true to confirm deleting the rule"),
+    }, (0, middlewares_1.withErrorHandling)((args) => __awaiter(this, void 0, void 0, function* () {
+        if (!api)
+            throw new Error("Please configure API connection first");
+        if (!args.confirm) {
+            throw new Error("Confirmation required. Set confirm: true to delete the mail rule.");
+        }
+        yield api.deleteMailRule(args.id);
+        return {
+            content: [
+                { type: "text", text: JSON.stringify({ status: "deleted" }) },
+            ],
+        };
+    })));
+}

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

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