@retiform/paperless-mcp 2.3.5 → 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 +10 -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/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
package/build/server.js
CHANGED
|
@@ -1,8 +1,18 @@
|
|
|
1
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
|
+
};
|
|
2
11
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
12
|
exports.createMcpServer = createMcpServer;
|
|
4
13
|
exports.getBearerToken = getBearerToken;
|
|
5
14
|
exports.sendUnauthorized = sendUnauthorized;
|
|
15
|
+
exports.enforceDeterministicToolOrder = enforceDeterministicToolOrder;
|
|
6
16
|
const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
|
|
7
17
|
const PaperlessAPI_1 = require("./api/PaperlessAPI");
|
|
8
18
|
const documents_1 = require("./resources/documents");
|
|
@@ -12,6 +22,7 @@ const documents_2 = require("./tools/documents");
|
|
|
12
22
|
const documentTypes_1 = require("./tools/documentTypes");
|
|
13
23
|
const mail_1 = require("./tools/mail");
|
|
14
24
|
const notes_1 = require("./tools/notes");
|
|
25
|
+
const search_1 = require("./tools/search");
|
|
15
26
|
const tags_1 = require("./tools/tags");
|
|
16
27
|
function createMcpServer({ baseUrl, token, version, publicUrl, }) {
|
|
17
28
|
const api = new PaperlessAPI_1.PaperlessAPI(baseUrl, token);
|
|
@@ -24,6 +35,24 @@ function createMcpServer({ baseUrl, token, version, publicUrl, }) {
|
|
|
24
35
|
(0, documentTypes_1.registerDocumentTypeTools)(server, api);
|
|
25
36
|
(0, customFields_1.registerCustomFieldTools)(server, api);
|
|
26
37
|
(0, mail_1.registerMailTools)(server, api);
|
|
38
|
+
// Semantic search registers ONLY when its configuration is present. The
|
|
39
|
+
// gateway passes one environment to every child, so an unconfigured install
|
|
40
|
+
// must not advertise three tools that would fail on first call -- and must
|
|
41
|
+
// not open a ~1 GB SQLite file at startup to decide. SearchContext resolves
|
|
42
|
+
// the config and opens nothing; the open happens on the first tool call.
|
|
43
|
+
const searchContext = (0, search_1.registerSearchTools)(server, api);
|
|
44
|
+
// `onclose` lives on the low-level Server (exposed as `server.server`), not on
|
|
45
|
+
// McpServer, and the SDK does not set it -- verified in protocol.js: `_onclose()`
|
|
46
|
+
// calls `this.onclose?.()`, and mcp.js never assigns it. Chaining rather than
|
|
47
|
+
// overwriting so a future SDK assignment is not silently clobbered.
|
|
48
|
+
const previousOnClose = server.server.onclose;
|
|
49
|
+
server.server.onclose = () => {
|
|
50
|
+
previousOnClose === null || previousOnClose === void 0 ? void 0 : previousOnClose();
|
|
51
|
+
searchContext.close();
|
|
52
|
+
};
|
|
53
|
+
// Enforced last, so it sees the complete set including the conditional
|
|
54
|
+
// semantic-search tools.
|
|
55
|
+
enforceDeterministicToolOrder(server);
|
|
27
56
|
return server;
|
|
28
57
|
}
|
|
29
58
|
function getBearerToken(req, options) {
|
|
@@ -49,6 +78,54 @@ function sendUnauthorized(res) {
|
|
|
49
78
|
.set("WWW-Authenticate", 'Bearer realm="paperless-mcp"')
|
|
50
79
|
.json({ error: "unauthorized" });
|
|
51
80
|
}
|
|
81
|
+
/**
|
|
82
|
+
* Makes the `tools/list` ordering a property of the tool SET rather than of the
|
|
83
|
+
* order the registration functions happened to run in.
|
|
84
|
+
*
|
|
85
|
+
* The MCP spec: "Servers SHOULD return tools in a deterministic order (i.e.,
|
|
86
|
+
* the same ordering across requests when the underlying set of tools has not
|
|
87
|
+
* changed). Deterministic ordering enables clients to reliably cache the tool
|
|
88
|
+
* list and improves LLM prompt cache hit rates when tools are included in
|
|
89
|
+
* model context."
|
|
90
|
+
*
|
|
91
|
+
* Registration order is already stable today -- module evaluation order is
|
|
92
|
+
* deterministic in Node and nothing here reads a directory or races. But that
|
|
93
|
+
* makes determinism an ACCIDENT of the call order, not a guarantee. Two things
|
|
94
|
+
* break it without anyone intending it:
|
|
95
|
+
* - reordering a `register*Tools(...)` call, or moving a `server.tool(...)`
|
|
96
|
+
* call within one, silently reshuffles the list;
|
|
97
|
+
* - `RegisteredTool.update({ name })` is a delete-then-add, so a rename
|
|
98
|
+
* moves that tool to the end of the list.
|
|
99
|
+
* Sorting at the point the list is returned makes both of those no-ops.
|
|
100
|
+
*
|
|
101
|
+
* The comparator is `a.name < b.name`, NOT `localeCompare`: locale collation
|
|
102
|
+
* varies with the host's ICU data, which would trade one non-determinism for a
|
|
103
|
+
* subtler one. Code-unit comparison is identical on every Node build.
|
|
104
|
+
*
|
|
105
|
+
* If the SDK ever stops holding the handler in `_requestHandlers`, this returns
|
|
106
|
+
* without wrapping and the list falls back to registration order -- still
|
|
107
|
+
* deterministic, just no longer enforced. It never throws.
|
|
108
|
+
*/
|
|
109
|
+
function enforceDeterministicToolOrder(server) {
|
|
110
|
+
var _a;
|
|
111
|
+
const handlers = (_a = server.server) === null || _a === void 0 ? void 0 : _a._requestHandlers;
|
|
112
|
+
if (!(handlers instanceof Map))
|
|
113
|
+
return;
|
|
114
|
+
// Measured from the live handler map, not assumed: the key is the literal
|
|
115
|
+
// method string, and the SDK has already registered it by the time every
|
|
116
|
+
// register*Tools() call has returned.
|
|
117
|
+
const method = "tools/list";
|
|
118
|
+
const original = handlers.get(method);
|
|
119
|
+
if (typeof original !== "function")
|
|
120
|
+
return;
|
|
121
|
+
handlers.set(method, (request, extra) => __awaiter(this, void 0, void 0, function* () {
|
|
122
|
+
const result = yield original(request, extra);
|
|
123
|
+
if (!result || !Array.isArray(result.tools))
|
|
124
|
+
return result;
|
|
125
|
+
const tools = [...result.tools].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
|
|
126
|
+
return Object.assign(Object.assign({}, result), { tools });
|
|
127
|
+
}));
|
|
128
|
+
}
|
|
52
129
|
function buildInstructions(publicUrl) {
|
|
53
130
|
return `
|
|
54
131
|
Paperless-NGX MCP Server Instructions
|
|
@@ -13,8 +13,18 @@ export type BulkCustomFieldParameters = {
|
|
|
13
13
|
};
|
|
14
14
|
/** Default number of characters returned by a bounded content read. */
|
|
15
15
|
export declare const DEFAULT_CONTENT_MAX_CHARS = 8000;
|
|
16
|
-
/**
|
|
17
|
-
|
|
16
|
+
/**
|
|
17
|
+
* Hard cap on characters a single tool response may inline.
|
|
18
|
+
*
|
|
19
|
+
* 20,000 matches the client-side truncation ceiling our primary consumer
|
|
20
|
+
* applies (`DEFAULT_MAX_TOOL_RESULT_LENGTH`), and it matches the search path's
|
|
21
|
+
* own `MAX_RESULT_CHARS`. It was 50,000, which is 2.5x the consumer's limit —
|
|
22
|
+
* a budget above the one your reader enforces is not a budget: the response
|
|
23
|
+
* was built whole and then mangled downstream, silently, with the caller
|
|
24
|
+
* unable to detect it. Bounding at the source is the only honest option for a
|
|
25
|
+
* published server, since we cannot fix the client.
|
|
26
|
+
*/
|
|
27
|
+
export declare const DEFAULT_MAX_INLINE_CHARS = 20000;
|
|
18
28
|
/** Default passage size for search_passages. */
|
|
19
29
|
export declare const DEFAULT_PASSAGE_WINDOW = 800;
|
|
20
30
|
/** Default maximum number of passages returned by search_passages. */
|
|
@@ -60,7 +70,7 @@ export declare function sliceDocumentContent(doc: Pick<Document, "id" | "title"
|
|
|
60
70
|
* crosses this boundary un-sliced. Anchoring prefers the server's own
|
|
61
71
|
* highlighted phrase — the only anchor that survives whoosh stemming, since
|
|
62
72
|
* the index may match word variants the stored text does not contain
|
|
63
|
-
* verbatim — then falls back to the
|
|
73
|
+
* verbatim — then falls back to the LONGEST matching verbatim term, and
|
|
64
74
|
* finally to the head of the document rather than returning nothing.
|
|
65
75
|
*/
|
|
66
76
|
export declare function buildSearchPassage(doc: Pick<Document, "id" | "title" | "content">, terms: string[], window: number, searchHit?: Pick<SearchHit, "score" | "highlights">): {
|
package/build/tools/documents.js
CHANGED
|
@@ -49,8 +49,18 @@ const ALLOWED_UPLOAD_PATHS = process.env.PAPERLESS_MCP_UPLOAD_PATHS
|
|
|
49
49
|
: [];
|
|
50
50
|
/** Default number of characters returned by a bounded content read. */
|
|
51
51
|
exports.DEFAULT_CONTENT_MAX_CHARS = 8000;
|
|
52
|
-
/**
|
|
53
|
-
|
|
52
|
+
/**
|
|
53
|
+
* Hard cap on characters a single tool response may inline.
|
|
54
|
+
*
|
|
55
|
+
* 20,000 matches the client-side truncation ceiling our primary consumer
|
|
56
|
+
* applies (`DEFAULT_MAX_TOOL_RESULT_LENGTH`), and it matches the search path's
|
|
57
|
+
* own `MAX_RESULT_CHARS`. It was 50,000, which is 2.5x the consumer's limit —
|
|
58
|
+
* a budget above the one your reader enforces is not a budget: the response
|
|
59
|
+
* was built whole and then mangled downstream, silently, with the caller
|
|
60
|
+
* unable to detect it. Bounding at the source is the only honest option for a
|
|
61
|
+
* published server, since we cannot fix the client.
|
|
62
|
+
*/
|
|
63
|
+
exports.DEFAULT_MAX_INLINE_CHARS = 20000;
|
|
54
64
|
/** Default passage size for search_passages. */
|
|
55
65
|
exports.DEFAULT_PASSAGE_WINDOW = 800;
|
|
56
66
|
/** Default maximum number of passages returned by search_passages. */
|
|
@@ -117,7 +127,7 @@ function sliceDocumentContent(doc, offset, maxChars) {
|
|
|
117
127
|
* crosses this boundary un-sliced. Anchoring prefers the server's own
|
|
118
128
|
* highlighted phrase — the only anchor that survives whoosh stemming, since
|
|
119
129
|
* the index may match word variants the stored text does not contain
|
|
120
|
-
* verbatim — then falls back to the
|
|
130
|
+
* verbatim — then falls back to the LONGEST matching verbatim term, and
|
|
121
131
|
* finally to the head of the document rather than returning nothing.
|
|
122
132
|
*/
|
|
123
133
|
function buildSearchPassage(doc, terms, window, searchHit) {
|
|
@@ -141,7 +151,14 @@ function buildSearchPassage(doc, terms, window, searchHit) {
|
|
|
141
151
|
}
|
|
142
152
|
}
|
|
143
153
|
if (center < 0) {
|
|
144
|
-
|
|
154
|
+
// The FALLBACK walks terms LONGEST-FIRST, matching buildPassage in
|
|
155
|
+
// search.ts. Walking query order here meant "the practice of a wrathful
|
|
156
|
+
// deity with a lion head" anchored on "the" at character 3 whenever the
|
|
157
|
+
// server's highlight did not resolve -- and because the highlight usually
|
|
158
|
+
// DOES resolve on this path, the two tools silently disagreed about where
|
|
159
|
+
// a window belongs while the README described them as mirror images.
|
|
160
|
+
// Length is the cheap correct proxy for the most distinctive term.
|
|
161
|
+
for (const term of [...terms].sort((a, b) => b.length - a.length)) {
|
|
145
162
|
const idx = lowerFull.indexOf(term.toLowerCase());
|
|
146
163
|
if (idx >= 0) {
|
|
147
164
|
center = idx;
|
|
@@ -202,7 +219,7 @@ function extractHighlightPhrases(highlights) {
|
|
|
202
219
|
function extractSearchTerms(query) {
|
|
203
220
|
const terms = query
|
|
204
221
|
.toLowerCase()
|
|
205
|
-
.split(/[^\p{L}\p{N}_]+/u)
|
|
222
|
+
.split(/[^\p{L}\p{N}\p{M}_]+/u)
|
|
206
223
|
.filter((term) => term.length > 0);
|
|
207
224
|
return terms;
|
|
208
225
|
}
|
|
@@ -576,7 +593,7 @@ function registerDocumentTools(server, api) {
|
|
|
576
593
|
throw new Error("Please configure API connection first");
|
|
577
594
|
return executeDocumentQuery(api, args);
|
|
578
595
|
})));
|
|
579
|
-
server.tool("search_passages", "Search documents full-text and return bounded text passages around each hit instead of whole documents. The window is anchored on the server's own highlighted phrase (falling back to the
|
|
596
|
+
server.tool("search_passages", "Search documents full-text and return bounded text passages around each hit instead of whole documents. The window is anchored on the server's own highlighted phrase (falling back to the LONGEST matching query term, then the document head), so the returned passage contains the actual hit even when stemming matched a word variant. Queries that the server rejects with an HTTP 400 are retried once with a defensively rewritten query (apostrophes and stray quotes removed); such responses carry query_sanitized: true. Returns document id, title, score, offset, content_length, and the highlighted snippet. Use this to locate and skim evidence across many documents without flooding context; page further with get_document_content offsets.", {
|
|
580
597
|
query: zod_1.z
|
|
581
598
|
.string()
|
|
582
599
|
.min(1)
|