@retiform/paperless-mcp 0.0.0-stage → 2.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (74) hide show
  1. package/LICENSE +18 -0
  2. package/README.md +1005 -2
  3. package/build/api/PaperlessAPI.d.ts +63 -0
  4. package/build/api/PaperlessAPI.js +405 -0
  5. package/build/api/documentEnhancer.d.ts +24 -0
  6. package/build/api/documentEnhancer.js +111 -0
  7. package/build/api/documentEnhancer.test.d.ts +1 -0
  8. package/build/api/documentEnhancer.test.js +80 -0
  9. package/build/api/types.d.ts +203 -0
  10. package/build/api/types.js +15 -0
  11. package/build/api/utils.d.ts +16 -0
  12. package/build/api/utils.js +29 -0
  13. package/build/index.d.ts +2 -0
  14. package/build/index.js +189 -0
  15. package/build/resources/documents.d.ts +7 -0
  16. package/build/resources/documents.js +119 -0
  17. package/build/resources/documents.test.d.ts +1 -0
  18. package/build/resources/documents.test.js +124 -0
  19. package/build/server.d.ts +24 -0
  20. package/build/server.js +70 -0
  21. package/build/server.test.d.ts +1 -0
  22. package/build/server.test.js +54 -0
  23. package/build/test/mocks/paperlessApi.d.ts +4 -0
  24. package/build/test/mocks/paperlessApi.js +33 -0
  25. package/build/tools/boundedContent.test.d.ts +1 -0
  26. package/build/tools/boundedContent.test.js +544 -0
  27. package/build/tools/correspondents.d.ts +3 -0
  28. package/build/tools/correspondents.js +149 -0
  29. package/build/tools/customFields.d.ts +3 -0
  30. package/build/tools/customFields.js +142 -0
  31. package/build/tools/documentTypes.d.ts +3 -0
  32. package/build/tools/documentTypes.js +143 -0
  33. package/build/tools/documents.d.ts +134 -0
  34. package/build/tools/documents.js +814 -0
  35. package/build/tools/documents.test.d.ts +1 -0
  36. package/build/tools/documents.test.js +658 -0
  37. package/build/tools/mail.d.ts +3 -0
  38. package/build/tools/mail.js +187 -0
  39. package/build/tools/mail.test.d.ts +1 -0
  40. package/build/tools/mail.test.js +212 -0
  41. package/build/tools/notes.d.ts +3 -0
  42. package/build/tools/notes.js +55 -0
  43. package/build/tools/notes.test.d.ts +1 -0
  44. package/build/tools/notes.test.js +177 -0
  45. package/build/tools/schemaCompat.test.d.ts +1 -0
  46. package/build/tools/schemaCompat.test.js +59 -0
  47. package/build/tools/tags.d.ts +3 -0
  48. package/build/tools/tags.js +143 -0
  49. package/build/tools/utils/descriptions.d.ts +1 -0
  50. package/build/tools/utils/descriptions.js +4 -0
  51. package/build/tools/utils/documentQuery.d.ts +71 -0
  52. package/build/tools/utils/documentQuery.js +270 -0
  53. package/build/tools/utils/empty.d.ts +2 -0
  54. package/build/tools/utils/empty.js +7 -0
  55. package/build/tools/utils/matchingAlgorithm.d.ts +2 -0
  56. package/build/tools/utils/matchingAlgorithm.js +15 -0
  57. package/build/tools/utils/middlewares.d.ts +3 -0
  58. package/build/tools/utils/middlewares.js +31 -0
  59. package/build/tools/utils/monetary.d.ts +5 -0
  60. package/build/tools/utils/monetary.js +34 -0
  61. package/build/tools/utils/monetary.test.d.ts +1 -0
  62. package/build/tools/utils/monetary.test.js +25 -0
  63. package/build/tools/utils/queryString.d.ts +1 -0
  64. package/build/tools/utils/queryString.js +12 -0
  65. package/build/tools/utils/resourceUri.d.ts +29 -0
  66. package/build/tools/utils/resourceUri.js +37 -0
  67. package/build/tools/utils/resourceUri.test.d.ts +1 -0
  68. package/build/tools/utils/resourceUri.test.js +50 -0
  69. package/build/tools/utils/selectFields.d.ts +13 -0
  70. package/build/tools/utils/selectFields.js +91 -0
  71. package/build/tools/utils/selectFields.test.d.ts +1 -0
  72. package/build/tools/utils/selectFields.test.js +164 -0
  73. package/package.json +59 -4
  74. package/paperless-mcp.dxt +0 -0
