@retiform/paperless-mcp 2.3.6 → 2.4.0

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 (52) hide show
  1. package/README.md +301 -4
  2. package/build/api/PaperlessAPI.js +1 -6
  3. package/build/search/build-outcome.d.ts +28 -0
  4. package/build/search/build-outcome.js +31 -0
  5. package/build/search/chunk.d.ts +16 -0
  6. package/build/search/chunk.js +64 -0
  7. package/build/search/config.d.ts +120 -0
  8. package/build/search/config.js +264 -0
  9. package/build/search/embedder.d.ts +346 -0
  10. package/build/search/embedder.js +734 -0
  11. package/build/search/rank.d.ts +11 -0
  12. package/build/search/rank.js +87 -0
  13. package/build/search/store.d.ts +406 -0
  14. package/build/search/store.js +847 -0
  15. package/build/search/sync.d.ts +204 -0
  16. package/build/search/sync.js +819 -0
  17. package/build/search/webhook.d.ts +193 -0
  18. package/build/search/webhook.js +445 -0
  19. package/build/server.d.ts +29 -0
  20. package/build/server.js +77 -0
  21. package/build/tools/documents.d.ts +13 -3
  22. package/build/tools/documents.js +23 -6
  23. package/build/tools/search.d.ts +518 -0
  24. package/build/tools/search.js +1199 -0
  25. package/build/tools/utils/middlewares.d.ts +5 -0
  26. package/build/tools/utils/middlewares.js +282 -9
  27. package/package.json +9 -3
  28. package/paperless-mcp.dxt +0 -0
  29. package/build/api/documentEnhancer.test.d.ts +0 -1
  30. package/build/api/documentEnhancer.test.js +0 -80
  31. package/build/manifest.test.d.ts +0 -1
  32. package/build/manifest.test.js +0 -66
  33. package/build/resources/documents.test.d.ts +0 -1
  34. package/build/resources/documents.test.js +0 -124
  35. package/build/server.test.d.ts +0 -1
  36. package/build/server.test.js +0 -54
  37. package/build/tools/boundedContent.test.d.ts +0 -1
  38. package/build/tools/boundedContent.test.js +0 -565
  39. package/build/tools/documents.test.d.ts +0 -1
  40. package/build/tools/documents.test.js +0 -658
  41. package/build/tools/mail.test.d.ts +0 -1
  42. package/build/tools/mail.test.js +0 -212
  43. package/build/tools/notes.test.d.ts +0 -1
  44. package/build/tools/notes.test.js +0 -177
  45. package/build/tools/schemaCompat.test.d.ts +0 -1
  46. package/build/tools/schemaCompat.test.js +0 -59
  47. package/build/tools/utils/monetary.test.d.ts +0 -1
  48. package/build/tools/utils/monetary.test.js +0 -25
  49. package/build/tools/utils/resourceUri.test.d.ts +0 -1
  50. package/build/tools/utils/resourceUri.test.js +0 -50
  51. package/build/tools/utils/selectFields.test.d.ts +0 -1
  52. package/build/tools/utils/selectFields.test.js +0 -164
