@baruchiro/paperless-mcp 0.4.4 → 0.5.0

package/README.md

@@ -59,6 +59,15 @@ Add these to your MCP config file:
    - `your-api-token` with the token you just generated
    - `https://your-public-domain.com` with your public Paperless-NGX URL (optional, falls back to PAPERLESS_URL)
 
+### Environment Variables
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `PAPERLESS_URL` | Yes | — | Base URL of your Paperless-NGX instance |
+| `PAPERLESS_API_KEY` | Yes | — | API token from your Paperless-NGX profile |
+| `PAPERLESS_PUBLIC_URL` | No | `PAPERLESS_URL` | Public-facing URL for document links |
+| `PAPERLESS_API_VERSION` | No | `5` | Paperless-ngx REST API version. Use `10` for Paperless-ngx v3+. If you see HTTP 406 errors, set this to `10`. |
+
 That's it! Now you can ask Claude to help you manage your Paperless-NGX documents.
 
 ### Example Usage
@@ -215,9 +224,20 @@ bulk_edit_documents({
 bulk_edit_documents({
   documents: [12, 13],
   method: "modify_custom_fields",
-  add_custom_fields: {
-    "2": "שנה"
-  }
+  add_custom_fields: [
+    { field: 2, value: "year" }
+  ],
+  remove_custom_fields: []
+})
+
+// Set an empty custom field value, e.g. a date field used as a pending marker
+bulk_edit_documents({
+  documents: [14],
+  method: "modify_custom_fields",
+  add_custom_fields: [
+    { field: 9, value: "" }
+  ],
+  remove_custom_fields: []
 })
 ```
 
@@ -483,6 +503,22 @@ npm run start -- <baseUrl> <token> --http --port 3000
 - Each request is handled statelessly, following the [StreamableHTTPServerTransport](https://github.com/modelcontextprotocol/typescript-sdk) pattern.
 - GET and DELETE requests to `/mcp` will return 405 Method Not Allowed.
 
+#### Per-request API token (HTTP/Docker mode)
+
+In HTTP mode, clients can supply their own Paperless-NGX API token via the standard `Authorization` header instead of (or in addition to) the server-configured `PAPERLESS_API_KEY`. The client-supplied token takes precedence.
+
+```
+Authorization: Bearer <paperless-ngx-api-token>
+```
+
+| Scenario | Token used |
+|---|---|
+| Client sends `Authorization: Bearer <tok>` | `<tok>` (client-supplied, takes precedence) |
+| No header, `PAPERLESS_API_KEY` env var set | `PAPERLESS_API_KEY` from env |
+| No header, no env var | `401 Unauthorized` |
+
+This allows a single server instance to serve multiple users, each authenticating with their own Paperless-NGX token. The same behaviour applies to both `/mcp` and `/sse` endpoints.
+
 <details>
 <summary>Docker Deployment</summary>
 

package/build/api/PaperlessAPI.d.ts

@@ -3,6 +3,7 @@ import { BulkEditDocumentsResult, BulkEditParameters, Correspondent, CustomField
 export declare class PaperlessAPI {
     private readonly baseUrl;
     private readonly token;
+    private readonly apiVersion;
     constructor(baseUrl: string, token: string);
     request<T = any>(path: string, options?: RequestInit): Promise<T>;
     bulkEditDocuments(documents: number[], method: string, parameters?: BulkEditParameters): Promise<BulkEditDocumentsResult>;

package/build/api/PaperlessAPI.js

@@ -22,13 +22,14 @@ class PaperlessAPI {
         this.token = token;
         this.baseUrl = baseUrl;
         this.token = token;
+        this.apiVersion = process.env.PAPERLESS_API_VERSION || "5";
     }
     request(path_1) {
         return __awaiter(this, arguments, void 0, function* (path, options = {}) {
-            var _a, _b;
+            var _a, _b, _c;
             const url = `${this.baseUrl}/api${path}`;
             const isJson = !options.body || typeof options.body === "string";
-            const mergedHeaders = Object.assign(Object.assign({ Authorization: `Token ${this.token}`, Accept: "application/json; version=5", "Accept-Language": "en-US,en;q=0.9" }, (isJson ? { "Content-Type": "application/json" } : {})), (0, utils_1.headersToObject)(options.headers));
+            const mergedHeaders = Object.assign(Object.assign({ Authorization: `Token ${this.token}`, Accept: `application/json; version=${this.apiVersion}`, "Accept-Language": "en-US,en;q=0.9" }, (isJson ? { "Content-Type": "application/json" } : {})), (0, utils_1.headersToObject)(options.headers));
             try {
                 const response = yield (0, axios_1.default)({
                     url,
@@ -54,13 +55,17 @@ class PaperlessAPI {
                 return body;
             }
             catch (error) {
+                if (axios_1.default.isAxiosError(error) && ((_a = error.response) === null || _a === void 0 ? void 0 : _a.status) === 406) {
+                    throw new Error(`HTTP 406: Paperless-ngx rejected API version ${this.apiVersion}. ` +
+                        `Set the PAPERLESS_API_VERSION environment variable to match your server's API version (e.g., "10" for Paperless-ngx v3+).`);
+                }
                 console.error({
                     error: "Error executing request",
                     message: error instanceof Error ? error.message : String(error),
                     url,
                     options,
-                    responseData: (_a = error === null || error === void 0 ? void 0 : error.response) === null || _a === void 0 ? void 0 : _a.data,
-                    status: (_b = error === null || error === void 0 ? void 0 : error.response) === null || _b === void 0 ? void 0 : _b.status,
+                    responseData: axios_1.default.isAxiosError(error) ? (_b = error.response) === null || _b === void 0 ? void 0 : _b.data : undefined,
+                    status: axios_1.default.isAxiosError(error) ? (_c = error.response) === null || _c === void 0 ? void 0 : _c.status : undefined,
                 });
                 throw error;
             }
