@baruchiro/paperless-mcp 2.1.0 → 2.2.0

package/build/api/PaperlessAPI.d.ts

@@ -7,7 +7,7 @@ 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(document: Buffer, filename: string, metadata?: Record<string, string | string[] | number | number[]>): Promise<string>;
+    postDocument(document: Buffer, filename: string, metadata?: Record<string, string | string[] | number | number[] | undefined>): Promise<string>;
     getDocuments(query?: string): Promise<DocumentsResponse>;
     getDocument(id: number): Promise<Document>;
     updateDocument(id: number, data: Partial<Document>): Promise<Document>;

package/build/api/types.d.ts

@@ -68,7 +68,7 @@ export interface Document {
     id: number;
     correspondent: number | null;
     document_type: number | null;
-    storage_path: string | null;
+    storage_path: number | null;
     title: string;
     content: string | null;
     tags: number[];
@@ -77,7 +77,7 @@ export interface Document {
     modified: string;
     added: string;
     deleted_at: string | null;
-    archive_serial_number: string | null;
+    archive_serial_number: number | null;
     original_file_name: string;
     archived_file_name: string;
     owner: number | null;

package/build/tools/correspondents.js

@@ -22,8 +22,8 @@ var __rest = (this && this.__rest) || function (s, e) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerCorrespondentTools = registerCorrespondentTools;
 const zod_1 = require("zod");
-const types_1 = require("../api/types");
 const utils_1 = require("../api/utils");
+const matchingAlgorithm_1 = require("./utils/matchingAlgorithm");
 const middlewares_1 = require("./utils/middlewares");
 const queryString_1 = require("./utils/queryString");
 function registerCorrespondentTools(server, api) {
@@ -64,13 +64,7 @@ function registerCorrespondentTools(server, api) {
     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
-            .number()
-            .int()
-            .min(0)
-            .max(6)
-            .optional()
-            .describe(types_1.MATCHING_ALGORITHM_DESCRIPTION),
+        matching_algorithm: matchingAlgorithm_1.matchingAlgorithmSchema.optional(),
     }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
         if (!api)
             throw new Error("Please configure API connection first");
@@ -86,13 +80,7 @@ function registerCorrespondentTools(server, api) {
         id: zod_1.z.number(),
         name: zod_1.z.string(),
         match: zod_1.z.string().optional(),
-        matching_algorithm: zod_1.z
-            .number()
-            .int()
-            .min(0)
-            .max(6)
-            .optional()
-            .describe(types_1.MATCHING_ALGORITHM_DESCRIPTION),
+        matching_algorithm: matchingAlgorithm_1.matchingAlgorithmSchema.optional(),
     }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
         if (!api)
             throw new Error("Please configure API connection first");

package/build/tools/customFields.js

@@ -33,7 +33,7 @@ function registerCustomFieldTools(server, api) {
         name__iexact: zod_1.z.string().optional(),
         name__istartswith: zod_1.z.string().optional(),
         ordering: zod_1.z.string().optional(),
-    }, (0, middlewares_1.withErrorHandling)((...args_1) => __awaiter(this, [...args_1], void 0, function* (args = {}) {
+    }, (0, middlewares_1.withErrorHandling)((args) => __awaiter(this, void 0, void 0, function* () {
         if (!api)
             throw new Error("Please configure API connection first");
         const queryString = (0, queryString_1.buildQueryString)(args);
@@ -68,7 +68,7 @@ function registerCustomFieldTools(server, api) {
             "documentlink",
             "select",
         ]),
-        extra_data: zod_1.z.record(zod_1.z.unknown()).nullable().optional(),
+        extra_data: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).nullable().optional(),
     }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
         if (!api)
             throw new Error("Please configure API connection first");
@@ -93,7 +93,7 @@ function registerCustomFieldTools(server, api) {
             "select",
         ])
             .optional(),
-        extra_data: zod_1.z.record(zod_1.z.unknown()).nullable().optional(),
+        extra_data: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).nullable().optional(),
     }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
         if (!api)
             throw new Error("Please configure API connection first");

package/build/tools/documentTypes.js

@@ -22,8 +22,8 @@ var __rest = (this && this.__rest) || function (s, e) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerDocumentTypeTools = registerDocumentTypeTools;
 const zod_1 = require("zod");
-const types_1 = require("../api/types");
 const utils_1 = require("../api/utils");
+const matchingAlgorithm_1 = require("./utils/matchingAlgorithm");
 const middlewares_1 = require("./utils/middlewares");
 const queryString_1 = require("./utils/queryString");
 function registerDocumentTypeTools(server, api) {
@@ -35,7 +35,7 @@ function registerDocumentTypeTools(server, api) {
         name__iexact: zod_1.z.string().optional(),
         name__istartswith: zod_1.z.string().optional(),
         ordering: zod_1.z.string().optional(),
-    }, (0, middlewares_1.withErrorHandling)((...args_1) => __awaiter(this, [...args_1], void 0, function* (args = {}, extra) {
+    }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
         if (!api)
             throw new Error("Please configure API connection first");
         const queryString = (0, queryString_1.buildQueryString)(args);
@@ -62,13 +62,7 @@ function registerDocumentTypeTools(server, api) {
     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
-            .number()
-            .int()
-            .min(0)
-            .max(6)
-            .optional()
-            .describe(types_1.MATCHING_ALGORITHM_DESCRIPTION),
+        matching_algorithm: matchingAlgorithm_1.matchingAlgorithmSchema.optional(),
     }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
         if (!api)
             throw new Error("Please configure API connection first");
@@ -82,13 +76,7 @@ function registerDocumentTypeTools(server, api) {
         id: zod_1.z.number(),
         name: zod_1.z.string(),
         match: zod_1.z.string().optional(),
-        matching_algorithm: zod_1.z
-            .number()
-            .int()
-            .min(0)
-            .max(6)
-            .optional()
-            .describe(types_1.MATCHING_ALGORITHM_DESCRIPTION),
+        matching_algorithm: matchingAlgorithm_1.matchingAlgorithmSchema.optional(),
     }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
         if (!api)
             throw new Error("Please configure API connection first");

package/build/tools/documents.js

@@ -188,6 +188,7 @@ function registerDocumentTools(server, api) {
             .describe("For set_permissions: view/change permissions to apply. Omitted actions (view/change) and omitted users/groups lists are left untouched; an empty list [] removes all (unless merge is true). Omit entirely for owner-only changes."),
         owner: zod_1.z
             .number()
+            .int()
             .nullable()
             .optional()
             .describe("For set_permissions: new owner user ID, or null to remove the owner. Unless merge is true, omitting owner also clears the current owner."),
@@ -295,7 +296,7 @@ function registerDocumentTools(server, api) {
             throw new Error("Please configure API connection first");
         const validationResult = postDocumentSchema.safeParse(args);
         if (!validationResult.success) {
-            throw new Error(validationResult.error.errors.map(e => e.message).join("; "));
+            throw new Error(validationResult.error.issues.map(e => e.message).join("; "));
         }
         let document;
         let filename;
@@ -451,16 +452,19 @@ function registerDocumentTools(server, api) {
             .describe("The new title for the document (max 128 characters)"),
         correspondent: zod_1.z
             .number()
+            .int()
             .nullable()
             .optional()
             .describe("The ID of the correspondent to assign"),
         document_type: zod_1.z
             .number()
+            .int()
             .nullable()
             .optional()
             .describe("The ID of the document type to assign"),
         storage_path: zod_1.z
             .number()
+            .int()
             .nullable()
             .optional()
             .describe("The ID of the storage path to assign"),
@@ -482,6 +486,7 @@ function registerDocumentTools(server, api) {
             .describe("The archive serial number (0-4294967295)"),
         owner: zod_1.z
             .number()
+            .int()
             .nullable()
             .optional()
             .describe("The ID of the user who owns the document"),

package/build/tools/documents.test.js

@@ -639,3 +639,20 @@ const OBJECT_SELECT_FIELD = {
         strict_1.default.equal(calls.bulkEditDocuments.length, 0);
     }));
 });
+(0, node_test_1.describe)("nullable foreign keys can still be cleared (#138)", () => {
+    (0, node_test_1.test)("update_document forwards an explicit null so a foreign key can be cleared", () => __awaiter(void 0, void 0, void 0, function* () {
+        const { api, calls } = createDocumentApi([]);
+        yield withDocumentClient(api, (client) => __awaiter(void 0, void 0, void 0, function* () {
+            var _a;
+            const result = (yield client.callTool({
+                name: "update_document",
+                arguments: { id: 42, correspondent: null, owner: null },
+            }));
+            strict_1.default.ok(!result.isError, (_a = parseToolText(result)) === null || _a === void 0 ? void 0 : _a.error);
+        }));
+        strict_1.default.equal(calls.updateDocument.length, 1);
+        const [, data] = calls.updateDocument[0];
+        strict_1.default.equal(data.correspondent, null);
+        strict_1.default.equal(data.owner, null);
+    }));
+});

package/build/tools/mail.js

@@ -35,10 +35,10 @@ const mailRuleFields = {
     account: zod_1.z.number().int().optional(),
     enabled: zod_1.z.boolean().optional(),
     folder: zod_1.z.string().optional(),
-    filter_from: zod_1.z.string().nullable().optional(),
-    filter_to: zod_1.z.string().nullable().optional(),
-    filter_subject: zod_1.z.string().nullable().optional(),
-    filter_body: zod_1.z.string().nullable().optional(),
+    filter_from: zod_1.z.string().max(256).nullable().optional(),
+    filter_to: zod_1.z.string().max(256).nullable().optional(),
+    filter_subject: zod_1.z.string().max(256).nullable().optional(),
+    filter_body: zod_1.z.string().max(256).nullable().optional(),
     filter_attachment_filename_include: zod_1.z.string().nullable().optional(),
     filter_attachment_filename_exclude: zod_1.z.string().nullable().optional(),
     maximum_age: zod_1.z.number().int().min(0).optional(),
@@ -96,7 +96,7 @@ function registerMailTools(server, api) {
     server.tool("list_mail_accounts", "List Paperless mail accounts for selecting the account ID needed by mail rules. Does not expose account passwords.", {
         page: zod_1.z.number().optional(),
         page_size: zod_1.z.number().optional(),
-    }, (0, middlewares_1.withErrorHandling)((...args_1) => __awaiter(this, [...args_1], void 0, function* (args = {}) {
+    }, (0, middlewares_1.withErrorHandling)((args) => __awaiter(this, void 0, void 0, function* () {
         if (!api)
             throw new Error("Please configure API connection first");
         const queryString = (0, queryString_1.buildQueryString)(args);
@@ -132,7 +132,7 @@ function registerMailTools(server, api) {
     server.tool("list_mail_rules", "List Paperless mail rules with optional pagination.", {
         page: zod_1.z.number().optional(),
         page_size: zod_1.z.number().optional(),
-    }, (0, middlewares_1.withErrorHandling)((...args_1) => __awaiter(this, [...args_1], void 0, function* (args = {}) {
+    }, (0, middlewares_1.withErrorHandling)((args) => __awaiter(this, void 0, void 0, function* () {
         if (!api)
             throw new Error("Please configure API connection first");
         const queryString = (0, queryString_1.buildQueryString)(args);

package/build/tools/schemaCompat.test.d.ts

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

package/build/tools/schemaCompat.test.js

@@ -0,0 +1,59 @@
+"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 inMemory_js_1 = require("@modelcontextprotocol/sdk/inMemory.js");
+const server_1 = require("../server");
+// Strict MCP clients and gateways reject an array-valued `type` and silently drop
+// the whole tool (#138). A JSON Schema converter reaches that form by collapsing a
+// union of unchecked primitives: `zod-to-json-schema` (the zod v3 path) always does
+// it, and zod's own converter did it again from 4.5.0 on. The tools are only free
+// of it because the server is on the zod v4 path with zod pinned to 4.4.x, so this
+// walks every advertised schema rather than a field list: bumping that pin, moving
+// off zod v4, or adding a construct that reintroduces the form fails here.
+function arrayFormTypes(node, path = "") {
+    if (Array.isArray(node)) {
+        return node.flatMap((item, i) => arrayFormTypes(item, `${path}[${i}]`));
+    }
+    if (!node || typeof node !== "object") {
+        return [];
+    }
+    return Object.entries(node).flatMap(([key, value]) => key === "type" && Array.isArray(value)
+        ? [`${path}.type = ${JSON.stringify(value)}`]
+        : arrayFormTypes(value, `${path}.${key}`));
+}
+(0, node_test_1.test)("no tool advertises an array-form `type` (#138)", () => __awaiter(void 0, void 0, void 0, function* () {
+    const server = (0, server_1.createMcpServer)({
+        baseUrl: "http://paperless.test",
+        token: "test-token",
+        version: "0.0.0-test",
+        publicUrl: "http://paperless.test",
+    });
+    const [clientTransport, serverTransport] = inMemory_js_1.InMemoryTransport.createLinkedPair();
+    const client = new index_js_1.Client({ name: "schema-compat-test", version: "1.0.0" });
+    yield Promise.all([server.connect(serverTransport), client.connect(clientTransport)]);
+    try {
+        const { tools } = yield client.listTools();
+        const found = tools
+            .flatMap((tool) => arrayFormTypes(tool.inputSchema).map((hit) => `${tool.name} ${hit}`))
+            .sort();
+        strict_1.default.deepEqual(found, []);
+    }
+    finally {
+        yield client.close();
+        yield server.close();
+    }
+}));

package/build/tools/tags.js

@@ -11,8 +11,8 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerTagTools = registerTagTools;
 const zod_1 = require("zod");
-const types_1 = require("../api/types");
 const utils_1 = require("../api/utils");
+const matchingAlgorithm_1 = require("./utils/matchingAlgorithm");
 const middlewares_1 = require("./utils/middlewares");
 const queryString_1 = require("./utils/queryString");
 function registerTagTools(server, api) {
@@ -24,7 +24,7 @@ function registerTagTools(server, api) {
         name__iexact: zod_1.z.string().optional(),
         name__istartswith: zod_1.z.string().optional(),
         ordering: zod_1.z.string().optional(),
-    }, (0, middlewares_1.withErrorHandling)((...args_1) => __awaiter(this, [...args_1], void 0, function* (args = {}) {
+    }, (0, middlewares_1.withErrorHandling)((args) => __awaiter(this, void 0, void 0, function* () {
         if (!api)
             throw new Error("Please configure API connection first");
         const queryString = (0, queryString_1.buildQueryString)(args);
@@ -46,13 +46,7 @@ function registerTagTools(server, api) {
             .regex(/^#[0-9A-Fa-f]{6}$/)
             .optional(),
         match: zod_1.z.string().optional(),
-        matching_algorithm: zod_1.z
-            .number()
-            .int()
-            .min(0)
-            .max(6)
-            .optional()
-            .describe(types_1.MATCHING_ALGORITHM_DESCRIPTION),
+        matching_algorithm: matchingAlgorithm_1.matchingAlgorithmSchema.optional(),
     }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
         if (!api)
             throw new Error("Please configure API connection first");
@@ -75,13 +69,7 @@ function registerTagTools(server, api) {
             .regex(/^#[0-9A-Fa-f]{6}$/)
             .optional(),
         match: zod_1.z.string().optional(),
-        matching_algorithm: zod_1.z
-            .number()
-            .int()
-            .min(0)
-            .max(6)
-            .optional()
-            .describe(types_1.MATCHING_ALGORITHM_DESCRIPTION),
+        matching_algorithm: matchingAlgorithm_1.matchingAlgorithmSchema.optional(),
     }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
         if (!api)
             throw new Error("Please configure API connection first");

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

@@ -6,8 +6,8 @@ export type CustomFieldQuery = [fieldNameOrId: string | number, operator: string
     clauses: CustomFieldQuery[]
 ];
 export declare const customFieldQuerySchema: z.ZodType<CustomFieldQuery>;
-export declare const paperlessFilterValueSchema: z.ZodUnion<[z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>, z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>, "many">]>;
-export declare const paperlessFiltersSchema: z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>, z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>, "many">]>>;
+export declare const paperlessFilterValueSchema: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>]>;
+export declare const paperlessFiltersSchema: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>]>>;
 export declare const LIST_DOCUMENTS_ARGS_SHAPE: {
     custom_field_query: z.ZodOptional<z.ZodString>;
     page: z.ZodOptional<z.ZodNumber>;
@@ -27,8 +27,8 @@ export declare const LIST_DOCUMENTS_ARGS_SHAPE: {
 export declare const QUERY_DOCUMENTS_ARGS_SHAPE: {
     query: z.ZodOptional<z.ZodString>;
     more_like_id: z.ZodOptional<z.ZodNumber>;
-    custom_field_query: z.ZodOptional<z.ZodType<CustomFieldQuery, z.ZodTypeDef, CustomFieldQuery>>;
-    paperless_filters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>, z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>, "many">]>>>;
+    custom_field_query: z.ZodOptional<z.ZodType<CustomFieldQuery, unknown, z.core.$ZodTypeInternals<CustomFieldQuery, unknown>>>;
+    paperless_filters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>]>>>;
     page: z.ZodOptional<z.ZodNumber>;
     page_size: z.ZodOptional<z.ZodNumber>;
     search: z.ZodOptional<z.ZodString>;

package/build/tools/utils/documentQuery.js

@@ -68,7 +68,7 @@ exports.paperlessFilterValueSchema = zod_1.z.union([
     paperlessFilterScalarSchema,
     zod_1.z.array(paperlessFilterScalarSchema),
 ]);
-exports.paperlessFiltersSchema = zod_1.z.record(exports.paperlessFilterValueSchema);
+exports.paperlessFiltersSchema = zod_1.z.record(zod_1.z.string(), exports.paperlessFilterValueSchema);
 const DOCUMENT_QUERY_BASE_ARGS_SHAPE = {
     page: zod_1.z.number().optional(),
     page_size: zod_1.z.number().optional(),

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

@@ -0,0 +1,2 @@
+import { z } from "zod";
+export declare const matchingAlgorithmSchema: z.ZodPipe<z.ZodNumber, z.ZodTransform<0 | 1 | 2 | 3 | 4 | 5 | 6, number>>;

package/build/tools/utils/matchingAlgorithm.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.matchingAlgorithmSchema = void 0;
+const zod_1 = require("zod");
+const types_1 = require("../../api/types");
+// The 0-6 range the API declares is exactly the set `MatchingAlgorithm`
+// enumerates, so narrowing to it after the check lets the PaperlessAPI request
+// types take the parsed value without a cast at every call site.
+exports.matchingAlgorithmSchema = zod_1.z
+    .number()
+    .int()
+    .min(0)
+    .max(6)
+    .transform((value) => value)
+    .describe(types_1.MATCHING_ALGORITHM_DESCRIPTION);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@baruchiro/paperless-mcp",
-  "version": "2.1.0",
+  "version": "2.2.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": {
@@ -44,12 +44,12 @@
     "url": "https://github.com/baruchiro/paperless-mcp/issues"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.11.1",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "axios": "^1.9.0",
     "express": "^5.1.0",
     "form-data": "^4.0.2",
     "typescript": "^5.8.3",
-    "zod": "^3.24.1"
+    "zod": "~4.4.3"
   },
   "devDependencies": {
     "@anthropic-ai/dxt": "^0.2.6",