@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,193 @@
1
+ import { type IncomingMessage } from "node:http";
2
+ import type { SyncReport } from "./sync";
3
+ /**
4
+ * A webhook endpoint that keeps the vector index in step with document changes.
5
+ *
6
+ * WHY THIS EXISTS AT ALL, AND WHY IT IS NOT A POLLER. Paperless' own webhook
7
+ * action fires on document add/update, so the index can be told about a change
8
+ * instead of asking. That matters for one case the watermark structurally
9
+ * cannot see: a tag, correspondent or document-type edit goes through a
10
+ * queryset update on a through-table, `auto_now` never runs, and neither
11
+ * `count` nor `max(modified)` moves. A poller checks, sees nothing, and the
12
+ * stale metadata chunk stays searchable indefinitely. The event is the only
13
+ * signal that exists for that change.
14
+ *
15
+ * ⚠️ THIS IS NOT A REPLACEMENT FOR THE WATERMARK. See `IndexSync` for what the
16
+ * two scalars still cover: events that happened while this process was not
17
+ * running. A webhook only ever reports events it was alive to receive.
18
+ *
19
+ * ⚠️ AND IT CANNOT REPORT DELETES, because there is nothing to report. The
20
+ * trigger set in the server this was written against enumerates four types --
21
+ * consumption started, document added, document updated, scheduled -- and no
22
+ * delete type. The document `post_delete` receiver in the same source only
23
+ * feeds a different subsystem's index. So a deleted document produces no
24
+ * delivery, and the `count` half of the watermark remains the only thing that
25
+ * detects one. Nothing here pretends otherwise.
26
+ */
27
+ /**
28
+ * The header an operator puts the shared secret in, on the webhook action's
29
+ * `headers` field.
30
+ *
31
+ * A header rather than a query string because the secret belongs in one, and
32
+ * rather than a signature because a signature scheme would need a canonical
33
+ * request encoding that this receiver does not have; a shared secret over a
34
+ * header is the whole of what an operator can configure on that side.
35
+ */
36
+ export declare const SECRET_HEADER = "x-paperless-mcp-secret";
37
+ /**
38
+ * A body larger than this is refused rather than buffered.
39
+ *
40
+ * The payload is a handful of scalar fields -- the largest of them a title --
41
+ * so a megabyte is already two orders of magnitude of headroom. The cap is not
42
+ * about legitimate payloads; it is so that an unauthenticated flood, or a
43
+ * misconfigured operator pointing a different system at this port, cannot make
44
+ * the process hold an arbitrary amount of memory before the size is known.
45
+ */
46
+ export declare const MAX_BODY_BYTES: number;
47
+ /**
48
+ * How long the receiver waits for quiet before acting.
49
+ *
50
+ * A bulk edit -- "add this tag to these 200 documents" -- delivers one request
51
+ * per document within a few seconds. Acting on each one would run 200 syncs
52
+ * over a corpus that changed once. Waiting for the events to stop converts that
53
+ * into a single run naming every id, which is both cheaper and less likely to
54
+ * collide with itself.
55
+ */
56
+ export declare const DEFAULT_DEBOUNCE_MS = 2000;
57
+ /**
58
+ * What the receiver will run. Narrower than `IndexSync` so a test can count
59
+ * runs without a real index, and so the receiver cannot reach for a method the
60
+ * sync does not offer.
61
+ */
62
+ export interface SyncRunner {
63
+ run(opts?: {
64
+ force?: boolean;
65
+ documentIds?: number[];
66
+ }): Promise<SyncReport>;
67
+ readonly isRunning: boolean;
68
+ }
69
+ export interface ParsedEvent {
70
+ /** Every document id the delivery named. May be empty. */
71
+ ids: number[];
72
+ /**
73
+ * True when the delivery named no id at all.
74
+ *
75
+ * `use_params` with an empty `params` sends an empty body, and an operator
76
+ * who configured neither `params` nor `body` gets exactly that. Those events
77
+ * still mean "something changed", so they are acted on as a plain sync rather
78
+ * than dropped -- but they cannot be targeted, and saying so here is what
79
+ * keeps the caller from confusing "no ids" with "nothing happened".
80
+ */
81
+ idless: boolean;
82
+ }
83
+ /**
84
+ * Read document ids out of a delivery.
85
+ *
86
+ * ⚠️ THE BODY SHAPE IS NOT GUARANTEED. The sending side renders a template into
87
+ * a dictionary and then either serialises it as JSON or posts it form-encoded
88
+ * depending on one boolean. Both are legitimate configurations of the same
89
+ * feature, so both are parsed here. A body that is neither is not an error: it
90
+ * is an event that named no id, which is a state the caller already handles.
91
+ */
92
+ export declare function parseEvent(body: string, contentType: string | undefined): ParsedEvent;
93
+ /**
94
+ * Compare two strings without leaking their length or content through timing.
95
+ *
96
+ * `timingSafeEqual` refuses buffers of different length, so the length is
97
+ * compared first and the result is discarded -- a wrong-length secret and a
98
+ * wrong-content secret then both fail, and only the second comparison is
99
+ * constant-time. Returning early on a length mismatch would leak the secret's
100
+ * length, which is a small leak but a free one to avoid.
101
+ */
102
+ export declare function secretMatches(provided: string | undefined, expected: string): boolean;
103
+ /** Pull the presented secret out of the headers, in either accepted form. */
104
+ export declare function presentedSecret(headers: IncomingMessage["headers"]): string | undefined;
105
+ export interface WebhookOptions {
106
+ /** Shared secret. The receiver refuses to start without one. */
107
+ secret: string;
108
+ /** Port to listen on. 0 asks the OS for an ephemeral one, which tests use. */
109
+ port: number;
110
+ /**
111
+ * Address to bind.
112
+ *
113
+ * Defaults to loopback. It is deliberately NOT defaulted to a wildcard: an
114
+ * endpoint that writes to a local index should not be reachable from off the
115
+ * host unless the operator asked for it, and a containerised deployment is
116
+ * the case that genuinely needs the wider bind and therefore has to say so.
117
+ */
118
+ host?: string;
119
+ /** Quiet period before the coalesced run. */
120
+ debounceMs?: number;
121
+ /** Resolves the runner at fire time, so a failure to build it is not fatal. */
122
+ runner: () => SyncRunner;
123
+ /** Where to report. Defaults to stderr, matching the rest of this package. */
124
+ log?: (line: string) => void;
125
+ }
126
+ /**
127
+ * The receiver.
128
+ *
129
+ * Lifecycle: `start()` binds and returns once listening; `close()` stops the
130
+ * debounce timer first and then closes the server, so a run is never kicked off
131
+ * against a store that is being closed underneath it.
132
+ */
133
+ export declare class WebhookReceiver {
134
+ private readonly options;
135
+ private server?;
136
+ private timer?;
137
+ /** Ids heard since the last run. Empty means "something changed, location unknown". */
138
+ private readonly pending;
139
+ private pendingWasIdless;
140
+ private closed;
141
+ constructor(options: WebhookOptions);
142
+ private log;
143
+ /**
144
+ * Bind and listen.
145
+ *
146
+ * ⚠️ AN UNSET SECRET IS A REFUSAL, NOT A WARNING. This endpoint causes work --
147
+ * embedding calls against whatever provider the install points at. An
148
+ * unauthenticated trigger for that is a resource-abuse vector, and a warning
149
+ * in a log nobody reads is not a mitigation. Failing to start is.
150
+ */
151
+ start(): Promise<{
152
+ port: number;
153
+ host: string;
154
+ }>;
155
+ /**
156
+ * The port actually bound, or undefined when not listening.
157
+ *
158
+ * Reported rather than assumed: a test that binds port 0 needs the real port,
159
+ * and a caller that hardcoded the requested one would connect to nothing.
160
+ */
161
+ get boundPort(): number | undefined;
162
+ get isListening(): boolean;
163
+ /**
164
+ * Stop listening and cancel any pending run.
165
+ *
166
+ * The timer is cleared FIRST. A run scheduled microseconds ago would otherwise
167
+ * fire against a closed store, which is the same failure the background
168
+ * interval is stopped ahead of `close()` to avoid.
169
+ */
170
+ close(): Promise<void>;
171
+ private handle;
172
+ /** The event path, tolerating a trailing slash. */
173
+ private isEventPath;
174
+ /**
175
+ * Buffer the body under a cap, answering 413 when it is exceeded.
176
+ *
177
+ * Returns undefined when it has already responded. The connection is destroyed
178
+ * after the refusal because the unread remainder would otherwise be left in
179
+ * the socket for the next request to trip over.
180
+ */
181
+ private readBody;
182
+ private refuseTooLarge;
183
+ /**
184
+ * Fold an event into the pending set and (re)arm the quiet timer.
185
+ *
186
+ * Re-arming on every event is what makes the wait a quiet period rather than a
187
+ * fixed window: a burst that lasts longer than the debounce still produces one
188
+ * run, at the end of the burst.
189
+ */
190
+ private enqueue;
191
+ /** Run once for everything gathered, then clear. */
192
+ private flush;
193
+ }
@@ -0,0 +1,445 @@
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 __asyncValues = (this && this.__asyncValues) || function (o) {
12
+ if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
13
+ var m = o[Symbol.asyncIterator], i;
14
+ return m ? m.call(o) : (o = typeof __values === "function" ? __values(o) : o[Symbol.iterator](), i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i);
15
+ function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
16
+ function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
17
+ };
18
+ Object.defineProperty(exports, "__esModule", { value: true });
19
+ exports.WebhookReceiver = exports.DEFAULT_DEBOUNCE_MS = exports.MAX_BODY_BYTES = exports.SECRET_HEADER = void 0;
20
+ exports.parseEvent = parseEvent;
21
+ exports.secretMatches = secretMatches;
22
+ exports.presentedSecret = presentedSecret;
23
+ const node_http_1 = require("node:http");
24
+ const node_crypto_1 = require("node:crypto");
25
+ /**
26
+ * A webhook endpoint that keeps the vector index in step with document changes.
27
+ *
28
+ * WHY THIS EXISTS AT ALL, AND WHY IT IS NOT A POLLER. Paperless' own webhook
29
+ * action fires on document add/update, so the index can be told about a change
30
+ * instead of asking. That matters for one case the watermark structurally
31
+ * cannot see: a tag, correspondent or document-type edit goes through a
32
+ * queryset update on a through-table, `auto_now` never runs, and neither
33
+ * `count` nor `max(modified)` moves. A poller checks, sees nothing, and the
34
+ * stale metadata chunk stays searchable indefinitely. The event is the only
35
+ * signal that exists for that change.
36
+ *
37
+ * ⚠️ THIS IS NOT A REPLACEMENT FOR THE WATERMARK. See `IndexSync` for what the
38
+ * two scalars still cover: events that happened while this process was not
39
+ * running. A webhook only ever reports events it was alive to receive.
40
+ *
41
+ * ⚠️ AND IT CANNOT REPORT DELETES, because there is nothing to report. The
42
+ * trigger set in the server this was written against enumerates four types --
43
+ * consumption started, document added, document updated, scheduled -- and no
44
+ * delete type. The document `post_delete` receiver in the same source only
45
+ * feeds a different subsystem's index. So a deleted document produces no
46
+ * delivery, and the `count` half of the watermark remains the only thing that
47
+ * detects one. Nothing here pretends otherwise.
48
+ */
49
+ /**
50
+ * The header an operator puts the shared secret in, on the webhook action's
51
+ * `headers` field.
52
+ *
53
+ * A header rather than a query string because the secret belongs in one, and
54
+ * rather than a signature because a signature scheme would need a canonical
55
+ * request encoding that this receiver does not have; a shared secret over a
56
+ * header is the whole of what an operator can configure on that side.
57
+ */
58
+ exports.SECRET_HEADER = "x-paperless-mcp-secret";
59
+ /** Accept the secret as a bearer token too, because that needs no custom header. */
60
+ const AUTH_PREFIX = "Bearer ";
61
+ /**
62
+ * A body larger than this is refused rather than buffered.
63
+ *
64
+ * The payload is a handful of scalar fields -- the largest of them a title --
65
+ * so a megabyte is already two orders of magnitude of headroom. The cap is not
66
+ * about legitimate payloads; it is so that an unauthenticated flood, or a
67
+ * misconfigured operator pointing a different system at this port, cannot make
68
+ * the process hold an arbitrary amount of memory before the size is known.
69
+ */
70
+ exports.MAX_BODY_BYTES = 1024 * 1024;
71
+ /**
72
+ * How long the receiver waits for quiet before acting.
73
+ *
74
+ * A bulk edit -- "add this tag to these 200 documents" -- delivers one request
75
+ * per document within a few seconds. Acting on each one would run 200 syncs
76
+ * over a corpus that changed once. Waiting for the events to stop converts that
77
+ * into a single run naming every id, which is both cheaper and less likely to
78
+ * collide with itself.
79
+ */
80
+ exports.DEFAULT_DEBOUNCE_MS = 2000;
81
+ /**
82
+ * Read document ids out of a delivery.
83
+ *
84
+ * ⚠️ THE BODY SHAPE IS NOT GUARANTEED. The sending side renders a template into
85
+ * a dictionary and then either serialises it as JSON or posts it form-encoded
86
+ * depending on one boolean. Both are legitimate configurations of the same
87
+ * feature, so both are parsed here. A body that is neither is not an error: it
88
+ * is an event that named no id, which is a state the caller already handles.
89
+ */
90
+ function parseEvent(body, contentType) {
91
+ const type = (contentType !== null && contentType !== void 0 ? contentType : "").toLowerCase();
92
+ const fields = {};
93
+ if (type.includes("json")) {
94
+ try {
95
+ const parsed = JSON.parse(body);
96
+ if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
97
+ Object.assign(fields, parsed);
98
+ }
99
+ }
100
+ catch (_a) {
101
+ // A JSON-labelled body that is not JSON. Fall through: no ids, and the
102
+ // caller runs a plain sync rather than refusing an event it received.
103
+ }
104
+ }
105
+ else if (type.includes("urlencoded") || (!type && body.includes("="))) {
106
+ for (const [key, value] of new URLSearchParams(body))
107
+ fields[key] = value;
108
+ }
109
+ else if (body.trim().startsWith("{")) {
110
+ // No content type, or an unexpected one, but the body is plainly JSON.
111
+ try {
112
+ const parsed = JSON.parse(body);
113
+ if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
114
+ Object.assign(fields, parsed);
115
+ }
116
+ }
117
+ catch (_b) {
118
+ // Same reasoning as above.
119
+ }
120
+ }
121
+ const ids = [];
122
+ // Two names because the sending side offers the document's primary key under
123
+ // a short alias and a longer one, and an operator may place either in the
124
+ // template. Both are the same value.
125
+ for (const key of ["id", "doc_id", "document_id"]) {
126
+ const raw = fields[key];
127
+ const value = typeof raw === "number" ? raw : Number.parseInt(String(raw !== null && raw !== void 0 ? raw : ""), 10);
128
+ if (Number.isInteger(value) && value > 0 && !ids.includes(value))
129
+ ids.push(value);
130
+ }
131
+ return { ids, idless: ids.length === 0 };
132
+ }
133
+ /**
134
+ * Compare two strings without leaking their length or content through timing.
135
+ *
136
+ * `timingSafeEqual` refuses buffers of different length, so the length is
137
+ * compared first and the result is discarded -- a wrong-length secret and a
138
+ * wrong-content secret then both fail, and only the second comparison is
139
+ * constant-time. Returning early on a length mismatch would leak the secret's
140
+ * length, which is a small leak but a free one to avoid.
141
+ */
142
+ function secretMatches(provided, expected) {
143
+ if (typeof provided !== "string")
144
+ return false;
145
+ const a = Buffer.from(provided, "utf8");
146
+ const b = Buffer.from(expected, "utf8");
147
+ if (a.length !== b.length) {
148
+ // Still do work proportional to the expected value, so the fast path is not
149
+ // distinguishable by timing from the slow one.
150
+ (0, node_crypto_1.timingSafeEqual)(b, b);
151
+ return false;
152
+ }
153
+ return (0, node_crypto_1.timingSafeEqual)(a, b);
154
+ }
155
+ /** Pull the presented secret out of the headers, in either accepted form. */
156
+ function presentedSecret(headers) {
157
+ const direct = headers[exports.SECRET_HEADER];
158
+ if (typeof direct === "string" && direct.length > 0)
159
+ return direct;
160
+ const authorization = headers.authorization;
161
+ if (typeof authorization === "string" && authorization.startsWith(AUTH_PREFIX)) {
162
+ return authorization.slice(AUTH_PREFIX.length);
163
+ }
164
+ return undefined;
165
+ }
166
+ /**
167
+ * The receiver.
168
+ *
169
+ * Lifecycle: `start()` binds and returns once listening; `close()` stops the
170
+ * debounce timer first and then closes the server, so a run is never kicked off
171
+ * against a store that is being closed underneath it.
172
+ */
173
+ class WebhookReceiver {
174
+ constructor(options) {
175
+ /** Ids heard since the last run. Empty means "something changed, location unknown". */
176
+ this.pending = new Set();
177
+ this.pendingWasIdless = false;
178
+ this.closed = false;
179
+ this.options = options;
180
+ }
181
+ log(line) {
182
+ var _a;
183
+ ((_a = this.options.log) !== null && _a !== void 0 ? _a : ((l) => console.error(`[paperless-mcp] webhook: ${l}`)))(line);
184
+ }
185
+ /**
186
+ * Bind and listen.
187
+ *
188
+ * ⚠️ AN UNSET SECRET IS A REFUSAL, NOT A WARNING. This endpoint causes work --
189
+ * embedding calls against whatever provider the install points at. An
190
+ * unauthenticated trigger for that is a resource-abuse vector, and a warning
191
+ * in a log nobody reads is not a mitigation. Failing to start is.
192
+ */
193
+ start() {
194
+ return __awaiter(this, void 0, void 0, function* () {
195
+ var _a;
196
+ if (this.options.secret.length === 0) {
197
+ throw new Error("The webhook receiver needs a shared secret. Set " +
198
+ "PAPERLESS_MCP_WEBHOOK_SECRET to a value the Paperless workflow will " +
199
+ "send in the " +
200
+ exports.SECRET_HEADER +
201
+ " header, or leave PAPERLESS_MCP_WEBHOOK_PORT unset to keep the " +
202
+ "receiver off.");
203
+ }
204
+ if (this.server) {
205
+ throw new Error("The webhook receiver is already started.");
206
+ }
207
+ const host = (_a = this.options.host) !== null && _a !== void 0 ? _a : "127.0.0.1";
208
+ const server = (0, node_http_1.createServer)((req, res) => {
209
+ void this.handle(req, res);
210
+ });
211
+ this.server = server;
212
+ yield new Promise((resolve, reject) => {
213
+ const onError = (err) => {
214
+ server.removeListener("listening", onListening);
215
+ this.server = undefined;
216
+ reject(err);
217
+ };
218
+ const onListening = () => {
219
+ server.removeListener("error", onError);
220
+ resolve();
221
+ };
222
+ server.once("error", onError);
223
+ server.once("listening", onListening);
224
+ server.listen(this.options.port, host);
225
+ });
226
+ const address = server.address();
227
+ const bound = typeof address === "object" && address !== null ? address.port : this.options.port;
228
+ this.log(`listening on ${host}:${bound}`);
229
+ return { port: bound, host };
230
+ });
231
+ }
232
+ /**
233
+ * The port actually bound, or undefined when not listening.
234
+ *
235
+ * Reported rather than assumed: a test that binds port 0 needs the real port,
236
+ * and a caller that hardcoded the requested one would connect to nothing.
237
+ */
238
+ get boundPort() {
239
+ var _a;
240
+ const address = (_a = this.server) === null || _a === void 0 ? void 0 : _a.address();
241
+ if (typeof address === "object" && address !== null)
242
+ return address.port;
243
+ return undefined;
244
+ }
245
+ get isListening() {
246
+ var _a;
247
+ return ((_a = this.server) === null || _a === void 0 ? void 0 : _a.listening) === true;
248
+ }
249
+ /**
250
+ * Stop listening and cancel any pending run.
251
+ *
252
+ * The timer is cleared FIRST. A run scheduled microseconds ago would otherwise
253
+ * fire against a closed store, which is the same failure the background
254
+ * interval is stopped ahead of `close()` to avoid.
255
+ */
256
+ close() {
257
+ return __awaiter(this, void 0, void 0, function* () {
258
+ this.closed = true;
259
+ if (this.timer)
260
+ clearTimeout(this.timer);
261
+ this.timer = undefined;
262
+ this.pending.clear();
263
+ this.pendingWasIdless = false;
264
+ const server = this.server;
265
+ this.server = undefined;
266
+ if (!server)
267
+ return;
268
+ yield new Promise((resolve) => {
269
+ // Idle keep-alive sockets would hold the server open for as long as the
270
+ // peer keeps them; dropping them makes close() mean closed.
271
+ const closeAll = () => {
272
+ var _a;
273
+ (_a = server.closeAllConnections) === null || _a === void 0 ? void 0 : _a.call(server);
274
+ resolve();
275
+ };
276
+ server.close(() => resolve());
277
+ closeAll();
278
+ });
279
+ });
280
+ }
281
+ handle(req, res) {
282
+ return __awaiter(this, void 0, void 0, function* () {
283
+ var _a;
284
+ try {
285
+ if (req.method !== "POST" || !this.isEventPath(req.url)) {
286
+ // A health probe on the root is useful and harmless; anything else is
287
+ // not this endpoint's business.
288
+ res.writeHead(req.method === "GET" ? 200 : 404, { "content-type": "application/json" });
289
+ res.end(JSON.stringify({ ok: req.method === "GET", path: (_a = req.url) !== null && _a !== void 0 ? _a : "" }));
290
+ return;
291
+ }
292
+ if (!secretMatches(presentedSecret(req.headers), this.options.secret)) {
293
+ // No sync, no body buffering, no detail. 401 and close.
294
+ res.writeHead(401, { "content-type": "application/json" });
295
+ res.end(JSON.stringify({ error: "unauthorized" }));
296
+ return;
297
+ }
298
+ const body = yield this.readBody(req, res);
299
+ if (body === undefined)
300
+ return; // readBody already answered (413 or aborted).
301
+ const event = parseEvent(body, req.headers["content-type"]);
302
+ // ⚠️ ACKNOWLEDGE BEFORE WORKING. The sending side has a five-second
303
+ // timeout and retries on failure, so a receiver that embedded first and
304
+ // answered after would turn one edit into up to four deliveries of the
305
+ // same event. Acknowledging immediately is what makes those retries
306
+ // harmless -- and the coalescing below is what makes the duplicates cheap.
307
+ res.writeHead(202, { "content-type": "application/json" });
308
+ res.end(JSON.stringify({ accepted: true }));
309
+ this.enqueue(event);
310
+ }
311
+ catch (err) {
312
+ this.log(`request failed: ${err instanceof Error ? err.message : String(err)}`);
313
+ if (!res.headersSent) {
314
+ res.writeHead(500, { "content-type": "application/json" });
315
+ res.end(JSON.stringify({ error: "internal" }));
316
+ }
317
+ else {
318
+ res.end();
319
+ }
320
+ }
321
+ });
322
+ }
323
+ /** The event path, tolerating a trailing slash. */
324
+ isEventPath(url) {
325
+ if (!url)
326
+ return false;
327
+ const path = url.split("?")[0];
328
+ return path === "/webhook/paperless" || path === "/webhook/paperless/";
329
+ }
330
+ /**
331
+ * Buffer the body under a cap, answering 413 when it is exceeded.
332
+ *
333
+ * Returns undefined when it has already responded. The connection is destroyed
334
+ * after the refusal because the unread remainder would otherwise be left in
335
+ * the socket for the next request to trip over.
336
+ */
337
+ readBody(req, res) {
338
+ return __awaiter(this, void 0, void 0, function* () {
339
+ var _a, req_1, req_1_1;
340
+ var _b, e_1, _c, _d;
341
+ var _e;
342
+ const declared = Number.parseInt(String((_e = req.headers["content-length"]) !== null && _e !== void 0 ? _e : ""), 10);
343
+ if (Number.isFinite(declared) && declared > exports.MAX_BODY_BYTES) {
344
+ this.refuseTooLarge(res);
345
+ return undefined;
346
+ }
347
+ const chunks = [];
348
+ let total = 0;
349
+ try {
350
+ try {
351
+ for (_a = true, req_1 = __asyncValues(req); req_1_1 = yield req_1.next(), _b = req_1_1.done, !_b; _a = true) {
352
+ _d = req_1_1.value;
353
+ _a = false;
354
+ const chunk = _d;
355
+ const buf = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
356
+ total += buf.length;
357
+ if (total > exports.MAX_BODY_BYTES) {
358
+ this.refuseTooLarge(res);
359
+ return undefined;
360
+ }
361
+ chunks.push(buf);
362
+ }
363
+ }
364
+ catch (e_1_1) { e_1 = { error: e_1_1 }; }
365
+ finally {
366
+ try {
367
+ if (!_a && !_b && (_c = req_1.return)) yield _c.call(req_1);
368
+ }
369
+ finally { if (e_1) throw e_1.error; }
370
+ }
371
+ }
372
+ catch (err) {
373
+ // A client that vanished mid-body is not this endpoint's failure.
374
+ this.log(`body read aborted: ${err instanceof Error ? err.message : String(err)}`);
375
+ return undefined;
376
+ }
377
+ return Buffer.concat(chunks).toString("utf8");
378
+ });
379
+ }
380
+ refuseTooLarge(res) {
381
+ // Declared oversize is refused without reading a byte; an oversize that
382
+ // arrived unannounced has already had its prefix consumed, so the socket is
383
+ // torn down rather than trying to resynchronise it.
384
+ res.writeHead(413, { "content-type": "application/json", connection: "close" });
385
+ res.end(JSON.stringify({ error: "payload too large", limit: exports.MAX_BODY_BYTES }));
386
+ }
387
+ /**
388
+ * Fold an event into the pending set and (re)arm the quiet timer.
389
+ *
390
+ * Re-arming on every event is what makes the wait a quiet period rather than a
391
+ * fixed window: a burst that lasts longer than the debounce still produces one
392
+ * run, at the end of the burst.
393
+ */
394
+ enqueue(event) {
395
+ var _a, _b, _c;
396
+ if (this.closed)
397
+ return;
398
+ if (event.idless)
399
+ this.pendingWasIdless = true;
400
+ for (const id of event.ids)
401
+ this.pending.add(id);
402
+ if (this.timer)
403
+ clearTimeout(this.timer);
404
+ this.timer = setTimeout(() => {
405
+ this.timer = undefined;
406
+ void this.flush();
407
+ }, (_a = this.options.debounceMs) !== null && _a !== void 0 ? _a : exports.DEFAULT_DEBOUNCE_MS);
408
+ // A pending run must not keep the process alive on its own; the MCP client
409
+ // owns this process's lifetime.
410
+ (_c = (_b = this.timer).unref) === null || _c === void 0 ? void 0 : _c.call(_b);
411
+ }
412
+ /** Run once for everything gathered, then clear. */
413
+ flush() {
414
+ return __awaiter(this, void 0, void 0, function* () {
415
+ var _a;
416
+ if (this.closed)
417
+ return;
418
+ // Snapshot and clear FIRST: events arriving during the run belong to the
419
+ // next one, and a set mutated mid-iteration by a later delivery would make
420
+ // the run's target list depend on network timing.
421
+ const ids = [...this.pending];
422
+ const idless = this.pendingWasIdless;
423
+ this.pending.clear();
424
+ this.pendingWasIdless = false;
425
+ try {
426
+ const runner = this.options.runner();
427
+ // ⚠️ An idless event means "something changed, and the sender did not say
428
+ // what". Passing no ids makes the run consult the full diff, which is the
429
+ // expensive-but-correct answer; passing an empty target list would look
430
+ // like "nothing to do" and do nothing.
431
+ const opts = ids.length > 0 ? { documentIds: ids } : {};
432
+ const report = yield runner.run(opts);
433
+ this.log(`run finished: ${ids.length > 0 ? `${ids.length} targeted` : idless ? "untargeted" : "no-op"}` +
434
+ `, +${report.added} ~${report.updated} -${report.deleted}` +
435
+ (report.skipped ? ` (skipped: ${(_a = report.skipReason) !== null && _a !== void 0 ? _a : "no reason given"})` : ""));
436
+ }
437
+ catch (err) {
438
+ // A failed run must not take down the receiver: the next event retries,
439
+ // and the watermark still converges on the next start.
440
+ this.log(`run failed: ${err instanceof Error ? err.message : String(err)}`);
441
+ }
442
+ });
443
+ }
444
+ }
445
+ exports.WebhookReceiver = WebhookReceiver;
package/build/server.d.ts CHANGED
@@ -22,3 +22,32 @@ export interface ResolveTokenOptions {
22
22
  }
