@baruchiro/paperless-mcp 0.0.3 → 0.2.0

package/README.md

@@ -206,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
@@ -232,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]
 })
 ```
 
@@ -252,14 +262,21 @@ Parameters:
 - name: Tag name
 - color (optional): Hex color code (e.g. "#ff0000")
 - match (optional): Text pattern to match
-- matching_algorithm (optional): One of "any", "all", "exact", "regular expression", "fuzzy"
+- matching_algorithm (optional): Number between 0 and 6:
+  0 - None
+  1 - Any word
+  2 - All words
+  3 - Exact match
+  4 - Regular expression
+  5 - Fuzzy word
+  6 - Automatic
 
 ```typescript
 create_tag({
   name: "Invoice",
   color: "#ff0000",
   match: "invoice",
-  matching_algorithm: "fuzzy"
+  matching_algorithm: 5
 })
 ```
 
@@ -278,13 +295,20 @@ Create a new correspondent.
 Parameters:
 - name: Correspondent name
 - match (optional): Text pattern to match
-- matching_algorithm (optional): One of "any", "all", "exact", "regular expression", "fuzzy"
+- matching_algorithm (optional): Number between 0 and 6:
+  0 - None
+  1 - Any word
+  2 - All words
+  3 - Exact match
+  4 - Regular expression
+  5 - Fuzzy word
+  6 - Automatic
 
 ```typescript
 create_correspondent({
   name: "ACME Corp",
   match: "ACME",
-  matching_algorithm: "fuzzy"
+  matching_algorithm: 5
 })
 ```
 
@@ -303,13 +327,99 @@ Create a new document type.
 Parameters:
 - name: Document type name
 - match (optional): Text pattern to match
-- matching_algorithm (optional): One of "any", "all", "exact", "regular expression", "fuzzy"
+- matching_algorithm (optional): Number between 0 and 6:
+  0 - None
+  1 - Any word
+  2 - All words
+  3 - Exact match
+  4 - Regular expression
+  5 - Fuzzy word
+  6 - Automatic
 
 ```typescript
 create_document_type({
   name: "Invoice",
   match: "invoice total amount due",
-  matching_algorithm: "any"
+  matching_algorithm: 1
+})
+```
+
+### 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"
 })
 ```
 
@@ -372,3 +482,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,20 +1,22 @@
-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>;
     createTag(data: Partial<Tag>): Promise<Tag>;
     updateTag(id: number, data: Partial<Tag>): Promise<Tag>;
     deleteTag(id: number): Promise<void>;
-    getCorrespondents(): Promise<GetCorrespondentsResponse>;
+    getCorrespondents(queryString?: string): Promise<GetCorrespondentsResponse>;
+    getCorrespondent(id: number): Promise<Correspondent>;
     createCorrespondent(data: Partial<Correspondent>): Promise<Correspondent>;
     updateCorrespondent(id: number, data: Partial<Correspondent>): Promise<Correspondent>;
     deleteCorrespondent(id: number): Promise<void>;
