@baruchiro/paperless-mcp 0.5.1 → 2.0.0

package/README.md

@@ -67,6 +67,7 @@ Add these to your MCP config file:
 | `PAPERLESS_API_KEY` | Yes | — | API token from your Paperless-NGX profile |
 | `PAPERLESS_PUBLIC_URL` | No | `PAPERLESS_URL` | Public-facing URL for document links |
 | `PAPERLESS_API_VERSION` | No | `5` | Paperless-ngx REST API version. Use `10` for Paperless-ngx v3+. If you see HTTP 406 errors, set this to `10`. |
+| `PAPERLESS_MCP_UPLOAD_PATHS` | No | — | Colon-separated list of allowed directories for `file_path` uploads. **Recommended for security.** Example: `/var/uploads:/tmp/scans` |
 
 That's it! Now you can ask Claude to help you manage your Paperless-NGX documents.
 
@@ -86,11 +87,23 @@ Here are some things you can ask Claude to do:
 ### Document Operations
 
 #### list_documents
-Get a paginated list of all documents.
+Get a paginated list of documents with simple filters. Use this for straightforward listing tasks. For full-text queries, structured custom field filtering, or advanced Paperless filters, use `query_documents`.
 
 Parameters:
 - page (optional): Page number
 - page_size (optional): Number of documents per page
+- search (optional): Simple Paperless search term
+- correspondent (optional): Correspondent ID
+- document_type (optional): Document type ID
+- tag (optional): Tag ID
+- storage_path (optional): Storage path ID
+- created__date__gte (optional): Created date on or after YYYY-MM-DD
+- created__date__lte (optional): Created date on or before YYYY-MM-DD
+- ordering (optional): Paperless ordering field
+- archive_serial_number (optional): Archive serial number
+- archive_serial_number__isnull (optional): Whether the archive serial number is empty
+- custom_field_query (optional): Raw JSON-encoded Paperless custom field query string
+- custom_fields__icontains (optional): Case-insensitive substring match across custom field values
 
 ```typescript
 list_documents({
@@ -99,6 +112,70 @@ list_documents({
 })
 ```
 
+#### query_documents
+Canonical document query tool. Supports full-text querying, simple Paperless search, custom field filters, and documented `/api/documents/` Paperless query parameters.
+
+Parameters:
+- page (optional): Page number
+- page_size (optional): Number of documents per page
+- ordering (optional): Paperless ordering field
+- query (optional): Full-text query string
+- search (optional): Simple Paperless search term
+- more_like_id (optional): Find documents similar to this document ID
+- correspondent (optional): Correspondent ID
+- document_type (optional): Document type ID
+- tag (optional): Tag ID
+- storage_path (optional): Storage path ID
+- created__date__gte (optional): Created date on or after YYYY-MM-DD
+- created__date__lte (optional): Created date on or before YYYY-MM-DD
+- custom_field_query (optional): Structured Paperless custom field query using `[field_name_or_id, operator, value]` leaves or `["AND" | "OR", [clause1, clause2]]` groups
+- paperless_filters (optional): Additional documented `/api/documents/` Paperless query parameters, passed as key/value pairs
+
+```typescript
+// Full-text query
+query_documents({
+  query: "invoice 2024"
+})
+
+// Simple search term
+query_documents({
+  search: "acme"
+})
+
+// Custom field exact match
+query_documents({
+  custom_field_query: ["Invoice Number", "exact", "12345"]
+})
+
+// Custom field empty
+query_documents({
+  custom_field_query: ["OR", [
+    ["Invoice Number", "isnull", true],
+    ["Invoice Number", "exact", ""]
+  ]]
+})
+
+// Custom field missing
+query_documents({
+  custom_field_query: ["Invoice Number", "exists", false]
+})
+
+// Combined filters
+query_documents({
+  query: "invoice",
+  tag: 5,
+  created__date__gte: "2024-01-01",
+  custom_field_query: ["Invoice Number", "exists", true]
+})
+
+// One documented Paperless filter that is not a first-class argument
+query_documents({
+  paperless_filters: {
+    id__in: [101, 202, 303]
+  }
+})
+```
+
 #### get_document
 Get a specific document by ID.
 
