@baruchiro/paperless-mcp 0.5.1 → 2.0.0

package/build/index.js

@@ -20,13 +20,14 @@ const express_1 = __importDefault(require("express"));
 const node_util_1 = require("node:util");
 const server_1 = require("./server");
 const { version } = require("../package.json");
-const { values: { baseUrl, token, http: useHttp, port, publicUrl }, } = (0, node_util_1.parseArgs)({
+const { values: { baseUrl, token, http: useHttp, port, publicUrl, "no-auth": noAuth }, } = (0, node_util_1.parseArgs)({
     options: {
         baseUrl: { type: "string" },
         token: { type: "string" },
         http: { type: "boolean", default: false },
         port: { type: "string" },
         publicUrl: { type: "string", default: "" },
+        "no-auth": { type: "boolean", default: false },
     },
     allowPositionals: true,
 });
@@ -35,15 +36,21 @@ 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) {
-    console.error("Usage: paperless-mcp --baseUrl <url> --token <token> [--http] [--port <port>] [--publicUrl <url>]");
+    console.error("Usage: paperless-mcp --baseUrl <url> --token <token> [--http] [--port <port>] [--publicUrl <url>] [--no-auth]");
     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("Usage: paperless-mcp --baseUrl <url> --token <token> [--http] [--port <port>] [--publicUrl <url>] [--no-auth]");
     console.error("Or set PAPERLESS_URL and PAPERLESS_API_KEY environment variables.");
     process.exit(1);
 }
+if (noAuth && !resolvedToken) {
+    console.error("--no-auth allows unauthenticated requests to use the server's Paperless token, " +
+        "but no server token is configured. Provide --token <token> or set PAPERLESS_API_KEY, " +
+        "or drop --no-auth and have clients authenticate with 'Authorization: Bearer <token>'.");
+    process.exit(1);
+}
 function buildServer(requestToken) {
     return (0, server_1.createMcpServer)({
         baseUrl: resolvedBaseUrl,
@@ -55,12 +62,25 @@ function buildServer(requestToken) {
 function main() {
     return __awaiter(this, void 0, void 0, function* () {
         if (useHttp) {
+            if (noAuth) {
+                console.log("[paperless-mcp] --no-auth is enabled: requests without an 'Authorization: Bearer' header " +
+                    "will use the server's Paperless token. Only use this on a trusted/local network.");
+            }
+            else if (resolvedToken) {
+                console.log("[paperless-mcp] A server token is configured, but unauthenticated requests are rejected. " +
+                    "Clients must send 'Authorization: Bearer <paperless-token>'. " +
+                    "To use the server token for unauthenticated requests instead, restart with the --no-auth flag " +
+                    "(trusted/local networks only).");
+            }
             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);
+                const requestToken = (0, server_1.getBearerToken)(req, {
+                    fallbackToken: resolvedToken,
+                    allowAnonymous: noAuth,
+                });
                 if (!requestToken) {
                     (0, server_1.sendUnauthorized)(res);
                     return;
@@ -112,7 +132,10 @@ function main() {
             }));
             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);
+                const requestToken = (0, server_1.getBearerToken)(req, {
+                    fallbackToken: resolvedToken,
+                    allowAnonymous: noAuth,
+                });
                 if (!requestToken) {
                     (0, server_1.sendUnauthorized)(res);
                     return;

package/build/resources/documents.d.ts

@@ -0,0 +1,7 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+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 readDocumentResource(api: PaperlessAPI, uri: URL, variables: TemplateVariables): Promise<ReadResourceResult>;
+export {};

package/build/resources/documents.js

@@ -0,0 +1,119 @@
+"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.readDocumentResource = readDocumentResource;
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+function registerDocumentResources(server, api) {
+    server.resource("paperless-document-resource", new mcp_js_1.ResourceTemplate("paperless://documents/{id}/{resource}", {
+        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,
+    }), (uri, variables) => __awaiter(this, void 0, void 0, function* () {
+        return readDocumentDownloadResource(api, uri, parseDocumentId(readVariable(variables, "id")), isTrueQueryValue(readVariable(variables, "original")));
+    }));
+}
+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 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,124 @@
+"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 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([
+                (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, []);
+    }));
+}));
+(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.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

@@ -5,33 +5,49 @@ 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 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_1.registerDocumentTools)(server, api);
+    (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.
@@ -32,5 +34,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;