@baruchiro/paperless-mcp 0.0.2 → 0.1.0

package/README.md

@@ -1,3 +1,5 @@
+<!-- [![MseeP.ai Security Assessment Badge](https://mseep.net/pr/nloui-paperless-mcp-badge.png)](https://mseep.ai/app/nloui-paperless-mcp) -->
+
 # Paperless-NGX MCP Server
 
 [![smithery badge](https://smithery.ai/badge/@baruchiro/paperless-mcp)](https://smithery.ai/server/@baruchiro/paperless-mcp)
@@ -6,6 +8,8 @@ An MCP (Model Context Protocol) server for interacting with a Paperless-NGX API
 
 ## Quick Start
 
+[![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):
@@ -28,7 +32,8 @@ Add these to your MCP config file:
   ],
   "env": {
     "PAPERLESS_URL": "http://your-paperless-instance:8000",
-    "PAPERLESS_API_KEY": "your-api-token"
+    "PAPERLESS_API_KEY": "your-api-token",
+    "PAPERLESS_PUBLIC_URL": "https://your-public-domain.com"
   }
 }
 ```
@@ -45,7 +50,8 @@ Add these to your MCP config file:
   ],
   "env": {
     "PAPERLESS_URL": "http://your-paperless-instance:8000",
-    "PAPERLESS_API_KEY": "your-api-token"
+    "PAPERLESS_API_KEY": "your-api-token",
+    "PAPERLESS_PUBLIC_URL": "https://your-public-domain.com"
   }
 }
 ```
@@ -59,6 +65,7 @@ Add these to your MCP config file:
 4. Replace the placeholders in your MCP config:
    - `http://your-paperless-instance:8000` with your Paperless-NGX URL
    - `your-api-token` with the token you just generated
+   - `https://your-public-domain.com` with your public Paperless-NGX URL (optional, falls back to PAPERLESS_URL)
 
 That's it! Now you can ask Claude to help you manage your Paperless-NGX documents.
 
@@ -199,6 +206,15 @@ bulk_edit_documents({
   add_tags: [1, 2],
   remove_tags: [3, 4]
 })
+
+// Modify custom fields
+bulk_edit_documents({
+  documents: [12, 13],
+  method: "modify_custom_fields",
+  add_custom_fields: {
+    "2": "שנה"
+  }
+})
 ```
 
 #### post_document
@@ -225,7 +241,8 @@ post_document({
   correspondent: 1,
   document_type: 2,
   tags: [1, 3],
-  archive_serial_number: "2024-001"
+  archive_serial_number: "2024-001",
+  custom_fields: [1, 2]
 })
 ```
 
@@ -306,6 +323,85 @@ create_document_type({
 })
 ```
 
+### Custom Field Operations
+
+#### list_custom_fields
+Get all custom fields.
+
+```typescript
+list_custom_fields()
+```
+
+#### get_custom_field
+Get a specific custom field by ID.
+
+Parameters:
+- id: Custom field ID
+
+```typescript
+get_custom_field({
+  id: 1
+})
+```
+
+#### create_custom_field
+Create a new custom field.
+
+Parameters:
+- name: Custom field name
+- data_type: One of "string", "url", "date", "boolean", "integer", "float", "monetary", "documentlink", "select"
+- extra_data (optional): Extra data for the custom field, such as select options
+
+```typescript
+create_custom_field({
+  name: "Invoice Number",
+  data_type: "string"
+})
+```
+
+#### update_custom_field
+Update an existing custom field.
+
+Parameters:
+- id: Custom field ID
+- name (optional): New custom field name
+- data_type (optional): New data type
+- extra_data (optional): Extra data for the custom field
+
+```typescript
+update_custom_field({
+  id: 1,
+  name: "Updated Invoice Number",
+  data_type: "string"
+})
+```
+
+#### delete_custom_field
+Delete a custom field.
+
+Parameters:
+- id: Custom field ID
+
+```typescript
+delete_custom_field({
+  id: 1
+})
+```
+
+#### bulk_edit_custom_fields
+Perform bulk operations on multiple custom fields.
+
+Parameters:
+- custom_fields: Array of custom field IDs
+- operation: One of "delete"
+
+```typescript
+bulk_edit_custom_fields({
+  custom_fields: [1, 2, 3],
+  operation: "delete"
+})
+```
+
 ## Error Handling
 
 The server will show clear error messages if:
@@ -365,3 +461,42 @@ npm run start -- <baseUrl> <token> --http --port 3000
 # 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.
+
+## Debugging
+
+To debug the MCP server in VS Code, use the following launch configuration:
+
+```json
+{
+    "type": "node",
+    "request": "launch",
+    "name": "Debug Paperless MCP (HTTP, ts-node ESM)",
+    "program": "${workspaceFolder}/node_modules/ts-node/dist/bin.js",
+    "args": [
+        "--esm",
+        "src/index.ts",
+        "--http",
+        "--baseUrl",
+        "http://your-paperless-instance:8000",
+        "--token",
+        "your-api-token",
+        "--port",
+        "3002"
+    ],
+    "env": {
+        "NODE_OPTIONS": "--loader ts-node/esm",
+    },
+    "console": "integratedTerminal",
+    "skipFiles": [
+        "<node_internals>/**"
+    ]
+}
+```
+
+**Important:** Before debugging, uncomment the following line in `src/index.ts` (around line 175):
+
+```typescript
+// await new Promise((resolve) => setTimeout(resolve, 1000000));
+```
+
+This prevents the server from exiting immediately and allows you to set breakpoints and debug the code.

package/build/api/PaperlessAPI.d.ts

@@ -1,13 +1,14 @@
-import { BulkEditDocumentsResult, Correspondent, Document, DocumentsResponse, DocumentType, GetCorrespondentsResponse, GetDocumentTypesResponse, GetTagsResponse, Tag } from "./types";
+import { BulkEditDocumentsResult, BulkEditParameters, Correspondent, CustomField, Document, DocumentsResponse, DocumentType, GetCorrespondentsResponse, GetCustomFieldsResponse, GetDocumentTypesResponse, GetTagsResponse, Tag } from "./types";
 export declare class PaperlessAPI {
     private readonly baseUrl;
     private readonly token;
     constructor(baseUrl: string, token: string);
     request<T = any>(path: string, options?: RequestInit): Promise<T>;
-    bulkEditDocuments(documents: number[], method: string, parameters?: {}): Promise<BulkEditDocumentsResult>;
+    bulkEditDocuments(documents: number[], method: string, parameters?: BulkEditParameters): Promise<BulkEditDocumentsResult>;
     postDocument(file: File, 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>>;
     getTags(): Promise<GetTagsResponse>;
@@ -22,5 +23,10 @@ export declare class PaperlessAPI {
     createDocumentType(data: Partial<DocumentType>): Promise<DocumentType>;
     updateDocumentType(id: number, data: Partial<DocumentType>): Promise<DocumentType>;
     deleteDocumentType(id: number): Promise<void>;
+    getCustomFields(): Promise<GetCustomFieldsResponse>;
+    getCustomField(id: number): Promise<CustomField>;
+    createCustomField(data: Partial<CustomField>): Promise<CustomField>;
+    updateCustomField(id: number, data: Partial<CustomField>): Promise<CustomField>;
+    deleteCustomField(id: number): Promise<void>;
     bulkEditObjects(objects: any, objectType: any, operation: any, parameters?: {}): Promise<any>;
 }

package/build/api/PaperlessAPI.js

@@ -25,6 +25,7 @@ class PaperlessAPI {
     }
     request(path_1) {
         return __awaiter(this, arguments, void 0, function* (path, options = {}) {
+            var _a, _b;
             const url = `${this.baseUrl}/api${path}`;
             const isJson = !options.body || typeof options.body === "string";
             const mergedHeaders = Object.assign(Object.assign({ Authorization: `Token ${this.token}`, Accept: "application/json; version=5", "Accept-Language": "en-US,en;q=0.9" }, (isJson ? { "Content-Type": "application/json" } : {})), (0, utils_1.headersToObject)(options.headers));
@@ -44,7 +45,11 @@ class PaperlessAPI {
                         status: response.status,
                         response: body,
                     });
-                    throw new Error(`HTTP error! status: ${response.status}`);
+                    const errorMessage = (body === null || body === void 0 ? void 0 : body.detail) ||
+                        (body === null || body === void 0 ? void 0 : body.error) ||
+                        (body === null || body === void 0 ? void 0 : body.message) ||
+                        `HTTP error! status: ${response.status}`;
+                    throw new Error(String(errorMessage));
                 }
                 return body;
             }
@@ -54,6 +59,8 @@ class PaperlessAPI {
                     message: error instanceof Error ? error.message : String(error),
                     url,
                     options,
+                    responseData: (_a = error === null || error === void 0 ? void 0 : error.response) === null || _a === void 0 ? void 0 : _a.data,
+                    status: (_b = error === null || error === void 0 ? void 0 : error.response) === null || _b === void 0 ? void 0 : _b.status,
                 });
                 throw error;
             }
@@ -115,6 +122,14 @@ class PaperlessAPI {
             return this.request(`/documents/${id}/`);
         });
     }
+    updateDocument(id, data) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.request(`/documents/${id}/`, {
+                method: "PATCH",
+                body: JSON.stringify(data),
+            });
+        });
+    }
     searchDocuments(query) {
         return __awaiter(this, void 0, void 0, function* () {
             const response = yield this.request(`/documents/?query=${encodeURIComponent(query)}`);
@@ -220,6 +235,40 @@ class PaperlessAPI {
             });
         });
     }
+    // Custom field operations
+    getCustomFields() {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.request("/custom_fields/");
+        });
+    }
+    getCustomField(id) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.request(`/custom_fields/${id}/`);
+        });
+    }
+    createCustomField(data) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.request("/custom_fields/", {
+                method: "POST",
+                body: JSON.stringify(data),
+            });
+        });
+    }
+    updateCustomField(id, data) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.request(`/custom_fields/${id}/`, {
+                method: "PUT",
+                body: JSON.stringify(data),
+            });
+        });
+    }
+    deleteCustomField(id) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.request(`/custom_fields/${id}/`, {
+                method: "DELETE",
+            });
+        });
+    }
     // Bulk object operations
     bulkEditObjects(objects_1, objectType_1, operation_1) {
         return __awaiter(this, arguments, void 0, function* (objects, objectType, operation, parameters = {}) {

package/build/api/documentEnhancer.d.ts

@@ -0,0 +1,21 @@
+import { CallToolResult } from "@modelcontextprotocol/sdk/types";
+import { PaperlessAPI } from "./PaperlessAPI";
+import { Document, DocumentsResponse } from "./types";
+interface NamedItem {
+    id: number;
+    name: string;
+}
+interface CustomField {
+    field: number;
+    name: string;
+    value: string | number | boolean | object | null;
+}
+export interface EnhancedDocument extends Omit<Document, "correspondent" | "document_type" | "tags" | "custom_fields"> {
+    correspondent: NamedItem | null;
+    document_type: NamedItem | null;
+    tags: NamedItem[];
+    custom_fields: CustomField[];
+}
+export declare function convertDocsWithNames(document: Document, api: PaperlessAPI): Promise<CallToolResult>;
+export declare function convertDocsWithNames(documentsResponse: DocumentsResponse, api: PaperlessAPI): Promise<CallToolResult>;
+export {};

package/build/api/documentEnhancer.js

@@ -0,0 +1,88 @@
+"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.convertDocsWithNames = convertDocsWithNames;
+function convertDocsWithNames(input, api) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if ("results" in input) {
+            const enhancedResults = yield enhanceDocumentsArray(input.results || [], api);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: (enhancedResults === null || enhancedResults === void 0 ? void 0 : enhancedResults.length)
+                            ? JSON.stringify(Object.assign(Object.assign({}, input), { results: enhancedResults }))
+                            : "No documents found",
+                    },
+                ],
+            };
+        }
+        if (!input) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "No document found",
+                    },
+                ],
+            };
+        }
+        const [enhanced] = yield enhanceDocumentsArray([input], api);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(enhanced),
+                },
+            ],
+        };
+    });
+}
+function enhanceDocumentsArray(documents, api) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (!(documents === null || documents === void 0 ? void 0 : documents.length)) {
+            return [];
+        }
+        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]));
+        return documents.map((doc) => (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 })));
+    });
+}

package/build/api/types.d.ts

@@ -12,6 +12,21 @@ export interface Tag {
     owner: number | null;
     user_can_change: boolean;
 }
+export interface CustomField {
+    id: number;
+    name: string;
+    data_type: string;
+    extra_data?: Record<string, unknown> | null;
+    document_count: number;
+}
+export interface CustomFieldInstance {
+    field: number;
+    value: string | number | boolean | object | null;
+}
+export interface CustomFieldInstanceRequest {
+    field: number;
+    value: string | number | boolean | object | null;
+}
 export interface PaginationResponse<T> {
     count: number;
     next: string | null;
@@ -21,6 +36,8 @@ export interface PaginationResponse<T> {
 }
 export interface GetTagsResponse extends PaginationResponse<Tag> {
 }
+export interface GetCustomFieldsResponse extends PaginationResponse<CustomField> {
+}
 export interface DocumentsResponse extends PaginationResponse<Document> {
 }
 export interface Document {
@@ -43,7 +60,7 @@ export interface Document {
     user_can_change: boolean;
     is_shared_by_requester: boolean;
     notes: any[];
-    custom_fields: any[];
+    custom_fields: CustomFieldInstance[];
     page_count: number;
     mime_type: string;
     __search_hit__?: SearchHit;
@@ -87,3 +104,32 @@ export interface GetDocumentTypesResponse extends PaginationResponse<DocumentTyp
 export interface BulkEditDocumentsResult {
     result: string;
 }
+export interface BulkEditParameters {
+    assign_custom_fields?: number[];
+    assign_custom_fields_values?: CustomFieldInstanceRequest[];
+    remove_custom_fields?: number[];
+    add_tags?: number[];
+    remove_tags?: number[];
+    degrees?: number;
+    pages?: string;
+    metadata_document_id?: number;
+    delete_originals?: boolean;
+    correspondent?: number;
+    document_type?: number;
+    storage_path?: number;
+    tag?: number;
+    permissions?: {
+        owner?: number | null;
+        set_permissions?: {
+            view: {
+                users: number[];
+                groups: number[];
+            };
+            change: {
+                users: number[];
+                groups: number[];
+            };
+        };
+        merge?: boolean;
+    };
+}

package/build/index.js

@@ -21,23 +21,26 @@ const express_1 = __importDefault(require("express"));
 const node_util_1 = require("node:util");
 const PaperlessAPI_1 = require("./api/PaperlessAPI");
 const correspondents_1 = require("./tools/correspondents");
+const customFields_1 = require("./tools/customFields");
 const documents_1 = require("./tools/documents");
 const documentTypes_1 = require("./tools/documentTypes");
 const tags_1 = require("./tools/tags");
-const { values: { baseUrl, token, http: useHttp, port }, } = (0, node_util_1.parseArgs)({
+const { values: { baseUrl, token, http: useHttp, port, publicUrl }, } = (0, node_util_1.parseArgs)({
     options: {
         baseUrl: { type: "string" },
         token: { type: "string" },
         http: { type: "boolean", default: false },
         port: { type: "string" },
+        publicUrl: { type: "string", default: "" },
     },
     allowPositionals: true,
 });
 const resolvedBaseUrl = baseUrl || process.env.PAPERLESS_URL;
 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 || !resolvedToken) {
-    console.error("Usage: paperless-mcp --baseUrl <url> --token <token> [--http] [--port <port>]");
+    console.error("Usage: paperless-mcp --baseUrl <url> --token <token> [--http] [--port <port>] [--publicUrl <url>]");
     console.error("Or set PAPERLESS_URL and PAPERLESS_API_KEY environment variables.");
     process.exit(1);
 }
@@ -45,11 +48,30 @@ function main() {
     return __awaiter(this, void 0, void 0, function* () {
         // Initialize API client and server once
         const api = new PaperlessAPI_1.PaperlessAPI(resolvedBaseUrl, resolvedToken);
-        const server = new mcp_js_1.McpServer({ name: "paperless-ngx", version: "1.0.0" });
+        const server = new mcp_js_1.McpServer({ name: "paperless-ngx", version: "1.0.0" }, {
+            instructions: `
+Paperless-NGX MCP Server Instructions
+
+⚠️ CRITICAL: Always differentiate between operations on specific documents vs operations on the entire system:
+
+- REMOVE operations (e.g., remove_tag in bulk_edit_documents): Affect only the specified documents, items remain in the system
+- DELETE operations (e.g., delete_tag, delete_correspondent): Permanently delete items from the entire system, affecting ALL documents that use them
+
+When a user asks to "remove" something, prefer operations that affect specific documents. Only use DELETE operations when explicitly asked to delete from the system.
+
+To view documents in your Paperless-NGX web interface, construct URLs using this pattern:
+${resolvedPublicUrl}/documents/{document_id}/
+
+Example: If your base URL is "http://localhost:8000", the web interface URL would be "http://localhost:8000/documents/123/" for document ID 123.
+
+The document tools return JSON data with document IDs that you can use to construct these URLs.
+      `,
+        });
         (0, documents_1.registerDocumentTools)(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);
         if (useHttp) {
             const app = (0, express_1.default)();
             app.use(express_1.default.json());
@@ -138,11 +160,11 @@ function main() {
             app.listen(resolvedPort, () => {
                 console.log(`MCP Stateless Streamable HTTP Server listening on port ${resolvedPort}`);
             });
+            // await new Promise((resolve) => setTimeout(resolve, 1000000));
         }
         else {
             const transport = new stdio_js_1.StdioServerTransport();
             yield server.connect(transport);
-            console.log("MCP server running with stdio transport");
         }
     });
 }

package/build/tools/correspondents.js

@@ -22,7 +22,7 @@ function registerCorrespondentTools(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.errorMiddleware)((args, extra) => __awaiter(this, void 0, void 0, function* () {
+    }, (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);
@@ -36,7 +36,7 @@ function registerCorrespondentTools(server, api) {
             ],
         };
     })));
-    server.tool("get_correspondent", { id: zod_1.z.number() }, (0, middlewares_1.errorMiddleware)((args, extra) => __awaiter(this, void 0, void 0, function* () {
+    server.tool("get_correspondent", { 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(`/correspondents/${args.id}/`);
@@ -50,7 +50,7 @@ function registerCorrespondentTools(server, api) {
         matching_algorithm: zod_1.z
             .enum(["any", "all", "exact", "regular expression", "fuzzy"])
             .optional(),
-    }, (0, middlewares_1.errorMiddleware)((args, extra) => __awaiter(this, void 0, void 0, function* () {
+    }, (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.createCorrespondent(args);
@@ -65,7 +65,7 @@ function registerCorrespondentTools(server, api) {
         matching_algorithm: zod_1.z
             .enum(["any", "all", "exact", "regular expression", "fuzzy"])
             .optional(),
-    }, (0, middlewares_1.errorMiddleware)((args, extra) => __awaiter(this, void 0, void 0, function* () {
+    }, (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(`/correspondents/${args.id}/`, {
@@ -76,9 +76,17 @@ function registerCorrespondentTools(server, api) {
             content: [{ type: "text", text: JSON.stringify(response) }],
         };
     })));
-    server.tool("delete_correspondent", { id: zod_1.z.number() }, (0, middlewares_1.errorMiddleware)((args, extra) => __awaiter(this, void 0, void 0, function* () {
+    server.tool("delete_correspondent", "⚠️ DESTRUCTIVE: Permanently delete a correspondent from the entire system. This will affect ALL documents that use this correspondent.", {
+        id: zod_1.z.number(),
+        confirm: zod_1.z
+            .boolean()
+            .describe("Must be true to confirm this destructive operation"),
+    }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
         if (!api)
             throw new Error("Please configure API connection first");
+        if (!args.confirm) {
+            throw new Error("Confirmation required for destructive operation. Set confirm: true to proceed.");
+        }
         yield api.request(`/correspondents/${args.id}/`, { method: "DELETE" });
         return {
             content: [
@@ -86,9 +94,13 @@ function registerCorrespondentTools(server, api) {
             ],
         };
     })));
-    server.tool("bulk_edit_correspondents", {
+    server.tool("bulk_edit_correspondents", "Bulk edit correspondents. ⚠️ WARNING: 'delete' operation permanently removes correspondents from the entire system.", {
         correspondent_ids: zod_1.z.array(zod_1.z.number()),
         operation: zod_1.z.enum(["set_permissions", "delete"]),
+        confirm: zod_1.z
+            .boolean()
+            .optional()
+            .describe("Must be true when operation is 'delete' to confirm destructive operation"),
         owner: zod_1.z.number().optional(),
         permissions: zod_1.z
             .object({
@@ -103,9 +115,12 @@ function registerCorrespondentTools(server, api) {
         })
             .optional(),
         merge: zod_1.z.boolean().optional(),
-    }, (0, middlewares_1.errorMiddleware)((args, extra) => __awaiter(this, void 0, void 0, function* () {
+    }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
         if (!api)
             throw new Error("Please configure API connection first");
+        if (args.operation === "delete" && !args.confirm) {
+            throw new Error("Confirmation required for destructive operation. Set confirm: true to proceed.");
+        }
         return api.bulkEditObjects(args.correspondent_ids, "correspondents", args.operation, args.operation === "set_permissions"
             ? {
                 owner: args.owner,

package/build/tools/customFields.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp";
+import { PaperlessAPI } from "../api/PaperlessAPI";
+export declare function registerCustomFieldTools(server: McpServer, api: PaperlessAPI): void;