@baruchiro/paperless-mcp 1.0.0 → 2.0.0

package/build/resources/documents.d.ts

@@ -1,8 +1,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import type { ListResourcesResult, ReadResourceResult } from "@modelcontextprotocol/sdk/types";
+import type { ReadResourceResult } from "@modelcontextprotocol/sdk/types";
 import { PaperlessAPI } from "../api/PaperlessAPI";
 type TemplateVariables = Record<string, string | string[]>;
 export declare function registerDocumentResources(server: McpServer, api: PaperlessAPI): void;
-export declare function listDocumentResources(api: PaperlessAPI): Promise<ListResourcesResult>;
 export declare function readDocumentResource(api: PaperlessAPI, uri: URL, variables: TemplateVariables): Promise<ReadResourceResult>;
 export {};

package/build/resources/documents.js

@@ -10,13 +10,11 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerDocumentResources = registerDocumentResources;
-exports.listDocumentResources = listDocumentResources;
 exports.readDocumentResource = readDocumentResource;
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
-const resourceUri_1 = require("../tools/utils/resourceUri");
 function registerDocumentResources(server, api) {
     server.resource("paperless-document-resource", new mcp_js_1.ResourceTemplate("paperless://documents/{id}/{resource}", {
-        list: () => __awaiter(this, void 0, void 0, function* () { return listDocumentResources(api); }),
+        list: undefined,
     }), (uri, variables) => __awaiter(this, void 0, void 0, function* () { return readDocumentResource(api, uri, variables); }));
     server.resource("paperless-document-original-download", new mcp_js_1.ResourceTemplate("paperless://documents/{id}/download{?original}", {
         list: undefined,
@@ -24,22 +22,6 @@ function registerDocumentResources(server, api) {
         return readDocumentDownloadResource(api, uri, parseDocumentId(readVariable(variables, "id")), isTrueQueryValue(readVariable(variables, "original")));
     }));
 }
-function listDocumentResources(api) {
-    return __awaiter(this, void 0, void 0, function* () {
-        // Return only the first page of documents. Paperless libraries can
-        // contain tens of thousands of documents; expanding the full `all`
-        // ID array would produce an unbounded `resources/list` payload.
-        // Clients that need to enumerate more documents can use the
-        // `list_documents` tool (which paginates) and read
-        // `paperless://documents/{id}/download` directly — the resource
-        // template handles `resources/read` for any document ID.
-        const documentsResponse = yield api.getDocuments();
-        const documents = documentsResponse.results || [];
-        return {
-            resources: documents.flatMap((document) => buildResourcesForDocument(document.id, document)),
-        };
-    });
-}
 function readDocumentResource(api, uri, variables) {
     return __awaiter(this, void 0, void 0, function* () {
         assertPaperlessDocumentsUri(uri);
@@ -74,23 +56,6 @@ function readDocumentThumbnailResource(api, uri, id) {
         };
     });
 }
-function buildResourcesForDocument(id, document) {
-    const label = (document === null || document === void 0 ? void 0 : document.title) || (document === null || document === void 0 ? void 0 : document.original_file_name) || `Document ${id}`;
-    return [
-        {
-            uri: (0, resourceUri_1.buildDocumentResourceUri)(id),
-            name: `${label} download`,
-            description: `Full file content for Paperless document ${id}`,
-            mimeType: (document === null || document === void 0 ? void 0 : document.mime_type) || "application/octet-stream",
-        },
-        {
-            uri: (0, resourceUri_1.buildThumbnailResourceUri)(id),
-            name: `${label} thumbnail`,
-            description: `Thumbnail image for Paperless document ${id}`,
-            mimeType: "image/webp",
-        },
-    ];
-}
 function responseToResourceContents(uri, response, fallbackMimeType) {
     const mimeType = getHeader(response, "content-type") || fallbackMimeType;
     const data = Buffer.from(response.data);

package/build/resources/documents.test.js

@@ -78,11 +78,11 @@ function withResourceClient(api, run) {
         }
     });
 }
