@baruchiro/paperless-mcp 0.5.1 → 2.0.0

package/build/tools/documents.js

@@ -20,15 +20,59 @@ var __rest = (this && this.__rest) || function (s, e) {
     return t;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateFilePath = validateFilePath;
 exports.buildBulkEditParameters = buildBulkEditParameters;
 exports.registerDocumentTools = registerDocumentTools;
 const zod_1 = require("zod");
+const promises_1 = require("fs/promises");
+const path_1 = require("path");
 const documentEnhancer_1 = require("../api/documentEnhancer");
 const empty_1 = require("./utils/empty");
+const documentQuery_1 = require("./utils/documentQuery");
 const middlewares_1 = require("./utils/middlewares");
 const monetary_1 = require("./utils/monetary");
+const selectFields_1 = require("./utils/selectFields");
 const descriptions_1 = require("./utils/descriptions");
 const resourceUri_1 = require("./utils/resourceUri");
+const MAX_FILE_SIZE_BYTES = 100 * 1024 * 1024;
+const ALLOWED_UPLOAD_PATHS = process.env.PAPERLESS_MCP_UPLOAD_PATHS
+    ? process.env.PAPERLESS_MCP_UPLOAD_PATHS.split(":")
+    : [];
+/** Validates that a file path is safe to read for document upload. */
+function validateFilePath(filePath) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (!(0, path_1.isAbsolute)(filePath)) {
+            throw new Error("file_path must be an absolute path");
+        }
+        // Resolve symlinks to get canonical path for allowlist checks
+        let realPath;
+        try {
+            realPath = yield (0, promises_1.realpath)(filePath);
+        }
+        catch (_a) {
+            throw new Error("File not found");
+        }
+        if (ALLOWED_UPLOAD_PATHS.length > 0) {
+            const isAllowed = ALLOWED_UPLOAD_PATHS.some((allowedPath) => {
+                return realPath.startsWith(allowedPath + "/") || realPath === allowedPath;
+            });
+            if (!isAllowed) {
+                throw new Error("file_path is outside allowed upload directories. " +
+                    "Configure PAPERLESS_MCP_UPLOAD_PATHS environment variable to specify allowed paths.");
+            }
+        }
+        const stats = yield (0, promises_1.stat)(realPath);
+        if (!stats.isFile()) {
+            throw new Error("Path must point to a regular file");
+        }
+        if (stats.size > MAX_FILE_SIZE_BYTES) {
+            throw new Error(`File size (${Math.round(stats.size / 1024 / 1024)}MB) exceeds maximum allowed size (${MAX_FILE_SIZE_BYTES / 1024 / 1024}MB)`);
+        }
+        if (stats.size === 0) {
+            throw new Error("File is empty");
+        }
+    });
+}
 /**
  * Builds Paperless-NGX bulk edit parameters from base parameters plus optional
  * custom field updates.
@@ -52,8 +96,9 @@ const resourceUri_1 = require("./utils/resourceUri");
  * @returns The merged API parameters with custom field updates transformed into
  * Paperless-NGX's `add_custom_fields` record shape.
  */
