@orellbuehler/paperless-mcp 1.0.1 → 1.1.0

package/README.md

@@ -96,7 +96,7 @@ This fetches `GET /api/schema/` and overwrites `paperless-openapi.yaml`. Run it
 | Search              | `search_documents`, `search_autocomplete`                                                                                       |
 | Documents           | `list_documents`, `get_document`, `get_documents`, `download_document`, `update_document`, `delete_document`, `upload_document` |
 | Document details    | `get_document_metadata`, `get_document_suggestions`, `get_document_notes`, `add_document_note`, `delete_document_note`          |
-| Bulk operations     | `bulk_edit_documents`, `get_next_asn`                                                                                           |
+| Bulk operations     | `bulk_edit_documents`, `bulk_set_object_permissions`, `get_next_asn`                                                            |
 | Correspondents      | `list_correspondents`, `get_correspondent`, `create_correspondent`, `update_correspondent`, `delete_correspondent`              |
 | Document types      | `list_document_types`, `get_document_type`, `create_document_type`, `update_document_type`, `delete_document_type`              |
 | Tags                | `list_tags`, `get_tag`, `create_tag`, `update_tag`, `delete_tag`                                                                |
@@ -111,6 +111,8 @@ This fetches `GET /api/schema/` and overwrites `paperless-openapi.yaml`. Run it
 > **Note:** `list_documents` and `search_documents` return document metadata only (no OCR text) to keep responses small. Use `get_document` (single) or `get_documents` (batch) to retrieve full content.
 >
 > Saved views, users/groups, and workflows support read + create + update only — no delete tools (use the Paperless web UI to delete). User management covers accounts and group membership; it does not set per-document permissions. Notes support add and delete only (no edit), so there is no note-editing tool.
+>
+> The `update_*` tools for tags, correspondents, document types, storage paths, saved views, and custom fields accept `owner` and `set_permissions` (`{ view, change }` → `{ users, groups }`) to share objects. `bulk_set_object_permissions` sets owner/permissions on many tags, correspondents, document types, or storage paths in one call (saved views and custom fields are not supported by the bulk endpoint — share those individually).
 
 ### Extended Tools
 

package/dist/paperless/format.js

@@ -6,10 +6,7 @@ export function buildQS(params) {
         if (Array.isArray(v)) {
             if (v.length === 0)
                 continue;
-            if (k === "id__in")
-                sp.set(k, v.join(","));
-            else
-                v.forEach((item) => sp.append(k, String(item)));
+            sp.set(k, v.join(","));
         }
         else {
             sp.set(k, String(v));

package/dist/tools/core.js

@@ -1,6 +1,22 @@
 import { z } from "zod";
 import { readFile } from "node:fs/promises";
 import { buildQS, ok, err, summarizeDocs } from "../paperless/format.js";
+const permissionGrant = z.object({
+    users: z.array(z.number()).optional().describe("User IDs"),
+    groups: z.array(z.number()).optional().describe("Group IDs"),
+});
+const permissionMap = z.object({
+    view: permissionGrant.optional(),
+    change: permissionGrant.optional(),
+});
+const ownerField = z
+    .number()
+    .nullable()
+    .optional()
+    .describe("Owner user ID, or null to make it unowned (visible to everyone)");
+const setPermissionsField = permissionMap
+    .optional()
+    .describe("Grant view (read) and change (edit) access to users and groups");
 export function registerCoreTools(server, client) {
     // --- System ---
     server.tool("get_status", "Get Paperless-ngx server status", {}, async () => {
@@ -243,6 +259,37 @@ export function registerCoreTools(server, client) {
             return err(e);
         }
     });
+    server.tool("bulk_set_object_permissions", "Set owner and/or view/change permissions on many tags, correspondents, document types or storage paths at once (e.g. share a whole taxonomy with a household group). Saved views and custom fields are not supported here — update those individually with set_permissions.", {
+        object_type: z.enum(["tags", "correspondents", "document_types", "storage_paths"]),
+        objects: z.array(z.number()).describe("IDs of the objects to update"),
+        owner: ownerField,
+        permissions: setPermissionsField,
+        merge: z
+            .boolean()
+            .optional()
+            .describe("Merge with existing permissions instead of replacing them (default false)"),
+    }, async ({ object_type, objects, owner, permissions, merge }) => {
+        try {
+            const body = {
+                objects,
+                object_type,
+                operation: "set_permissions",
+            };
+            if (owner !== undefined)
+                body.owner = owner;
+            if (permissions !== undefined)
+                body.permissions = permissions;
+            if (merge !== undefined)
+                body.merge = merge;
+            return ok(await client.fetch("/api/bulk_edit_objects/", {
+                method: "POST",
+                body: JSON.stringify(body),
+            }));
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
     server.tool("get_next_asn", "Get the next available archive serial number", {}, async () => {
         try {
             return ok(await client.fetch("/api/documents/next_asn/"));
@@ -301,6 +348,8 @@ export function registerCoreTools(server, client) {
             .optional()
             .describe("1=any, 2=all, 3=literal, 4=regex, 5=fuzzy, 6=auto"),
         is_insensitive: z.boolean().optional(),
+        owner: ownerField,
+        set_permissions: setPermissionsField,
     }, async ({ id, ...body }) => {
         try {
             return ok(await client.fetch(`/api/correspondents/${id}/`, {
@@ -370,6 +419,8 @@ export function registerCoreTools(server, client) {
             .optional()
             .describe("1=any, 2=all, 3=literal, 4=regex, 5=fuzzy, 6=auto"),
         is_insensitive: z.boolean().optional(),
+        owner: ownerField,
+        set_permissions: setPermissionsField,
     }, async ({ id, ...body }) => {
         try {
             return ok(await client.fetch(`/api/document_types/${id}/`, {
@@ -444,6 +495,8 @@ export function registerCoreTools(server, client) {
             .optional()
             .describe("1=any, 2=all, 3=literal, 4=regex, 5=fuzzy, 6=auto"),
         is_insensitive: z.boolean().optional(),
+        owner: ownerField,
+        set_permissions: setPermissionsField,
     }, async ({ id, ...body }) => {
         try {
             return ok(await client.fetch(`/api/tags/${id}/`, {
@@ -513,6 +566,8 @@ export function registerCoreTools(server, client) {
         sort_field: z.string().optional(),
         sort_reverse: z.boolean().optional(),
         page_size: z.number().optional(),
+        owner: ownerField,
+        set_permissions: setPermissionsField,
     }, async ({ id, ...body }) => {
         try {
             return ok(await client.fetch(`/api/saved_views/${id}/`, {
@@ -575,6 +630,8 @@ export function registerCoreTools(server, client) {
             .optional()
             .describe("1=any, 2=all, 3=literal, 4=regex, 5=fuzzy, 6=auto"),
         is_insensitive: z.boolean().optional(),
+        owner: ownerField,
+        set_permissions: setPermissionsField,
     }, async ({ id, ...body }) => {
         try {
             return ok(await client.fetch(`/api/storage_paths/${id}/`, {
@@ -640,6 +697,8 @@ export function registerCoreTools(server, client) {
         id: z.number(),
         name: z.string().optional(),
         extra_data: z.record(z.unknown()).optional(),
+        owner: ownerField,
+        set_permissions: setPermissionsField,
     }, async ({ id, ...body }) => {
         try {
             return ok(await client.fetch(`/api/custom_fields/${id}/`, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orellbuehler/paperless-mcp",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Model Context Protocol server for Paperless-ngx: documents, organization, saved views, users, workflows, and optional semantic search.",
   "type": "module",
   "bin": {