@baruchiro/paperless-mcp 0.5.1 → 1.0.0

package/README.md

@@ -455,6 +455,52 @@ The server will show clear error messages if:
 - The requested operation fails
 - The provided parameters are invalid
 
+## Testing
+
+### Unit tests
+
+Run the unit test suite (no external dependencies required):
+
+```bash
+npm test
+```
+
+### E2E tests
+
+The E2E suite boots an empty Paperless-ngx instance, runs the compiled MCP server, and drives a deterministic serial scenario through `tools/call` requests — creating a tag, correspondent, and document type, uploading a PDF, then exercising list / get / search / download / thumbnail / bulk-edit on the same document. No LLM and no Paperless REST client outside MCP.
+
+**Prerequisites:** Docker, Docker Compose, and `jq`.
+
+```bash
+# 1. Build the MCP server
+npm run build
+
+# 2. Start Paperless-ngx
+docker compose -f docker-compose.e2e.yml up -d
+
+# 3. Wait for Paperless to be ready, then get a token
+TOKEN=$(curl -s -X POST http://localhost:8000/api/token/ \
+  -H 'Content-Type: application/json' \
+  -d '{"username":"admin","password":"admin123"}' | jq -r '.token')
+
+# 4. Start the MCP server
+node build/index.js --http --port 3001 \
+  --baseUrl http://localhost:8000 --token "$TOKEN" &
+MCP_PID=$!
+
+# 5. Run the E2E tests
+MCP_URL=http://localhost:3001/mcp \
+PAPERLESS_URL=http://localhost:8000 \
+PAPERLESS_TOKEN="$TOKEN" \
+npm run test:e2e
+
+# 6. Cleanup
+kill "$MCP_PID"
+docker compose -f docker-compose.e2e.yml down -v
+```
+
+E2E tests also run automatically in CI on every pull request and push to `main`, covering both the `build/index.js` CLI and the published Docker image.
+
 ## Development
 
 Want to contribute or modify the server? Here's what you need to know:

package/build/resources/documents.d.ts

@@ -0,0 +1,8 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ListResourcesResult, 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

@@ -0,0 +1,154 @@
+"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.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); }),
+    }), (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,
+    }), (uri, variables) => __awaiter(this, void 0, void 0, function* () {
+        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);
+        const id = parseDocumentId(readVariable(variables, "id"));
+        const resource = readVariable(variables, "resource").split("?")[0];
+        switch (resource) {
+            case "download":
+                return readDocumentDownloadResource(api, uri, id, isTrueQueryValue(uri.searchParams.get("original") || undefined));
+            case "thumbnail":
+            case "thumb":
+                return readDocumentThumbnailResource(api, uri, id);
+            default:
+                throw new Error(`Unsupported Paperless document resource: ${resource}`);
+        }
+    });
+}
+function readDocumentDownloadResource(api, uri, id, original) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const response = yield api.downloadDocument(id, original);
+        return {
+            contents: [
+                responseToResourceContents(uri.href, response, "application/octet-stream"),
+            ],
+        };
+    });
+}
+function readDocumentThumbnailResource(api, uri, id) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const response = yield api.getThumbnail(id);
+        return {
+            contents: [responseToResourceContents(uri.href, response, "image/webp")],
+        };
+    });
+}
+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);
+    if (isTextMimeType(mimeType)) {
+        return {
+            uri,
+            mimeType,
+            text: data.toString("utf8"),
+        };
+    }
+    return {
+        uri,
+        mimeType,
+        blob: data.toString("base64"),
+    };
+}
+function assertPaperlessDocumentsUri(uri) {
+    if (uri.protocol !== "paperless:" || uri.hostname !== "documents") {
+        throw new Error(`Unsupported Paperless resource URI: ${uri.href}`);
+    }
+}
+function parseDocumentId(idValue) {
+    const id = Number(idValue);
+    if (!Number.isInteger(id) || id <= 0) {
+        throw new Error(`Invalid Paperless document id in resource URI: ${idValue}`);
+    }
+    return id;
+}
+function readVariable(variables, name) {
+    const value = variables[name];
+    const stringValue = Array.isArray(value) ? value[0] : value;
+    if (!stringValue) {
+        throw new Error(`Missing ${name} in Paperless resource URI`);
+    }
+    return stringValue;
+}
+function isTrueQueryValue(value) {
+    return value === "true" || value === "1";
+}
+function getHeader(response, headerName) {
+    const headers = response.headers;
+    if (typeof headers.get === "function") {
+        const value = headers.get(headerName);
+        if (typeof value === "string") {
+            return value;
+        }
+    }
+    const value = headers[headerName] || headers[headerName.toLowerCase()];
+    if (Array.isArray(value)) {
+        return String(value[0]);
+    }
+    return typeof value === "string" ? value : undefined;
+}
+function isTextMimeType(mimeType) {
+    const normalizedMimeType = mimeType.split(";")[0].trim().toLowerCase();
+    return (normalizedMimeType.startsWith("text/") ||
+        normalizedMimeType === "application/json" ||
+        normalizedMimeType === "application/xml" ||
+        normalizedMimeType.endsWith("+json") ||
+        normalizedMimeType.endsWith("+xml"));
+}

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

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

