@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,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;
|