@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
|
@@ -1,3 +1,8 @@
|
|
|
1
1
|
import { ToolCallback } from "@modelcontextprotocol/sdk/server/mcp";
|
|
2
2
|
import { ZodRawShape } from "zod";
|
|
3
|
+
/**
|
|
4
|
+
* Wraps a tool callback so a thrown error reaches the model as an actionable
|
|
5
|
+
* sentence. The signature and generic parameters are unchanged so the ~48 call
|
|
6
|
+
* sites keep typechecking untouched.
|
|
7
|
+
*/
|
|
3
8
|
export declare const withErrorHandling: <Args extends ZodRawShape>(cb: ToolCallback<Args>) => ToolCallback<Args>;
|
|
@@ -10,21 +10,294 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
|
|
|
10
10
|
};
|
|
11
11
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
12
12
|
exports.withErrorHandling = void 0;
|
|
13
|
+
/**
|
|
14
|
+
* Turns a thrown error into a sentence a model can act on, then rethrows it.
|
|
15
|
+
*
|
|
16
|
+
* The THROW is load-bearing and must not change: the MCP SDK catches it and
|
|
17
|
+
* converts it into a tool *execution* error (`isError: true`), which the spec
|
|
18
|
+
* requires for input-validation failures because "clients SHOULD provide tool
|
|
19
|
+
* execution errors to language models to enable self-correction". A JSON-RPC
|
|
20
|
+
* protocol error is documented as "less likely to result in successful
|
|
21
|
+
* recovery".
|
|
22
|
+
*
|
|
23
|
+
* The defect this fixes was the payload, not the mechanism. The old form threw
|
|
24
|
+
* `JSON.stringify({error, responseData, status})` -- a blob that names no field
|
|
25
|
+
* and suggests no fix. The spec's own example of a good execution error is a
|
|
26
|
+
* sentence: "Invalid departure date: must be in the future. Current date is
|
|
27
|
+
* 08/08/2025."
|
|
28
|
+
*
|
|
29
|
+
* Two hazards are handled explicitly rather than assumed away, both measured
|
|
30
|
+
* against a live axios error on this repo:
|
|
31
|
+
* 1. `err.config.headers.Authorization` carries the API token, and it
|
|
32
|
+
* survives `JSON.stringify(err)` and `err.toJSON()`. We never serialise
|
|
33
|
+
* the config, and we additionally scrub any harvested credential value
|
|
34
|
+
* out of the final sentence in case the server echoes it back.
|
|
35
|
+
* 2. `err.response` is circular. `JSON.stringify` on it throws, which would
|
|
36
|
+
* replace a useful error with a TypeError from inside the handler.
|
|
37
|
+
*/
|
|
38
|
+
/** Cap on any quoted server detail, so a 200-field validation body stays readable. */
|
|
39
|
+
const MAX_DETAIL_CHARS = 240;
|
|
40
|
+
/** Headers whose values are credentials; never emitted, always scrubbed. */
|
|
41
|
+
const SENSITIVE_HEADER = /^(authorization|proxy-authorization|cookie|set-cookie|x-api-key|api-key)$/i;
|
|
42
|
+
/** Error codes that mean "we never got a response". */
|
|
43
|
+
const UNREACHABLE_CODES = new Set([
|
|
44
|
+
"ECONNREFUSED",
|
|
45
|
+
"ECONNRESET",
|
|
46
|
+
"ENOTFOUND",
|
|
47
|
+
"EAI_AGAIN",
|
|
48
|
+
"EHOSTUNREACH",
|
|
49
|
+
"ENETUNREACH",
|
|
50
|
+
"EPIPE",
|
|
51
|
+
"ERR_NETWORK",
|
|
52
|
+
]);
|
|
53
|
+
/** Error codes that mean "we gave up waiting". */
|
|
54
|
+
const TIMEOUT_CODES = new Set(["ECONNABORTED", "ETIMEDOUT", "UND_ERR_CONNECT_TIMEOUT"]);
|
|
55
|
+
function truncate(value, max) {
|
|
56
|
+
const collapsed = value.replace(/\s+/g, " ").trim();
|
|
57
|
+
return collapsed.length <= max ? collapsed : `${collapsed.slice(0, Math.max(0, max - 1))}…`;
|
|
58
|
+
}
|
|
59
|
+
/** Truncates, then drops a trailing full stop so callers can punctuate once. */
|
|
60
|
+
function sentenceFragment(value, max) {
|
|
61
|
+
return truncate(value, max).replace(/[.\u3002]+$/, "");
|
|
62
|
+
}
|
|
63
|
+
/**
|
|
64
|
+
* JSON.stringify that cannot throw and cannot recurse forever. Circular
|
|
65
|
+
* references become "[circular]"; a value that still defeats serialisation
|
|
66
|
+
* falls back to String(), and only a String() that also throws returns
|
|
67
|
+
* undefined. Never call JSON.stringify directly in this file.
|
|
68
|
+
*/
|
|
69
|
+
function safeStringify(value, max) {
|
|
70
|
+
if (value === undefined || value === null)
|
|
71
|
+
return undefined;
|
|
72
|
+
if (typeof value === "string")
|
|
73
|
+
return truncate(value, max);
|
|
74
|
+
const seen = new WeakSet();
|
|
75
|
+
let out;
|
|
76
|
+
try {
|
|
77
|
+
out = JSON.stringify(value, (_key, val) => {
|
|
78
|
+
if (typeof val === "object" && val !== null) {
|
|
79
|
+
if (seen.has(val))
|
|
80
|
+
return "[circular]";
|
|
81
|
+
seen.add(val);
|
|
82
|
+
}
|
|
83
|
+
return val;
|
|
84
|
+
});
|
|
85
|
+
}
|
|
86
|
+
catch (_a) {
|
|
87
|
+
try {
|
|
88
|
+
out = String(value);
|
|
89
|
+
}
|
|
90
|
+
catch (_b) {
|
|
91
|
+
return undefined;
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
return out === undefined ? undefined : truncate(out, max);
|
|
95
|
+
}
|
|
96
|
+
/**
|
|
97
|
+
* Harvests credential values worth scrubbing out of anything we emit.
|
|
98
|
+
*
|
|
99
|
+
* Measured hazard, not a theoretical one: an axios error carries the request
|
|
100
|
+
* config, and `config.headers.Authorization` still holds `Token <api-token>`
|
|
101
|
+
* after the failure. Anything that serialises the whole error object publishes
|
|
102
|
+
* the credential. We never emit the config, but a server can echo a header back
|
|
103
|
+
* in an error body, so the values are scrubbed from the final sentence too.
|
|
104
|
+
*/
|
|
105
|
+
function credentialValues(err) {
|
|
106
|
+
var _a;
|
|
107
|
+
const found = new Set();
|
|
108
|
+
const headers = (_a = err === null || err === void 0 ? void 0 : err.config) === null || _a === void 0 ? void 0 : _a.headers;
|
|
109
|
+
if (!headers || typeof headers !== "object")
|
|
110
|
+
return [];
|
|
111
|
+
const entries = typeof headers.toJSON === "function"
|
|
112
|
+
? Object.entries(headers.toJSON())
|
|
113
|
+
: Object.entries(headers);
|
|
114
|
+
for (const [name, value] of entries) {
|
|
115
|
+
if (typeof value !== "string" || value.length < 4)
|
|
116
|
+
continue;
|
|
117
|
+
if (!SENSITIVE_HEADER.test(name))
|
|
118
|
+
continue;
|
|
119
|
+
// `Token abc123` -> scrub the bare credential as well as the whole header.
|
|
120
|
+
found.add(value);
|
|
121
|
+
const stripped = value.replace(/^(Bearer|Token|Basic)\s+/i, "").trim();
|
|
122
|
+
if (stripped.length >= 8)
|
|
123
|
+
found.add(stripped);
|
|
124
|
+
}
|
|
125
|
+
return [...found];
|
|
126
|
+
}
|
|
127
|
+
function scrub(text, secrets) {
|
|
128
|
+
let out = text;
|
|
129
|
+
for (const secret of secrets) {
|
|
130
|
+
if (secret && out.includes(secret))
|
|
131
|
+
out = out.split(secret).join("[redacted]");
|
|
132
|
+
}
|
|
133
|
+
return out;
|
|
134
|
+
}
|
|
135
|
+
/**
|
|
136
|
+
* Names the host a request was aimed at, from the axios config. Returns
|
|
137
|
+
* undefined rather than a guess when the config carries no usable URL.
|
|
138
|
+
*/
|
|
139
|
+
function requestHost(err) {
|
|
140
|
+
const config = err === null || err === void 0 ? void 0 : err.config;
|
|
141
|
+
if (!config)
|
|
142
|
+
return undefined;
|
|
143
|
+
const candidates = [config.url, config.baseURL];
|
|
144
|
+
for (const candidate of candidates) {
|
|
145
|
+
if (typeof candidate !== "string")
|
|
146
|
+
continue;
|
|
147
|
+
try {
|
|
148
|
+
const parsed = new URL(candidate);
|
|
149
|
+
return parsed.host;
|
|
150
|
+
}
|
|
151
|
+
catch (_a) {
|
|
152
|
+
/* relative url against a separate baseURL -- try the pair below */
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
const { baseURL, url } = config;
|
|
156
|
+
if (typeof baseURL === "string" && typeof url === "string") {
|
|
157
|
+
try {
|
|
158
|
+
return new URL(url, baseURL).host;
|
|
159
|
+
}
|
|
160
|
+
catch (_b) {
|
|
161
|
+
return undefined;
|
|
162
|
+
}
|
|
163
|
+
}
|
|
164
|
+
return undefined;
|
|
165
|
+
}
|
|
166
|
+
/**
|
|
167
|
+
* Extracts `field -> detail` pairs from a DRF-style validation body.
|
|
168
|
+
*
|
|
169
|
+
* paperless-ngx is Django REST Framework, so a 400 normally arrives as
|
|
170
|
+
* `{"field": ["message"]}` or `{"non_field_errors": ["message"]}`. Naming the
|
|
171
|
+
* field is the whole point of this function: an agent that cannot see which
|
|
172
|
+
* field was wrong cannot fix its call.
|
|
173
|
+
*/
|
|
174
|
+
function fieldDetails(body, depth = 0) {
|
|
175
|
+
if (depth > 2 || !body || typeof body !== "object" || Array.isArray(body))
|
|
176
|
+
return [];
|
|
177
|
+
const pairs = [];
|
|
178
|
+
for (const [field, value] of Object.entries(body)) {
|
|
179
|
+
if (typeof value === "string") {
|
|
180
|
+
pairs.push([field, sentenceFragment(value, MAX_DETAIL_CHARS)]);
|
|
181
|
+
continue;
|
|
182
|
+
}
|
|
183
|
+
if (Array.isArray(value)) {
|
|
184
|
+
const parts = value
|
|
185
|
+
.map((item) => { var _a; return typeof item === "string" ? item : (_a = safeStringify(item, MAX_DETAIL_CHARS)) !== null && _a !== void 0 ? _a : ""; })
|
|
186
|
+
.filter((item) => item.length > 0);
|
|
187
|
+
if (parts.length > 0)
|
|
188
|
+
pairs.push([field, sentenceFragment(parts.join("; "), MAX_DETAIL_CHARS)]);
|
|
189
|
+
continue;
|
|
190
|
+
}
|
|
191
|
+
// Nested shape, e.g. {"custom_fields": {"12": ["bad"]}} -- flatten one level.
|
|
192
|
+
for (const [childField, childValue] of fieldDetails(value, depth + 1)) {
|
|
193
|
+
pairs.push([`${field}.${childField}`, childValue]);
|
|
194
|
+
}
|
|
195
|
+
}
|
|
196
|
+
return pairs;
|
|
197
|
+
}
|
|
198
|
+
/** Renders the field list as `field: detail; field: detail`, capped. */
|
|
199
|
+
function describeFields(body) {
|
|
200
|
+
const pairs = fieldDetails(body);
|
|
201
|
+
if (pairs.length === 0)
|
|
202
|
+
return undefined;
|
|
203
|
+
const rendered = pairs.map(([field, detail]) => `${field}: ${detail}`).join("; ");
|
|
204
|
+
return sentenceFragment(rendered, MAX_DETAIL_CHARS);
|
|
205
|
+
}
|
|
206
|
+
/**
|
|
207
|
+
* Builds the caller-facing sentence. Every branch names what went wrong AND
|
|
208
|
+
* what to do about it, because that is what makes the error actionable; the
|
|
209
|
+
* original message is always appended so nothing is lost.
|
|
210
|
+
*/
|
|
211
|
+
function buildMessage(err) {
|
|
212
|
+
var _a, _b, _c;
|
|
213
|
+
const status = (_a = err === null || err === void 0 ? void 0 : err.response) === null || _a === void 0 ? void 0 : _a.status;
|
|
214
|
+
const body = (_b = err === null || err === void 0 ? void 0 : err.response) === null || _b === void 0 ? void 0 : _b.data;
|
|
215
|
+
const code = err === null || err === void 0 ? void 0 : err.code;
|
|
216
|
+
const original = err instanceof Error ? err.message : String(err !== null && err !== void 0 ? err : "Unknown error");
|
|
217
|
+
const host = requestHost(err);
|
|
218
|
+
// --- No response. Two very different things land here, and conflating them
|
|
219
|
+
// is worse than the original defect: a LOCAL validation error thrown by a
|
|
220
|
+
// tool body (e.g. documents.ts "Confirmation required for destructive
|
|
221
|
+
// operation. Set confirm: true to proceed.") also carries no `response`.
|
|
222
|
+
// Reporting that as a network problem tells the caller to check its base URL
|
|
223
|
+
// when the fix is a different argument. So a transport failure is only
|
|
224
|
+
// claimed when the error actually looks like one -- an axios error, or a
|
|
225
|
+
// recognised network code -- and anything else is passed through, because a
|
|
226
|
+
// locally-authored message is already a sentence aimed at the model.
|
|
227
|
+
if (status === undefined) {
|
|
228
|
+
const isTransportError = Boolean(err === null || err === void 0 ? void 0 : err.isAxiosError) ||
|
|
229
|
+
(typeof code === "string" &&
|
|
230
|
+
(TIMEOUT_CODES.has(code) || UNREACHABLE_CODES.has(code))) ||
|
|
231
|
+
Boolean(err === null || err === void 0 ? void 0 : err.config);
|
|
232
|
+
if (!isTransportError) {
|
|
233
|
+
return original;
|
|
234
|
+
}
|
|
235
|
+
if (typeof code === "string" && TIMEOUT_CODES.has(code)) {
|
|
236
|
+
const where = host ? ` at ${host}` : "";
|
|
237
|
+
return `Request to the paperless-ngx server${where} timed out. The server may be overloaded or unreachable -- retry, and if it keeps timing out check that the server is up. (${original})`;
|
|
238
|
+
}
|
|
239
|
+
if (typeof code === "string" && UNREACHABLE_CODES.has(code)) {
|
|
240
|
+
const where = host ? ` at ${host}` : "";
|
|
241
|
+
return `Could not reach the paperless-ngx server${where} (${code}). The host may be down, misconfigured, or unreachable from here -- verify the base URL and that the server is running. (${original})`;
|
|
242
|
+
}
|
|
243
|
+
const where = host ? ` at ${host}` : "";
|
|
244
|
+
return `The request to the paperless-ngx server${where} failed before any response was received. This is a connection problem, not a problem with your arguments. (${original})`;
|
|
245
|
+
}
|
|
246
|
+
// --- Server returned an error status.
|
|
247
|
+
const fields = describeFields(body);
|
|
248
|
+
const quote = fields !== null && fields !== void 0 ? fields : ((_c = safeStringify(body, MAX_DETAIL_CHARS)) !== null && _c !== void 0 ? _c : "").replace(/[.\u3002]+$/, "");
|
|
249
|
+
if (status === 400 || status === 422) {
|
|
250
|
+
if (fields) {
|
|
251
|
+
return `The paperless-ngx server rejected the request as invalid -- ${fields}. Fix those field(s) and retry. (HTTP ${status})`;
|
|
252
|
+
}
|
|
253
|
+
if (quote) {
|
|
254
|
+
return `The paperless-ngx server rejected the request as invalid: ${quote}. Check the document ids, field names and value formats, then retry. (HTTP ${status})`;
|
|
255
|
+
}
|
|
256
|
+
return `The paperless-ngx server rejected the request as invalid and returned no detail. Check the argument names and value formats against the tool's input schema, then retry. (HTTP ${status})`;
|
|
257
|
+
}
|
|
258
|
+
if (status === 401) {
|
|
259
|
+
return `The paperless-ngx server rejected the credentials (HTTP 401): the API token was not accepted, or none was sent. This is a server configuration problem, not something a different tool argument will fix. (${original})`;
|
|
260
|
+
}
|
|
261
|
+
if (status === 403) {
|
|
262
|
+
const detail = quote ? ` Server said: ${quote}.` : "";
|
|
263
|
+
return `The paperless-ngx server refused this operation as forbidden (HTTP 403): the token is valid but lacks permission for it.${detail} Do not retry unchanged -- use a token with the required permission or ask the server owner to grant it. (${original})`;
|
|
264
|
+
}
|
|
265
|
+
if (status === 404) {
|
|
266
|
+
const detail = quote ? ` Server said: ${quote}.` : "";
|
|
267
|
+
return `The paperless-ngx server found nothing at the requested path (HTTP 404).${detail} A document, tag, correspondent or other id in the arguments does not exist -- most often it was deleted, or the id belongs to a different object type. Verify the id with a list tool before retrying. (${original})`;
|
|
268
|
+
}
|
|
269
|
+
if (status === 409) {
|
|
270
|
+
const detail = quote ? ` Server said: ${quote}.` : "";
|
|
271
|
+
return `The paperless-ngx server reported a conflict (HTTP 409).${detail} The object likely changed or already exists; re-read it, then retry. (${original})`;
|
|
272
|
+
}
|
|
273
|
+
if (status === 429) {
|
|
274
|
+
const detail = quote ? ` Server said: ${quote}.` : "";
|
|
275
|
+
return `The paperless-ngx server is rate limiting requests (HTTP 429).${detail} Wait briefly and retry the same call; reduce how many calls you issue in parallel. (${original})`;
|
|
276
|
+
}
|
|
277
|
+
if (status >= 500) {
|
|
278
|
+
const detail = quote ? ` Server said: ${quote}.` : "";
|
|
279
|
+
return `The paperless-ngx server failed internally (HTTP ${status}).${detail} This is a server-side fault, not a problem with your arguments -- retrying the same call unchanged is reasonable, but the fix is on the server. (${original})`;
|
|
280
|
+
}
|
|
281
|
+
// Any other status: still a sentence, still keeps the detail and the original.
|
|
282
|
+
const detail = quote ? ` Server said: ${quote}.` : "";
|
|
283
|
+
return `The paperless-ngx server returned an unexpected HTTP ${status}.${detail} (${original})`;
|
|
284
|
+
}
|
|
285
|
+
/**
|
|
286
|
+
* Wraps a tool callback so a thrown error reaches the model as an actionable
|
|
287
|
+
* sentence. The signature and generic parameters are unchanged so the ~48 call
|
|
288
|
+
* sites keep typechecking untouched.
|
|
289
|
+
*/
|
|
13
290
|
const withErrorHandling = (cb) => {
|
|
14
291
|
return ((args, extra) => __awaiter(void 0, void 0, void 0, function* () {
|
|
15
|
-
var _a, _b;
|
|
16
292
|
try {
|
|
17
293
|
return yield cb(args, extra);
|
|
18
294
|
}
|
|
19
295
|
catch (err) {
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
const
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
responseData,
|
|
26
|
-
status,
|
|
27
|
-
}));
|
|
296
|
+
// `buildMessage` never throws: every serialisation goes through
|
|
297
|
+
// `safeStringify`, and a failure there degrades to the original message.
|
|
298
|
+
const secrets = credentialValues(err);
|
|
299
|
+
const message = scrub(buildMessage(err), secrets);
|
|
300
|
+
throw new Error(message);
|
|
28
301
|
}
|
|
29
302
|
}));
|
|
30
303
|
};
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@retiform/paperless-mcp",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.4.0",
|
|
4
4
|
"description": "MCP server for Paperless-NGX with bounded content reads - ranged document windows and passage search so agents never flood their context.",
|
|
5
5
|
"main": "build/index.js",
|
|
6
6
|
"bin": {
|
|
@@ -10,11 +10,14 @@
|
|
|
10
10
|
"test": "node --require ts-node/register --test \"src/**/*.test.ts\"",
|
|
11
11
|
"test:e2e": "node --require ts-node/register --test e2e/e2e.test.ts",
|
|
12
12
|
"start": "ts-node src/index.ts",
|
|
13
|
-
"build": "tsc",
|
|
13
|
+
"build": "tsc -p tsconfig.build.json",
|
|
14
14
|
"dxt-pack": "dxt pack",
|
|
15
15
|
"inspect": "npm run build && npx -y @modelcontextprotocol/inspector node build/index.js",
|
|
16
16
|
"prepack": "rm -rf build && npm run build && npm run sync-manifest && npm run dxt-pack",
|
|
17
|
-
"sync-manifest": "node scripts/sync-manifest-version.mjs"
|
|
17
|
+
"sync-manifest": "node scripts/sync-manifest-version.mjs && node scripts/sync-manifest-tools.mjs",
|
|
18
|
+
"eval": "node eval/run.mjs",
|
|
19
|
+
"typecheck": "tsc --noEmit -p tsconfig.json",
|
|
20
|
+
"sync-manifest-tools": "node scripts/sync-manifest-tools.mjs"
|
|
18
21
|
},
|
|
19
22
|
"keywords": [
|
|
20
23
|
"mcp",
|
|
@@ -47,13 +50,16 @@
|
|
|
47
50
|
"dependencies": {
|
|
48
51
|
"@modelcontextprotocol/sdk": "^1.30.0",
|
|
49
52
|
"axios": "^1.20.0",
|
|
53
|
+
"better-sqlite3": "^13.2.0",
|
|
50
54
|
"express": "^5.1.0",
|
|
51
55
|
"form-data": "^4.0.2",
|
|
56
|
+
"sqlite-vec": "^0.1.9",
|
|
52
57
|
"zod": "~4.4.3"
|
|
53
58
|
},
|
|
54
59
|
"devDependencies": {
|
|
55
60
|
"@anthropic-ai/dxt": "^0.2.6",
|
|
56
61
|
"@changesets/cli": "^2.29.4",
|
|
62
|
+
"@types/better-sqlite3": "^7.6.13",
|
|
57
63
|
"@types/express": "^5.0.2",
|
|
58
64
|
"@types/node": "^24.0.0",
|
|
59
65
|
"ts-node": "^10.9.2",
|
package/paperless-mcp.dxt
CHANGED
|
Binary file
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
export {};
|
|
@@ -1,80 +0,0 @@
|
|
|
1
|
-
"use strict";
|
|
2
|
-
var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
|
|
3
|
-
function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
|
|
4
|
-
return new (P || (P = Promise))(function (resolve, reject) {
|
|
5
|
-
function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
|
|
6
|
-
function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
|
|
7
|
-
function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
|
|
8
|
-
step((generator = generator.apply(thisArg, _arguments || [])).next());
|
|
9
|
-
});
|
|
10
|
-
};
|
|
11
|
-
var __importDefault = (this && this.__importDefault) || function (mod) {
|
|
12
|
-
return (mod && mod.__esModule) ? mod : { "default": mod };
|
|
13
|
-
};
|
|
14
|
-
Object.defineProperty(exports, "__esModule", { value: true });
|
|
15
|
-
const strict_1 = __importDefault(require("node:assert/strict"));
|
|
16
|
-
const node_test_1 = require("node:test");
|
|
17
|
-
const documentEnhancer_1 = require("./documentEnhancer");
|
|
18
|
-
const paperlessApi_1 = require("../test/mocks/paperlessApi");
|
|
19
|
-
const LARGE_DOCUMENT_COUNT = 709;
|
|
20
|
-
const MAX_RESPONSE_SIZE_BYTES = 2000;
|
|
21
|
-
function getTextContent(result) {
|
|
22
|
-
var _a;
|
|
23
|
-
const item = (_a = result.content) === null || _a === void 0 ? void 0 : _a[0];
|
|
24
|
-
if (!item || item.type !== "text") {
|
|
25
|
-
throw new Error("Expected text content");
|
|
26
|
-
}
|
|
27
|
-
return item.text;
|
|
28
|
-
}
|
|
29
|
-
(0, node_test_1.test)("convertDocsWithNames omits `all` and keeps paginated JSON shape", () => __awaiter(void 0, void 0, void 0, function* () {
|
|
30
|
-
const docsResponse = {
|
|
31
|
-
count: 2,
|
|
32
|
-
next: null,
|
|
33
|
-
previous: null,
|
|
34
|
-
all: [1, 2],
|
|
35
|
-
results: [(0, paperlessApi_1.createDocument)(), (0, paperlessApi_1.createDocument)({ id: 2, title: "Document 2" })],
|
|
36
|
-
};
|
|
37
|
-
const result = yield (0, documentEnhancer_1.convertDocsWithNames)(docsResponse, (0, paperlessApi_1.createPaperlessApiMock)());
|
|
38
|
-
const parsed = JSON.parse(getTextContent(result));
|
|
39
|
-
strict_1.default.ok(!("all" in parsed));
|
|
40
|
-
strict_1.default.deepEqual(parsed.results.map((doc) => doc.id), [1, 2]);
|
|
41
|
-
strict_1.default.ok(!("content" in parsed.results[0]));
|
|
42
|
-
}));
|
|
43
|
-
(0, node_test_1.test)("convertDocsWithNames keeps responses small when source has large `all` arrays", () => __awaiter(void 0, void 0, void 0, function* () {
|
|
44
|
-
const docsResponse = {
|
|
45
|
-
count: LARGE_DOCUMENT_COUNT,
|
|
46
|
-
next: "http://localhost:8000/api/documents/?page=2",
|
|
47
|
-
previous: null,
|
|
48
|
-
all: Array.from({ length: LARGE_DOCUMENT_COUNT }, (_, index) => index + 1),
|
|
49
|
-
results: [
|
|
50
|
-
(0, paperlessApi_1.createDocument)({
|
|
51
|
-
id: 123,
|
|
52
|
-
title: "Large all payload case",
|
|
53
|
-
content: "x".repeat(2700),
|
|
54
|
-
}),
|
|
55
|
-
],
|
|
56
|
-
};
|
|
57
|
-
const result = yield (0, documentEnhancer_1.convertDocsWithNames)(docsResponse, (0, paperlessApi_1.createPaperlessApiMock)());
|
|
58
|
-
const responseText = getTextContent(result);
|
|
59
|
-
strict_1.default.ok(responseText.length < MAX_RESPONSE_SIZE_BYTES);
|
|
60
|
-
const parsed = JSON.parse(responseText);
|
|
61
|
-
strict_1.default.ok(!("all" in parsed));
|
|
62
|
-
strict_1.default.ok(!("content" in parsed.results[0]));
|
|
63
|
-
}));
|
|
64
|
-
(0, node_test_1.test)("convertDocsWithNames returns paginated JSON for empty multi-document results", () => __awaiter(void 0, void 0, void 0, function* () {
|
|
65
|
-
const docsResponse = {
|
|
66
|
-
count: 0,
|
|
67
|
-
next: null,
|
|
68
|
-
previous: null,
|
|
69
|
-
all: [],
|
|
70
|
-
results: [],
|
|
71
|
-
};
|
|
72
|
-
const result = yield (0, documentEnhancer_1.convertDocsWithNames)(docsResponse, (0, paperlessApi_1.createPaperlessApiMock)());
|
|
73
|
-
const parsed = JSON.parse(getTextContent(result));
|
|
74
|
-
strict_1.default.deepEqual(parsed, {
|
|
75
|
-
count: 0,
|
|
76
|
-
next: null,
|
|
77
|
-
previous: null,
|
|
78
|
-
results: [],
|
|
79
|
-
});
|
|
80
|
-
}));
|
package/build/manifest.test.d.ts
DELETED
|
@@ -1 +0,0 @@
|
|
|
1
|
-
export {};
|
package/build/manifest.test.js
DELETED
|
@@ -1,66 +0,0 @@
|
|
|
1
|
-
"use strict";
|
|
2
|
-
var __importDefault = (this && this.__importDefault) || function (mod) {
|
|
3
|
-
return (mod && mod.__esModule) ? mod : { "default": mod };
|
|
4
|
-
};
|
|
5
|
-
Object.defineProperty(exports, "__esModule", { value: true });
|
|
6
|
-
const strict_1 = __importDefault(require("node:assert/strict"));
|
|
7
|
-
const node_child_process_1 = require("node:child_process");
|
|
8
|
-
const node_fs_1 = require("node:fs");
|
|
9
|
-
const node_os_1 = require("node:os");
|
|
10
|
-
const node_path_1 = require("node:path");
|
|
11
|
-
const node_test_1 = require("node:test");
|
|
12
|
-
// The DXT manifest carries its own copy of the version and changesets only
|
|
13
|
-
// bumps package.json, so the two drifted on every bot-driven release: 2.3.3
|
|
14
|
-
// shipped a 2.3.2 manifest, 2.3.5 shipped a 2.3.4 one. scripts/sync-manifest-version.mjs
|
|
15
|
-
// derives it at pack time; this pins both halves of that guarantee.
|
|
16
|
-
const root = (0, node_path_1.join)(__dirname, "..");
|
|
17
|
-
function readManifest() {
|
|
18
|
-
return JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(root, "manifest.json"), "utf8"));
|
|
19
|
-
}
|
|
20
|
-
// NOTE: there is deliberately no assertion that the TRACKED manifest matches
|
|
21
|
-
// package.json. The changesets Version PR bumps package.json only, so that
|
|
22
|
-
// state is legitimately unequal between a version bump and the next pack; a
|
|
23
|
-
// test on it would fail for a correct reason. What is pinned below is the
|
|
24
|
-
// mechanism - prepack stamps the manifest from the package version - which is
|
|
25
|
-
// the property the published artifact actually depends on.
|
|
26
|
-
(0, node_test_1.test)("sync-manifest-version stamps package.json over a stale manifest version", () => {
|
|
27
|
-
const dir = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "manifest-sync-"));
|
|
28
|
-
try {
|
|
29
|
-
(0, node_fs_1.cpSync)((0, node_path_1.join)(root, "package.json"), (0, node_path_1.join)(dir, "package.json"));
|
|
30
|
-
const manifest = readManifest();
|
|
31
|
-
manifest.version = "0.0.0-stale";
|
|
32
|
-
(0, node_fs_1.writeFileSync)((0, node_path_1.join)(dir, "manifest.json"), JSON.stringify(manifest, null, 2));
|
|
33
|
-
(0, node_fs_1.cpSync)((0, node_path_1.join)(root, "scripts"), (0, node_path_1.join)(dir, "scripts"), { recursive: true });
|
|
34
|
-
(0, node_fs_1.cpSync)((0, node_path_1.join)(root, "src"), (0, node_path_1.join)(dir, "src"), { recursive: true });
|
|
35
|
-
(0, node_child_process_1.execFileSync)(process.execPath, [(0, node_path_1.join)(dir, "scripts", "sync-manifest-version.mjs")], {
|
|
36
|
-
stdio: "pipe",
|
|
37
|
-
});
|
|
38
|
-
const pkg = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(dir, "package.json"), "utf8"));
|
|
39
|
-
const after = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(dir, "manifest.json"), "utf8"));
|
|
40
|
-
strict_1.default.equal(after.version, pkg.version, "sync did not stamp package.json version");
|
|
41
|
-
strict_1.default.notEqual(after.version, "0.0.0-stale", "stale literal survived the sync");
|
|
42
|
-
strict_1.default.equal(after.dxt_version, manifest.dxt_version, "sync clobbered dxt_version");
|
|
43
|
-
}
|
|
44
|
-
finally {
|
|
45
|
-
(0, node_fs_1.rmSync)(dir, { recursive: true, force: true });
|
|
46
|
-
}
|
|
47
|
-
});
|
|
48
|
-
(0, node_test_1.test)("sync-manifest-version is idempotent", () => {
|
|
49
|
-
const dir = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "manifest-idem-"));
|
|
50
|
-
try {
|
|
51
|
-
(0, node_fs_1.cpSync)((0, node_path_1.join)(root, "package.json"), (0, node_path_1.join)(dir, "package.json"));
|
|
52
|
-
(0, node_fs_1.cpSync)((0, node_path_1.join)(root, "manifest.json"), (0, node_path_1.join)(dir, "manifest.json"));
|
|
53
|
-
(0, node_fs_1.cpSync)((0, node_path_1.join)(root, "scripts"), (0, node_path_1.join)(dir, "scripts"), { recursive: true });
|
|
54
|
-
const run = () => (0, node_child_process_1.execFileSync)(process.execPath, [(0, node_path_1.join)(dir, "scripts", "sync-manifest-version.mjs")], {
|
|
55
|
-
stdio: "pipe",
|
|
56
|
-
});
|
|
57
|
-
run();
|
|
58
|
-
const once = (0, node_fs_1.readFileSync)((0, node_path_1.join)(dir, "manifest.json"), "utf8");
|
|
59
|
-
run();
|
|
60
|
-
const twice = (0, node_fs_1.readFileSync)((0, node_path_1.join)(dir, "manifest.json"), "utf8");
|
|
61
|
-
strict_1.default.equal(twice, once, "second run changed the manifest");
|
|
62
|
-
}
|
|
63
|
-
finally {
|
|
64
|
-
(0, node_fs_1.rmSync)(dir, { recursive: true, force: true });
|
|
65
|
-
}
|
|
66
|
-
});
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
export {};
|
|
@@ -1,124 +0,0 @@
|
|
|
1
|
-
"use strict";
|
|
2
|
-
var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
|
|
3
|
-
function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
|
|
4
|
-
return new (P || (P = Promise))(function (resolve, reject) {
|
|
5
|
-
function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
|
|
6
|
-
function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
|
|
7
|
-
function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
|
|
8
|
-
step((generator = generator.apply(thisArg, _arguments || [])).next());
|
|
9
|
-
});
|
|
10
|
-
};
|
|
11
|
-
var __importDefault = (this && this.__importDefault) || function (mod) {
|
|
12
|
-
return (mod && mod.__esModule) ? mod : { "default": mod };
|
|
13
|
-
};
|
|
14
|
-
Object.defineProperty(exports, "__esModule", { value: true });
|
|
15
|
-
const strict_1 = __importDefault(require("node:assert/strict"));
|
|
16
|
-
const node_test_1 = require("node:test");
|
|
17
|
-
const index_js_1 = require("@modelcontextprotocol/sdk/client/index.js");
|
|
18
|
-
const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
|
|
19
|
-
const paperlessApi_1 = require("../test/mocks/paperlessApi");
|
|
20
|
-
const documents_1 = require("./documents");
|
|
21
|
-
class TestTransport {
|
|
22
|
-
start() {
|
|
23
|
-
return __awaiter(this, void 0, void 0, function* () { });
|
|
24
|
-
}
|
|
25
|
-
send(message) {
|
|
26
|
-
return __awaiter(this, void 0, void 0, function* () {
|
|
27
|
-
queueMicrotask(() => { var _a, _b; return (_b = (_a = this.peer) === null || _a === void 0 ? void 0 : _a.onmessage) === null || _b === void 0 ? void 0 : _b.call(_a, message); });
|
|
28
|
-
});
|
|
29
|
-
}
|
|
30
|
-
close() {
|
|
31
|
-
return __awaiter(this, void 0, void 0, function* () {
|
|
32
|
-
var _a;
|
|
33
|
-
(_a = this.onclose) === null || _a === void 0 ? void 0 : _a.call(this);
|
|
34
|
-
});
|
|
35
|
-
}
|
|
36
|
-
}
|
|
37
|
-
function createTransportPair() {
|
|
38
|
-
const clientTransport = new TestTransport();
|
|
39
|
-
const serverTransport = new TestTransport();
|
|
40
|
-
clientTransport.peer = serverTransport;
|
|
41
|
-
serverTransport.peer = clientTransport;
|
|
42
|
-
return { clientTransport, serverTransport };
|
|
43
|
-
}
|
|
44
|
-
function emptyPaginationResponse(results = [], all = []) {
|
|
45
|
-
return {
|
|
46
|
-
count: results.length,
|
|
47
|
-
next: null,
|
|
48
|
-
previous: null,
|
|
49
|
-
all,
|
|
50
|
-
results,
|
|
51
|
-
};
|
|
52
|
-
}
|
|
53
|
-
function createBinaryResponse(body, contentType) {
|
|
54
|
-
return {
|
|
55
|
-
data: Buffer.from(body),
|
|
56
|
-
status: 200,
|
|
57
|
-
statusText: "OK",
|
|
58
|
-
headers: {
|
|
59
|
-
"content-type": contentType,
|
|
60
|
-
},
|
|
61
|
-
config: {},
|
|
62
|
-
};
|
|
63
|
-
}
|
|
64
|
-
function withResourceClient(api, run) {
|
|
65
|
-
return __awaiter(this, void 0, void 0, function* () {
|
|
66
|
-
const server = new mcp_js_1.McpServer({ name: "paperless-test", version: "1.0.0" });
|
|
67
|
-
(0, documents_1.registerDocumentResources)(server, api);
|
|
68
|
-
const client = new index_js_1.Client({ name: "paperless-test-client", version: "1.0.0" });
|
|
69
|
-
const { clientTransport, serverTransport } = createTransportPair();
|
|
70
|
-
yield server.connect(serverTransport);
|
|
71
|
-
yield client.connect(clientTransport);
|
|
72
|
-
try {
|
|
73
|
-
yield run(client);
|
|
74
|
-
}
|
|
75
|
-
finally {
|
|
76
|
-
yield client.close();
|
|
77
|
-
yield server.close();
|
|
78
|
-
}
|
|
79
|
-
});
|
|
80
|
-
}
|
|
81
|
-
(0, node_test_1.test)("resources/list does not enumerate documents at startup", () => __awaiter(void 0, void 0, void 0, function* () {
|
|
82
|
-
// Documents are dynamic DMS data and must not be pre-registered as MCP
|
|
83
|
-
// resources: enumerating them floods `resources/list` and the LLM context
|
|
84
|
-
// window (issue #112). The list must stay empty even when documents exist;
|
|
85
|
-
// documents are reached on demand via tools + the `resources/read` template.
|
|
86
|
-
const api = {
|
|
87
|
-
getDocuments: () => __awaiter(void 0, void 0, void 0, function* () {
|
|
88
|
-
return emptyPaginationResponse([
|
|
89
|
-
(0, paperlessApi_1.createDocument)({
|
|
90
|
-
id: 1,
|
|
91
|
-
title: "Invoice",
|
|
92
|
-
mime_type: "application/pdf",
|
|
93
|
-
}),
|
|
94
|
-
(0, paperlessApi_1.createDocument)({
|
|
95
|
-
id: 2,
|
|
96
|
-
title: "Receipt",
|
|
97
|
-
mime_type: "image/png",
|
|
98
|
-
}),
|
|
99
|
-
], [1, 2, 3]);
|
|
100
|
-
}),
|
|
101
|
-
};
|
|
102
|
-
yield withResourceClient(api, (client) => __awaiter(void 0, void 0, void 0, function* () {
|
|
103
|
-
const result = yield client.listResources();
|
|
104
|
-
strict_1.default.deepEqual(result.resources, []);
|
|
105
|
-
}));
|
|
106
|
-
}));
|
|
107
|
-
(0, node_test_1.test)("resources/read returns text contents for text responses", () => __awaiter(void 0, void 0, void 0, function* () {
|
|
108
|
-
const api = {
|
|
109
|
-
getDocuments: () => __awaiter(void 0, void 0, void 0, function* () { return emptyPaginationResponse(); }),
|
|
110
|
-
downloadDocument: () => __awaiter(void 0, void 0, void 0, function* () { return createBinaryResponse("plain text", "text/plain; charset=utf-8"); }),
|
|
111
|
-
};
|
|
112
|
-
yield withResourceClient(api, (client) => __awaiter(void 0, void 0, void 0, function* () {
|
|
113
|
-
const result = yield client.readResource({
|
|
114
|
-
uri: "paperless://documents/4/download",
|
|
115
|
-
});
|
|
116
|
-
strict_1.default.deepEqual(result.contents, [
|
|
117
|
-
{
|
|
118
|
-
uri: "paperless://documents/4/download",
|
|
119
|
-
mimeType: "text/plain; charset=utf-8",
|
|
120
|
-
text: "plain text",
|
|
121
|
-
},
|
|
122
|
-
]);
|
|
123
|
-
}));
|
|
124
|
-
}));
|
package/build/server.test.d.ts
DELETED
|
@@ -1 +0,0 @@
|
|
|
1
|
-
export {};
|