-function buildBulkEditParameters(parameters, addCustomFields, includeCustomFieldDefaults = false) {
-    var _a, _b;
+function buildBulkEditParameters(parameters, addCustomFields, includeCustomFieldDefaults = false, includeTagDefaults = false) {
+    var _a, _b, _c, _d;
+    var _e, _f;
     const apiParameters = Object.assign({}, parameters);
     if (addCustomFields) {
         apiParameters.add_custom_fields = Object.fromEntries(addCustomFields.map((customField) => [
@@ -65,8 +110,18 @@ function buildBulkEditParameters(parameters, addCustomFields, includeCustomField
         (_a = apiParameters.add_custom_fields) !== null && _a !== void 0 ? _a : (apiParameters.add_custom_fields = {});
         (_b = apiParameters.remove_custom_fields) !== null && _b !== void 0 ? _b : (apiParameters.remove_custom_fields = []);
     }
+    if (includeTagDefaults) {
+        (_c = (_e = apiParameters).add_tags) !== null && _c !== void 0 ? _c : (_e.add_tags = []);
+        (_d = (_f = apiParameters).remove_tags) !== null && _d !== void 0 ? _d : (_f.remove_tags = []);
+    }
     return apiParameters;
 }
+function executeDocumentQuery(api, args) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const docsResponse = yield api.getDocuments((0, documentQuery_1.buildDocumentQueryString)(args));
+        return (0, documentEnhancer_1.convertDocsWithNames)(docsResponse, api);
+    });
+}
 function registerDocumentTools(server, api) {
     server.tool("bulk_edit_documents", "Perform bulk operations on multiple documents. Note: 'remove_tag' removes a tag from specific documents (tag remains in system), while 'delete_tag' permanently deletes a tag from the entire system. ⚠️ WARNING: 'delete' method permanently deletes documents and requires confirmation.", {
         documents: zod_1.z.array(zod_1.z.number()),
@@ -144,9 +199,10 @@ function registerDocumentTools(server, api) {
         }
         const { documents, method, add_custom_fields, confirm } = args, parameters = __rest(args, ["documents", "method", "add_custom_fields", "confirm"]);
         (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"
             ? {}
-            : buildBulkEditParameters(parameters, add_custom_fields, method === "modify_custom_fields"));
+            : buildBulkEditParameters(parameters, resolvedCustomFields, method === "modify_custom_fields", method === "modify_tags"));
         return {
             content: [
                 {
@@ -156,9 +212,10 @@ function registerDocumentTools(server, api) {
             ],
         };
     })));
-    server.tool("post_document", "Upload a new document to Paperless-NGX with optional metadata like title, correspondent, document type, tags, and custom fields.", {
-        file: zod_1.z.string(),
-        filename: zod_1.z.string(),
+    const postDocumentBaseSchema = zod_1.z.object({
+        file: zod_1.z.string().optional().describe("Base64-encoded file content. Either 'file' or 'file_path' must be provided."),
+        file_path: zod_1.z.string().optional().describe("Absolute path to a file on the server's filesystem. Either 'file' or 'file_path' must be provided. The filename is derived from the path unless 'filename' is also specified. For security, configure PAPERLESS_MCP_UPLOAD_PATHS to restrict allowed directories."),
+        filename: zod_1.z.string().optional().describe("Filename for the uploaded document. Required when using 'file', optional when using 'file_path' (defaults to the basename of the path)."),
         title: zod_1.z.string().optional(),
         created: zod_1.z.string().optional(),
         correspondent: zod_1.z.number().optional(),
@@ -167,16 +224,90 @@ function registerDocumentTools(server, api) {
         tags: zod_1.z.array(zod_1.z.number()).optional(),
         archive_serial_number: zod_1.z.number().optional(),
         custom_fields: zod_1.z.array(zod_1.z.number()).optional(),
-    }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
+    });
+    const postDocumentSchema = postDocumentBaseSchema.superRefine((data, ctx) => {
+        const hasFile = data.file !== undefined;
+        const hasFilePath = data.file_path !== undefined;
+        if (!hasFile && !hasFilePath) {
+            ctx.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                message: "Either 'file' (base64) or 'file_path' must be provided.",
+                path: ["file"],
+            });
+            ctx.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                message: "Either 'file' (base64) or 'file_path' must be provided.",
+                path: ["file_path"],
+            });
+        }
+        if (hasFile && hasFilePath) {
+            ctx.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                message: "Only one of 'file' or 'file_path' should be provided, not both.",
+                path: ["file"],
+            });
+            ctx.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                message: "Only one of 'file' or 'file_path' should be provided, not both.",
+                path: ["file_path"],
+            });
+        }
+        if (hasFile && !data.filename) {
+            ctx.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                message: "'filename' is required when using 'file' (base64 mode).",
+                path: ["filename"],
+            });
+        }
+        if (hasFilePath && data.file_path && !(0, path_1.isAbsolute)(data.file_path)) {
+            ctx.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                message: "file_path must be an absolute path",
+                path: ["file_path"],
+            });
+        }
+    });
+    server.tool("post_document", "Upload a new document to Paperless-NGX with optional metadata like title, correspondent, document type, tags, and custom fields. Provide either 'file' (base64-encoded content) or 'file_path' (absolute path to a file on the server's filesystem). Using file_path avoids base64 encoding overhead for large files. SECURITY: When using file_path, set PAPERLESS_MCP_UPLOAD_PATHS environment variable to restrict uploads to specific directories (colon-separated paths).", postDocumentBaseSchema.shape, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
         if (!api)
             throw new Error("Please configure API connection first");
-        // Validate base64 input
-        const base64Regex = /^[A-Za-z0-9+/]*={0,2}$/;
-        if (!base64Regex.test(args.file)) {
-            throw new Error("Invalid base64-encoded file data. Please provide a valid base64 string.");
+        const validationResult = postDocumentSchema.safeParse(args);
+        if (!validationResult.success) {
+            throw new Error(validationResult.error.errors.map(e => e.message).join("; "));
+        }
+        let document;
+        let filename;
+        if (args.file_path) {
+            yield validateFilePath(args.file_path);
+            try {
+                document = yield (0, promises_1.readFile)(args.file_path);
+            }
+            catch (err) {
+                throw new Error("Failed to read file");
+            }
+            filename = args.filename || (0, path_1.basename)(args.file_path);
+            if (!filename) {
+                throw new Error("Could not derive filename from file_path");
+            }
+        }
+        else if (args.file) {
+            const base64Regex = /^[A-Za-z0-9+/]*={0,2}$/;
+            if (!base64Regex.test(args.file)) {
+                throw new Error("Invalid base64-encoded file data. Please provide a valid base64 string.");
+            }
+            document = Buffer.from(args.file, "base64");
+            if (document.length > MAX_FILE_SIZE_BYTES) {
+                throw new Error(`File size (${Math.round(document.length / 1024 / 1024)}MB) exceeds maximum allowed size (${MAX_FILE_SIZE_BYTES / 1024 / 1024}MB)`);
+            }
+            if (document.length === 0) {
+                throw new Error("File is empty");
+            }
+            filename = args.filename;
+        }
+        else {
+            // This should never happen due to schema validation, but TypeScript needs it
+            throw new Error("Either 'file' (base64) or 'file_path' must be provided.");
         }
-        const { file, filename } = args, metadata = __rest(args, ["file", "filename"]);
-        const document = Buffer.from(file, "base64");
+        const { file, file_path, filename: _fn } = args, metadata = __rest(args, ["file", "file_path", "filename"]);
         const response = yield api.postDocument(document, filename, metadata);
         let result;
         if (typeof response === "string" && /^\d+$/.test(response)) {
@@ -194,43 +325,15 @@ function registerDocumentTools(server, api) {
             ],
         };
     })));