@@ -112,7 +189,7 @@ get_document({
 ```
 
 #### search_documents
-Full-text search across documents.
+Deprecated compatibility wrapper for full-text search. Prefer `query_documents({ query: ... })` for new integrations.
 
 Parameters:
 - query: Search query string
@@ -244,9 +321,17 @@ bulk_edit_documents({
 #### post_document
 Upload a new document to Paperless-NGX.
 
+**Two upload modes:**
+
+1. **Base64 mode** (traditional): Provide `file` (base64-encoded content) + `filename`
+2. **Filesystem mode** (efficient): Provide `file_path` (absolute path on server)
+
+**Security Note:** When using `file_path`, set the `PAPERLESS_MCP_UPLOAD_PATHS` environment variable (colon-separated list of allowed directories) to restrict uploads to specific locations. Without this, any file on the server's filesystem could be uploaded.
+
 Parameters:
-- file: Base64 encoded file content
-- filename: Name of the file
+- file (optional): Base64 encoded file content. Either `file` or `file_path` required.
+- file_path (optional): Absolute path to file on server's filesystem. Either `file` or `file_path` required.
+- filename (optional): Name of the file. Required with `file`, optional with `file_path` (derives from path).
 - title (optional): Title for the document
 - created (optional): DateTime when the document was created (e.g. "2024-01-19" or "2024-01-19 06:15:00+02:00")
 - correspondent (optional): ID of a correspondent
@@ -256,7 +341,10 @@ Parameters:
 - archive_serial_number (optional): Archive serial number
 - custom_fields (optional): Array of custom field IDs
 
+**File size limit:** 100MB for both modes
+
 ```typescript
+// Base64 mode (traditional)
 post_document({
   file: "base64_encoded_content",
   filename: "invoice.pdf",
@@ -268,6 +356,59 @@ post_document({
   archive_serial_number: "2024-001",
   custom_fields: [1, 2]
 })
+
+// Filesystem mode (more efficient for large files)
+post_document({
+  file_path: "/var/uploads/invoice.pdf",
+  title: "January Invoice",
+  correspondent: 1,
+  document_type: 2,
+  tags: [1, 3]
+})
+```
+
+### Document Notes
+
+#### list_document_notes
+List all notes attached to a document.
+
+Parameters:
+- id: Document ID
+
+```typescript
+list_document_notes({
+  id: 123
+})
+```
+
+#### create_document_note
+Add a note to a document. Returns the document's full list of notes.
+
+Parameters:
+- id: Document ID
+- note: The note text to add
+
+```typescript
+create_document_note({
+  id: 123,
+  note: "Invoice paid on 2026-06-30 from Commerzbank account."
+})
+```
+
+#### delete_document_note
+⚠️ Delete a single note from a document by its note ID. This operation is irreversible.
+
+Parameters:
+- id: Document ID
+- note_id: The ID of the note to delete
+- confirm: Must be `true` to confirm this destructive operation
+
+```typescript
+delete_document_note({
+  id: 123,
+  note_id: 5,
+  confirm: true
+})
 ```
 
 ### Tag Operations
@@ -447,6 +588,133 @@ bulk_edit_custom_fields({
 })
 ```
 
+### Mail Operations
+
+Tools for managing Paperless mail accounts and the mail rules that drive
+automatic email ingestion. Account passwords/tokens are never exposed: they are
+redacted from every tool response.
+
+#### list_mail_accounts
+List mail accounts so you can pick the account ID needed when creating a mail
+rule. Passwords are redacted.
+
+Parameters:
+- page (optional): Page number
+- page_size (optional): Number of results per page
+
+```typescript
+list_mail_accounts()
+```
+
+#### get_mail_account
+Get a single mail account by ID. Password/token fields are redacted.
+
+Parameters:
+- id: Mail account ID
+
+```typescript
+get_mail_account({
+  id: 1
+})
+```
+
+#### process_mail_account
+Manually trigger Paperless mail processing for one account. This can consume
+matching mails according to the account's enabled mail rules.
+
+Parameters:
+- id: Mail account ID
+
+```typescript
+process_mail_account({
+  id: 1
+})
+```
+
+#### list_mail_rules
+List mail rules with optional pagination.
+
+Parameters:
+- page (optional): Page number
+- page_size (optional): Number of results per page
+
+```typescript
+list_mail_rules()
+```
+
+#### get_mail_rule
+Get a single mail rule by ID.
+
+Parameters:
+- id: Mail rule ID
+
+```typescript
+get_mail_rule({
+  id: 1
+})
+```
+
+#### create_mail_rule
+Create a mail rule. Use `list_mail_accounts` first to choose the account.
+
+Required parameters:
+- name: Rule name
+- account: Mail account ID
+- folder: IMAP folder to scan (e.g. "INBOX")
+
+Common optional parameters:
+- enabled (default true): Whether the rule is active
+- filter_from / filter_to / filter_subject / filter_body: Match incoming mail
+- maximum_age: Only process mail newer than this many days
+- action: 1=Delete, 2=Move to folder, 3=Mark as read, 4=Flag, 5=Tag
+- action_parameter: Target folder/tag for the chosen action
+- assign_title_from: 1=Subject, 2=Attachment filename, 3=Do not assign
+- assign_tags / assign_correspondent / assign_document_type: Metadata to apply
+- assign_correspondent_from: 1=None, 2=Mail address, 3=Sender name, 4=Use assign_correspondent
+- attachment_type: 1=Attachments only, 2=All files incl. inline
+- consumption_scope: 1=Attachments only, 2=Full mail as .eml, 3=Both
+- pdf_layout: 0=System default, 1=Text+HTML, 2=HTML+text, 3=HTML only, 4=Text only
+
+```typescript
+create_mail_rule({
+  name: "Invoices",
+  account: 1,
+  folder: "INBOX",
+  filter_subject: "invoice",
+  action: 3,
+  attachment_type: 1
+})
+```
+
+#### update_mail_rule
+Patch an existing mail rule. Only the fields you supply are changed.
+
+Parameters:
+- id: Mail rule ID
+- ...any of the `create_mail_rule` fields to update
+
+```typescript
+update_mail_rule({
+  id: 1,
+  enabled: false
+})
+```
+
+#### delete_mail_rule
+Delete a mail rule. Requires an explicit confirmation flag. This changes future
+mail ingestion behavior but does not delete any existing documents.
+
+Parameters:
+- id: Mail rule ID
+- confirm: Must be `true` to confirm deletion
+
+```typescript
+delete_mail_rule({
+  id: 1,
+  confirm: true
+})
+```
+
 ## Error Handling
 
 The server will show clear error messages if:
@@ -455,6 +723,52 @@ The server will show clear error messages if:
 - The requested operation fails
 - The provided parameters are invalid
 
+## Testing
+
+### Unit tests
+
+Run the unit test suite (no external dependencies required):
+
+```bash
+npm test
+```
+
+### E2E tests
+
+The E2E suite boots an empty Paperless-ngx instance, runs the compiled MCP server, and drives a deterministic serial scenario through `tools/call` requests — creating a tag, correspondent, and document type, uploading a PDF, then exercising list / get / search / download / thumbnail / bulk-edit on the same document. No LLM and no Paperless REST client outside MCP.
+
+**Prerequisites:** Docker, Docker Compose, and `jq`.
+
+```bash
+# 1. Build the MCP server
+npm run build
+
+# 2. Start Paperless-ngx
+docker compose -f docker-compose.e2e.yml up -d
+
+# 3. Wait for Paperless to be ready, then get a token
+TOKEN=$(curl -s -X POST http://localhost:8000/api/token/ \
+  -H 'Content-Type: application/json' \
+  -d '{"username":"admin","password":"admin123"}' | jq -r '.token')
+
+# 4. Start the MCP server
+node build/index.js --http --port 3001 \
+  --baseUrl http://localhost:8000 --token "$TOKEN" &
+MCP_PID=$!
+
+# 5. Run the E2E tests
+MCP_URL=http://localhost:3001/mcp \
+PAPERLESS_URL=http://localhost:8000 \
+PAPERLESS_TOKEN="$TOKEN" \
+npm run test:e2e
+
+# 6. Cleanup
+kill "$MCP_PID"
+docker compose -f docker-compose.e2e.yml down -v
+```
+
+E2E tests also run automatically in CI on every pull request and push to `main`, covering both the `build/index.js` CLI and the published Docker image.
+
 ## Development
 
 Want to contribute or modify the server? Here's what you need to know:
@@ -505,19 +819,28 @@ npm run start -- <baseUrl> <token> --http --port 3000
 
 #### Per-request API token (HTTP/Docker mode)
 
-In HTTP mode, clients can supply their own Paperless-NGX API token via the standard `Authorization` header instead of (or in addition to) the server-configured `PAPERLESS_API_KEY`. The client-supplied token takes precedence.
+In HTTP mode, clients authenticate by supplying a Paperless-NGX API token via the standard `Authorization` header:
 
 ```
 Authorization: Bearer <paperless-ngx-api-token>
 ```
 
-| Scenario | Token used |
-|---|---|
-| Client sends `Authorization: Bearer <tok>` | `<tok>` (client-supplied, takes precedence) |
-| No header, `PAPERLESS_API_KEY` env var set | `PAPERLESS_API_KEY` from env |
-| No header, no env var | `401 Unauthorized` |
+The token is passed straight through to Paperless-NGX, so each client's own Paperless permissions are enforced end-to-end. This lets a single server instance serve multiple users, each with their own token. The same behaviour applies to both `/mcp` and `/sse` endpoints.
+
+> **⚠️ Breaking change in v2.0.0 — HTTP mode is now authenticated by default.**
+>
+> Previously, a request with no `Authorization` header silently fell back to the server-configured `PAPERLESS_API_KEY`, which left the HTTP endpoint open to anyone who could reach the port. As of v2.0.0, requests without a `Bearer` token are rejected with `401 Unauthorized`. The server token is **never** used for unauthenticated requests unless you explicitly opt in with `--no-auth`.
+
+| Scenario | `--no-auth` off (default) | `--no-auth` on |
+|---|---|---|
+| Client sends `Authorization: Bearer <tok>` | `<tok>` (client-supplied) | `<tok>` (client-supplied) |
+| No header, `PAPERLESS_API_KEY` / `--token` set | `401 Unauthorized` | server token |
+| No header, no server token | `401 Unauthorized` | `401 Unauthorized` |
+
+**Migrating from v1.x:** if you relied on the old fallback (a single shared `PAPERLESS_API_KEY` with clients that don't send a token), you have two options:
 
-This allows a single server instance to serve multiple users, each authenticating with their own Paperless-NGX token. The same behaviour applies to both `/mcp` and `/sse` endpoints.
+1. **Recommended:** have each client send `Authorization: Bearer <paperless-token>`.
+2. **Restore the old behaviour** (trusted/local networks only): start the server with the `--no-auth` flag, e.g. append it to the Docker `command`/args or your CLI invocation. This requires a server token (`PAPERLESS_API_KEY` or `--token`) to be configured.
 
 <details>
 <summary>Docker Deployment</summary>

package/build/api/PaperlessAPI.d.ts

@@ -1,5 +1,5 @@
 import { AxiosResponse } from "axios";
-import { BulkEditDocumentsResult, BulkEditParameters, Correspondent, CustomField, Document, DocumentsResponse, DocumentType, GetCorrespondentsResponse, GetCustomFieldsResponse, GetDocumentTypesResponse, GetTagsResponse, Tag } from "./types";
+import { BulkEditDocumentsResult, BulkEditParameters, Correspondent, CustomField, Document, DocumentsResponse, DocumentType, GetCorrespondentsResponse, GetCustomFieldsResponse, GetDocumentTypesResponse, GetMailAccountsResponse, GetMailRulesResponse, MailAccount, MailRule, GetTagsResponse, Note, Tag } from "./types";
 export declare class PaperlessAPI {
     private readonly baseUrl;
     private readonly token;
@@ -11,9 +11,28 @@ export declare class PaperlessAPI {
     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<AxiosResponse<ArrayBuffer>>;
     getThumbnail(id: number): Promise<AxiosResponse<ArrayBuffer>>;
+    /**
+     * Retrieve all notes attached to a document.
+     * @param documentId - The document ID.
+     * @returns The document's notes.
+     */
+    getDocumentNotes(documentId: number): Promise<Note[]>;
+    /**
+     * Create a note on a document.
+     * @param documentId - The document ID.
+     * @param note - The note text to add.
+     * @returns The document's full notes list after creation.
+     */
+    createDocumentNote(documentId: number, note: string): Promise<Note[]>;
+    /**
+     * Delete a note from a document by its note ID.
+     * @param documentId - The document ID.
+     * @param noteId - The ID of the note to delete.
+     * @returns The document's remaining notes after deletion.
+     */
+    deleteDocumentNote(documentId: number, noteId: number): Promise<Note[]>;
     getTags(): Promise<GetTagsResponse>;
     createTag(data: Partial<Tag>): Promise<Tag>;
     updateTag(id: number, data: Partial<Tag>): Promise<Tag>;
@@ -27,6 +46,14 @@ export declare class PaperlessAPI {
     createDocumentType(data: Partial<DocumentType>): Promise<DocumentType>;
     updateDocumentType(id: number, data: Partial<DocumentType>): Promise<DocumentType>;
     deleteDocumentType(id: number): Promise<void>;
+    getMailAccounts(queryString?: string): Promise<GetMailAccountsResponse>;
+    getMailAccount(id: number): Promise<MailAccount>;
+    processMailAccount(id: number): Promise<void>;
+    getMailRules(queryString?: string): Promise<GetMailRulesResponse>;
+    getMailRule(id: number): Promise<MailRule>;
+    createMailRule(data: Partial<MailRule>): Promise<MailRule>;
+    updateMailRule(id: number, data: Partial<MailRule>): Promise<MailRule>;
+    deleteMailRule(id: number): Promise<void>;
     getCustomFields(): Promise<GetCustomFieldsResponse>;
     getCustomField(id: number): Promise<CustomField>;
     createCustomField(data: Partial<CustomField>): Promise<CustomField>;

package/build/api/PaperlessAPI.js

@@ -42,7 +42,7 @@ class PaperlessAPI {
                     console.error({
                         error: "Error executing request",
                         url,
-                        options,
+                        method: options.method || "GET",
                         status: response.status,
                         response: body,
                     });
@@ -63,7 +63,7 @@ class PaperlessAPI {
                     error: "Error executing request",
                     message: error instanceof Error ? error.message : String(error),
                     url,
-                    options,
+                    method: options.method || "GET",
                     responseData: axios_1.default.isAxiosError(error) ? (_b = error.response) === null || _b === void 0 ? void 0 : _b.data : undefined,
                     status: axios_1.default.isAxiosError(error) ? (_c = error.response) === null || _c === void 0 ? void 0 : _c.status : undefined,
                 });
@@ -145,12 +145,6 @@ class PaperlessAPI {
             });
         });
     }
-    searchDocuments(query) {
-        return __awaiter(this, void 0, void 0, function* () {
-            const response = yield this.request(`/documents/?query=${encodeURIComponent(query)}`);
-            return response;
-        });
-    }
     downloadDocument(id_1) {
         return __awaiter(this, arguments, void 0, function* (id, asOriginal = false) {
             const query = asOriginal ? "?original=true" : "";
@@ -174,6 +168,44 @@ class PaperlessAPI {
             return response;
         });
     }
+    // Document note operations
+    /**
+     * Retrieve all notes attached to a document.
+     * @param documentId - The document ID.
+     * @returns The document's notes.
+     */
+    getDocumentNotes(documentId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.request(`/documents/${documentId}/notes/`);
+        });
+    }
+    /**
+     * Create a note on a document.
+     * @param documentId - The document ID.
+     * @param note - The note text to add.
+     * @returns The document's full notes list after creation.
+     */
+    createDocumentNote(documentId, note) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.request(`/documents/${documentId}/notes/`, {
+                method: "POST",
+                body: JSON.stringify({ note }),
+            });
+        });
+    }
+    /**
+     * Delete a note from a document by its note ID.
+     * @param documentId - The document ID.
+     * @param noteId - The ID of the note to delete.
+     * @returns The document's remaining notes after deletion.
+     */
+    deleteDocumentNote(documentId, noteId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.request(`/documents/${documentId}/notes/?id=${noteId}`, {
+                method: "DELETE",
+            });
+        });
+    }
     // Tag operations
     getTags() {
         return __awaiter(this, void 0, void 0, function* () {
@@ -269,6 +301,63 @@ class PaperlessAPI {
             });
         });
     }
