bulk_edit_correspondents
Manage multiple correspondents in Paperless-NGX by setting permissions, assigning owners, or deleting them in bulk using the MCP server. Streamline document organization and access control.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| correspondent_ids | Yes | ||
| merge | No | ||
| operation | Yes | ||
| owner | No | ||
| permissions | No |
Implementation Reference
- src/tools/correspondents.ts:167-186 (handler)The tool handler logic, which performs input validation (API check, delete confirmation) and invokes the generic bulkEditObjects API method with appropriate parameters for correspondents.withErrorHandling(async (args, extra) => { 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, permissions: args.permissions, merge: args.merge, } : {} ); })
- src/tools/correspondents.ts:143-166 (schema)Zod input schema defining parameters for bulk editing correspondents: list of IDs, operation (set_permissions or delete), confirmation flag, owner ID, permissions object, and merge flag.{ correspondent_ids: z.array(z.number()), operation: z.enum(["set_permissions", "delete"]), confirm: z .boolean() .optional() .describe( "Must be true when operation is 'delete' to confirm destructive operation" ), owner: z.number().optional(), permissions: z .object({ view: z.object({ users: z.array(z.number()).optional(), groups: z.array(z.number()).optional(), }), change: z.object({ users: z.array(z.number()).optional(), groups: z.array(z.number()).optional(), }), }) .optional(), merge: z.boolean().optional(), },
- src/tools/correspondents.ts:140-187 (registration)Registration of the 'bulk_edit_correspondents' tool on the MCP server using server.tool(), including description, input schema, and handler function.server.tool( "bulk_edit_correspondents", "Bulk edit correspondents. ⚠️ WARNING: 'delete' operation permanently removes correspondents from the entire system.", { correspondent_ids: z.array(z.number()), operation: z.enum(["set_permissions", "delete"]), confirm: z .boolean() .optional() .describe( "Must be true when operation is 'delete' to confirm destructive operation" ), owner: z.number().optional(), permissions: z .object({ view: z.object({ users: z.array(z.number()).optional(), groups: z.array(z.number()).optional(), }), change: z.object({ users: z.array(z.number()).optional(), groups: z.array(z.number()).optional(), }), }) .optional(), merge: z.boolean().optional(), }, withErrorHandling(async (args, extra) => { 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, permissions: args.permissions, merge: args.merge, } : {} ); }) );
- src/api/PaperlessAPI.ts:304-314 (helper)Generic helper method in PaperlessAPI class that performs bulk edit operations on various object types (e.g., correspondents) by posting to the Paperless-ngx /bulk_edit_objects/ endpoint.async bulkEditObjects(objects, objectType, operation, parameters = {}) { return this.request("/bulk_edit_objects/", { method: "POST", body: JSON.stringify({ objects, object_type: objectType, operation, ...parameters, }), }); }
- src/index.ts:71-71 (registration)Top-level invocation of registerCorrespondentTools function, which registers the bulk_edit_correspondents tool (and other correspondent tools) on the MCP server.registerCorrespondentTools(server, api);