23
23
  export declare function getBearerToken(req: express.Request, options: ResolveTokenOptions): string | undefined;
24
24
  export declare function sendUnauthorized(res: express.Response): void;
25
+ /**
26
+ * Makes the `tools/list` ordering a property of the tool SET rather than of the
27
+ * order the registration functions happened to run in.
28
+ *
29
+ * The MCP spec: "Servers SHOULD return tools in a deterministic order (i.e.,
30
+ * the same ordering across requests when the underlying set of tools has not
31
+ * changed). Deterministic ordering enables clients to reliably cache the tool
32
+ * list and improves LLM prompt cache hit rates when tools are included in
33
+ * model context."
34
+ *
35
+ * Registration order is already stable today -- module evaluation order is
36
+ * deterministic in Node and nothing here reads a directory or races. But that
37
+ * makes determinism an ACCIDENT of the call order, not a guarantee. Two things
38
+ * break it without anyone intending it:
39
+ * - reordering a `register*Tools(...)` call, or moving a `server.tool(...)`
40
+ * call within one, silently reshuffles the list;
41
+ * - `RegisteredTool.update({ name })` is a delete-then-add, so a rename
42
+ * moves that tool to the end of the list.
43
+ * Sorting at the point the list is returned makes both of those no-ops.
44
+ *
45
+ * The comparator is `a.name < b.name`, NOT `localeCompare`: locale collation
46
+ * varies with the host's ICU data, which would trade one non-determinism for a
47
+ * subtler one. Code-unit comparison is identical on every Node build.
48
+ *
49
+ * If the SDK ever stops holding the handler in `_requestHandlers`, this returns
50
+ * without wrapping and the list falls back to registration order -- still
51
+ * deterministic, just no longer enforced. It never throws.
52
+ */
53
+ export declare function enforceDeterministicToolOrder(server: McpServer): void;