-(0, node_test_1.test)("resources/list exposes download and thumbnail resources for the first page only", () => __awaiter(void 0, void 0, void 0, function* () {
-    // `all` lists IDs across every page (potentially tens of thousands of
-    // documents) — `resources/list` must not expand that or it will produce
-    // an unbounded payload. Only the documents on the fetched page should
-    // appear; the rest are still reachable via the resource template.
+(0, node_test_1.test)("resources/list does not enumerate documents at startup", () => __awaiter(void 0, void 0, void 0, function* () {
+    // Documents are dynamic DMS data and must not be pre-registered as MCP
+    // resources: enumerating them floods `resources/list` and the LLM context
+    // window (issue #112). The list must stay empty even when documents exist;
+    // documents are reached on demand via tools + the `resources/read` template.
     const api = {
         getDocuments: () => __awaiter(void 0, void 0, void 0, function* () {
             return emptyPaginationResponse([
@@ -101,19 +101,7 @@ function withResourceClient(api, run) {
     };
     yield withResourceClient(api, (client) => __awaiter(void 0, void 0, void 0, function* () {
         const result = yield client.listResources();
-        strict_1.default.deepEqual(result.resources.map((resource) => resource.uri), [
-            "paperless://documents/1/download",
-            "paperless://documents/1/thumb",
-            "paperless://documents/2/download",
-            "paperless://documents/2/thumb",
-        ]);
-        strict_1.default.equal(result.resources[0].name, "Invoice download");
-        strict_1.default.equal(result.resources[0].mimeType, "application/pdf");
-        strict_1.default.equal(result.resources[3].name, "Receipt thumbnail");
-        // Document 3 lives in `all` but not on this page — it must not leak in.
-        for (const resource of result.resources) {
-            strict_1.default.ok(!resource.uri.includes("/3/"), `unexpected page-3 resource in list: ${resource.uri}`);
-        }
+        strict_1.default.deepEqual(result.resources, []);
     }));
 }));
 (0, node_test_1.test)("resources/read returns text contents for text responses", () => __awaiter(void 0, void 0, void 0, function* () {

package/build/server.d.ts

@@ -7,5 +7,18 @@ export interface CreateMcpServerOptions {
     publicUrl: string;
 }
 export declare function createMcpServer({ baseUrl, token, version, publicUrl, }: CreateMcpServerOptions): McpServer;
-export declare function getBearerToken(req: express.Request, fallbackToken?: string): string | undefined;
+export interface ResolveTokenOptions {
+    /**
+     * Server-configured token used as a fallback for unauthenticated requests.
+     * Only consulted when `allowAnonymous` is true.
+     */
+    fallbackToken?: string;
+    /**
+     * When true, requests without a `Bearer` header fall back to `fallbackToken`
+     * (the legacy behaviour). When false (the default in HTTP mode), a request
+     * without a `Bearer` header is rejected and never uses the server token.
+     */
+    allowAnonymous: boolean;
+}
+export declare function getBearerToken(req: express.Request, options: ResolveTokenOptions): string | undefined;
 export declare function sendUnauthorized(res: express.Response): void;

package/build/server.js

@@ -10,30 +10,44 @@ const correspondents_1 = require("./tools/correspondents");
 const customFields_1 = require("./tools/customFields");
 const documents_2 = require("./tools/documents");
 const documentTypes_1 = require("./tools/documentTypes");
+const mail_1 = require("./tools/mail");
+const notes_1 = require("./tools/notes");
 const tags_1 = require("./tools/tags");
 function createMcpServer({ baseUrl, token, version, publicUrl, }) {
     const api = new PaperlessAPI_1.PaperlessAPI(baseUrl, token);
     const server = new mcp_js_1.McpServer({ name: "paperless-ngx", version }, { instructions: buildInstructions(publicUrl) });
     (0, documents_2.registerDocumentTools)(server, api);
     (0, documents_1.registerDocumentResources)(server, api);
+    (0, notes_1.registerNoteTools)(server, api);
     (0, tags_1.registerTagTools)(server, api);
     (0, correspondents_1.registerCorrespondentTools)(server, api);
     (0, documentTypes_1.registerDocumentTypeTools)(server, api);
     (0, customFields_1.registerCustomFieldTools)(server, api);
+    (0, mail_1.registerMailTools)(server, api);
     return server;
 }
-function getBearerToken(req, fallbackToken) {
+function getBearerToken(req, options) {
     const authHeader = req.headers["authorization"];
     if (authHeader && authHeader.startsWith("Bearer ")) {
         return authHeader.slice(7);
     }
-    return fallbackToken || undefined;
+    if (options.allowAnonymous) {
+        return options.fallbackToken || undefined;
+    }
+    return undefined;
 }
 function sendUnauthorized(res) {
+    // Log operator-facing guidance server-side; keep the wire response minimal so
+    // we don't echo configuration hints back to unauthenticated callers.
+    console.error("[paperless-mcp] Rejected request with no 'Authorization: Bearer <paperless-ngx-api-token>' header. " +
+        "As of v2.0.0, HTTP mode requires a per-request Bearer token and no longer falls back to the " +
+        "server-configured token for unauthenticated requests. Have clients send their Paperless-NGX API " +
+        "token as a Bearer token, or restart the server with --no-auth to use the server token for " +
+        "unauthenticated requests (trusted/local networks only).");
     res
         .status(401)
         .set("WWW-Authenticate", 'Bearer realm="paperless-mcp"')
-        .end();
+        .json({ error: "unauthorized" });
 }
 function buildInstructions(publicUrl) {
     return `

package/build/server.test.d.ts

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

package/build/server.test.js

@@ -0,0 +1,54 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_test_1 = require("node:test");
+const strict_1 = __importDefault(require("node:assert/strict"));
+const server_1 = require("./server");
+function reqWith(authorization) {
+    return {
+        headers: authorization ? { authorization } : {},
+    };
+}
+(0, node_test_1.test)("client Bearer token takes precedence over the server token", () => {
+    const token = (0, server_1.getBearerToken)(reqWith("Bearer client-token"), {
+        fallbackToken: "server-token",
+        allowAnonymous: true,
+    });
+    strict_1.default.equal(token, "client-token");
+});
+(0, node_test_1.test)("client Bearer token is used even when anonymous access is disabled", () => {
+    const token = (0, server_1.getBearerToken)(reqWith("Bearer client-token"), {
+        fallbackToken: "server-token",
+        allowAnonymous: false,
+    });
+    strict_1.default.equal(token, "client-token");
+});
+(0, node_test_1.test)("falls back to the server token only when anonymous access is allowed", () => {
+    const token = (0, server_1.getBearerToken)(reqWith(), {
+        fallbackToken: "server-token",
+        allowAnonymous: true,
+    });
+    strict_1.default.equal(token, "server-token");
+});
+(0, node_test_1.test)("no header without anonymous access yields no token (request is rejected)", () => {
+    const token = (0, server_1.getBearerToken)(reqWith(), {
+        fallbackToken: "server-token",
+        allowAnonymous: false,
+    });
+    strict_1.default.equal(token, undefined);
+});
+(0, node_test_1.test)("non-Bearer Authorization scheme never leaks the server token by default", () => {
+    const token = (0, server_1.getBearerToken)(reqWith("Token server-token"), {
+        fallbackToken: "server-token",
+        allowAnonymous: false,
+    });
+    strict_1.default.equal(token, undefined);
+});
+(0, node_test_1.test)("anonymous access with no configured server token yields no token", () => {
+    const token = (0, server_1.getBearerToken)(reqWith(), {
+        allowAnonymous: true,
+    });
+    strict_1.default.equal(token, undefined);
+});

package/build/tools/documents.d.ts

@@ -9,6 +9,8 @@ export type BulkCustomFieldParameters = {
     add_custom_fields?: Record<string, BulkCustomFieldValue>;
     remove_custom_fields?: number[];
 };
+/** Validates that a file path is safe to read for document upload. */
+export declare function validateFilePath(filePath: string): Promise<void>;
 /**
  * Builds Paperless-NGX bulk edit parameters from base parameters plus optional
  * custom field updates.

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.
@@ -72,6 +116,12 @@ function buildBulkEditParameters(parameters, addCustomFields, includeCustomField
     }
     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()),
@@ -149,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", method === "modify_tags"));
+            : buildBulkEditParameters(parameters, resolvedCustomFields, method === "modify_custom_fields", method === "modify_tags"));
         return {
             content: [
                 {
@@ -161,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(),
@@ -172,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");
+            }
         }
-        const { file, filename } = args, metadata = __rest(args, ["file", "filename"]);
-        const document = Buffer.from(file, "base64");
+        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, 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)) {
@@ -199,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(),
@@ -264,13 +362,10 @@ 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 a paperless:// resource URI; read the resource to fetch the file content.", {
         id: zod_1.z.number().int().positive(),
@@ -380,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);
     })));