@baruchiro/paperless-mcp 0.3.0 → 0.4.1

package/README.md

@@ -2,7 +2,6 @@
 
 # Paperless-NGX MCP Server
 
-[![smithery badge](https://smithery.ai/badge/@baruchiro/paperless-mcp)](https://smithery.ai/server/@baruchiro/paperless-mcp)
 ![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/baruchiro/paperless-mcp?utm_source=oss&utm_medium=github&utm_campaign=baruchiro%2Fpaperless-mcp&labelColor=171717&color=FF570A&link=https%3A%2F%2Fcoderabbit.ai&label=CodeRabbit+Reviews)
 
 An MCP (Model Context Protocol) server for interacting with a Paperless-NGX API server. This server provides tools for managing documents, tags, correspondents, and document types in your Paperless-NGX instance.
@@ -11,15 +10,7 @@ An MCP (Model Context Protocol) server for interacting with a Paperless-NGX API
 
 [![Install MCP Server](https://cursor.com/deeplink/mcp-install-light.svg)](https://cursor.com/install-mcp?name=paperless&config=eyJjb21tYW5kIjoibnB4IC15IEBiYXJ1Y2hpcm8vcGFwZXJsZXNzLW1jcEBsYXRlc3QiLCJlbnYiOnsiUEFQRVJMRVNTX1VSTCI6Imh0dHA6Ly95b3VyLXBhcGVybGVzcy1pbnN0YW5jZTo4MDAwIiwiUEFQRVJMRVNTX0FQSV9LRVkiOiJ5b3VyLWFwaS10b2tlbiJ9fQ%3D%3D)
 
-### Installing via Smithery
-
-To install Paperless NGX MCP Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@baruchiro/paperless-mcp):
-
-```bash
-npx -y @smithery/cli install @baruchiro/paperless-mcp --client claude
-```
-
-### Manual Installation
+### Installation
 
 Add these to your MCP config file:
 
@@ -137,6 +128,18 @@ download_document({
 })
 ```
 
+#### get_document_thumbnail
+Get a document thumbnail (image preview) by ID. Returns the thumbnail as a base64-encoded WebP image resource.
+
+Parameters:
+- id: Document ID
+
+```typescript
+get_document_thumbnail({
+  id: 123
+})
+```
+
 #### bulk_edit_documents
 Perform bulk operations on multiple documents.
 
@@ -480,6 +483,57 @@ 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.
 
+<details>
+<summary>Docker Deployment</summary>
+
+The MCP server can be deployed using Docker and Docker Compose. The Docker image automatically runs in HTTP mode with SSE (Server-Sent Events) support on port 3000.
+
+### Docker Compose Configuration
+
+Create a `docker-compose.yml` file:
+
+```yaml
+services:
+  paperless-mcp:
+    container_name: paperless-mcp
+    image: ghcr.io/baruchiro/paperless-mcp:latest
+    environment:
+      - PAPERLESS_URL=http://your-paperless-ngx-server:8000
+      - PAPERLESS_API_KEY=your-paperless-api-key
+      - PAPERLESS_PUBLIC_URL=https://paperless-ngx.yourpublicurl.com
+    ports:
+      - "3000:3000"
+    restart: unless-stopped
+```
+
+Then run:
+```bash
+docker-compose up -d
+```
+
+### Using with Continue VS Code Extension
+
+If you're using the [Continue VS Code extension](https://continue.dev/), you can configure it to use the Dockerized MCP server via SSE.
+
+Create or edit `.continue/mcpServers/paperless-mcp.yaml` at your workspace root:
+
+```yaml
+name: Paperless
+version: 0.0.1
+schema: v1
+mcpServers:
+  - name: Paperless
+    type: sse
+    url: http://localhost:3000/sse
+```
+
+**Notes:**
+- Replace `localhost` with your Docker host's IP address or hostname if running on a remote server
+- The Docker container handles authentication via environment variables, so no credentials are needed in the Continue config
+- The SSE endpoint is available at `/sse` on the configured port (default: 3000)
+
+</details>
+
 # Credits
 
 This project is a fork of [nloui/paperless-mcp](https://github.com/nloui/paperless-mcp). Many thanks to the original author for their work. Contributions and improvements may be returned upstream.

package/build/api/PaperlessAPI.d.ts

@@ -1,3 +1,4 @@
+import { AxiosResponse } from "axios";
 import { BulkEditDocumentsResult, BulkEditParameters, Correspondent, CustomField, Document, DocumentsResponse, DocumentType, GetCorrespondentsResponse, GetCustomFieldsResponse, GetDocumentTypesResponse, GetTagsResponse, Tag } from "./types";
 export declare class PaperlessAPI {
     private readonly baseUrl;
@@ -5,12 +6,13 @@ export declare class PaperlessAPI {
     constructor(baseUrl: string, token: string);
     request<T = any>(path: string, options?: RequestInit): Promise<T>;
     bulkEditDocuments(documents: number[], method: string, parameters?: BulkEditParameters): Promise<BulkEditDocumentsResult>;
-    postDocument(file: File, metadata?: Record<string, string | string[] | number | number[]>): Promise<string>;
+    postDocument(document: Buffer, filename: string, metadata?: Record<string, string | string[] | number | number[]>): Promise<string>;
     getDocuments(query?: string): Promise<DocumentsResponse>;
     getDocument(id: number): Promise<Document>;
     updateDocument(id: number, data: Partial<Document>): Promise<Document>;
     searchDocuments(query: string): Promise<DocumentsResponse>;
-    downloadDocument(id: number, asOriginal?: boolean): Promise<import("axios").AxiosResponse<any, any>>;
+    downloadDocument(id: number, asOriginal?: boolean): Promise<AxiosResponse<ArrayBuffer>>;
+    getThumbnail(id: number): Promise<AxiosResponse<ArrayBuffer>>;
     getTags(): Promise<GetTagsResponse>;
     createTag(data: Partial<Tag>): Promise<Tag>;
     updateTag(id: number, data: Partial<Tag>): Promise<Tag>;

package/build/api/PaperlessAPI.js

@@ -79,10 +79,10 @@ class PaperlessAPI {
             });
         });
     }
-    postDocument(file_1) {
-        return __awaiter(this, arguments, void 0, function* (file, metadata = {}) {
+    postDocument(document_1, filename_1) {
+        return __awaiter(this, arguments, void 0, function* (document, filename, metadata = {}) {
             const formData = new form_data_1.default();
-            formData.append("document", file);
+            formData.append("document", document, { filename });
             // Add optional metadata fields
             if (metadata.title)
                 formData.append("title", metadata.title);
@@ -98,10 +98,10 @@ class PaperlessAPI {
                 metadata.tags.forEach((tag) => formData.append("tags", tag));
             }
             if (metadata.archive_serial_number) {
-                formData.append("archive_serial_number", metadata.archive_serial_number);
+                formData.append("archive_serial_number", String(metadata.archive_serial_number));
             }
             if (metadata.custom_fields) {
-                metadata.custom_fields.forEach((field) => formData.append("custom_fields", field));
+                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()),
@@ -148,6 +148,17 @@ class PaperlessAPI {
             return response;
         });
     }
+    getThumbnail(id) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const response = yield axios_1.default.get(`${this.baseUrl}/api/documents/${id}/thumb/`, {
+                headers: {
+                    Authorization: `Token ${this.token}`,
+                },
+                responseType: "arraybuffer",
+            });
+            return response;
+        });
+    }
     // Tag operations
     getTags() {
         return __awaiter(this, void 0, void 0, function* () {

package/build/tools/customFields.js

@@ -55,7 +55,7 @@ function registerCustomFieldTools(server, api) {
             content: [{ type: "text", text: JSON.stringify(response) }],
         };
     })));
-    server.tool("create_custom_field", "Create a new custom field with a specified data type (string, url, date, boolean, integer, float, monetary, documentlink, or select).", {
+    server.tool("create_custom_field", "Create a new custom field with a specified data type (string, url, date, boolean, integer, float, monetary, documentlink, or select). For monetary fields, values must use currency code prefix format (e.g., USD10.00, GBP123.45) — NOT trailing symbol format (e.g., 10.00$).", {
         name: zod_1.z.string(),
         data_type: zod_1.z.enum([
             "string",

package/build/tools/documents.js

@@ -25,6 +25,8 @@ const zod_1 = require("zod");
 const documentEnhancer_1 = require("../api/documentEnhancer");
 const empty_1 = require("./utils/empty");
 const middlewares_1 = require("./utils/middlewares");
+const monetary_1 = require("./utils/monetary");
+const descriptions_1 = require("./utils/descriptions");
 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()),
@@ -59,7 +61,7 @@ function registerDocumentTools(server, api) {
                 zod_1.z.boolean(),
                 zod_1.z.array(zod_1.z.number()),
                 zod_1.z.null(),
-            ]),
+            ]).describe(descriptions_1.CUSTOM_FIELD_VALUE_DESCRIPTION),
         }))
             .optional()
             .transform(empty_1.arrayNotEmpty),
@@ -101,6 +103,7 @@ function registerDocumentTools(server, api) {
             throw new Error("Confirmation required for destructive operation. Set confirm: true to proceed.");
         }
         const { documents, method, add_custom_fields } = args, parameters = __rest(args, ["documents", "method", "add_custom_fields"]);
+        (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) {
@@ -126,16 +129,19 @@ function registerDocumentTools(server, api) {
         document_type: zod_1.z.number().optional(),
         storage_path: zod_1.z.number().optional(),
         tags: zod_1.z.array(zod_1.z.number()).optional(),
-        archive_serial_number: zod_1.z.string().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* () {
         if (!api)
             throw new Error("Please configure API connection first");
-        const binaryData = Buffer.from(args.file, "base64");
-        const blob = new Blob([binaryData]);
-        const file = new File([blob], args.filename);
-        const { file: _, filename: __ } = args, metadata = __rest(args, ["file", "filename"]);
-        const response = yield api.postDocument(file, metadata);
+        // 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 { file, filename } = args, metadata = __rest(args, ["file", "filename"]);
+        const document = Buffer.from(file, "base64");
+        const response = yield api.postDocument(document, filename, metadata);
         let result;
         if (typeof response === "string" && /^\d+$/.test(response)) {
             result = { id: Number(response) };
@@ -249,6 +255,25 @@ function registerDocumentTools(server, api) {
             ],
         };
     })));
+    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(),
+    }, (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: `document-${args.id}-thumb.webp`,
+                        blob: Buffer.from(response.data).toString("base64"),
+                        mimeType: "image/webp",
+                    },
+                },
+            ],
+        };
+    })));
     server.tool("update_document", "Update a specific document with new values. This tool allows you to modify any document field including title, correspondent, document type, storage path, tags, custom fields, and more. Only the fields you specify will be updated.", {
         id: zod_1.z.number().describe("The ID of the document to update"),
         title: zod_1.z
@@ -303,7 +328,7 @@ function registerDocumentTools(server, api) {
                 zod_1.z.array(zod_1.z.number()),
                 zod_1.z.null(),
             ])
-                .describe("The value for the custom field. For documentlink fields, use a single document ID (e.g., 123) or an array of document IDs (e.g., [123, 456])."),
+                .describe(descriptions_1.CUSTOM_FIELD_VALUE_DESCRIPTION),
         }))
             .optional()
             .describe("Array of custom field values to assign"),
@@ -311,6 +336,7 @@ function registerDocumentTools(server, api) {
         if (!api)
             throw new Error("Please configure API connection first");
         const { id } = args, updateData = __rest(args, ["id"]);
+        (0, monetary_1.validateCustomFields)(updateData.custom_fields);
         const response = yield api.updateDocument(id, updateData);
         return (0, documentEnhancer_1.convertDocsWithNames)(response, api);
     })));

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

@@ -0,0 +1 @@
+export declare const CUSTOM_FIELD_VALUE_DESCRIPTION = "The value for the custom field. For monetary fields, use currency code prefix format (e.g., USD10.00, GBP123.45, EUR9.99) \u2014 NOT trailing symbol format (e.g., 10.00$). For documentlink fields, use a single document ID (e.g., 123) or an array of document IDs (e.g., [123, 456]).";

package/build/tools/utils/descriptions.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CUSTOM_FIELD_VALUE_DESCRIPTION = void 0;
+exports.CUSTOM_FIELD_VALUE_DESCRIPTION = "The value for the custom field. For monetary fields, use currency code prefix format (e.g., USD10.00, GBP123.45, EUR9.99) — NOT trailing symbol format (e.g., 10.00$). For documentlink fields, use a single document ID (e.g., 123) or an array of document IDs (e.g., [123, 456]).";

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

@@ -0,0 +1,5 @@
+export declare function getMonetaryValidationError(value: string): string | null;
+export declare function validateCustomFields(custom_fields: {
+    field: number;
+    value: unknown;
+}[] | undefined): void;

package/build/tools/utils/monetary.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getMonetaryValidationError = getMonetaryValidationError;
+exports.validateCustomFields = validateCustomFields;
+const SYMBOL_TO_CODE = {
+    $: "USD",
+    "€": "EUR",
+    "£": "GBP",
+    "¥": "JPY",
+    "₹": "INR",
+    "₪": "ILS",
+};
+const TRAILING_SYMBOL_REGEX = new RegExp(`^(\\d+(?:\\.\\d+)?)[${Object.keys(SYMBOL_TO_CODE).join("")}]$`);
+function getMonetaryValidationError(value) {
+    const trailingMatch = TRAILING_SYMBOL_REGEX.exec(value);
+    if (trailingMatch) {
+        const amount = trailingMatch[1];
+        const symbol = value.slice(-1);
+        const code = SYMBOL_TO_CODE[symbol] || "USD";
+        const numericAmount = parseFloat(amount);
+        const formattedAmount = isNaN(numericAmount) ? amount : numericAmount.toFixed(2);
+        return (`Invalid monetary format "${value}". ` +
+            `Paperless-NGX requires the currency code as a prefix, e.g. "${code}${formattedAmount}". ` +
+            `Use the format: {CURRENCY_CODE}{amount} (e.g., USD10.00, GBP123.45, EUR9.99).`);
+    }
+    return null;
+}
+function validateCustomFields(custom_fields) {
+    custom_fields === null || custom_fields === void 0 ? void 0 : custom_fields.filter((cf) => typeof cf.value === "string").forEach((cf) => {
+        const monetaryError = getMonetaryValidationError(cf.value);
+        if (monetaryError)
+            throw new Error(monetaryError);
+    });
+}

package/build/tools/utils/monetary.test.d.ts

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

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

@@ -0,0 +1,25 @@
+"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 monetary_1 = require("./monetary");
+(0, node_test_1.test)("returns null for non-monetary strings", () => {
+    strict_1.default.equal((0, monetary_1.getMonetaryValidationError)("hello"), null);
+    strict_1.default.equal((0, monetary_1.getMonetaryValidationError)("some text"), null);
+    strict_1.default.equal((0, monetary_1.getMonetaryValidationError)(""), null);
+});
+(0, node_test_1.test)("returns null for valid monetary prefix format", () => {
+    strict_1.default.equal((0, monetary_1.getMonetaryValidationError)("USD10.00"), null);
+    strict_1.default.equal((0, monetary_1.getMonetaryValidationError)("GBP123.45"), null);
+    strict_1.default.equal((0, monetary_1.getMonetaryValidationError)("EUR9.99"), null);
+    strict_1.default.equal((0, monetary_1.getMonetaryValidationError)("ILS50.00"), null);
+});
+(0, node_test_1.test)("returns error for trailing currency symbol", () => {
+    const err = (0, monetary_1.getMonetaryValidationError)("10.00$");
+    strict_1.default.ok(err);
+    strict_1.default.match(err, /USD10\.00/);
+    strict_1.default.match(err, /currency code as a prefix/);
+});

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@baruchiro/paperless-mcp",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "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": {
     "paperless-mcp": "build/index.js"
   },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
+    "test": "node --require ts-node/register --test src/**/*.test.ts",
     "start": "ts-node src/index.ts",
     "build": "tsc",
     "dxt-pack": "dxt pack",