@baruchiro/paperless-mcp 0.2.2 → 0.4.0

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;
@@ -10,7 +11,8 @@ export declare class PaperlessAPI {
     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

@@ -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/api/documentEnhancer.js

@@ -8,6 +8,17 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.convertDocsWithNames = convertDocsWithNames;
 function convertDocsWithNames(input, api) {
@@ -61,7 +72,12 @@ function enhanceDocumentsArray(documents, api) {
         const documentTypeMap = new Map((documentTypes.results || []).map((dt) => [dt.id, dt.name]));
         const tagMap = new Map((tags.results || []).map((tag) => [tag.id, tag.name]));
         const customFieldMap = new Map((customFields.results || []).map((cf) => [cf.id, cf.name]));
-        return documents.map((doc) => (Object.assign(Object.assign({}, doc), { correspondent: doc.correspondent
+        return documents
+            .map((doc) => {
+            const { content } = doc, docWithoutContent = __rest(doc, ["content"]);
+            return docWithoutContent;
+        })
+            .map((doc) => (Object.assign(Object.assign({}, doc), { correspondent: doc.correspondent
                 ? {
                     id: doc.correspondent,
                     name: correspondentMap.get(doc.correspondent) ||

package/build/tools/documents.js

@@ -53,7 +53,13 @@ function registerDocumentTools(server, api) {
         add_custom_fields: zod_1.z
             .array(zod_1.z.object({
             field: zod_1.z.number(),
-            value: zod_1.z.union([zod_1.z.string(), zod_1.z.number(), zod_1.z.boolean(), zod_1.z.null()]),
+            value: zod_1.z.union([
+                zod_1.z.string(),
+                zod_1.z.number(),
+                zod_1.z.boolean(),
+                zod_1.z.array(zod_1.z.number()),
+                zod_1.z.null(),
+            ]),
         }))
             .optional()
             .transform(empty_1.arrayNotEmpty),
@@ -146,7 +152,7 @@ function registerDocumentTools(server, api) {
             ],
         };
     })));
-    server.tool("list_documents", "List and filter documents by fields such as title, correspondent, document type, tag, storage path, creation date, and more. IMPORTANT: For queries like 'the last 3 contributions' or when searching by tag, correspondent, document type, or storage path, you should FIRST use the relevant tool (e.g., 'list_tags', 'list_correspondents', 'list_document_types', 'list_storage_paths') to find the correct ID, and then use that ID as a filter here. Only use the 'search' argument for free-text search when no specific field applies. Using the correct ID filter will yield much more accurate results.", {
+    server.tool("list_documents", "List and filter documents by fields such as title, correspondent, document type, tag, storage path, creation date, and more. IMPORTANT: For queries like 'the last 3 contributions' or when searching by tag, correspondent, document type, or storage path, you should FIRST use the relevant tool (e.g., 'list_tags', 'list_correspondents', 'list_document_types', 'list_storage_paths') to find the correct ID, and then use that ID as a filter here. Only use the 'search' argument for free-text search when no specific field applies. Using the correct ID filter will yield much more accurate results. Note: Document content is excluded from results by default. Use 'get_document_content' to retrieve content when needed.", {
         page: zod_1.z.number().optional(),
         page_size: zod_1.z.number().optional(),
         search: zod_1.z.string().optional(),
@@ -184,56 +190,34 @@ function registerDocumentTools(server, api) {
         const docsResponse = yield api.getDocuments(query.toString() ? `?${query.toString()}` : "");
         return (0, documentEnhancer_1.convertDocsWithNames)(docsResponse, api);
     })));
-    server.tool("get_document", "Get a specific document by ID with full details including correspondent, document type, tags, and custom fields.", {
+    server.tool("get_document", "Get a specific document by ID with full details including correspondent, document type, tags, and custom fields. Note: Document content is excluded from results by default. Use 'get_document_content' to retrieve content when needed.", {
+        id: zod_1.z.number(),
+    }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
+        if (!api)
+            throw new Error("Please configure API connection first");
+        const doc = yield api.getDocument(args.id);
+        return (0, documentEnhancer_1.convertDocsWithNames)(doc, api);
+    })));
+    server.tool("get_document_content", "Get the text content of a specific document by ID. Use this when you need to read or analyze the actual document text.", {
         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 doc = yield api.getDocument(args.id);
-        const [correspondents, documentTypes, tags, customFields] = yield Promise.all([
-            api.getCorrespondents(),
-            api.getDocumentTypes(),
-            api.getTags(),
-            api.getCustomFields(),
-        ]);
-        const correspondentMap = new Map((correspondents.results || []).map((c) => [c.id, c.name]));
-        const documentTypeMap = new Map((documentTypes.results || []).map((dt) => [dt.id, dt.name]));
-        const tagMap = new Map((tags.results || []).map((tag) => [tag.id, tag.name]));
-        const customFieldMap = new Map((customFields.results || []).map((cf) => [cf.id, cf.name]));
-        const docWithNames = Object.assign(Object.assign({}, doc), { correspondent: doc.correspondent
-                ? {
-                    id: doc.correspondent,
-                    name: correspondentMap.get(doc.correspondent) ||
-                        String(doc.correspondent),
-                }
-                : null, document_type: doc.document_type
-                ? {
-                    id: doc.document_type,
-                    name: documentTypeMap.get(doc.document_type) ||
-                        String(doc.document_type),
-                }
-                : null, tags: Array.isArray(doc.tags)
-                ? doc.tags.map((tagId) => ({
-                    id: tagId,
-                    name: tagMap.get(tagId) || String(tagId),
-                }))
-                : doc.tags, custom_fields: Array.isArray(doc.custom_fields)
-                ? doc.custom_fields.map((field) => ({
-                    field: field.field,
-                    name: customFieldMap.get(field.field) || String(field.field),
-                    value: field.value,
-                }))
-                : doc.custom_fields });
         return {
             content: [
                 {
                     type: "text",
-                    text: JSON.stringify(docWithNames),
+                    text: JSON.stringify({
+                        id: doc.id,
+                        title: doc.title,
+                        content: doc.content,
+                    }),
                 },
             ],
         };
     })));
-    server.tool("search_documents", "Full text search for documents. This tool is for searching document content, title, and metadata using a full text query. For general document listing or filtering by fields, use 'list_documents' instead.", {
+    server.tool("search_documents", "Full text search for documents. This tool is for searching document content, title, and metadata using a full text query. For general document listing or filtering by fields, use 'list_documents' instead. Note: Document content is excluded from results by default. Use 'get_document_content' to retrieve content when needed.", {
         query: zod_1.z.string(),
     }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
         if (!api)
@@ -265,6 +249,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
@@ -312,8 +315,14 @@ function registerDocumentTools(server, api) {
             .array(zod_1.z.object({
             field: zod_1.z.number().describe("The custom field ID"),
             value: zod_1.z
-                .union([zod_1.z.string(), zod_1.z.number(), zod_1.z.boolean(), zod_1.z.null()])
-                .describe("The value for the custom field"),
+                .union([
+                zod_1.z.string(),
+                zod_1.z.number(),
+                zod_1.z.boolean(),
+                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])."),
         }))
             .optional()
             .describe("Array of custom field values to assign"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@baruchiro/paperless-mcp",
-  "version": "0.2.2",
+  "version": "0.4.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": {
@@ -25,6 +25,9 @@
   ],
   "author": "Baruch Odem",
   "license": "ISC",
+  "engines": {
+    "node": ">=24.0.0"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/baruchiro/paperless-mcp.git"
@@ -51,7 +54,7 @@
     "@anthropic-ai/dxt": "^0.2.6",
     "@changesets/cli": "^2.29.4",
     "@types/express": "^5.0.2",
-    "@types/node": "^22.15.17",
+    "@types/node": "^24.0.0",
     "ts-node": "^10.9.2"
   }
 }