@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
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
- /** Hard cap on characters a single tool response may inline. */
17
- export declare const DEFAULT_MAX_INLINE_CHARS = 50000;
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 first verbatim term occurrence, and
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">): {
@@ -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
- /** Hard cap on characters a single tool response may inline. */
53
- exports.DEFAULT_MAX_INLINE_CHARS = 50000;
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 first verbatim term occurrence, and
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
- for (const term of terms) {
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 first verbatim 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.", {
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)