@@ -81,6 +86,7 @@ class PaperlessAPI {
     }
     postDocument(document_1, filename_1) {
         return __awaiter(this, arguments, void 0, function* (document, filename, metadata = {}) {
+            var _a;
             const formData = new form_data_1.default();
             formData.append("document", document, { filename });
             // Add optional metadata fields
@@ -103,13 +109,22 @@ class PaperlessAPI {
             if (metadata.custom_fields) {
                 metadata.custom_fields.forEach((field) => formData.append("custom_fields", String(field)));
             }
-            const response = yield axios_1.default.post(`${this.baseUrl}/api/documents/post_document/`, formData, {
-                headers: Object.assign({ Authorization: `Token ${this.token}` }, formData.getHeaders()),
-            });
-            if (response.status < 200 || response.status >= 300) {
-                throw new Error(`HTTP error! status: ${response.status}`);
+            try {
+                const response = yield axios_1.default.post(`${this.baseUrl}/api/documents/post_document/`, formData, {
+                    headers: Object.assign({ Authorization: `Token ${this.token}`, Accept: `application/json; version=${this.apiVersion}` }, formData.getHeaders()),
+                });
+                if (response.status < 200 || response.status >= 300) {
+                    throw new Error(`HTTP error! status: ${response.status}`);
+                }
+                return response.data;
+            }
+            catch (error) {
+                if (axios_1.default.isAxiosError(error) && ((_a = error.response) === null || _a === void 0 ? void 0 : _a.status) === 406) {
+                    throw new Error(`HTTP 406: Paperless-ngx rejected API version ${this.apiVersion}. ` +
+                        `Set the PAPERLESS_API_VERSION environment variable to match your server's API version (e.g., "10" for Paperless-ngx v3+).`);
+                }
+                throw error;
             }
-            return response.data;
         });
     }
     getDocuments() {
@@ -176,7 +191,7 @@ class PaperlessAPI {
     updateTag(id, data) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.request(`/tags/${id}/`, {
-                method: "PUT",
+                method: "PATCH",
                 body: JSON.stringify(data),
             });
         });
@@ -213,7 +228,7 @@ class PaperlessAPI {
     updateCorrespondent(id, data) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.request(`/correspondents/${id}/`, {
-                method: "PUT",
+                method: "PATCH",
                 body: JSON.stringify(data),
             });
         });
@@ -242,7 +257,7 @@ class PaperlessAPI {
     updateDocumentType(id, data) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.request(`/document_types/${id}/`, {
-                method: "PUT",
+                method: "PATCH",
                 body: JSON.stringify(data),
             });
         });