-    server.tool("list_documents", "List and filter documents by fields such as title, correspondent, document type, tag, storage path, creation date, and more. IMPORTANT: For queries like 'the last 3 contributions' or when searching by tag, correspondent, document type, or storage path, you should FIRST use the relevant tool (e.g., 'list_tags', 'list_correspondents', 'list_document_types', 'list_storage_paths') to find the correct ID, and then use that ID as a filter here. Only use the 'search' argument for free-text search when no specific field applies. Using the correct ID filter will yield much more accurate results. Note: Document content is excluded from results by default. Use 'get_document_content' to retrieve content when needed.", {
-        page: zod_1.z.number().optional(),
-        page_size: zod_1.z.number().optional(),
-        search: zod_1.z.string().optional(),
-        correspondent: zod_1.z.number().optional(),
-        document_type: zod_1.z.number().optional(),
-        tag: zod_1.z.number().optional(),
-        storage_path: zod_1.z.number().optional(),
-        created__date__gte: zod_1.z.string().optional(),
-        created__date__lte: zod_1.z.string().optional(),
-        ordering: zod_1.z.string().optional(),
-    }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
+    server.tool("list_documents", "List and filter documents with pagination and common Paperless filters such as title search, correspondent, document type, tag, storage path, creation date, archive serial number, and simple custom field filters. Use 'query_documents' for full-text query, structured custom field conditions, or advanced documented /api/documents/ query parameters. IMPORTANT: For queries like 'the last 3 contributions' or when searching by tag, correspondent, document type, or storage path, first use the relevant lookup tool to find the correct ID. Note: Document content is excluded from results by default. Use 'get_document_content' when you need the document text.", documentQuery_1.LIST_DOCUMENTS_ARGS_SHAPE, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
         if (!api)
             throw new Error("Please configure API connection first");
-        const query = new URLSearchParams();
-        if (args.page)
-            query.set("page", args.page.toString());
-        if (args.page_size)
-            query.set("page_size", args.page_size.toString());
-        if (args.search)
-            query.set("search", args.search);
-        if (args.correspondent)
-            query.set("correspondent__id", args.correspondent.toString());
-        if (args.document_type)
-            query.set("document_type__id", args.document_type.toString());
-        if (args.tag)
-            query.set("tags__id", args.tag.toString());
-        if (args.storage_path)
-            query.set("storage_path__id", args.storage_path.toString());
-        if (args.created__date__gte)
-            query.set("created__date__gte", args.created__date__gte);
-        if (args.created__date__lte)
-            query.set("created__date__lte", args.created__date__lte);
-        if (args.ordering)
-            query.set("ordering", args.ordering);
-        const docsResponse = yield api.getDocuments(query.toString() ? `?${query.toString()}` : "");
-        return (0, documentEnhancer_1.convertDocsWithNames)(docsResponse, api);
+        return executeDocumentQuery(api, args);
+    })));
+    server.tool("query_documents", "Query documents using the full-text query engine plus structured Paperless filters. Use this for complex filtering, custom field conditions, or any documented /api/documents/ query parameters that are not exposed as first-class arguments. Prefer the dedicated top-level arguments where available. custom_field_query supports [field_name_or_id, operator, value] leaves or ['AND'|'OR', [clause1, clause2]] groups. Note: Document content is excluded from results by default. Use 'get_document_content' when you need the document text.", documentQuery_1.QUERY_DOCUMENTS_ARGS_SHAPE, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
+        if (!api)
+            throw new Error("Please configure API connection first");
+        return executeDocumentQuery(api, args);
     })));
     server.tool("get_document", "Get a specific document by ID with full details including correspondent, document type, tags, and custom fields. Note: Document content is excluded from results by default. Use 'get_document_content' to retrieve content when needed.", {
         id: zod_1.z.number(),
@@ -259,51 +362,50 @@ function registerDocumentTools(server, api) {
             ],
         };
     })));