@@ -0,0 +1,204 @@
1
+ import { PaperlessAPI } from "../api/PaperlessAPI";
2
+ import { type Embedder } from "./embedder";
3
+ import { SearchIndex, type Watermark } from "./store";
4
+ /** How often a document's metadata chunk is rebuilt regardless of `modified`. */
5
+ export declare const METADATA_REFRESH_MS: number;
6
+ /**
7
+ * Paged in id order, with the fields the diff needs and nothing else.
8
+ *
9
+ * Ordering by id matters: an insert does not move a row, so a document added
10
+ * while the list is being paged lands at the end rather than shuffling the
11
+ * pages already read. A delete DOES move rows, which is why the row count is
12
+ * compared to the reported count below.
13
+ */
14
+ export declare const DOCUMENT_LIST_PATH = "/documents/?fields=id,modified&page_size=1000&ordering=id";
15
+ /** A repeated or endless `next` would otherwise keep a run pending forever. */
16
+ export declare const MAX_LIST_PAGES = 10000;
17
+ /**
18
+ * One request that answers "how big is the corpus, and when did it last move".
19
+ *
20
+ * Deliberately NOT a walk of the document list. The list is paged at 1000 rows
21
+ * with a full `id,modified` payload per row; on a corpus of a few thousand that
22
+ * is several requests and a few hundred kilobytes to learn two scalars. This is
23
+ * ONE request and about 200 bytes.
24
+ *
25
+ * `ordering=-modified&page_size=1` makes `results[0].modified` the maximum over
26
+ * the whole corpus, which is the value the incremental diff is keyed on.
27
+ */
28
+ export declare const WATERMARK_PATH = "/documents/?fields=id,modified&ordering=-modified&page_size=1";
29
+ /** The two scalars, and nothing else. */
30
+ export interface CorpusState {
31
+ count: number;
32
+ /** `max(modified)` over the corpus, or null when the corpus is empty. */
33
+ modified: string | null;
34
+ }
35
+ /**
36
+ * Whether the live corpus differs from the indexed one.
37
+ *
38
+ * ⚠️ COMPARED AS INSTANTS, NOT STRINGS. `modified` arrives as an ISO 8601 string
39
+ * with an offset, and the same moment can be serialised with a different offset
40
+ * (`…+00:00` one day, `…-05:00` the next). A string compare would report a
41
+ * change on every run and defeat the entire point of the watermark, while
42
+ * looking exactly like a working check. The existing document diff already got
43
+ * this right; this is the same treatment applied to the corpus-level value.
44
+ *
45
+ * `count` is checked FIRST and separately. It is the only signal a soft delete
46
+ * produces: Paperless clears `deleted_at` through a queryset `.update()`, which
47
+ * does not fire `auto_now`, so a deleted document never bumps `max(modified)`.
48
+ * The count still drops, and the count is free in the same response.
49
+ */
50
+ export declare function corpusChanged(live: CorpusState, watermark: Watermark): boolean;
51
+ /**
52
+ * The corpus's size and newest `modified`, from ONE request.
53
+ *
54
+ * Returns undefined when the request fails. A watermark probe that THROWS would
55
+ * turn a cosmetic optimisation into a hard dependency: the sync would stop
56
+ * working on any Paperless that declines this particular query, when the list
57
+ * walk it already knows how to do would have succeeded. Falling back to the full
58
+ * diff is always correct, merely slower.
59
+ *
60
+ * Module-level rather than a private method because two callers need it — the
61
+ * sync's skip check and the search tool's opt-in staleness report — and two
62
+ * copies of "which fields, which ordering, which page size" is how they drift
63
+ * apart. One request shape, one place.
64
+ */
65
+ export declare function readCorpusState(api: PaperlessAPI, requestTimeoutMs?: number): Promise<CorpusState | undefined>;
66
+ /** Without a limit, a Paperless that never answers keeps a run pending forever. */
67
+ export declare const REQUEST_TIMEOUT_MS = 60000;
68
+ export interface SyncReport {
69
+ added: number;
70
+ updated: number;
71
+ deleted: number;
72
+ metadataRefreshed: number;
73
+ failed: number;
74
+ /** True when the delete step was skipped because the list changed mid-run. */
75
+ deletedSkipped: boolean;
76
+ /**
77
+ * Text splits performed because the embedding server refused an input as
78
+ * over-long, summed over the run.
79
+ *
80
+ * Reported because the alternative is silence: a run that split 400 chunks
81
+ * and one that split none produce identical counts, and the number is the
82
+ * only evidence the fallback is load-bearing rather than merely present.
83
+ */
84
+ splits: number;
85
+ /**
86
+ * True when the run returned without touching the index because the live
87
+ * corpus matched the recorded watermark.
88
+ *
89
+ * Reported rather than left implicit: a skipped run and a run that found
90
+ * nothing to do produce identical counts (all zero), and the difference is
91
+ * the whole reason the watermark exists. A caller that cannot tell them apart
92
+ * cannot tell a 218 ms no-op from a wasted full sweep.
93
+ */
94
+ skipped: boolean;
95
+ /** Why the run skipped, when it did. Absent otherwise. */
96
+ skipReason?: string;
97
+ }
98
+ /**
99
+ * Turn an absolute `next` URL into the path this API client accepts.
100
+ *
101
+ * The list answer carries `next` as a full URL (verified: `GET
102
+ * /api/documents/?fields=id,modified&page_size=3&ordering=id` returns an
103
+ * absolute URL), while `PaperlessAPI.request` prepends `/api` itself. So the
104
+ * base is stripped and the query string kept.
105
+ *
106
+ * Deliberately NOT the reference's arithmetic: it slices at
107
+ * `indexOf("/api/") + 4`, which returns a four-character-amputated path when
108
+ * the marker is missing -- a wrong URL that looks like a right one. An absent
109
+ * marker returns the input unchanged, which fails loudly at the request instead.
110
+ */
111
+ export declare function pathAfterApi(url: string): string;
112
+ export declare class IndexSync {
113
+ private readonly api;
114
+ private readonly store;
115
+ private readonly embedder;
116
+ private readonly maxChunks;
117
+ private readonly now;
118
+ private readonly requestTimeoutMs;
119
+ private readonly maxListPages;
120
+ private timer?;
121
+ private running?;
122
+ /** Whether the run in flight is a targeted one. See `run()`. */
123
+ private runningTargeted;
124
+ constructor(opts: {
125
+ api: PaperlessAPI;
126
+ store: SearchIndex;
127
+ embedder: Embedder;
128
+ maxChunks?: number;
129
+ now?: () => number;
130
+ requestTimeoutMs?: number;
131
+ maxListPages?: number;
132
+ });
133
+ /**
134
+ * Run one sync. Re-entrant calls join the run in flight.
135
+ *
136
+ * Two concurrent writers on one SQLite file is a failure this arc has already
137
+ * hit once, and WAL plus `busy_timeout` only makes the second writer wait --
138
+ * it does not make two simultaneous passes correct, because both would diff
139
+ * against the same stale `indexed()` snapshot and the loser's deletes would
140
+ * remove the winner's work.
141
+ */
142
+ run(opts?: {
143
+ force?: boolean;
144
+ documentIds?: number[];
145
+ }): Promise<SyncReport>;
146
+ /**
147
+ * Run once and then on an interval. NOT called by this package.
148
+ *
149
+ * A stdio child's lifetime is the gateway's, so a timer here refreshes on a
150
+ * schedule nobody can see. The observable path is the `sync_embeddings` tool,
151
+ * which can be scheduled where the schedule is legible.
152
+ */
153
+ start(intervalMs: number): void;
154
+ stop(): void;
155
+ get isRunning(): boolean;
156
+ /**
157
+ * True while a background timer is live.
158
+ *
159
+ * Distinct from `isRunning`, which reports a pass in flight: between two
160
+ * scheduled ticks the timer is set and nothing is running. A wiring test that
161
+ * asked `isRunning` would report "no schedule" on a working schedule whenever
162
+ * it happened to look between ticks.
163
+ */
164
+ get isScheduled(): boolean;
165
+ private doRun;
166
+ private syncAll;
167
+ /**
168
+ * Rebuild the metadata chunk of every indexed document whose stamp is older
169
+ * than the refresh window.
170
+ *
171
+ * Extracted because TWO paths need it: the full run, and the watermark skip.
172
+ * A skip that returned before this would silently retire the 24 h refresh on
173
+ * any corpus that had stopped changing — and a stopped corpus is exactly the
174
+ * one whose tags and correspondents still get edited by hand, because nobody
175
+ * is uploading to it.
176
+ *
177
+ * `remote` is optional: the full run passes the live id set so a document
178
+ * deleted since the last sync is not refreshed, while the skip path has no
179
+ * list to consult and passes undefined.
180
+ */
181
+ private refreshStaleMetadata;
182
+ /**
183
+ * Page through a list endpoint, following `next`.
184
+ *
185
+ * A repeated `next` would loop forever and an endless one would never finish,
186
+ * so pages already fetched are tracked and the run fails past a page cap
187
+ * rather than hanging with no diagnostic.
188
+ */
189
+ private listAll;
190
+ /**
191
+ * One request with a timeout.
192
+ *
193
+ * `PaperlessAPI.request` passes `options.signal` through to axios, which is
194
+ * what makes the budget real: before that was wired, this signal was accepted
195
+ * and silently ignored, so a Paperless that accepted the connection and then
196
+ * stalled would hold the sync open forever while the code read as though it
197
+ * had a 60 second limit.
198
+ */
199
+ private get;
200
+ private loadNames;
201
+ private metadataTextFor;
202
+ private syncDocument;
203
+ private refreshMetadata;
204
+ }