paperless-mcp

Implementation Reference

• src/tools/documents.ts:279-301 (handler)

  The handler function for the 'download_document' tool. It uses the PaperlessAPI to download the document and returns it as a base64-encoded resource with mimeType 'application/pdf'.

  withErrorHandling(async (args, extra) => {
    if (!api) throw new Error("Please configure API connection first");
    const response = await api.downloadDocument(args.id, args.original);
    const filename =
      (typeof response.headers.get === "function"
        ? response.headers.get("content-disposition")
        : response.headers["content-disposition"]
      )
        ?.split("filename=")[1]
        ?.replace(/"/g, "") || `document-${args.id}`;
    return {
      content: [
        {
          type: "resource",
          resource: {
            uri: filename,
            blob: Buffer.from(response.data).toString("base64"),
            mimeType: "application/pdf",
          },
        },
      ],
    };
  })

• src/tools/documents.ts:275-278 (schema)

  Input schema for the download_document tool using Zod: id (number, required), original (boolean, optional).

  {
    id: z.number(),
    original: z.boolean().optional(),
  },

• src/tools/documents.ts:273-302 (registration)

  Registration of the 'download_document' tool using server.tool() in the registerDocumentTools function.

  server.tool(
    "download_document",
    {
      id: z.number(),
      original: z.boolean().optional(),
    },
    withErrorHandling(async (args, extra) => {
      if (!api) throw new Error("Please configure API connection first");
      const response = await api.downloadDocument(args.id, args.original);
      const filename =
        (typeof response.headers.get === "function"
          ? response.headers.get("content-disposition")
          : response.headers["content-disposition"]
        )
          ?.split("filename=")[1]
          ?.replace(/"/g, "") || `document-${args.id}`;
      return {
        content: [
          {
            type: "resource",
            resource: {
              uri: filename,
              blob: Buffer.from(response.data).toString("base64"),
              mimeType: "application/pdf",
            },
          },
        ],
      };
    })
  );

• src/api/PaperlessAPI.ts:165-177 (helper)

  The PaperlessAPI.downloadDocument method that performs the actual HTTP GET request to the Paperless API download endpoint /api/documents/{id}/download/ with optional original file query param.

  async downloadDocument(id: number, asOriginal = false) {
    const query = asOriginal ? "?original=true" : "";
    const response = await axios.get(
      `${this.baseUrl}/api/documents/${id}/download/${query}`,
      {
        headers: {
          Authorization: `Token ${this.token}`,
        },
        responseType: "arraybuffer",
      }
    );
    return response;
  }