-    server.tool("search_documents", "Full text search for documents. This tool is for searching document content, title, and metadata using a full text query. For general document listing or filtering by fields, use 'list_documents' instead. Note: Document content is excluded from results by default. Use 'get_document_content' to retrieve content when needed.", {
-        query: zod_1.z.string(),
-    }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
+    server.tool("search_documents", "Deprecated compatibility wrapper for full-text document search. Use 'query_documents' with the 'query' argument for new integrations. Note: Document content is excluded from results by default. Use 'get_document_content' to retrieve content when needed.", documentQuery_1.SEARCH_DOCUMENTS_ARGS_SHAPE, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
         if (!api)
             throw new Error("Please configure API connection first");
-        const docsResponse = yield api.searchDocuments(args.query);
-        return (0, documentEnhancer_1.convertDocsWithNames)(docsResponse, api);
+        return executeDocumentQuery(api, args);
     })));
-    server.tool("download_document", "Download a document file by ID. Returns the document as a base64-encoded resource.", {
-        id: zod_1.z.number(),
+    server.tool("download_document", "Download a document file by ID. Returns a paperless:// resource URI; read the resource to fetch the file content.", {
+        id: zod_1.z.number().int().positive(),
         original: zod_1.z.boolean().optional(),
     }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
-        var _a, _b;
         if (!api)
             throw new Error("Please configure API connection first");
-        const response = yield api.downloadDocument(args.id, args.original);
-        const filename = ((_b = (_a = (typeof response.headers.get === "function"
-            ? response.headers.get("content-disposition")
-            : response.headers["content-disposition"])) === null || _a === void 0 ? void 0 : _a.split("filename=")[1]) === null || _b === void 0 ? void 0 : _b.replace(/"/g, "")) || `document-${args.id}`;
+        const uri = (0, resourceUri_1.buildDocumentResourceUri)(args.id, {
+            original: args.original,
+        });
         return {
             content: [
                 {
                     type: "resource",
                     resource: {
-                        uri: (0, resourceUri_1.buildDocumentResourceUri)(args.id, filename),
-                        blob: Buffer.from(response.data).toString("base64"),
-                        mimeType: "application/pdf",
+                        uri,
+                        // MCP SDK 1.11 embedded resources require text or blob. Keep the
+                        // existing resource-shaped tool result while making resources/read
+                        // the canonical place for the large binary payload.
+                        text: "",
+                        mimeType: "application/octet-stream",
                     },
                 },
             ],
         };
     })));
-    server.tool("get_document_thumbnail", "Get a document thumbnail (image preview) by ID. Returns the thumbnail as a base64-encoded WebP image resource.", {
-        id: zod_1.z.number(),
+    server.tool("get_document_thumbnail", "Get a document thumbnail (image preview) by ID. Returns a paperless:// resource URI; read the resource to fetch the image content.", {
+        id: zod_1.z.number().int().positive(),
     }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
         if (!api)
             throw new Error("Please configure API connection first");
-        const response = yield api.getThumbnail(args.id);
         return {
             content: [
                 {
                     type: "resource",
                     resource: {
                         uri: (0, resourceUri_1.buildThumbnailResourceUri)(args.id),
-                        blob: Buffer.from(response.data).toString("base64"),
+                        // See download_document above: the binary thumbnail is fetched
+                        // lazily through resources/read instead of embedded here.
+                        text: "",
                         mimeType: "image/webp",
                     },
                 },
@@ -373,6 +475,7 @@ function registerDocumentTools(server, 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");
         const response = yield api.updateDocument(id, updateData);
         return (0, documentEnhancer_1.convertDocsWithNames)(response, api);
     })));