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);
```

paperless-mcp