package/build/resources/documents.test.js

@@ -0,0 +1,136 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const strict_1 = __importDefault(require("node:assert/strict"));
+const node_test_1 = require("node:test");
+const index_js_1 = require("@modelcontextprotocol/sdk/client/index.js");
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const paperlessApi_1 = require("../test/mocks/paperlessApi");
+const documents_1 = require("./documents");
+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 emptyPaginationResponse(results = [], all = []) {
+    return {
+        count: results.length,
+        next: null,
+        previous: null,
+        all,
+        results,
+    };
+}
+function createBinaryResponse(body, contentType) {
+    return {
+        data: Buffer.from(body),
+        status: 200,
+        statusText: "OK",
+        headers: {
+            "content-type": contentType,
+        },
+        config: {},
+    };
+}
+function withResourceClient(api, run) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const server = new mcp_js_1.McpServer({ name: "paperless-test", version: "1.0.0" });
+        (0, documents_1.registerDocumentResources)(server, api);
+        const client = new index_js_1.Client({ name: "paperless-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();
+        }
+    });
+}
+(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.
+    const api = {
+        getDocuments: () => __awaiter(void 0, void 0, void 0, function* () {
+            return emptyPaginationResponse([
+                (0, paperlessApi_1.createDocument)({
+                    id: 1,
+                    title: "Invoice",
+                    mime_type: "application/pdf",
+                }),
+                (0, paperlessApi_1.createDocument)({
+                    id: 2,
+                    title: "Receipt",
+                    mime_type: "image/png",
+                }),
+            ], [1, 2, 3]);
+        }),
+    };
+    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}`);
+        }
+    }));
+}));
+(0, node_test_1.test)("resources/read returns text contents for text responses", () => __awaiter(void 0, void 0, void 0, function* () {
+    const api = {
+        getDocuments: () => __awaiter(void 0, void 0, void 0, function* () { return emptyPaginationResponse(); }),
+        downloadDocument: () => __awaiter(void 0, void 0, void 0, function* () { return createBinaryResponse("plain text", "text/plain; charset=utf-8"); }),
+    };
+    yield withResourceClient(api, (client) => __awaiter(void 0, void 0, void 0, function* () {
+        const result = yield client.readResource({
+            uri: "paperless://documents/4/download",
+        });
+        strict_1.default.deepEqual(result.contents, [
+            {
+                uri: "paperless://documents/4/download",
+                mimeType: "text/plain; charset=utf-8",
+                text: "plain text",
+            },
+        ]);
+    }));
+}));

package/build/server.js

@@ -5,15 +5,17 @@ exports.getBearerToken = getBearerToken;
 exports.sendUnauthorized = sendUnauthorized;
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const PaperlessAPI_1 = require("./api/PaperlessAPI");
+const documents_1 = require("./resources/documents");
 const correspondents_1 = require("./tools/correspondents");
 const customFields_1 = require("./tools/customFields");
-const documents_1 = require("./tools/documents");
+const documents_2 = 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, documents_2.registerDocumentTools)(server, api);
+    (0, documents_1.registerDocumentResources)(server, api);
     (0, tags_1.registerTagTools)(server, api);
     (0, correspondents_1.registerCorrespondentTools)(server, api);
     (0, documentTypes_1.registerDocumentTypeTools)(server, api);

package/build/tools/documents.d.ts

@@ -32,5 +32,5 @@ export type BulkCustomFieldParameters = {
  * @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 buildBulkEditParameters<T extends Record<string, unknown>>(parameters: T, addCustomFields?: BulkCustomFieldUpdate[], includeCustomFieldDefaults?: boolean, includeTagDefaults?: boolean): T & BulkCustomFieldParameters;
 export declare function registerDocumentTools(server: McpServer, api: PaperlessAPI): void;

package/build/tools/documents.js

@@ -52,8 +52,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,6 +66,10 @@ 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 registerDocumentTools(server, api) {
@@ -146,7 +151,7 @@ function registerDocumentTools(server, api) {
         (0, monetary_1.validateCustomFields)(add_custom_fields);
         const response = yield api.bulkEditDocuments(documents, method, method === "delete"
             ? {}
-            : buildBulkEditParameters(parameters, add_custom_fields, method === "modify_custom_fields"));
+            : buildBulkEditParameters(parameters, add_custom_fields, method === "modify_custom_fields", method === "modify_tags"));
         return {
             content: [
                 {
@@ -267,43 +272,45 @@ function registerDocumentTools(server, api) {
         const docsResponse = yield api.searchDocuments(args.query);
         return (0, documentEnhancer_1.convertDocsWithNames)(docsResponse, api);
     })));
-    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",
                     },
                 },

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

@@ -1,21 +1,26 @@
 /**
  * Resource URI builders for document/thumbnail downloads.
  *
- * URIs mirror the Paperless REST API paths under a custom `paperless://`
- * scheme, so the same identifiers can later back proper MCP resources
- * (`resources/list` / `resources/read`) without a second naming scheme.
+ * URIs mirror document resources under a custom `paperless://` scheme, so the
+ * same identifiers can back MCP resources (`resources/list` / `resources/read`)
+ * without a second naming scheme.
  *
  * The scheme also keeps the URI well-formed regardless of filename
  * content, which Python MCP clients (pydantic-validated) require.
  */
