@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.
- package/README.md +301 -4
- package/build/api/PaperlessAPI.js +1 -6
- package/build/search/build-outcome.d.ts +28 -0
- package/build/search/build-outcome.js +31 -0
- package/build/search/chunk.d.ts +16 -0
- package/build/search/chunk.js +64 -0
- package/build/search/config.d.ts +120 -0
- package/build/search/config.js +264 -0
- package/build/search/embedder.d.ts +346 -0
- package/build/search/embedder.js +734 -0
- package/build/search/rank.d.ts +11 -0
- package/build/search/rank.js +87 -0
- package/build/search/store.d.ts +406 -0
- package/build/search/store.js +847 -0
- package/build/search/sync.d.ts +204 -0
- package/build/search/sync.js +819 -0
- package/build/search/webhook.d.ts +193 -0
- package/build/search/webhook.js +445 -0
- package/build/server.d.ts +29 -0
- package/build/server.js +77 -0
- package/build/tools/documents.d.ts +13 -3
- package/build/tools/documents.js +23 -6
- package/build/tools/search.d.ts +518 -0
- package/build/tools/search.js +1199 -0
- package/build/tools/utils/middlewares.d.ts +5 -0
- package/build/tools/utils/middlewares.js +282 -9
- package/package.json +9 -3
- package/paperless-mcp.dxt +0 -0
- package/build/api/documentEnhancer.test.d.ts +0 -1
- package/build/api/documentEnhancer.test.js +0 -80
- package/build/manifest.test.d.ts +0 -1
- package/build/manifest.test.js +0 -66
- package/build/resources/documents.test.d.ts +0 -1
- package/build/resources/documents.test.js +0 -124
- package/build/server.test.d.ts +0 -1
- package/build/server.test.js +0 -54
- package/build/tools/boundedContent.test.d.ts +0 -1
- package/build/tools/boundedContent.test.js +0 -565
- package/build/tools/documents.test.d.ts +0 -1
- package/build/tools/documents.test.js +0 -658
- package/build/tools/mail.test.d.ts +0 -1
- package/build/tools/mail.test.js +0 -212
- package/build/tools/notes.test.d.ts +0 -1
- package/build/tools/notes.test.js +0 -177
- package/build/tools/schemaCompat.test.d.ts +0 -1
- package/build/tools/schemaCompat.test.js +0 -59
- package/build/tools/utils/monetary.test.d.ts +0 -1
- package/build/tools/utils/monetary.test.js +0 -25
- package/build/tools/utils/resourceUri.test.d.ts +0 -1
- package/build/tools/utils/resourceUri.test.js +0 -50
- package/build/tools/utils/selectFields.test.d.ts +0 -1
- 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
|
+
}
|