@@ -0,0 +1,34 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.getMonetaryValidationError = getMonetaryValidationError;
4
+ exports.validateCustomFields = validateCustomFields;
5
+ const SYMBOL_TO_CODE = {
6
+ $: "USD",
7
+ "€": "EUR",
8
+ "£": "GBP",
9
+ "¥": "JPY",
10
+ "₹": "INR",
11
+ "₪": "ILS",
12
+ };
13
+ const TRAILING_SYMBOL_REGEX = new RegExp(`^(\\d+(?:\\.\\d+)?)[${Object.keys(SYMBOL_TO_CODE).join("")}]$`);
14
+ function getMonetaryValidationError(value) {
15
+ const trailingMatch = TRAILING_SYMBOL_REGEX.exec(value);
16
+ if (trailingMatch) {
17
+ const amount = trailingMatch[1];
18
+ const symbol = value.slice(-1);
19
+ const code = SYMBOL_TO_CODE[symbol] || "USD";
20
+ const numericAmount = parseFloat(amount);
21
+ const formattedAmount = isNaN(numericAmount) ? amount : numericAmount.toFixed(2);
22
+ return (`Invalid monetary format "${value}". ` +
23
+ `Paperless-NGX requires the currency code as a prefix, e.g. "${code}${formattedAmount}". ` +
24
+ `Use the format: {CURRENCY_CODE}{amount} (e.g., USD10.00, GBP123.45, EUR9.99).`);
25
+ }
26
+ return null;
27
+ }
28
+ function validateCustomFields(custom_fields) {
29
+ custom_fields === null || custom_fields === void 0 ? void 0 : custom_fields.filter((cf) => typeof cf.value === "string").forEach((cf) => {
30
+ const monetaryError = getMonetaryValidationError(cf.value);
31
+ if (monetaryError)
32
+ throw new Error(monetaryError);
33
+ });
34
+ }
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,25 @@
1
+ "use strict";
2
+ var __importDefault = (this && this.__importDefault) || function (mod) {
3
+ return (mod && mod.__esModule) ? mod : { "default": mod };
4
+ };
5
+ Object.defineProperty(exports, "__esModule", { value: true });
6
+ const node_test_1 = require("node:test");
7
+ const strict_1 = __importDefault(require("node:assert/strict"));
8
+ const monetary_1 = require("./monetary");
9
+ (0, node_test_1.test)("returns null for non-monetary strings", () => {
10
+ strict_1.default.equal((0, monetary_1.getMonetaryValidationError)("hello"), null);
11
+ strict_1.default.equal((0, monetary_1.getMonetaryValidationError)("some text"), null);
12
+ strict_1.default.equal((0, monetary_1.getMonetaryValidationError)(""), null);
13
+ });
14
+ (0, node_test_1.test)("returns null for valid monetary prefix format", () => {
15
+ strict_1.default.equal((0, monetary_1.getMonetaryValidationError)("USD10.00"), null);
16
+ strict_1.default.equal((0, monetary_1.getMonetaryValidationError)("GBP123.45"), null);
17
+ strict_1.default.equal((0, monetary_1.getMonetaryValidationError)("EUR9.99"), null);
18
+ strict_1.default.equal((0, monetary_1.getMonetaryValidationError)("ILS50.00"), null);
19
+ });
20
+ (0, node_test_1.test)("returns error for trailing currency symbol", () => {
21
+ const err = (0, monetary_1.getMonetaryValidationError)("10.00$");
22
+ strict_1.default.ok(err);
23
+ strict_1.default.match(err, /USD10\.00/);
24
+ strict_1.default.match(err, /currency code as a prefix/);
25
+ });
@@ -0,0 +1 @@
1
+ export declare function buildQueryString(args: Record<string, any>): string;
@@ -0,0 +1,12 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.buildQueryString = buildQueryString;
4
+ function buildQueryString(args) {
5
+ const query = new URLSearchParams();
6
+ for (const key in args) {
7
+ if (args[key] !== undefined && args[key] !== null) {
8
+ query.set(key, args[key].toString());
9
+ }
10
+ }
11
+ return query.toString();
12
+ }
@@ -0,0 +1,29 @@
1
+ /**
2
+ * Resource URI builders for document/thumbnail downloads.
3
+ *
4
+ * URIs mirror document resources under a custom `paperless://` scheme, so the
5
+ * same identifiers can back MCP resources (`resources/list` / `resources/read`)
6
+ * without a second naming scheme.
7
+ *
8
+ * The scheme also keeps the URI well-formed regardless of filename
9
+ * content, which Python MCP clients (pydantic-validated) require.
10
+ */
11
+ /**
12
+ * Optional flags for document download resource URIs.
13
+ */
14
+ export interface DocumentResourceUriOptions {
15
+ original?: boolean;
16
+ }
17
+ /**
18
+ * Builds a resource URI for a downloaded document.
19
+ *
20
+ * The MCP resource URI is intentionally canonical and filename-free; filenames
21
+ * belong in resource metadata, while the URI identifies the fetchable content.
22
+ */
23
+ export declare function buildDocumentResourceUri(id: number, optionsOrFilename?: DocumentResourceUriOptions | string): string;
24
+ /**
25
+ * Builds a resource URI for a document thumbnail.
26
+ *
27
+ * Mirrors `GET /api/documents/{id}/thumb/`.
28
+ */
29
+ export declare function buildThumbnailResourceUri(id: number): string;
@@ -0,0 +1,37 @@
1
+ "use strict";
2
+ /**
3
+ * Resource URI builders for document/thumbnail downloads.
4
+ *
5
+ * URIs mirror document resources under a custom `paperless://` scheme, so the
6
+ * same identifiers can back MCP resources (`resources/list` / `resources/read`)
7
+ * without a second naming scheme.
8
+ *
9
+ * The scheme also keeps the URI well-formed regardless of filename
10
+ * content, which Python MCP clients (pydantic-validated) require.
11
+ */
12
+ Object.defineProperty(exports, "__esModule", { value: true });
13
+ exports.buildDocumentResourceUri = buildDocumentResourceUri;
14
+ exports.buildThumbnailResourceUri = buildThumbnailResourceUri;
15
+ /**
16
+ * Builds a resource URI for a downloaded document.
17
+ *
18
+ * The MCP resource URI is intentionally canonical and filename-free; filenames
19
+ * belong in resource metadata, while the URI identifies the fetchable content.
20
+ */
21
+ function buildDocumentResourceUri(id, optionsOrFilename) {
22
+ const options = typeof optionsOrFilename === "string" ? {} : optionsOrFilename || {};
23
+ const params = new URLSearchParams();
24
+ if (options.original) {
25
+ params.set("original", "true");
26
+ }
27
+ const query = params.toString();
28
+ return `paperless://documents/${id}/download${query ? `?${query}` : ""}`;
29
+ }
30
+ /**
31
+ * Builds a resource URI for a document thumbnail.
32
+ *
33
+ * Mirrors `GET /api/documents/{id}/thumb/`.
34
+ */
35
+ function buildThumbnailResourceUri(id) {
36
+ return `paperless://documents/${id}/thumb`;
37
+ }
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,50 @@
1
+ "use strict";
2
+ var __importDefault = (this && this.__importDefault) || function (mod) {
3
+ return (mod && mod.__esModule) ? mod : { "default": mod };
4
+ };
5
+ Object.defineProperty(exports, "__esModule", { value: true });
6
+ const node_test_1 = require("node:test");
7
+ const strict_1 = __importDefault(require("node:assert/strict"));
8
+ const resourceUri_1 = require("./resourceUri");
9
+ (0, node_test_1.test)("buildDocumentResourceUri mirrors the REST download path", () => {
10
+ const uri = (0, resourceUri_1.buildDocumentResourceUri)(1, "doc.pdf");
11
+ strict_1.default.match(uri, /^paperless:\/\/documents\/1\/download(\?|$)/);
12
+ });
13
+ (0, node_test_1.test)("buildDocumentResourceUri is canonical without filenames", () => {
14
+ const uri = (0, resourceUri_1.buildDocumentResourceUri)(1, "invoice 2026.pdf");
15
+ strict_1.default.equal(uri, "paperless://documents/1/download");
16
+ });
17
+ (0, node_test_1.test)("buildDocumentResourceUri ignores reserved chars in legacy filename input", () => {
18
+ const uri = (0, resourceUri_1.buildDocumentResourceUri)(42, "weird ?#&=+name.pdf");
19
+ const url = new URL(uri);
20
+ strict_1.default.equal(url.pathname, "/42/download");
21
+ strict_1.default.equal(url.search, "");
22
+ });
23
+ (0, node_test_1.test)("buildDocumentResourceUri ignores path separators in legacy filename input", () => {
24
+ // A filename containing a slash must not become an extra path segment.
25
+ const uri = (0, resourceUri_1.buildDocumentResourceUri)(7, "sub/dir/file.pdf");
26
+ const url = new URL(uri);
27
+ strict_1.default.equal(url.pathname, "/7/download");
28
+ strict_1.default.equal(url.search, "");
29
+ });
30
+ (0, node_test_1.test)("buildDocumentResourceUri keeps unicode filenames out of the URI", () => {
31
+ const original = "Rechnüng — März.pdf";
32
+ const uri = (0, resourceUri_1.buildDocumentResourceUri)(1, original);
33
+ const url = new URL(uri);
34
+ strict_1.default.equal(url.pathname, "/1/download");
35
+ strict_1.default.equal(url.search, "");
36
+ });
37
+ (0, node_test_1.test)("buildDocumentResourceUri preserves original download intent", () => {
38
+ strict_1.default.equal((0, resourceUri_1.buildDocumentResourceUri)(1, { original: true }), "paperless://documents/1/download?original=true");
39
+ });
40
+ (0, node_test_1.test)("buildDocumentResourceUri produces a valid URL", () => {
41
+ const uri = (0, resourceUri_1.buildDocumentResourceUri)(1, "Some File.pdf");
42
+ strict_1.default.doesNotThrow(() => new URL(uri));
43
+ });
44
+ (0, node_test_1.test)("buildThumbnailResourceUri mirrors the REST thumb path", () => {
45
+ strict_1.default.equal((0, resourceUri_1.buildThumbnailResourceUri)(1), "paperless://documents/1/thumb");
46
+ strict_1.default.equal((0, resourceUri_1.buildThumbnailResourceUri)(123), "paperless://documents/123/thumb");
47
+ });
48
+ (0, node_test_1.test)("buildThumbnailResourceUri produces a valid URL", () => {
49
+ strict_1.default.doesNotThrow(() => new URL((0, resourceUri_1.buildThumbnailResourceUri)(99)));
50
+ });
@@ -0,0 +1,13 @@
1
+ import { PaperlessAPI } from "../../api/PaperlessAPI";
2
+ import { CustomField, CustomFieldInstanceRequest, CustomFieldValue } from "../../api/types";
3
+ /**
4
+ * Encoding Paperless expects for a select value. On the supported API versions
5
+ * (v9+) both `update_document` and `bulk_edit` take the option's stored form:
6
+ * the option id on 2.17+ fields, or the index on pre-2.17 string-option fields.
7
+ * The bare `index` form is retained for older API versions whose document
8
+ * endpoint accepted the option index directly.
9
+ */
10
+ export type SelectValueEncoding = "index" | "stored";
11
+ /** Translates a select value (label, option id, or index) to the `encoding` Paperless expects; throws on no match. */
12
+ export declare function resolveSelectCustomFieldValue(field: CustomField, value: CustomFieldValue, encoding?: SelectValueEncoding): CustomFieldValue;
13
+ export declare function resolveSelectCustomFieldValues(api: PaperlessAPI, customFields: CustomFieldInstanceRequest[] | undefined, encoding?: SelectValueEncoding): Promise<CustomFieldInstanceRequest[] | undefined>;
@@ -0,0 +1,91 @@
1
+ "use strict";
2
+ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
3
+ function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
4
+ return new (P || (P = Promise))(function (resolve, reject) {
5
+ function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
6
+ function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
7
+ function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
8
+ step((generator = generator.apply(thisArg, _arguments || [])).next());
9
+ });
10
+ };
11
+ Object.defineProperty(exports, "__esModule", { value: true });
12
+ exports.resolveSelectCustomFieldValue = resolveSelectCustomFieldValue;
13
+ exports.resolveSelectCustomFieldValues = resolveSelectCustomFieldValues;
14
+ function normalizeSelectOptions(field) {
15
+ var _a;
16
+ const rawOptions = (_a = field.extra_data) === null || _a === void 0 ? void 0 : _a.select_options;
17
+ if (!Array.isArray(rawOptions)) {
18
+ return [];
19
+ }
20
+ return rawOptions.map((option, index) => {
21
+ if (option && typeof option === "object") {
22
+ const { id, label } = option;
23
+ return {
24
+ index,
25
+ label: typeof label === "string" ? label : String(label),
26
+ id: typeof id === "string" ? id : undefined,
27
+ };
28
+ }
29
+ return { index, label: String(option) };
30
+ });
31
+ }
32
+ function findSelectOption(options, value) {
33
+ if (typeof value === "string") {
34
+ const byLabel = options.find((option) => option.label === value);
35
+ const byId = options.find((option) => option.id === value);
36
+ if (byLabel && byId && byLabel.index !== byId.index) {
37
+ throw new Error(`Ambiguous select value ${JSON.stringify(value)}: it matches one ` +
38
+ `option's label and a different option's id.`);
39
+ }
40
+ return byLabel !== null && byLabel !== void 0 ? byLabel : byId;
41
+ }
42
+ if (typeof value === "number" && Number.isInteger(value)) {
43
+ return options.find((option) => option.index === value);
44
+ }
45
+ return undefined;
46
+ }
47
+ /** Translates a select value (label, option id, or index) to the `encoding` Paperless expects; throws on no match. */
48
+ function resolveSelectCustomFieldValue(field, value, encoding = "index") {
49
+ var _a;
50
+ if (field.data_type !== "select" || value === null) {
51
+ return value;
52
+ }
53
+ const options = normalizeSelectOptions(field);
54
+ if (options.length === 0) {
55
+ return value;
56
+ }
57
+ const option = findSelectOption(options, value);
58
+ if (!option) {
59
+ const optionList = options
60
+ .map((o) => `${JSON.stringify(o.label)} (index ${o.index})`)
61
+ .join(", ");
62
+ throw new Error(`Invalid value ${JSON.stringify(value)} for select custom field ` +
63
+ `"${field.name}" (id ${field.id}). Pass one of the option labels. ` +
64
+ `Valid options: ${optionList}.`);
65
+ }
66
+ return encoding === "stored" ? (_a = option.id) !== null && _a !== void 0 ? _a : option.index : option.index;
67
+ }
68
+ function resolveSelectCustomFieldValues(api_1, customFields_1) {
69
+ return __awaiter(this, arguments, void 0, function* (api, customFields, encoding = "index") {
70
+ if (!customFields || customFields.length === 0) {
71
+ return customFields;
72
+ }
73
+ const uniqueFieldIds = [...new Set(customFields.map((cf) => cf.field))];
74
+ const definitions = new Map();
75
+ yield Promise.all(uniqueFieldIds.map((id) => __awaiter(this, void 0, void 0, function* () {
76
+ try {
77
+ definitions.set(id, yield api.getCustomField(id));
78
+ }
79
+ catch (_a) {
80
+ // Definition unavailable; leave the value for Paperless to validate.
81
+ }
82
+ })));
83
+ return customFields.map((cf) => {
84
+ const field = definitions.get(cf.field);
85
+ if (!field || field.data_type !== "select") {
86
+ return cf;
87
+ }
88
+ return Object.assign(Object.assign({}, cf), { value: resolveSelectCustomFieldValue(field, cf.value, encoding) });
89
+ });
90
+ });
91
+ }
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,164 @@
1
+ "use strict";
2
+ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
3
+ function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
4
+ return new (P || (P = Promise))(function (resolve, reject) {
5
+ function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
6
+ function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
7
+ function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
8
+ step((generator = generator.apply(thisArg, _arguments || [])).next());
9
+ });
10
+ };
11
+ var __importDefault = (this && this.__importDefault) || function (mod) {
12
+ return (mod && mod.__esModule) ? mod : { "default": mod };
13
+ };
14
+ Object.defineProperty(exports, "__esModule", { value: true });
15
+ const node_test_1 = require("node:test");
16
+ const strict_1 = __importDefault(require("node:assert/strict"));
17
+ const selectFields_1 = require("./selectFields");
18
+ const LEGACY_SELECT_FIELD = {
19
+ id: 2,
20
+ name: "Retention period",
21
+ data_type: "select",
22
+ extra_data: { select_options: ["1 year", "7 years", "2 years"], default_currency: null },
23
+ document_count: 10,
24
+ };
25
+ const OBJECT_SELECT_FIELD = {
26
+ id: 3,
27
+ name: "Priority",
28
+ data_type: "select",
29
+ extra_data: {
30
+ select_options: [
31
+ { id: "abc123", label: "Low" },
32
+ { id: "def456", label: "High" },
33
+ ],
34
+ },
35
+ document_count: 5,
36
+ };
37
+ const STRING_FIELD = {
38
+ id: 4,
39
+ name: "Reference",
40
+ data_type: "string",
41
+ document_count: 1,
42
+ };
43
+ (0, node_test_1.describe)("resolveSelectCustomFieldValue", () => {
44
+ (0, node_test_1.test)("translates a label to its zero-based index (pre-2.17 string options)", () => {
45
+ strict_1.default.equal((0, selectFields_1.resolveSelectCustomFieldValue)(LEGACY_SELECT_FIELD, "1 year"), 0);
46
+ strict_1.default.equal((0, selectFields_1.resolveSelectCustomFieldValue)(LEGACY_SELECT_FIELD, "7 years"), 1);
47
+ strict_1.default.equal((0, selectFields_1.resolveSelectCustomFieldValue)(LEGACY_SELECT_FIELD, "2 years"), 2);
48
+ });
49
+ (0, node_test_1.test)("translates a label to its zero-based index (2.17+ object options)", () => {
50
+ strict_1.default.equal((0, selectFields_1.resolveSelectCustomFieldValue)(OBJECT_SELECT_FIELD, "Low"), 0);
51
+ strict_1.default.equal((0, selectFields_1.resolveSelectCustomFieldValue)(OBJECT_SELECT_FIELD, "High"), 1);
52
+ });
53
+ (0, node_test_1.test)("passes through an already-encoded index (pre-2.17)", () => {
54
+ strict_1.default.equal((0, selectFields_1.resolveSelectCustomFieldValue)(LEGACY_SELECT_FIELD, 1), 1);
55
+ });
56
+ (0, node_test_1.test)("maps an option id back to its zero-based index (2.17+ round-trip)", () => {
57
+ strict_1.default.equal((0, selectFields_1.resolveSelectCustomFieldValue)(OBJECT_SELECT_FIELD, "def456"), 1);
58
+ });
59
+ (0, node_test_1.test)("resolves both the label and the option id to the same index", () => {
60
+ strict_1.default.equal((0, selectFields_1.resolveSelectCustomFieldValue)(OBJECT_SELECT_FIELD, "Low"), 0);
61
+ strict_1.default.equal((0, selectFields_1.resolveSelectCustomFieldValue)(OBJECT_SELECT_FIELD, "abc123"), 0);
62
+ });
63
+ (0, node_test_1.test)("returns null unchanged so the field can be cleared", () => {
64
+ strict_1.default.equal((0, selectFields_1.resolveSelectCustomFieldValue)(LEGACY_SELECT_FIELD, null), null);
65
+ });
66
+ (0, node_test_1.test)("leaves non-select field values untouched", () => {
67
+ strict_1.default.equal((0, selectFields_1.resolveSelectCustomFieldValue)(STRING_FIELD, "1 year"), "1 year");
68
+ });
69
+ (0, node_test_1.test)("throws an actionable error listing valid options for an unknown value", () => {
70
+ strict_1.default.throws(() => (0, selectFields_1.resolveSelectCustomFieldValue)(LEGACY_SELECT_FIELD, "forever"), (err) => {
71
+ strict_1.default.match(err.message, /forever/);
72
+ strict_1.default.match(err.message, /Retention period/);
73
+ strict_1.default.match(err.message, /1 year/);
74
+ strict_1.default.match(err.message, /7 years/);
75
+ return true;
76
+ });
77
+ });
78
+ (0, node_test_1.test)("rejects an out-of-range index rather than forwarding it", () => {
79
+ strict_1.default.throws(() => (0, selectFields_1.resolveSelectCustomFieldValue)(LEGACY_SELECT_FIELD, 9));
80
+ });
81
+ (0, node_test_1.test)("throws on a value that matches one option's label and another's id", () => {
82
+ const collidingField = {
83
+ id: 5,
84
+ name: "Collision",
85
+ data_type: "select",
86
+ extra_data: {
87
+ select_options: [
88
+ { id: "High", label: "Low" },
89
+ { id: "xyz789", label: "High" },
90
+ ],
91
+ },
92
+ document_count: 0,
93
+ };
94
+ strict_1.default.throws(() => (0, selectFields_1.resolveSelectCustomFieldValue)(collidingField, "High"), /Ambiguous/);
95
+ });
96
+ });
97
+ (0, node_test_1.describe)("resolveSelectCustomFieldValue with stored encoding (bulk_edit path)", () => {
98
+ (0, node_test_1.test)("translates a label to the option id on 2.17+ object options", () => {
99
+ strict_1.default.equal((0, selectFields_1.resolveSelectCustomFieldValue)(OBJECT_SELECT_FIELD, "Low", "stored"), "abc123");
100
+ strict_1.default.equal((0, selectFields_1.resolveSelectCustomFieldValue)(OBJECT_SELECT_FIELD, "High", "stored"), "def456");
101
+ });
102
+ (0, node_test_1.test)("translates a label to the index on pre-2.17 string options (no id to store)", () => {
103
+ strict_1.default.equal((0, selectFields_1.resolveSelectCustomFieldValue)(LEGACY_SELECT_FIELD, "7 years", "stored"), 1);
104
+ });
105
+ (0, node_test_1.test)("passes an already-stored option id through unchanged", () => {
106
+ strict_1.default.equal((0, selectFields_1.resolveSelectCustomFieldValue)(OBJECT_SELECT_FIELD, "def456", "stored"), "def456");
107
+ });
108
+ (0, node_test_1.test)("maps an option index to its stored id (2.17+)", () => {
109
+ strict_1.default.equal((0, selectFields_1.resolveSelectCustomFieldValue)(OBJECT_SELECT_FIELD, 1, "stored"), "def456");
110
+ });
111
+ });
112
+ function apiReturning(fields) {
113
+ const requestedIds = [];
114
+ const fieldMap = new Map(fields.map((field) => [field.id, field]));
115
+ const api = {
116
+ getCustomField: (id) => __awaiter(this, void 0, void 0, function* () {
117
+ requestedIds.push(id);
118
+ const field = fieldMap.get(id);
119
+ if (!field)
120
+ throw new Error(`custom field ${id} not found`);
121
+ return field;
122
+ }),
123
+ };
124
+ return { api, requestedIds };
125
+ }
126
+ (0, node_test_1.describe)("resolveSelectCustomFieldValues", () => {
127
+ (0, node_test_1.test)("returns undefined/empty input unchanged without fetching definitions", () => __awaiter(void 0, void 0, void 0, function* () {
128
+ const { api, requestedIds } = apiReturning([]);
129
+ strict_1.default.equal(yield (0, selectFields_1.resolveSelectCustomFieldValues)(api, undefined), undefined);
130
+ strict_1.default.deepEqual(yield (0, selectFields_1.resolveSelectCustomFieldValues)(api, []), []);
131
+ strict_1.default.deepEqual(requestedIds, []);
132
+ }));
133
+ (0, node_test_1.test)("resolves select labels and leaves other fields untouched", () => __awaiter(void 0, void 0, void 0, function* () {
134
+ const { api } = apiReturning([LEGACY_SELECT_FIELD, STRING_FIELD]);
135
+ const resolved = yield (0, selectFields_1.resolveSelectCustomFieldValues)(api, [
136
+ { field: 2, value: "2 years" },
137
+ { field: 4, value: "INV-001" },
138
+ ]);
139
+ strict_1.default.deepEqual(resolved, [
140
+ { field: 2, value: 2 },
141
+ { field: 4, value: "INV-001" },
142
+ ]);
143
+ }));
144
+ (0, node_test_1.test)("applies the stored encoding (option id) when requested", () => __awaiter(void 0, void 0, void 0, function* () {
145
+ const { api } = apiReturning([OBJECT_SELECT_FIELD]);
146
+ const resolved = yield (0, selectFields_1.resolveSelectCustomFieldValues)(api, [{ field: 3, value: "High" }], "stored");
147
+ strict_1.default.deepEqual(resolved, [{ field: 3, value: "def456" }]);
148
+ }));
149
+ (0, node_test_1.test)("fetches each referenced field definition only once", () => __awaiter(void 0, void 0, void 0, function* () {
150
+ const { api, requestedIds } = apiReturning([LEGACY_SELECT_FIELD]);
151
+ yield (0, selectFields_1.resolveSelectCustomFieldValues)(api, [
152
+ { field: 2, value: "1 year" },
153
+ { field: 2, value: "7 years" },
154
+ ]);
155
+ strict_1.default.deepEqual(requestedIds, [2]);
156
+ }));
157
+ (0, node_test_1.test)("passes the value through when the field definition cannot be fetched", () => __awaiter(void 0, void 0, void 0, function* () {
158
+ const { api } = apiReturning([]);
159
+ const resolved = yield (0, selectFields_1.resolveSelectCustomFieldValues)(api, [
160
+ { field: 99, value: "whatever" },
161
+ ]);
162
+ strict_1.default.deepEqual(resolved, [{ field: 99, value: "whatever" }]);
163
+ }));
164
+ });
package/package.json CHANGED
@@ -1,6 +1,61 @@
1
1
  {
2
2
  "name": "@retiform/paperless-mcp",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "2.3.2",
4
+ "description": "MCP server for Paperless-NGX with bounded content reads - ranged document windows and passage search so agents never flood their context.",
5
+ "main": "build/index.js",
6
+ "bin": {
7
+ "paperless-mcp": "build/index.js"
8
+ },
9
+ "scripts": {
10
+ "test": "node --require ts-node/register --test \"src/**/*.test.ts\"",
11
+ "test:e2e": "node --require ts-node/register --test e2e/e2e.test.ts",
12
+ "start": "ts-node src/index.ts",
13
+ "build": "tsc",
14
+ "dxt-pack": "dxt pack",
15
+ "inspect": "npm run build && npx -y @modelcontextprotocol/inspector node build/index.js",
16
+ "prepack": "rm -rf build && npm run build && npm run dxt-pack"
17
+ },
18
+ "keywords": [
19
+ "mcp",
20
+ "paperless-ngx",
21
+ "document-management",
22
+ "ai",
23
+ "claude",
24
+ "model-context-protocol",
25
+ "paperless"
26
+ ],
27
+ "author": "Guan <guan@retiform.dev>",
28
+ "license": "ISC",
29
+ "engines": {
30
+ "node": ">=24.0.0"
31
+ },
32
+ "repository": {
33
+ "type": "git",
34
+ "url": "git+https://github.com/retiform-labs/paperless-mcp.git"
35
+ },
36
+ "homepage": "https://github.com/retiform-labs/paperless-mcp",
37
+ "files": [
38
+ "build",
39
+ "README.md",
40
+ "LICENSE",
41
+ "paperless-mcp.dxt"
42
+ ],
43
+ "bugs": {
44
+ "url": "https://github.com/retiform-labs/paperless-mcp/issues"
45
+ },
46
+ "dependencies": {
47
+ "@modelcontextprotocol/sdk": "^1.30.0",
48
+ "axios": "^1.20.0",
49
+ "express": "^5.1.0",
50
+ "form-data": "^4.0.2",
51
+ "zod": "~4.4.3"
52
+ },
53
+ "devDependencies": {
54
+ "@anthropic-ai/dxt": "^0.2.6",
55
+ "@changesets/cli": "^2.29.4",
56
+ "@types/express": "^5.0.2",
57
+ "@types/node": "^24.0.0",
58
+ "ts-node": "^10.9.2",
59
+ "typescript": "^5.8.3"
60
+ }
61
+ }
Binary file