+/**
+ * Optional flags for document download resource URIs.
+ */
+export interface DocumentResourceUriOptions {
+    original?: boolean;
+}
 /**
  * Builds a resource URI for a downloaded document.
  *
- * Mirrors `GET /api/documents/{id}/download/`. The original filename is
- * preserved as a `filename` query parameter (URL-encoded) so clients
- * that need the human-readable name can still recover it.
+ * The MCP resource URI is intentionally canonical and filename-free; filenames
+ * belong in resource metadata, while the URI identifies the fetchable content.
  */
-export declare function buildDocumentResourceUri(id: number, filename: string): string;
+export declare function buildDocumentResourceUri(id: number, optionsOrFilename?: DocumentResourceUriOptions | string): string;
 /**
  * Builds a resource URI for a document thumbnail.
  *

package/build/tools/utils/resourceUri.js

@@ -2,9 +2,9 @@
 /**
  * Resource URI builders for document/thumbnail downloads.
  *
- * URIs mirror the Paperless REST API paths under a custom `paperless://`
- * scheme, so the same identifiers can later back proper MCP resources
- * (`resources/list` / `resources/read`) without a second naming scheme.
+ * URIs mirror document resources under a custom `paperless://` scheme, so the
+ * same identifiers can back MCP resources (`resources/list` / `resources/read`)
+ * without a second naming scheme.
  *
  * The scheme also keeps the URI well-formed regardless of filename
  * content, which Python MCP clients (pydantic-validated) require.
@@ -15,12 +15,17 @@ exports.buildThumbnailResourceUri = buildThumbnailResourceUri;
 /**
  * Builds a resource URI for a downloaded document.
  *
- * Mirrors `GET /api/documents/{id}/download/`. The original filename is
- * preserved as a `filename` query parameter (URL-encoded) so clients
- * that need the human-readable name can still recover it.
+ * The MCP resource URI is intentionally canonical and filename-free; filenames
+ * belong in resource metadata, while the URI identifies the fetchable content.
  */