@@ -22,5 +24,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)}`);
@@ -163,9 +178,17 @@ class PaperlessAPI {
         });
     }
     // Correspondent operations
-    getCorrespondents() {
+    getCorrespondents(queryString) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const url = queryString
+                ? `/correspondents/?${queryString}`
+                : "/correspondents/";
+            return this.request(url);
+        });
+    }
+    getCorrespondent(id) {
         return __awaiter(this, void 0, void 0, function* () {
-            return this.request("/correspondents/");
+            return this.request(`/correspondents/${id}/`);
         });
     }
     createCorrespondent(data) {
@@ -220,6 +243,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,18 @@
+import { CallToolResult } from "@modelcontextprotocol/sdk/types";
+import { PaperlessAPI } from "./PaperlessAPI";
+import { Document, DocumentsResponse } from "./types";
+import { NamedItem } from "./utils";
+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

@@ -1,3 +1,14 @@
+export declare const MATCHING_ALGORITHM_OPTIONS: {
+    readonly 0: "None";
+    readonly 1: "Any word";
+    readonly 2: "All words";
+    readonly 3: "Exact match";
+    readonly 4: "Regular expression";
+    readonly 5: "Fuzzy word";
+    readonly 6: "Automatic";
+};
+export type MatchingAlgorithm = keyof typeof MATCHING_ALGORITHM_OPTIONS;
+export declare const MATCHING_ALGORITHM_DESCRIPTION: string;
 export interface Tag {
     id: number;
     slug: string;
@@ -5,13 +16,28 @@ export interface Tag {
     color: string;
     text_color: string;
     match: string;
-    matching_algorithm: number;
+    matching_algorithm: MatchingAlgorithm;
     is_insensitive: boolean;
     is_inbox_tag: boolean;
     document_count: number;
     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 +47,20 @@ export interface PaginationResponse<T> {
 }
 export interface GetTagsResponse extends PaginationResponse<Tag> {
 }
+export interface GetCustomFieldsResponse extends PaginationResponse<CustomField> {
+}
+export interface BasicUser {
+    id: number;
+    username: string;
+    first_name?: string;
+    last_name?: string;
+}
+export interface Note {
+    id: number;
+    note: string;
+    created: string;
+    user: BasicUser;
+}
 export interface DocumentsResponse extends PaginationResponse<Document> {
 }
 export interface Document {
@@ -42,8 +82,8 @@ export interface Document {
     owner: number | null;
     user_can_change: boolean;
     is_shared_by_requester: boolean;
-    notes: any[];
-    custom_fields: any[];
+    notes: Note[];
+    custom_fields: CustomFieldInstance[];
     page_count: number;
     mime_type: string;
     __search_hit__?: SearchHit;
@@ -59,12 +99,12 @@ export interface Correspondent {
     slug: string;
     name: string;
     match: string;
-    matching_algorithm: number;
+    matching_algorithm: MatchingAlgorithm;
     is_insensitive: boolean;
     document_count: number;
     last_correspondence: string;
     owner: number | null;
-    permissions: any;
+    permissions: Record<string, unknown>;
     user_can_change: boolean;
 }
 export interface GetCorrespondentsResponse extends PaginationResponse<Correspondent> {
@@ -74,12 +114,12 @@ export interface DocumentType {
     slug: string;
     name: string;
     match: string;
-    matching_algorithm: number;
+    matching_algorithm: MatchingAlgorithm;
     is_insensitive: boolean;
     document_count: number;
     last_correspondence: string;
     owner: number | null;
-    permissions: any;
+    permissions: Record<string, unknown>;
     user_can_change: boolean;
 }
 export interface GetDocumentTypesResponse extends PaginationResponse<DocumentType> {
@@ -87,3 +127,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/api/types.js

@@ -1,2 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.MATCHING_ALGORITHM_DESCRIPTION = exports.MATCHING_ALGORITHM_OPTIONS = void 0;
+exports.MATCHING_ALGORITHM_OPTIONS = {
+    0: "None",
+    1: "Any word",
+    2: "All words",
+    3: "Exact match",
+    4: "Regular expression",
+    5: "Fuzzy word",
+    6: "Automatic",
+};
+exports.MATCHING_ALGORITHM_DESCRIPTION = `Matching algorithm: ${Object.entries(exports.MATCHING_ALGORITHM_OPTIONS)
+    .map(([id, name]) => `${id}=${name}`)
+    .join(", ")}`;

package/build/api/utils.d.ts

@@ -1 +1,16 @@
+import { MatchingAlgorithm } from "./types";
 export declare const headersToObject: (headers: any) => Record<string, string>;
+export interface NamedItem {
+    id: number;
+    name: string;
+}
+export declare function enhanceMatchingAlgorithm<T extends {
+    matching_algorithm: MatchingAlgorithm;
+}>(obj: T): T & {
+    matching_algorithm: NamedItem;
+};
+export declare function enhanceMatchingAlgorithmArray<T extends {
+    matching_algorithm: MatchingAlgorithm;
+}>(objects: T[]): (T & {
+    matching_algorithm: NamedItem;
+})[];

package/build/api/utils.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.headersToObject = void 0;
+exports.enhanceMatchingAlgorithm = enhanceMatchingAlgorithm;
+exports.enhanceMatchingAlgorithmArray = enhanceMatchingAlgorithmArray;
+const types_1 = require("./types");
 const headersToObject = (headers) => {
     if (!headers)
         return {};
@@ -14,3 +17,13 @@ const headersToObject = (headers) => {
     return headers;
 };
 exports.headersToObject = headersToObject;
+function enhanceMatchingAlgorithm(obj) {
+    return Object.assign(Object.assign({}, obj), { matching_algorithm: {
+            id: obj.matching_algorithm,
+            name: types_1.MATCHING_ALGORITHM_OPTIONS[obj.matching_algorithm] ||
+                String(obj.matching_algorithm),
+        } });
+}
+function enhanceMatchingAlgorithmArray(objects) {
+    return objects.map((obj) => enhanceMatchingAlgorithm(obj));
+}