@@ -276,7 +291,7 @@ class PaperlessAPI {
     updateCustomField(id, data) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.request(`/custom_fields/${id}/`, {
-                method: "PUT",
+                method: "PATCH",
                 body: JSON.stringify(data),
             });
         });

package/build/api/documentEnhancer.js

@@ -24,14 +24,13 @@ exports.convertDocsWithNames = convertDocsWithNames;
 function convertDocsWithNames(input, api) {
     return __awaiter(this, void 0, void 0, function* () {
         if ("results" in input) {
-            const enhancedResults = yield enhanceDocumentsArray(input.results || [], api);
+            const { all, results } = input, paginationMeta = __rest(input, ["all", "results"]);
+            const enhancedResults = yield enhanceDocumentsArray(results || [], api);
             return {
                 content: [
                     {
                         type: "text",
-                        text: (enhancedResults === null || enhancedResults === void 0 ? void 0 : enhancedResults.length)
-                            ? JSON.stringify(Object.assign(Object.assign({}, input), { results: enhancedResults }))
-                            : "No documents found",
+                        text: JSON.stringify(Object.assign(Object.assign({}, paginationMeta), { results: enhancedResults })),
                     },
                 ],
             };

package/build/api/documentEnhancer.test.d.ts

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

package/build/api/documentEnhancer.test.js

@@ -0,0 +1,80 @@
+"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 documentEnhancer_1 = require("./documentEnhancer");
+const paperlessApi_1 = require("../test/mocks/paperlessApi");
+const LARGE_DOCUMENT_COUNT = 709;
+const MAX_RESPONSE_SIZE_BYTES = 2000;
+function getTextContent(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 content");
+    }
+    return item.text;
+}
+(0, node_test_1.test)("convertDocsWithNames omits `all` and keeps paginated JSON shape", () => __awaiter(void 0, void 0, void 0, function* () {
+    const docsResponse = {
+        count: 2,
+        next: null,
+        previous: null,
+        all: [1, 2],
+        results: [(0, paperlessApi_1.createDocument)(), (0, paperlessApi_1.createDocument)({ id: 2, title: "Document 2" })],
+    };
+    const result = yield (0, documentEnhancer_1.convertDocsWithNames)(docsResponse, (0, paperlessApi_1.createPaperlessApiMock)());
+    const parsed = JSON.parse(getTextContent(result));
+    strict_1.default.ok(!("all" in parsed));
+    strict_1.default.deepEqual(parsed.results.map((doc) => doc.id), [1, 2]);
+    strict_1.default.ok(!("content" in parsed.results[0]));
+}));
+(0, node_test_1.test)("convertDocsWithNames keeps responses small when source has large `all` arrays", () => __awaiter(void 0, void 0, void 0, function* () {
+    const docsResponse = {
+        count: LARGE_DOCUMENT_COUNT,
+        next: "http://localhost:8000/api/documents/?page=2",
+        previous: null,
+        all: Array.from({ length: LARGE_DOCUMENT_COUNT }, (_, index) => index + 1),
+        results: [
+            (0, paperlessApi_1.createDocument)({
+                id: 123,
+                title: "Large all payload case",
+                content: "x".repeat(2700),
+            }),
+        ],
+    };
+    const result = yield (0, documentEnhancer_1.convertDocsWithNames)(docsResponse, (0, paperlessApi_1.createPaperlessApiMock)());
+    const responseText = getTextContent(result);
+    strict_1.default.ok(responseText.length < MAX_RESPONSE_SIZE_BYTES);
+    const parsed = JSON.parse(responseText);
+    strict_1.default.ok(!("all" in parsed));
+    strict_1.default.ok(!("content" in parsed.results[0]));
+}));
+(0, node_test_1.test)("convertDocsWithNames returns paginated JSON for empty multi-document results", () => __awaiter(void 0, void 0, void 0, function* () {
+    const docsResponse = {
+        count: 0,
+        next: null,
+        previous: null,
+        all: [],
+        results: [],
+    };
+    const result = yield (0, documentEnhancer_1.convertDocsWithNames)(docsResponse, (0, paperlessApi_1.createPaperlessApiMock)());
+    const parsed = JSON.parse(getTextContent(result));
+    strict_1.default.deepEqual(parsed, {
+        count: 0,
+        next: null,
+        previous: null,
+        results: [],
+    });
+}));

package/build/api/types.d.ts

@@ -30,13 +30,14 @@ export interface CustomField {
     extra_data?: Record<string, unknown> | null;
     document_count: number;
 }
+export type CustomFieldValue = string | number | boolean | number[] | null;
 export interface CustomFieldInstance {
     field: number;
-    value: string | number | boolean | object | null;
+    value: CustomFieldValue;
 }
 export interface CustomFieldInstanceRequest {
     field: number;
-    value: string | number | boolean | object | null;
+    value: CustomFieldValue;
 }
 export interface PaginationResponse<T> {
     count: number;
@@ -128,8 +129,7 @@ export interface BulkEditDocumentsResult {
     result: string;
 }
 export interface BulkEditParameters {
-    assign_custom_fields?: number[];
-    assign_custom_fields_values?: CustomFieldInstanceRequest[];
+    add_custom_fields?: Record<string, CustomFieldInstanceRequest["value"]>;
     remove_custom_fields?: number[];
     add_tags?: number[];
     remove_tags?: number[];

package/build/index.js

@@ -13,18 +13,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const sse_js_1 = require("@modelcontextprotocol/sdk/server/sse.js");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
 const streamableHttp_js_1 = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
 const express_1 = __importDefault(require("express"));
 const node_util_1 = require("node:util");
-const PaperlessAPI_1 = require("./api/PaperlessAPI");
-const correspondents_1 = require("./tools/correspondents");
-const customFields_1 = require("./tools/customFields");
-const documents_1 = require("./tools/documents");
-const documentTypes_1 = require("./tools/documentTypes");
-const tags_1 = require("./tools/tags");
+const server_1 = require("./server");
 const { version } = require("../package.json");
 const { values: { baseUrl, token, http: useHttp, port, publicUrl }, } = (0, node_util_1.parseArgs)({
     options: {
@@ -40,46 +34,39 @@ const resolvedBaseUrl = baseUrl || process.env.PAPERLESS_URL;
 const resolvedToken = token || process.env.PAPERLESS_API_KEY;
 const resolvedPublicUrl = publicUrl || process.env.PAPERLESS_PUBLIC_URL || resolvedBaseUrl;
 const resolvedPort = port ? parseInt(port, 10) : 3000;
-if (!resolvedBaseUrl || !resolvedToken) {
+if (!resolvedBaseUrl) {
     console.error("Usage: paperless-mcp --baseUrl <url> --token <token> [--http] [--port <port>] [--publicUrl <url>]");
     console.error("Or set PAPERLESS_URL and PAPERLESS_API_KEY environment variables.");
     process.exit(1);
 }
+if (!useHttp && !resolvedToken) {
+    console.error("Usage: paperless-mcp --baseUrl <url> --token <token> [--http] [--port <port>] [--publicUrl <url>]");
+    console.error("Or set PAPERLESS_URL and PAPERLESS_API_KEY environment variables.");
+    process.exit(1);
+}
+function buildServer(requestToken) {
+    return (0, server_1.createMcpServer)({
+        baseUrl: resolvedBaseUrl,
+        token: requestToken,
+        version,
+        publicUrl: resolvedPublicUrl,
+    });
+}
 function main() {
     return __awaiter(this, void 0, void 0, function* () {
-        // Initialize API client and server once
-        const api = new PaperlessAPI_1.PaperlessAPI(resolvedBaseUrl, resolvedToken);
-        const server = new mcp_js_1.McpServer({ name: "paperless-ngx", version }, {
-            instructions: `
-Paperless-NGX MCP Server Instructions
-
-⚠️ CRITICAL: Always differentiate between operations on specific documents vs operations on the entire system:
-
-- REMOVE operations (e.g., remove_tag in bulk_edit_documents): Affect only the specified documents, items remain in the system
-- DELETE operations (e.g., delete_tag, delete_correspondent): Permanently delete items from the entire system, affecting ALL documents that use them
-
-When a user asks to "remove" something, prefer operations that affect specific documents. Only use DELETE operations when explicitly asked to delete from the system.
-
-To view documents in your Paperless-NGX web interface, construct URLs using this pattern:
-${resolvedPublicUrl}/documents/{document_id}/
-
-Example: If your base URL is "http://localhost:8000", the web interface URL would be "http://localhost:8000/documents/123/" for document ID 123.
-
-The document tools return JSON data with document IDs that you can use to construct these URLs.
-      `,
-        });
-        (0, documents_1.registerDocumentTools)(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);
         if (useHttp) {
             const app = (0, express_1.default)();
             app.use(express_1.default.json());
             // Store transports for each session
             const sseTransports = {};
             app.post("/mcp", (req, res) => __awaiter(this, void 0, void 0, function* () {
+                const requestToken = (0, server_1.getBearerToken)(req, resolvedToken);
+                if (!requestToken) {
+                    (0, server_1.sendUnauthorized)(res);
+                    return;
+                }
                 try {
+                    const server = buildServer(requestToken);
                     const transport = new streamableHttp_js_1.StreamableHTTPServerTransport({
                         sessionIdGenerator: undefined,
                     });
@@ -125,7 +112,13 @@ The document tools return JSON data with document IDs that you can use to constr
             }));
             app.get("/sse", (req, res) => __awaiter(this, void 0, void 0, function* () {
                 console.log("SSE request received");
+                const requestToken = (0, server_1.getBearerToken)(req, resolvedToken);
+                if (!requestToken) {
+                    (0, server_1.sendUnauthorized)(res);
+                    return;
+                }
                 try {
+                    const server = buildServer(requestToken);
                     const transport = new sse_js_1.SSEServerTransport("/messages", res);
                     sseTransports[transport.sessionId] = transport;
                     res.on("close", () => {
@@ -164,6 +157,7 @@ The document tools return JSON data with document IDs that you can use to constr
             // await new Promise((resolve) => setTimeout(resolve, 1000000));
         }
         else {
+            const server = buildServer(resolvedToken);
             const transport = new stdio_js_1.StdioServerTransport();
             yield server.connect(transport);
         }

package/build/server.d.ts

@@ -0,0 +1,11 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type express from "express";
+export interface CreateMcpServerOptions {
+    baseUrl: string;
+    token: string;
+    version: string;
+    publicUrl: string;
+}
+export declare function createMcpServer({ baseUrl, token, version, publicUrl, }: CreateMcpServerOptions): McpServer;
+export declare function getBearerToken(req: express.Request, fallbackToken?: string): string | undefined;
+export declare function sendUnauthorized(res: express.Response): void;

package/build/server.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMcpServer = createMcpServer;
+exports.getBearerToken = getBearerToken;
+exports.sendUnauthorized = sendUnauthorized;
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const PaperlessAPI_1 = require("./api/PaperlessAPI");
+const correspondents_1 = require("./tools/correspondents");
+const customFields_1 = require("./tools/customFields");
+const documents_1 = require("./tools/documents");
+const documentTypes_1 = require("./tools/documentTypes");
+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_1.registerDocumentTools)(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);
+    return server;
+}
+function getBearerToken(req, fallbackToken) {
+    const authHeader = req.headers["authorization"];
+    if (authHeader && authHeader.startsWith("Bearer ")) {
+        return authHeader.slice(7);
+    }
+    return fallbackToken || undefined;
+}
+function sendUnauthorized(res) {
+    res
+        .status(401)
+        .set("WWW-Authenticate", 'Bearer realm="paperless-mcp"')
+        .end();
+}
+function buildInstructions(publicUrl) {
+    return `
+Paperless-NGX MCP Server Instructions
+
+⚠️ CRITICAL: Always differentiate between operations on specific documents vs operations on the entire system:
+
+- REMOVE operations (e.g., remove_tag in bulk_edit_documents): Affect only the specified documents, items remain in the system
+- DELETE operations (e.g., delete_tag, delete_correspondent): Permanently delete items from the entire system, affecting ALL documents that use them
+
+When a user asks to "remove" something, prefer operations that affect specific documents. Only use DELETE operations when explicitly asked to delete from the system.
+
+To view documents in your Paperless-NGX web interface, construct URLs using this pattern:
+${publicUrl}/documents/{document_id}/
+
+Example: If your base URL is "http://localhost:8000", the web interface URL would be "http://localhost:8000/documents/123/" for document ID 123.
+
+The document tools return JSON data with document IDs that you can use to construct these URLs.
+        `;
+}

package/build/test/mocks/paperlessApi.d.ts

@@ -0,0 +1,4 @@
+import { PaperlessAPI } from "../../api/PaperlessAPI";
+import { Document } from "../../api/types";
+export declare function createPaperlessApiMock(): PaperlessAPI;
+export declare function createDocument(overrides?: Partial<Document>): Document;

package/build/test/mocks/paperlessApi.js

@@ -0,0 +1,33 @@
+"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());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPaperlessApiMock = createPaperlessApiMock;
+exports.createDocument = createDocument;
+function emptyPaginationResponse(results = []) {
+    return {
+        count: results.length,
+        next: null,
+        previous: null,
+        all: [],
+        results,
+    };
+}
+function createPaperlessApiMock() {
+    return {
+        getCorrespondents: () => __awaiter(this, void 0, void 0, function* () { return emptyPaginationResponse(); }),
+        getDocumentTypes: () => __awaiter(this, void 0, void 0, function* () { return emptyPaginationResponse(); }),
+        getTags: () => __awaiter(this, void 0, void 0, function* () { return emptyPaginationResponse(); }),
+        getCustomFields: () => __awaiter(this, void 0, void 0, function* () { return emptyPaginationResponse(); }),
+    };
+}
+function createDocument(overrides = {}) {
+    return Object.assign({ id: 1, correspondent: null, document_type: null, storage_path: null, title: "Document 1", content: "OCR content", tags: [], created: "2026-01-01T00:00:00.000Z", created_date: "2026-01-01", modified: "2026-01-01T00:00:00.000Z", added: "2026-01-01T00:00:00.000Z", deleted_at: null, archive_serial_number: null, original_file_name: "doc1.pdf", archived_file_name: "2026/doc1.pdf", owner: null, user_can_change: true, is_shared_by_requester: false, notes: [], custom_fields: [], page_count: 1, mime_type: "application/pdf" }, overrides);
+}

package/build/tools/documents.d.ts

@@ -1,3 +1,36 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp";
 import { PaperlessAPI } from "../api/PaperlessAPI";
+export type BulkCustomFieldValue = string | number | boolean | number[] | null;
+export type BulkCustomFieldUpdate = {
+    field: number;
+    value: BulkCustomFieldValue;
+};
+export type BulkCustomFieldParameters = {
+    add_custom_fields?: Record<string, BulkCustomFieldValue>;
+    remove_custom_fields?: number[];
+};
+/**
+ * Builds Paperless-NGX bulk edit parameters from base parameters plus optional
+ * custom field updates.
+ *
+ * Paperless-NGX expects custom field bulk updates as an `add_custom_fields`
+ * record keyed by custom field id. `addCustomFields` is accepted as an array for
+ * the MCP tool schema and transformed into that id-to-value record while
+ * preserving supported value types, including `number[]` document links and
+ * `null` resets. Passing an empty `addCustomFields` array intentionally produces
+ * an empty `add_custom_fields` record.
+ *
+ * When `includeCustomFieldDefaults` is true, the function also initializes
+ * `add_custom_fields` and `remove_custom_fields` with empty defaults using
+ * nullish coalescing (`??=`). This keeps the `modify_custom_fields` method's
+ * payload shape acceptable to Paperless even when no field values are supplied.
+ *
+ * @param parameters - Base bulk edit parameters to include in the result.
+ * @param addCustomFields - Optional custom field updates to map by field id.
+ * @param includeCustomFieldDefaults - Whether to include empty custom field
+ * defaults required by `modify_custom_fields`.
+ * @returns The merged API parameters with custom field updates transformed into
+ * Paperless-NGX's `add_custom_fields` record shape.
+ */
+export declare function buildBulkEditParameters<T extends Record<string, unknown>>(parameters: T, addCustomFields?: BulkCustomFieldUpdate[], includeCustomFieldDefaults?: boolean): T & BulkCustomFieldParameters;
 export declare function registerDocumentTools(server: McpServer, api: PaperlessAPI): void;

package/build/tools/documents.js

@@ -20,6 +20,7 @@ var __rest = (this && this.__rest) || function (s, e) {
     return t;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildBulkEditParameters = buildBulkEditParameters;
 exports.registerDocumentTools = registerDocumentTools;
 const zod_1 = require("zod");
 const documentEnhancer_1 = require("../api/documentEnhancer");
@@ -27,6 +28,44 @@ const empty_1 = require("./utils/empty");
 const middlewares_1 = require("./utils/middlewares");
 const monetary_1 = require("./utils/monetary");
 const descriptions_1 = require("./utils/descriptions");
+/**
+ * Builds Paperless-NGX bulk edit parameters from base parameters plus optional
+ * custom field updates.
+ *
+ * Paperless-NGX expects custom field bulk updates as an `add_custom_fields`
+ * record keyed by custom field id. `addCustomFields` is accepted as an array for
+ * the MCP tool schema and transformed into that id-to-value record while
+ * preserving supported value types, including `number[]` document links and
+ * `null` resets. Passing an empty `addCustomFields` array intentionally produces
+ * an empty `add_custom_fields` record.
+ *
+ * When `includeCustomFieldDefaults` is true, the function also initializes
+ * `add_custom_fields` and `remove_custom_fields` with empty defaults using
+ * nullish coalescing (`??=`). This keeps the `modify_custom_fields` method's
+ * payload shape acceptable to Paperless even when no field values are supplied.
+ *
+ * @param parameters - Base bulk edit parameters to include in the result.
+ * @param addCustomFields - Optional custom field updates to map by field id.
+ * @param includeCustomFieldDefaults - Whether to include empty custom field
+ * defaults required by `modify_custom_fields`.
+ * @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;
+    const apiParameters = Object.assign({}, parameters);
+    if (addCustomFields) {
+        apiParameters.add_custom_fields = Object.fromEntries(addCustomFields.map((customField) => [
+            String(customField.field),
+            customField.value,
+        ]));
+    }
+    if (includeCustomFieldDefaults) {
+        (_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 = []);
+    }
+    return apiParameters;
+}
 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()),
@@ -104,13 +143,9 @@ 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);
-        // Transform add_custom_fields into the two separate API parameters
-        const apiParameters = Object.assign({}, parameters);
-        if (add_custom_fields && add_custom_fields.length > 0) {
-            apiParameters.assign_custom_fields = add_custom_fields.map((cf) => cf.field);
-            apiParameters.assign_custom_fields_values = add_custom_fields;
-        }
-        const response = yield api.bulkEditDocuments(documents, method, apiParameters);
+        const response = yield api.bulkEditDocuments(documents, method, method === "delete"
+            ? {}
+            : buildBulkEditParameters(parameters, add_custom_fields, method === "modify_custom_fields"));
         return {
             content: [
                 {

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

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

package/build/tools/documents.test.js

@@ -0,0 +1,78 @@
+"use strict";
+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 documents_1 = require("./documents");
+(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: "" },
+        { field: 10, value: "2026-05-14" },
+    ]);
+    strict_1.default.deepEqual(parameters, {
+        remove_custom_fields: [],
+        add_custom_fields: {
+            "9": "",
+            "10": "2026-05-14",
+        },
+    });
+    strict_1.default.ok(!("assign_custom_fields" in parameters));
+    strict_1.default.ok(!("assign_custom_fields_values" in parameters));
+});
+(0, node_test_1.test)("buildBulkEditParameters preserves null custom field values", () => {
+    const parameters = (0, documents_1.buildBulkEditParameters)({}, [{ field: 9, value: null }]);
+    strict_1.default.deepEqual(parameters, {
+        add_custom_fields: {
+            "9": null,
+        },
+    });
+});
+(0, node_test_1.test)("buildBulkEditParameters includes Paperless-required empty custom field keys", () => {
+    const parameters = (0, documents_1.buildBulkEditParameters)({}, undefined, true);
+    strict_1.default.deepEqual(parameters, {
+        add_custom_fields: {},
+        remove_custom_fields: [],
+    });
+});
+(0, node_test_1.test)("buildBulkEditParameters preserves an empty custom fields array", () => {
+    const parameters = (0, documents_1.buildBulkEditParameters)({}, []);
+    strict_1.default.deepEqual(parameters, {
+        add_custom_fields: {},
+    });
+    strict_1.default.ok(!("remove_custom_fields" in parameters));
+});
+(0, node_test_1.test)("buildBulkEditParameters preserves an empty custom fields array with defaults", () => {
+    const parameters = (0, documents_1.buildBulkEditParameters)({}, [], true);
+    strict_1.default.deepEqual(parameters, {
+        add_custom_fields: {},
+        remove_custom_fields: [],
+    });
+});
+(0, node_test_1.test)("buildBulkEditParameters combines base parameters with custom fields", () => {
+    const parameters = (0, documents_1.buildBulkEditParameters)({ add_tags: [3], remove_tags: [1, 2] }, [{ field: 9, value: "pending" }]);
+    strict_1.default.deepEqual(parameters, {
+        add_tags: [3],
+        remove_tags: [1, 2],
+        add_custom_fields: {
+            "9": "pending",
+        },
+    });
+});
+(0, node_test_1.test)("buildBulkEditParameters preserves supported custom field value types", () => {
+    const parameters = (0, documents_1.buildBulkEditParameters)({}, [
+        { field: 1, value: 42 },
+        { field: 2, value: true },
+        { field: 3, value: "" },
+        { field: 4, value: null },
+        { field: 5, value: [123, 456] },
+    ]);
+    strict_1.default.deepEqual(parameters.add_custom_fields, {
+        "1": 42,
+        "2": true,
+        "3": "",
+        "4": null,
+        "5": [123, 456],
+    });
+});

package/package.json

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