@baruchiro/paperless-mcp 0.2.1 → 0.3.0

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/correspondents.js

@@ -27,7 +27,7 @@ const utils_1 = require("../api/utils");
 const middlewares_1 = require("./utils/middlewares");
 const queryString_1 = require("./utils/queryString");
 function registerCorrespondentTools(server, api) {
-    server.tool("list_correspondents", {
+    server.tool("list_correspondents", "List all correspondents with optional filtering and pagination. Correspondents represent entities that send or receive documents.", {
         page: zod_1.z.number().optional(),
         page_size: zod_1.z.number().optional(),
         name__icontains: zod_1.z.string().optional(),
@@ -50,7 +50,7 @@ function registerCorrespondentTools(server, api) {
             ],
         };
     })));
-    server.tool("get_correspondent", { id: zod_1.z.number() }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
+    server.tool("get_correspondent", "Get a specific correspondent by ID with full details including matching rules.", { 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.getCorrespondent(args.id);
@@ -61,7 +61,7 @@ function registerCorrespondentTools(server, api) {
             ],
         };
     })));
-    server.tool("create_correspondent", {
+    server.tool("create_correspondent", "Create a new correspondent with optional matching pattern and algorithm for automatic document assignment.", {
         name: zod_1.z.string(),
         match: zod_1.z.string().optional(),
         matching_algorithm: zod_1.z
@@ -82,7 +82,7 @@ function registerCorrespondentTools(server, api) {
             ],
         };
     })));
-    server.tool("update_correspondent", {
+    server.tool("update_correspondent", "Update an existing correspondent's name, matching pattern, or matching algorithm.", {
         id: zod_1.z.number(),
         name: zod_1.z.string(),
         match: zod_1.z.string().optional(),

package/build/tools/customFields.js

@@ -47,7 +47,7 @@ function registerCustomFieldTools(server, api) {
             ],
         };
     })));
-    server.tool("get_custom_field", { id: zod_1.z.number() }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
+    server.tool("get_custom_field", "Get a specific custom field by ID with full details including data type and extra configuration.", { 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.getCustomField(args.id);
@@ -55,7 +55,7 @@ function registerCustomFieldTools(server, api) {
             content: [{ type: "text", text: JSON.stringify(response) }],
         };
     })));
-    server.tool("create_custom_field", {
+    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).", {
         name: zod_1.z.string(),
         data_type: zod_1.z.enum([
             "string",
@@ -77,7 +77,7 @@ function registerCustomFieldTools(server, api) {
             content: [{ type: "text", text: JSON.stringify(response) }],
         };
     })));
-    server.tool("update_custom_field", {
+    server.tool("update_custom_field", "Update an existing custom field's name, data type, or extra configuration data.", {
         id: zod_1.z.number(),
         name: zod_1.z.string().optional(),
         data_type: zod_1.z

package/build/tools/documentTypes.js

@@ -50,7 +50,7 @@ function registerDocumentTypeTools(server, api) {
             ],
         };
     })));
-    server.tool("get_document_type", { id: zod_1.z.number() }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
+    server.tool("get_document_type", "Get a specific document type by ID with full details including matching rules.", { 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.request(`/document_types/${args.id}/`);
@@ -59,7 +59,7 @@ function registerDocumentTypeTools(server, api) {
             content: [{ type: "text", text: JSON.stringify(enhancedDocumentType) }],
         };
     })));
-    server.tool("create_document_type", {
+    server.tool("create_document_type", "Create a new document type with optional matching pattern and algorithm for automatic document classification.", {
         name: zod_1.z.string(),
         match: zod_1.z.string().optional(),
         matching_algorithm: zod_1.z
@@ -78,7 +78,7 @@ function registerDocumentTypeTools(server, api) {
             content: [{ type: "text", text: JSON.stringify(enhancedDocumentType) }],
         };
     })));
-    server.tool("update_document_type", {
+    server.tool("update_document_type", "Update an existing document type's name, matching pattern, or matching algorithm.", {
         id: zod_1.z.number(),
         name: zod_1.z.string(),
         match: zod_1.z.string().optional(),

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),
@@ -111,7 +117,7 @@ function registerDocumentTools(server, api) {
             ],
         };
     })));
-    server.tool("post_document", {
+    server.tool("post_document", "Upload a new document to Paperless-NGX with optional metadata like title, correspondent, document type, tags, and custom fields.", {
         file: zod_1.z.string(),
         filename: zod_1.z.string(),
         title: zod_1.z.string().optional(),
@@ -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", {
+    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)
@@ -241,7 +225,7 @@ function registerDocumentTools(server, api) {
         const docsResponse = yield api.searchDocuments(args.query);
         return (0, documentEnhancer_1.convertDocsWithNames)(docsResponse, api);
     })));
-    server.tool("download_document", {
+    server.tool("download_document", "Download a document file by ID. Returns the document as a base64-encoded resource.", {
         id: zod_1.z.number(),
         original: zod_1.z.boolean().optional(),
     }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
@@ -312,8 +296,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/build/tools/tags.js

@@ -39,7 +39,7 @@ function registerTagTools(server, api) {
             ],
         };
     })));
-    server.tool("create_tag", {
+    server.tool("create_tag", "Create a new tag with optional color, matching pattern, and matching algorithm for automatic document tagging.", {
         name: zod_1.z.string(),
         color: zod_1.z
             .string()
@@ -67,7 +67,7 @@ function registerTagTools(server, api) {
             ],
         };
     })));
-    server.tool("update_tag", {
+    server.tool("update_tag", "Update an existing tag's name, color, matching pattern, or matching algorithm.", {
         id: zod_1.z.number(),
         name: zod_1.z.string(),
         color: zod_1.z

package/package.json

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