-function buildDocumentResourceUri(id, filename) {
-    return `paperless://documents/${id}/download?filename=${encodeURIComponent(filename)}`;
+function buildDocumentResourceUri(id, optionsOrFilename) {
+    const options = typeof optionsOrFilename === "string" ? {} : optionsOrFilename || {};
+    const params = new URLSearchParams();
+    if (options.original) {
+        params.set("original", "true");
+    }
+    const query = params.toString();
+    return `paperless://documents/${id}/download${query ? `?${query}` : ""}`;
 }
 /**
  * Builds a resource URI for a document thumbnail.

package/build/tools/utils/resourceUri.test.js

@@ -10,32 +10,32 @@ const resourceUri_1 = require("./resourceUri");
     const uri = (0, resourceUri_1.buildDocumentResourceUri)(1, "doc.pdf");
     strict_1.default.match(uri, /^paperless:\/\/documents\/1\/download(\?|$)/);
 });
-(0, node_test_1.test)("buildDocumentResourceUri puts the filename in a query parameter", () => {
+(0, node_test_1.test)("buildDocumentResourceUri is canonical without filenames", () => {
     const uri = (0, resourceUri_1.buildDocumentResourceUri)(1, "invoice 2026.pdf");
-    strict_1.default.equal(uri, "paperless://documents/1/download?filename=invoice%202026.pdf");
+    strict_1.default.equal(uri, "paperless://documents/1/download");
 });
-(0, node_test_1.test)("buildDocumentResourceUri encodes RFC-3986 reserved chars in the filename", () => {
+(0, node_test_1.test)("buildDocumentResourceUri ignores reserved chars in legacy filename input", () => {
     const uri = (0, resourceUri_1.buildDocumentResourceUri)(42, "weird ?#&=+name.pdf");
     const url = new URL(uri);
-    // The path stays canonical — only the literal `?` that separates
-    // path from query is allowed; nothing from the filename should
-    // bleed into the path or break query parsing.
     strict_1.default.equal(url.pathname, "/42/download");
-    strict_1.default.equal(url.searchParams.get("filename"), "weird ?#&=+name.pdf");
+    strict_1.default.equal(url.search, "");
 });
-(0, node_test_1.test)("buildDocumentResourceUri encodes path separators inside filename", () => {
+(0, node_test_1.test)("buildDocumentResourceUri ignores path separators in legacy filename input", () => {
     // A filename containing a slash must not become an extra path segment.
     const uri = (0, resourceUri_1.buildDocumentResourceUri)(7, "sub/dir/file.pdf");
     const url = new URL(uri);
     strict_1.default.equal(url.pathname, "/7/download");
-    strict_1.default.equal(url.searchParams.get("filename"), "sub/dir/file.pdf");
+    strict_1.default.equal(url.search, "");
 });
-(0, node_test_1.test)("buildDocumentResourceUri preserves unicode filenames", () => {
+(0, node_test_1.test)("buildDocumentResourceUri keeps unicode filenames out of the URI", () => {
     const original = "Rechnüng — März.pdf";
     const uri = (0, resourceUri_1.buildDocumentResourceUri)(1, original);
-    // Roundtrip via URL parsing should recover the original name.
     const url = new URL(uri);
-    strict_1.default.equal(url.searchParams.get("filename"), original);
+    strict_1.default.equal(url.pathname, "/1/download");
+    strict_1.default.equal(url.search, "");
+});
+(0, node_test_1.test)("buildDocumentResourceUri preserves original download intent", () => {
+    strict_1.default.equal((0, resourceUri_1.buildDocumentResourceUri)(1, { original: true }), "paperless://documents/1/download?original=true");
 });
 (0, node_test_1.test)("buildDocumentResourceUri produces a valid URL", () => {
     const uri = (0, resourceUri_1.buildDocumentResourceUri)(1, "Some File.pdf");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@baruchiro/paperless-mcp",
-  "version": "0.5.1",
+  "version": "1.0.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": {
@@ -8,6 +8,7 @@
   },
   "scripts": {
     "test": "node --require ts-node/register --test src/**/*.test.ts",
+    "test:e2e": "node --require ts-node/register --test e2e/e2e.test.ts",
     "start": "ts-node src/index.ts",
     "build": "tsc",
     "dxt-pack": "dxt pack",