+    // Mail account operations
+    getMailAccounts(queryString) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const url = queryString
+                ? `/mail_accounts/?${queryString}`
+                : "/mail_accounts/";
+            return this.request(url);
+        });
+    }
+    getMailAccount(id) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.request(`/mail_accounts/${id}/`);
+        });
+    }
+    processMailAccount(id) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.request(`/mail_accounts/${id}/process/`, {
+                method: "POST",
+                body: JSON.stringify({}),
+            });
+        });
+    }
+    // Mail rule operations
+    getMailRules(queryString) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const url = queryString ? `/mail_rules/?${queryString}` : "/mail_rules/";
+            return this.request(url);
+        });
+    }
+    getMailRule(id) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.request(`/mail_rules/${id}/`);
+        });
+    }
+    createMailRule(data) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.request("/mail_rules/", {
+                method: "POST",
+                body: JSON.stringify(data),
+            });
+        });
+    }
+    updateMailRule(id, data) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.request(`/mail_rules/${id}/`, {
+                method: "PATCH",
+                body: JSON.stringify(data),
+            });
+        });
+    }
+    deleteMailRule(id) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.request(`/mail_rules/${id}/`, {
+                method: "DELETE",
+            });
+        });
+    }
     // Custom field operations
     getCustomFields() {
         return __awaiter(this, void 0, void 0, function* () {

package/build/api/types.d.ts

@@ -125,6 +125,53 @@ export interface DocumentType {
 }
 export interface GetDocumentTypesResponse extends PaginationResponse<DocumentType> {
 }
+export interface MailAccount {
+    id: number;
+    name: string;
+    imap_server: string;
+    imap_port: number | null;
+    imap_security: number;
+    username: string;
+    password?: string;
+    character_set: string;
+    is_token: boolean;
+    owner: number | null;
+    user_can_change: boolean;
+    account_type: number;
+    expiration: string | null;
+}
+export interface GetMailAccountsResponse extends PaginationResponse<MailAccount> {
+}
+export interface MailRule {
+    id: number;
+    name: string;
+    account: number;
+    enabled: boolean;
+    folder: string;
+    filter_from: string | null;
+    filter_to: string | null;
+    filter_subject: string | null;
+    filter_body: string | null;
+    filter_attachment_filename_include: string | null;
+    filter_attachment_filename_exclude: string | null;
+    maximum_age: number;
+    action: number;
+    action_parameter: string | null;
+    assign_title_from: number;
+    assign_tags: Array<number | null>;
+    assign_correspondent_from: number;
+    assign_correspondent: number | null;
+    assign_document_type: number | null;
+    assign_owner_from_rule: boolean;
+    order: number;
+    attachment_type: number;
+    consumption_scope: number;
+    pdf_layout: number;
+    owner: number | null;
+    user_can_change: boolean;
+}
+export interface GetMailRulesResponse extends PaginationResponse<MailRule> {
+}
 export interface BulkEditDocumentsResult {
     result: string;
 }