paperless-mcp

Implementation Reference

• src/tools/tags.ts:113-139 (registration)

  Full registration of the 'delete_tag' tool, including name, description, input schema (id and confirm), and handler function that checks confirmation and calls api.deleteTag

  server.tool(
    "delete_tag",
    "⚠️ DESTRUCTIVE: Permanently delete a tag from the entire system. This will remove the tag from ALL documents that use it. Use with extreme caution.",
    {
      id: z.number(),
      confirm: z
        .boolean()
        .describe("Must be true to confirm this destructive operation"),
    },
    withErrorHandling(async (args, extra) => {
      if (!api) throw new Error("Please configure API connection first");
      if (!args.confirm) {
        throw new Error(
          "Confirmation required for destructive operation. Set confirm: true to proceed."
        );
      }
      await api.deleteTag(args.id);
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify({ status: "deleted" }),
          },
        ],
      };
    })
  );

• src/tools/tags.ts:122-138 (handler)

  Executes the core logic: validates API connection and confirmation flag, deletes the tag via API, returns success status

  withErrorHandling(async (args, extra) => {
    if (!api) throw new Error("Please configure API connection first");
    if (!args.confirm) {
      throw new Error(
        "Confirmation required for destructive operation. Set confirm: true to proceed."
      );
    }
    await api.deleteTag(args.id);
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify({ status: "deleted" }),
        },
      ],
    };
  })

• src/tools/tags.ts:116-121 (schema)

  Input schema using Zod: requires id (number) and confirm (boolean, must be true)

  {
    id: z.number(),
    confirm: z
      .boolean()
      .describe("Must be true to confirm this destructive operation"),
  },

• src/api/PaperlessAPI.ts:198-202 (helper)

  Thin wrapper in PaperlessAPI client that sends DELETE request to /tags/{id}/

  async deleteTag(id: number): Promise<void> {
    return this.request<void>(`/tags/${id}/`, {
      method: "DELETE",
    });
  }

• src/index.ts:70-70 (registration)

  Top-level call to register all tag tools, including delete_tag, on the MCP server

  registerTagTools(server, api);