@baruchiro/paperless-mcp
Version:
Model Context Protocol (MCP) server for interacting with Paperless-NGX document management system. Enables AI assistants to manage documents, tags, correspondents, and document types through the Paperless-NGX API.
406 lines (405 loc) • 16.2 kB
JavaScript
;
var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
return new (P || (P = Promise))(function (resolve, reject) {
function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
step((generator = generator.apply(thisArg, _arguments || [])).next());
});
};
var __importDefault = (this && this.__importDefault) || function (mod) {
return (mod && mod.__esModule) ? mod : { "default": mod };
};
Object.defineProperty(exports, "__esModule", { value: true });
exports.PaperlessAPI = void 0;
const axios_1 = __importDefault(require("axios"));
const form_data_1 = __importDefault(require("form-data"));
const utils_1 = require("./utils");
class PaperlessAPI {
constructor(baseUrl, token) {
this.baseUrl = baseUrl;
this.token = token;
this.baseUrl = baseUrl;
this.token = token;
this.apiVersion = process.env.PAPERLESS_API_VERSION || "5";
}
request(path_1) {
return __awaiter(this, arguments, void 0, function* (path, options = {}) {
var _a, _b, _c;
const url = `${this.baseUrl}/api${path}`;
const isJson = !options.body || typeof options.body === "string";
const mergedHeaders = Object.assign(Object.assign({ Authorization: `Token ${this.token}`, Accept: `application/json; version=${this.apiVersion}`, "Accept-Language": "en-US,en;q=0.9" }, (isJson ? { "Content-Type": "application/json" } : {})), (0, utils_1.headersToObject)(options.headers));
try {
const response = yield (0, axios_1.default)({
url,
method: options.method || "GET",
headers: mergedHeaders,
data: options.body,
});
const body = response.data;
if (response.status < 200 || response.status >= 300) {
console.error({
error: "Error executing request",
url,
method: options.method || "GET",
status: response.status,
response: body,
});
const errorMessage = (body === null || body === void 0 ? void 0 : body.detail) ||
(body === null || body === void 0 ? void 0 : body.error) ||
(body === null || body === void 0 ? void 0 : body.message) ||
`HTTP error! status: ${response.status}`;
throw new Error(String(errorMessage));
}
return body;
}
catch (error) {
if (axios_1.default.isAxiosError(error) && ((_a = error.response) === null || _a === void 0 ? void 0 : _a.status) === 406) {
throw new Error(`HTTP 406: Paperless-ngx rejected API version ${this.apiVersion}. ` +
`Set the PAPERLESS_API_VERSION environment variable to match your server's API version (e.g., "10" for Paperless-ngx v3+).`);
}
console.error({
error: "Error executing request",
message: error instanceof Error ? error.message : String(error),
url,
method: options.method || "GET",
responseData: axios_1.default.isAxiosError(error) ? (_b = error.response) === null || _b === void 0 ? void 0 : _b.data : undefined,
status: axios_1.default.isAxiosError(error) ? (_c = error.response) === null || _c === void 0 ? void 0 : _c.status : undefined,
});
throw error;
}
});
}
// Document operations
bulkEditDocuments(documents_1, method_1) {
return __awaiter(this, arguments, void 0, function* (documents, method, parameters = {}) {
return this.request("/documents/bulk_edit/", {
method: "POST",
body: JSON.stringify({
documents,
method,
parameters,
}),
});
});
}
postDocument(document_1, filename_1) {
return __awaiter(this, arguments, void 0, function* (document, filename, metadata = {}) {
var _a;
const formData = new form_data_1.default();
formData.append("document", document, { filename });
// Add optional metadata fields
if (metadata.title)
formData.append("title", metadata.title);
if (metadata.created)
formData.append("created", metadata.created);
if (metadata.correspondent)
formData.append("correspondent", metadata.correspondent);
if (metadata.document_type)
formData.append("document_type", metadata.document_type);
if (metadata.storage_path)
formData.append("storage_path", metadata.storage_path);
if (metadata.tags) {
metadata.tags.forEach((tag) => formData.append("tags", tag));
}
if (metadata.archive_serial_number) {
formData.append("archive_serial_number", String(metadata.archive_serial_number));
}
if (metadata.custom_fields) {
metadata.custom_fields.forEach((field) => formData.append("custom_fields", String(field)));
}
try {
const response = yield axios_1.default.post(`${this.baseUrl}/api/documents/post_document/`, formData, {
headers: Object.assign({ Authorization: `Token ${this.token}`, Accept: `application/json; version=${this.apiVersion}` }, formData.getHeaders()),
});
if (response.status < 200 || response.status >= 300) {
throw new Error(`HTTP error! status: ${response.status}`);
}
return response.data;
}
catch (error) {
if (axios_1.default.isAxiosError(error) && ((_a = error.response) === null || _a === void 0 ? void 0 : _a.status) === 406) {
throw new Error(`HTTP 406: Paperless-ngx rejected API version ${this.apiVersion}. ` +
`Set the PAPERLESS_API_VERSION environment variable to match your server's API version (e.g., "10" for Paperless-ngx v3+).`);
}
throw error;
}
});
}
getDocuments() {
return __awaiter(this, arguments, void 0, function* (query = "") {
return this.request(`/documents/${query}`);
});
}
getDocument(id) {
return __awaiter(this, void 0, void 0, function* () {
return this.request(`/documents/${id}/`);
});
}
updateDocument(id, data) {
return __awaiter(this, void 0, void 0, function* () {
return this.request(`/documents/${id}/`, {
method: "PATCH",
body: JSON.stringify(data),
});
});
}
downloadDocument(id_1) {
return __awaiter(this, arguments, void 0, function* (id, asOriginal = false) {
const query = asOriginal ? "?original=true" : "";
const response = yield axios_1.default.get(`${this.baseUrl}/api/documents/${id}/download/${query}`, {
headers: {
Authorization: `Token ${this.token}`,
},
responseType: "arraybuffer",
});
return response;
});
}
getThumbnail(id) {
return __awaiter(this, void 0, void 0, function* () {
const response = yield axios_1.default.get(`${this.baseUrl}/api/documents/${id}/thumb/`, {
headers: {
Authorization: `Token ${this.token}`,
},
responseType: "arraybuffer",
});
return response;
});
}
// Document note operations
/**
* Retrieve all notes attached to a document.
* @param documentId - The document ID.
* @returns The document's notes.
*/
getDocumentNotes(documentId) {
return __awaiter(this, void 0, void 0, function* () {
return this.request(`/documents/${documentId}/notes/`);
});
}
/**
* Create a note on a document.
* @param documentId - The document ID.
* @param note - The note text to add.
* @returns The document's full notes list after creation.
*/
createDocumentNote(documentId, note) {
return __awaiter(this, void 0, void 0, function* () {
return this.request(`/documents/${documentId}/notes/`, {
method: "POST",
body: JSON.stringify({ note }),
});
});
}
/**
* Delete a note from a document by its note ID.
* @param documentId - The document ID.
* @param noteId - The ID of the note to delete.
* @returns The document's remaining notes after deletion.
*/
deleteDocumentNote(documentId, noteId) {
return __awaiter(this, void 0, void 0, function* () {
return this.request(`/documents/${documentId}/notes/?id=${noteId}`, {
method: "DELETE",
});
});
}
// Tag operations
getTags() {
return __awaiter(this, void 0, void 0, function* () {
return this.request("/tags/");
});
}
createTag(data) {
return __awaiter(this, void 0, void 0, function* () {
return this.request("/tags/", {
method: "POST",
body: JSON.stringify(data),
});
});
}
updateTag(id, data) {
return __awaiter(this, void 0, void 0, function* () {
return this.request(`/tags/${id}/`, {
method: "PATCH",
body: JSON.stringify(data),
});
});
}
deleteTag(id) {
return __awaiter(this, void 0, void 0, function* () {
return this.request(`/tags/${id}/`, {
method: "DELETE",
});
});
}
// Correspondent operations
getCorrespondents(queryString) {
return __awaiter(this, void 0, void 0, function* () {
const url = queryString
? `/correspondents/?${queryString}`
: "/correspondents/";
return this.request(url);
});
}
getCorrespondent(id) {
return __awaiter(this, void 0, void 0, function* () {
return this.request(`/correspondents/${id}/`);
});
}
createCorrespondent(data) {
return __awaiter(this, void 0, void 0, function* () {
return this.request("/correspondents/", {
method: "POST",
body: JSON.stringify(data),
});
});
}
updateCorrespondent(id, data) {
return __awaiter(this, void 0, void 0, function* () {
return this.request(`/correspondents/${id}/`, {
method: "PATCH",
body: JSON.stringify(data),
});
});
}
deleteCorrespondent(id) {
return __awaiter(this, void 0, void 0, function* () {
return this.request(`/correspondents/${id}/`, {
method: "DELETE",
});
});
}
// Document type operations
getDocumentTypes() {
return __awaiter(this, void 0, void 0, function* () {
return this.request("/document_types/");
});
}
createDocumentType(data) {
return __awaiter(this, void 0, void 0, function* () {
return this.request("/document_types/", {
method: "POST",
body: JSON.stringify(data),
});
});
}
updateDocumentType(id, data) {
return __awaiter(this, void 0, void 0, function* () {
return this.request(`/document_types/${id}/`, {
method: "PATCH",
body: JSON.stringify(data),
});
});
}
deleteDocumentType(id) {
return __awaiter(this, void 0, void 0, function* () {
return this.request(`/document_types/${id}/`, {
method: "DELETE",
});
});
}
// Mail account operations
getMailAccounts(queryString) {
return __awaiter(this, void 0, void 0, function* () {
const url = queryString
? `/mail_accounts/?${queryString}`
: "/mail_accounts/";
return this.request(url);
});
}
getMailAccount(id) {
return __awaiter(this, void 0, void 0, function* () {
return this.request(`/mail_accounts/${id}/`);
});
}
processMailAccount(id) {
return __awaiter(this, void 0, void 0, function* () {
return this.request(`/mail_accounts/${id}/process/`, {
method: "POST",
body: JSON.stringify({}),
});
});
}
// Mail rule operations
getMailRules(queryString) {
return __awaiter(this, void 0, void 0, function* () {
const url = queryString ? `/mail_rules/?${queryString}` : "/mail_rules/";
return this.request(url);
});
}
getMailRule(id) {
return __awaiter(this, void 0, void 0, function* () {
return this.request(`/mail_rules/${id}/`);
});
}
createMailRule(data) {
return __awaiter(this, void 0, void 0, function* () {
return this.request("/mail_rules/", {
method: "POST",
body: JSON.stringify(data),
});
});
}
updateMailRule(id, data) {
return __awaiter(this, void 0, void 0, function* () {
return this.request(`/mail_rules/${id}/`, {
method: "PATCH",
body: JSON.stringify(data),
});
});
}
deleteMailRule(id) {
return __awaiter(this, void 0, void 0, function* () {
return this.request(`/mail_rules/${id}/`, {
method: "DELETE",
});
});
}
// Custom field operations
getCustomFields() {
return __awaiter(this, void 0, void 0, function* () {
return this.request("/custom_fields/");
});
}
getCustomField(id) {
return __awaiter(this, void 0, void 0, function* () {
return this.request(`/custom_fields/${id}/`);
});
}
createCustomField(data) {
return __awaiter(this, void 0, void 0, function* () {
return this.request("/custom_fields/", {
method: "POST",
body: JSON.stringify(data),
});
});
}
updateCustomField(id, data) {
return __awaiter(this, void 0, void 0, function* () {
return this.request(`/custom_fields/${id}/`, {
method: "PATCH",
body: JSON.stringify(data),
});
});
}
deleteCustomField(id) {
return __awaiter(this, void 0, void 0, function* () {
return this.request(`/custom_fields/${id}/`, {
method: "DELETE",
});
});
}
// Bulk object operations
bulkEditObjects(objects_1, objectType_1, operation_1) {
return __awaiter(this, arguments, void 0, function* (objects, objectType, operation, parameters = {}) {
return this.request("/bulk_edit_objects/", {
method: "POST",
body: JSON.stringify(Object.assign({ objects, object_type: objectType, operation }, parameters)),
});
});
}
}
exports.PaperlessAPI = PaperlessAPI;