@ssmeo/mcp-local-rag 0.18.6

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 (247) hide show
  1. package/LICENSE +21 -0
  2. package/README.de.md +441 -0
  3. package/README.es.md +441 -0
  4. package/README.fr.md +441 -0
  5. package/README.md +530 -0
  6. package/README.pt-BR.md +441 -0
  7. package/README.zh-CN.md +441 -0
  8. package/dist/bin/install-skills.d.ts +19 -0
  9. package/dist/bin/install-skills.d.ts.map +1 -0
  10. package/dist/bin/install-skills.js +218 -0
  11. package/dist/bin/install-skills.js.map +1 -0
  12. package/dist/chunker/index.d.ts +24 -0
  13. package/dist/chunker/index.d.ts.map +1 -0
  14. package/dist/chunker/index.js +2 -0
  15. package/dist/chunker/index.js.map +1 -0
  16. package/dist/chunker/semantic-chunker.d.ts +96 -0
  17. package/dist/chunker/semantic-chunker.d.ts.map +1 -0
  18. package/dist/chunker/semantic-chunker.js +362 -0
  19. package/dist/chunker/semantic-chunker.js.map +1 -0
  20. package/dist/chunker/sentence-splitter.d.ts +32 -0
  21. package/dist/chunker/sentence-splitter.d.ts.map +1 -0
  22. package/dist/chunker/sentence-splitter.js +231 -0
  23. package/dist/chunker/sentence-splitter.js.map +1 -0
  24. package/dist/chunker/token-containment.d.ts +39 -0
  25. package/dist/chunker/token-containment.d.ts.map +1 -0
  26. package/dist/chunker/token-containment.js +83 -0
  27. package/dist/chunker/token-containment.js.map +1 -0
  28. package/dist/cli/common.d.ts +34 -0
  29. package/dist/cli/common.d.ts.map +1 -0
  30. package/dist/cli/common.js +121 -0
  31. package/dist/cli/common.js.map +1 -0
  32. package/dist/cli/delete.d.ts +3 -0
  33. package/dist/cli/delete.d.ts.map +1 -0
  34. package/dist/cli/delete.js +169 -0
  35. package/dist/cli/delete.js.map +1 -0
  36. package/dist/cli/file-collection.d.ts +2 -0
  37. package/dist/cli/file-collection.d.ts.map +1 -0
  38. package/dist/cli/file-collection.js +53 -0
  39. package/dist/cli/file-collection.js.map +1 -0
  40. package/dist/cli/ingest.d.ts +69 -0
  41. package/dist/cli/ingest.d.ts.map +1 -0
  42. package/dist/cli/ingest.js +323 -0
  43. package/dist/cli/ingest.js.map +1 -0
  44. package/dist/cli/list.d.ts +27 -0
  45. package/dist/cli/list.d.ts.map +1 -0
  46. package/dist/cli/list.js +207 -0
  47. package/dist/cli/list.js.map +1 -0
  48. package/dist/cli/options.d.ts +89 -0
  49. package/dist/cli/options.d.ts.map +1 -0
  50. package/dist/cli/options.js +244 -0
  51. package/dist/cli/options.js.map +1 -0
  52. package/dist/cli/query.d.ts +17 -0
  53. package/dist/cli/query.d.ts.map +1 -0
  54. package/dist/cli/query.js +194 -0
  55. package/dist/cli/query.js.map +1 -0
  56. package/dist/cli/read-neighbors.d.ts +3 -0
  57. package/dist/cli/read-neighbors.d.ts.map +1 -0
  58. package/dist/cli/read-neighbors.js +192 -0
  59. package/dist/cli/read-neighbors.js.map +1 -0
  60. package/dist/cli/status.d.ts +6 -0
  61. package/dist/cli/status.d.ts.map +1 -0
  62. package/dist/cli/status.js +78 -0
  63. package/dist/cli/status.js.map +1 -0
  64. package/dist/cli/sync.d.ts +6 -0
  65. package/dist/cli/sync.d.ts.map +1 -0
  66. package/dist/cli/sync.js +271 -0
  67. package/dist/cli/sync.js.map +1 -0
  68. package/dist/cli-main.d.ts +9 -0
  69. package/dist/cli-main.d.ts.map +1 -0
  70. package/dist/cli-main.js +60 -0
  71. package/dist/cli-main.js.map +1 -0
  72. package/dist/embedder/index.d.ts +143 -0
  73. package/dist/embedder/index.d.ts.map +1 -0
  74. package/dist/embedder/index.js +429 -0
  75. package/dist/embedder/index.js.map +1 -0
  76. package/dist/embedder/remote.d.ts +51 -0
  77. package/dist/embedder/remote.d.ts.map +1 -0
  78. package/dist/embedder/remote.js +182 -0
  79. package/dist/embedder/remote.js.map +1 -0
  80. package/dist/features/list.d.ts +37 -0
  81. package/dist/features/list.d.ts.map +1 -0
  82. package/dist/features/list.js +41 -0
  83. package/dist/features/list.js.map +1 -0
  84. package/dist/features/sync.d.ts +219 -0
  85. package/dist/features/sync.d.ts.map +1 -0
  86. package/dist/features/sync.js +461 -0
  87. package/dist/features/sync.js.map +1 -0
  88. package/dist/index.d.ts +3 -0
  89. package/dist/index.d.ts.map +1 -0
  90. package/dist/index.js +56 -0
  91. package/dist/index.js.map +1 -0
  92. package/dist/ingest/compute.d.ts +63 -0
  93. package/dist/ingest/compute.d.ts.map +1 -0
  94. package/dist/ingest/compute.js +161 -0
  95. package/dist/ingest/compute.js.map +1 -0
  96. package/dist/ingest/file.d.ts +40 -0
  97. package/dist/ingest/file.d.ts.map +1 -0
  98. package/dist/ingest/file.js +74 -0
  99. package/dist/ingest/file.js.map +1 -0
  100. package/dist/ingest/visual.d.ts +52 -0
  101. package/dist/ingest/visual.d.ts.map +1 -0
  102. package/dist/ingest/visual.js +294 -0
  103. package/dist/ingest/visual.js.map +1 -0
  104. package/dist/parser/docx-parser.d.ts +12 -0
  105. package/dist/parser/docx-parser.d.ts.map +1 -0
  106. package/dist/parser/docx-parser.js +375 -0
  107. package/dist/parser/docx-parser.js.map +1 -0
  108. package/dist/parser/html-parser.d.ts +16 -0
  109. package/dist/parser/html-parser.d.ts.map +1 -0
  110. package/dist/parser/html-parser.js +119 -0
  111. package/dist/parser/html-parser.js.map +1 -0
  112. package/dist/parser/index.d.ts +125 -0
  113. package/dist/parser/index.d.ts.map +1 -0
  114. package/dist/parser/index.js +364 -0
  115. package/dist/parser/index.js.map +1 -0
  116. package/dist/parser/pdf-extract.d.ts +49 -0
  117. package/dist/parser/pdf-extract.d.ts.map +1 -0
  118. package/dist/parser/pdf-extract.js +114 -0
  119. package/dist/parser/pdf-extract.js.map +1 -0
  120. package/dist/parser/pdf-filter.d.ts +91 -0
  121. package/dist/parser/pdf-filter.d.ts.map +1 -0
  122. package/dist/parser/pdf-filter.js +522 -0
  123. package/dist/parser/pdf-filter.js.map +1 -0
  124. package/dist/parser/title-extractor.d.ts +28 -0
  125. package/dist/parser/title-extractor.d.ts.map +1 -0
  126. package/dist/parser/title-extractor.js +105 -0
  127. package/dist/parser/title-extractor.js.map +1 -0
  128. package/dist/pdf-visual/captioner.d.ts +11 -0
  129. package/dist/pdf-visual/captioner.d.ts.map +1 -0
  130. package/dist/pdf-visual/captioner.js +48 -0
  131. package/dist/pdf-visual/captioner.js.map +1 -0
  132. package/dist/pdf-visual/captioners/fast.d.ts +7 -0
  133. package/dist/pdf-visual/captioners/fast.d.ts.map +1 -0
  134. package/dist/pdf-visual/captioners/fast.js +108 -0
  135. package/dist/pdf-visual/captioners/fast.js.map +1 -0
  136. package/dist/pdf-visual/captioners/quality.d.ts +7 -0
  137. package/dist/pdf-visual/captioners/quality.d.ts.map +1 -0
  138. package/dist/pdf-visual/captioners/quality.js +101 -0
  139. package/dist/pdf-visual/captioners/quality.js.map +1 -0
  140. package/dist/pdf-visual/captioners/shared.d.ts +81 -0
  141. package/dist/pdf-visual/captioners/shared.d.ts.map +1 -0
  142. package/dist/pdf-visual/captioners/shared.js +156 -0
  143. package/dist/pdf-visual/captioners/shared.js.map +1 -0
  144. package/dist/pdf-visual/detector.d.ts +9 -0
  145. package/dist/pdf-visual/detector.d.ts.map +1 -0
  146. package/dist/pdf-visual/detector.js +269 -0
  147. package/dist/pdf-visual/detector.js.map +1 -0
  148. package/dist/pdf-visual/index.d.ts +13 -0
  149. package/dist/pdf-visual/index.d.ts.map +1 -0
  150. package/dist/pdf-visual/index.js +53 -0
  151. package/dist/pdf-visual/index.js.map +1 -0
  152. package/dist/pdf-visual/renderer.d.ts +9 -0
  153. package/dist/pdf-visual/renderer.d.ts.map +1 -0
  154. package/dist/pdf-visual/renderer.js +186 -0
  155. package/dist/pdf-visual/renderer.js.map +1 -0
  156. package/dist/pdf-visual/types.d.ts +53 -0
  157. package/dist/pdf-visual/types.d.ts.map +1 -0
  158. package/dist/pdf-visual/types.js +17 -0
  159. package/dist/pdf-visual/types.js.map +1 -0
  160. package/dist/server/error-utils.d.ts +63 -0
  161. package/dist/server/error-utils.d.ts.map +1 -0
  162. package/dist/server/error-utils.js +124 -0
  163. package/dist/server/error-utils.js.map +1 -0
  164. package/dist/server/index.d.ts +216 -0
  165. package/dist/server/index.d.ts.map +1 -0
  166. package/dist/server/index.js +1068 -0
  167. package/dist/server/index.js.map +1 -0
  168. package/dist/server/list-scanner.d.ts +30 -0
  169. package/dist/server/list-scanner.d.ts.map +1 -0
  170. package/dist/server/list-scanner.js +50 -0
  171. package/dist/server/list-scanner.js.map +1 -0
  172. package/dist/server/tool-definitions.d.ts +8 -0
  173. package/dist/server/tool-definitions.d.ts.map +1 -0
  174. package/dist/server/tool-definitions.js +181 -0
  175. package/dist/server/tool-definitions.js.map +1 -0
  176. package/dist/server/tool-input.d.ts +37 -0
  177. package/dist/server/tool-input.d.ts.map +1 -0
  178. package/dist/server/tool-input.js +211 -0
  179. package/dist/server/tool-input.js.map +1 -0
  180. package/dist/server/types.d.ts +307 -0
  181. package/dist/server/types.d.ts.map +1 -0
  182. package/dist/server/types.js +3 -0
  183. package/dist/server/types.js.map +1 -0
  184. package/dist/server-main.d.ts +40 -0
  185. package/dist/server-main.d.ts.map +1 -0
  186. package/dist/server-main.js +254 -0
  187. package/dist/server-main.js.map +1 -0
  188. package/dist/utils/base-dirs.d.ts +145 -0
  189. package/dist/utils/base-dirs.d.ts.map +1 -0
  190. package/dist/utils/base-dirs.js +344 -0
  191. package/dist/utils/base-dirs.js.map +1 -0
  192. package/dist/utils/errors.d.ts +32 -0
  193. package/dist/utils/errors.d.ts.map +1 -0
  194. package/dist/utils/errors.js +61 -0
  195. package/dist/utils/errors.js.map +1 -0
  196. package/dist/utils/limits.d.ts +26 -0
  197. package/dist/utils/limits.d.ts.map +1 -0
  198. package/dist/utils/limits.js +28 -0
  199. package/dist/utils/limits.js.map +1 -0
  200. package/dist/utils/list-sources.d.ts +38 -0
  201. package/dist/utils/list-sources.d.ts.map +1 -0
  202. package/dist/utils/list-sources.js +40 -0
  203. package/dist/utils/list-sources.js.map +1 -0
  204. package/dist/utils/raw-data-utils.d.ts +76 -0
  205. package/dist/utils/raw-data-utils.d.ts.map +1 -0
  206. package/dist/utils/raw-data-utils.js +202 -0
  207. package/dist/utils/raw-data-utils.js.map +1 -0
  208. package/dist/utils/scan.d.ts +114 -0
  209. package/dist/utils/scan.d.ts.map +1 -0
  210. package/dist/utils/scan.js +209 -0
  211. package/dist/utils/scan.js.map +1 -0
  212. package/dist/utils/scope-match.d.ts +38 -0
  213. package/dist/utils/scope-match.d.ts.map +1 -0
  214. package/dist/utils/scope-match.js +86 -0
  215. package/dist/utils/scope-match.js.map +1 -0
  216. package/dist/utils/sensitive-path.d.ts +9 -0
  217. package/dist/utils/sensitive-path.d.ts.map +1 -0
  218. package/dist/utils/sensitive-path.js +78 -0
  219. package/dist/utils/sensitive-path.js.map +1 -0
  220. package/dist/utils/sync-path-key.d.ts +14 -0
  221. package/dist/utils/sync-path-key.d.ts.map +1 -0
  222. package/dist/utils/sync-path-key.js +27 -0
  223. package/dist/utils/sync-path-key.js.map +1 -0
  224. package/dist/utils/type-guards.d.ts +18 -0
  225. package/dist/utils/type-guards.d.ts.map +1 -0
  226. package/dist/utils/type-guards.js +34 -0
  227. package/dist/utils/type-guards.js.map +1 -0
  228. package/dist/utils/visual-profile.d.ts +10 -0
  229. package/dist/utils/visual-profile.d.ts.map +1 -0
  230. package/dist/utils/visual-profile.js +15 -0
  231. package/dist/utils/visual-profile.js.map +1 -0
  232. package/dist/vectordb/index.d.ts +132 -0
  233. package/dist/vectordb/index.d.ts.map +1 -0
  234. package/dist/vectordb/index.js +617 -0
  235. package/dist/vectordb/index.js.map +1 -0
  236. package/dist/vectordb/search-filters.d.ts +15 -0
  237. package/dist/vectordb/search-filters.d.ts.map +1 -0
  238. package/dist/vectordb/search-filters.js +129 -0
  239. package/dist/vectordb/search-filters.js.map +1 -0
  240. package/dist/vectordb/types.d.ts +194 -0
  241. package/dist/vectordb/types.d.ts.map +1 -0
  242. package/dist/vectordb/types.js +237 -0
  243. package/dist/vectordb/types.js.map +1 -0
  244. package/package.json +108 -0
  245. package/skills/mcp-local-rag/SKILL.md +234 -0
  246. package/skills/mcp-local-rag/references/cli-reference.md +190 -0
  247. package/skills/mcp-local-rag/references/html-ingestion.md +78 -0
@@ -0,0 +1,186 @@
1
+ import * as mupdf from 'mupdf';
2
+ import { MAX_VISUAL_RENDITION_BYTES } from '../utils/limits.js';
3
+ import { VlmError } from './types.js';
4
+ export { VlmError };
5
+ const RENDER_DPI = 200;
6
+ const BASE_SCALE = RENDER_DPI / 72;
7
+ const CAPTION_LONG_EDGE_MAX = 4096;
8
+ const CAPTION_PIXEL_MAX = 16_777_216;
9
+ const RENDITION_LONG_EDGE_MAX = 1024;
10
+ const RENDITION_TARGET_BYTES = 256 * 1024;
11
+ const JPEG_QUALITIES = [82, 72, 62, 52];
12
+ const RENDITION_EDGES = [1024, 896, 768, 640, 512, 384, 256];
13
+ function cropDimensions(cropRect) {
14
+ const width = cropRect[2] - cropRect[0];
15
+ const height = cropRect[3] - cropRect[1];
16
+ if (![...cropRect, width, height].every(Number.isFinite) || width <= 0 || height <= 0) {
17
+ throw new Error('Invalid crop rectangle');
18
+ }
19
+ return { width, height };
20
+ }
21
+ function scaleForLongEdge(cropRect, longEdge) {
22
+ const { width, height } = cropDimensions(cropRect);
23
+ return Math.min(BASE_SCALE, longEdge / Math.max(width, height));
24
+ }
25
+ function captionScale(cropRect) {
26
+ const { width, height } = cropDimensions(cropRect);
27
+ return Math.min(BASE_SCALE, CAPTION_LONG_EDGE_MAX / Math.max(width, height), Math.sqrt(CAPTION_PIXEL_MAX / (width * height)));
28
+ }
29
+ function renderCrop(page, cropRect, scale, consume) {
30
+ const { width: sourceWidth, height: sourceHeight } = cropDimensions(cropRect);
31
+ const width = Math.max(1, Math.floor(sourceWidth * scale));
32
+ const height = Math.max(1, Math.floor(sourceHeight * scale));
33
+ const pixmap = new mupdf.Pixmap(mupdf.ColorSpace.DeviceRGB, [0, 0, width, height], false);
34
+ let device = null;
35
+ try {
36
+ const matrix = [scale, 0, 0, scale, -cropRect[0] * scale, -cropRect[1] * scale];
37
+ device = new mupdf.DrawDevice(matrix, pixmap);
38
+ pixmap.clear(255);
39
+ page.run(device, mupdf.Matrix.identity);
40
+ return consume(pixmap);
41
+ }
42
+ finally {
43
+ try {
44
+ device?.close();
45
+ }
46
+ finally {
47
+ pixmap.destroy();
48
+ }
49
+ }
50
+ }
51
+ function encodePixmap(pixmap, mimeType, quality = 82) {
52
+ const bytes = mimeType === 'image/png' ? pixmap.asPNG() : pixmap.asJPEG(quality);
53
+ return {
54
+ bytes,
55
+ mimeType,
56
+ };
57
+ }
58
+ function encodePixmapCandidates(pixmap, mimeType) {
59
+ const renditions = [];
60
+ const qualities = mimeType === 'image/jpeg' ? JPEG_QUALITIES : [82];
61
+ for (const quality of qualities) {
62
+ const rendition = encodePixmap(pixmap, mimeType, quality);
63
+ renditions.push(rendition);
64
+ if (rendition.bytes.byteLength <= RENDITION_TARGET_BYTES) {
65
+ break;
66
+ }
67
+ }
68
+ return renditions;
69
+ }
70
+ export async function renderPdfPage(doc, pageNum, cropRect) {
71
+ let page = null;
72
+ try {
73
+ page = doc.loadPage(pageNum - 1);
74
+ return renderCrop(page, cropRect, captionScale(cropRect), (pixmap) => pixmap.asPNG());
75
+ }
76
+ catch (error) {
77
+ if (error instanceof VlmError) {
78
+ throw error;
79
+ }
80
+ const cause = error instanceof Error ? error : new Error(String(error));
81
+ throw new VlmError('Failed to render PDF page', { cause, pageNum });
82
+ }
83
+ finally {
84
+ page?.destroy();
85
+ }
86
+ }
87
+ function preferredMime(evidence) {
88
+ return evidence === 'raster' ? 'image/jpeg' : 'image/png';
89
+ }
90
+ function renditionEdges(sourceLongEdge) {
91
+ const initialLongEdge = Math.min(RENDITION_LONG_EDGE_MAX, sourceLongEdge);
92
+ return [...new Set(RENDITION_EDGES.map((edge) => Math.min(edge, initialLongEdge)))].filter((edge) => edge >= 1);
93
+ }
94
+ function selectForMime(edges, mimeType, renderAtEdge) {
95
+ let withinHardLimit = null;
96
+ for (const edge of edges) {
97
+ for (const rendition of renderAtEdge(edge, mimeType)) {
98
+ if (rendition.bytes.byteLength <= MAX_VISUAL_RENDITION_BYTES && withinHardLimit === null) {
99
+ withinHardLimit = rendition;
100
+ }
101
+ if (rendition.bytes.byteLength <= RENDITION_TARGET_BYTES) {
102
+ return rendition;
103
+ }
104
+ }
105
+ }
106
+ return withinHardLimit;
107
+ }
108
+ function selectBoundedRendition(sourceLongEdge, preferred, renderAtEdge) {
109
+ const edges = renditionEdges(sourceLongEdge);
110
+ const rendition = selectForMime(edges, preferred, renderAtEdge);
111
+ if (rendition) {
112
+ return rendition;
113
+ }
114
+ if (preferred === 'image/png') {
115
+ const jpeg = selectForMime(edges, 'image/jpeg', renderAtEdge);
116
+ if (jpeg) {
117
+ return jpeg;
118
+ }
119
+ }
120
+ throw new Error('Rendition exceeds the encoded-size limit');
121
+ }
122
+ export async function renderPdfRendition(doc, pageNum, cropRect, evidence) {
123
+ let page = null;
124
+ try {
125
+ const loadedPage = doc.loadPage(pageNum - 1);
126
+ page = loadedPage;
127
+ const { width, height } = cropDimensions(cropRect);
128
+ const nativeLongEdge = Math.max(1, Math.floor(Math.max(width, height) * BASE_SCALE));
129
+ return selectBoundedRendition(nativeLongEdge, preferredMime(evidence), (edge, mimeType) => renderCrop(loadedPage, cropRect, scaleForLongEdge(cropRect, edge), (pixmap) => encodePixmapCandidates(pixmap, mimeType)));
130
+ }
131
+ catch (error) {
132
+ if (error instanceof VlmError) {
133
+ throw error;
134
+ }
135
+ const cause = error instanceof Error ? error : new Error(String(error));
136
+ throw new VlmError('Failed to render PDF rendition', { cause, pageNum });
137
+ }
138
+ finally {
139
+ page?.destroy();
140
+ }
141
+ }
142
+ function renderImageAtSize(image, target, consume) {
143
+ const { width, height, preserveAlpha } = target;
144
+ const pixmap = new mupdf.Pixmap(mupdf.ColorSpace.DeviceRGB, [0, 0, width, height], preserveAlpha);
145
+ let device = null;
146
+ try {
147
+ pixmap.clear(preserveAlpha ? 0 : 255);
148
+ device = new mupdf.DrawDevice(mupdf.Matrix.identity, pixmap);
149
+ device.fillImage(image, [width, 0, 0, height, 0, 0], 1);
150
+ device.close();
151
+ device = null;
152
+ return consume(pixmap);
153
+ }
154
+ finally {
155
+ try {
156
+ device?.close();
157
+ }
158
+ finally {
159
+ pixmap.destroy();
160
+ }
161
+ }
162
+ }
163
+ /** Bound a Mammoth-extracted PNG/JPEG using the same query payload limits as PDF crops. */
164
+ export function renderImageRendition(bytes, sourceMimeType) {
165
+ let image = null;
166
+ try {
167
+ const loadedImage = new mupdf.Image(bytes);
168
+ image = loadedImage;
169
+ const sourceWidth = loadedImage.getWidth();
170
+ const sourceHeight = loadedImage.getHeight();
171
+ if (sourceWidth <= 0 || sourceHeight <= 0) {
172
+ throw new Error('Image has invalid dimensions');
173
+ }
174
+ const sourceLongEdge = Math.max(sourceWidth, sourceHeight);
175
+ return selectBoundedRendition(sourceLongEdge, sourceMimeType, (edge, mimeType) => {
176
+ const scale = edge / sourceLongEdge;
177
+ const width = Math.max(1, Math.round(sourceWidth * scale));
178
+ const height = Math.max(1, Math.round(sourceHeight * scale));
179
+ return renderImageAtSize(loadedImage, { width, height, preserveAlpha: mimeType === 'image/png' }, (pixmap) => encodePixmapCandidates(pixmap, mimeType));
180
+ });
181
+ }
182
+ finally {
183
+ image?.destroy();
184
+ }
185
+ }
186
+ //# sourceMappingURL=renderer.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"renderer.js","sourceRoot":"","sources":["../../src/pdf-visual/renderer.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,53 @@
1
+ import { AppError } from '../utils/errors.js';
2
+ import type { QualityProfile } from '../utils/visual-profile.js';
3
+ /**
4
+ * Error raised by any module on the visual ingest path. Carries the offending
5
+ * 1-based page number so callers can correlate it with the page list.
6
+ */
7
+ export declare class VlmError extends AppError {
8
+ readonly pageNum: number;
9
+ constructor(message: string, options: {
10
+ cause?: Error;
11
+ pageNum: number;
12
+ });
13
+ }
14
+ /**
15
+ * Captioner configuration. The model id is not caller-tunable: the selected
16
+ * `profile` resolves it, so prompt, chat template, processor signature,
17
+ * generation options and model class stay coherent together.
18
+ */
19
+ export interface CaptionerConfig {
20
+ /** Visual-quality profile — selects the underlying VLM family. */
21
+ profile: QualityProfile;
22
+ /** Model cache directory (shared with the embedder via `env.cacheDir`). */
23
+ cacheDir: string;
24
+ /** Execution device passed through to Transformers.js model loading. */
25
+ device?: string | undefined;
26
+ }
27
+ /**
28
+ * Returns the caption, or `null` when the model produced nothing after
29
+ * stripping and trimming — which tells the orchestrator to skip the page
30
+ * without raising. Only load, decode and generation failures throw.
31
+ */
32
+ export interface Captioner {
33
+ caption(pngBytes: Uint8Array, pageNum: number): Promise<string | null>;
34
+ dispose(): Promise<void>;
35
+ }
36
+ export type VisualBBox = [number, number, number, number];
37
+ export type VisualEvidence = 'raster' | 'vector';
38
+ export interface DetectedVisualRegion {
39
+ pageNum: number;
40
+ detectionIndex: number;
41
+ bbox: VisualBBox;
42
+ evidence: VisualEvidence;
43
+ }
44
+ export type VisualImageMimeType = 'image/png' | 'image/jpeg';
45
+ export interface ImageRendition {
46
+ bytes: Uint8Array;
47
+ mimeType: VisualImageMimeType;
48
+ }
49
+ export interface ProcessedVisualRegion extends DetectedVisualRegion {
50
+ caption: string | null;
51
+ rendition?: ImageRendition;
52
+ }
53
+ //# sourceMappingURL=types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/pdf-visual/types.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAC7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAA;AAEhE;;;GAGG;AACH,qBAAa,QAAS,SAAQ,QAAQ;IACpC,SAAgB,OAAO,EAAE,MAAM,CAAA;IAE/B,YAAY,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,KAAK,CAAC,EAAE,KAAK,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAIvE;CACF;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,kEAAkE;IAClE,OAAO,EAAE,cAAc,CAAA;IACvB,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAA;IAChB,wEAAwE;IACxE,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC5B;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,OAAO,CAAC,QAAQ,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IACtE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACzB;AAED,MAAM,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;AAEzD,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAEhD,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAA;IACf,cAAc,EAAE,MAAM,CAAA;IACtB,IAAI,EAAE,UAAU,CAAA;IAChB,QAAQ,EAAE,cAAc,CAAA;CACzB;AAED,MAAM,MAAM,mBAAmB,GAAG,WAAW,GAAG,YAAY,CAAA;AAE5D,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,UAAU,CAAA;IACjB,QAAQ,EAAE,mBAAmB,CAAA;CAC9B;AAED,MAAM,WAAW,qBAAsB,SAAQ,oBAAoB;IACjE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,SAAS,CAAC,EAAE,cAAc,CAAA;CAC3B"}
@@ -0,0 +1,17 @@
1
+ // Shared types for the `pdf-visual` package: `VlmError` (the package-wide
2
+ // named error, which also carries the offending page number) plus the
3
+ // captioner's public interface.
4
+ import { AppError } from '../utils/errors.js';
5
+ /**
6
+ * Error raised by any module on the visual ingest path. Carries the offending
7
+ * 1-based page number so callers can correlate it with the page list.
8
+ */
9
+ export class VlmError extends AppError {
10
+ pageNum;
11
+ constructor(message, options) {
12
+ super(message, 'pdf-visual', 'internal', options);
13
+ this.name = 'VlmError';
14
+ this.pageNum = options.pageNum;
15
+ }
16
+ }
17
+ //# sourceMappingURL=types.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/pdf-visual/types.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,sEAAsE;AACtE,gCAAgC;AAEhC,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAG7C;;;GAGG;AACH,MAAM,OAAO,QAAS,SAAQ,QAAQ;IACpB,OAAO,CAAQ;IAE/B,YAAY,OAAe,EAAE,OAA2C;QACtE,KAAK,CAAC,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,OAAO,CAAC,CAAA;QACjD,IAAI,CAAC,IAAI,GAAG,UAAU,CAAA;QACtB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAA;IAChC,CAAC;CACF"}
@@ -0,0 +1,63 @@
1
+ import type { Annotations } from '@modelcontextprotocol/sdk/types.js';
2
+ import { McpError } from '@modelcontextprotocol/sdk/types.js';
3
+ /**
4
+ * The MCP content shapes this server emits. Defined here rather than reusing
5
+ * the SDK's union, so an SDK addition cannot widen handler signatures.
6
+ */
7
+ export type RagTextContentBlock = {
8
+ type: 'text';
9
+ text: string;
10
+ annotations?: Annotations;
11
+ };
12
+ export type RagImageContentBlock = {
13
+ type: 'image';
14
+ data: string;
15
+ mimeType: 'image/png' | 'image/jpeg';
16
+ annotations?: Annotations;
17
+ };
18
+ export type RagContentBlock = RagTextContentBlock | RagImageContentBlock;
19
+ /**
20
+ * Append config-warning blocks to an existing content array. Returns the
21
+ * same `content` reference for chainability (handlers typically build the
22
+ * array first, then call this once before returning).
23
+ */
24
+ export declare function appendConfigWarnings<T extends RagContentBlock[]>(content: T, warnings: readonly string[]): T;
25
+ /**
26
+ * Diagnostic block exposing a config error, so `status` can report a degraded
27
+ * server over MCP without the user inspecting stderr.
28
+ */
29
+ export declare function buildConfigErrorBlock(message: string): RagTextContentBlock;
30
+ /**
31
+ * Each handler's client-message policy. `prefix` applies to the native-error
32
+ * fallback message only; prefix-less handlers omit it.
33
+ */
34
+ export type ToMcpErrorContext = {
35
+ prefix?: string;
36
+ };
37
+ /**
38
+ * The controlled message sent to the MCP client: only `.message`, regardless
39
+ * of `NODE_ENV`, so no stack or cause chain can leak even in development.
40
+ */
41
+ export declare function formatErrorForClient(error: unknown): string;
42
+ /**
43
+ * Full diagnostic string for stderr: every `.cause` link with its stack. Never
44
+ * sent to the client — the log-side counterpart of {@link formatErrorForClient}.
45
+ */
46
+ export declare function formatErrorForLog(error: unknown): string;
47
+ /**
48
+ * Log an error to stderr with its operation context and full cause chain.
49
+ * The only side-effecting boundary function — the formatters are pure so they
50
+ * can be composed without emitting logs.
51
+ */
52
+ export declare function logError(context: string, error: unknown): void;
53
+ /**
54
+ * Map a handler error to an `McpError` for the client boundary.
55
+ *
56
+ * An existing `McpError` passes through, preserving hand-built validation
57
+ * codes. A recognized `AppError` maps by `kind` — `validation`/`config` to
58
+ * `InvalidParams`, else `InternalError` — and keeps its own message raw, with
59
+ * NO operation prefix even when `context.prefix` is set. Anything else becomes
60
+ * `InternalError` with the prefix applied. The cause chain is never included.
61
+ */
62
+ export declare function toMcpError(error: unknown, context: ToMcpErrorContext): McpError;
63
+ //# sourceMappingURL=error-utils.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"error-utils.d.ts","sourceRoot":"","sources":["../../src/server/error-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oCAAoC,CAAA;AACrE,OAAO,EAAa,QAAQ,EAAE,MAAM,oCAAoC,CAAA;AAIxE;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,WAAW,CAAA;CAC1B,CAAA;AAED,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,OAAO,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,WAAW,GAAG,YAAY,CAAA;IACpC,WAAW,CAAC,EAAE,WAAW,CAAA;CAC1B,CAAA;AAED,MAAM,MAAM,eAAe,GAAG,mBAAmB,GAAG,oBAAoB,CAAA;AAwCxE;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,eAAe,EAAE,EAC9D,OAAO,EAAE,CAAC,EACV,QAAQ,EAAE,SAAS,MAAM,EAAE,GAC1B,CAAC,CAIH;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,mBAAmB,CAM1E;AAgBD;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,CAAA;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAE3D;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAQxD;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAE9D;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,iBAAiB,GAAG,QAAQ,CAc/E"}
@@ -0,0 +1,124 @@
1
+ import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
2
+ import { getCauseChain, isAppError } from '../utils/errors.js';
3
+ import { isRecord } from '../utils/type-guards.js';
4
+ /**
5
+ * Annotations for config-warning blocks: the audience covers the assistant and
6
+ * the user, and priority 0.3 keeps the block secondary to the tool result.
7
+ */
8
+ const WARNING_ANNOTATIONS = {
9
+ audience: ['user', 'assistant'],
10
+ priority: 0.3,
11
+ };
12
+ /**
13
+ * Annotations for the config-error block on `status`. The priority is above a
14
+ * warning's because a degraded server leaves `status` as the only way to recover.
15
+ */
16
+ const CONFIG_ERROR_ANNOTATIONS = {
17
+ audience: ['user', 'assistant'],
18
+ priority: 0.9,
19
+ };
20
+ /**
21
+ * The (zero or one) warning content block for the supplied warnings.
22
+ *
23
+ * `[]` when there are none, so a caller can spread it unconditionally. The
24
+ * structured per-warning form lives in the configuration layer; this renders
25
+ * one user-facing string. Every handler must go through here.
26
+ */
27
+ function buildConfigWarningBlocks(warnings) {
28
+ if (warnings.length === 0) {
29
+ return [];
30
+ }
31
+ return [
32
+ {
33
+ type: 'text',
34
+ text: `Warning: Tell the user about this configuration issue. ${warnings.join(' | ')}`,
35
+ annotations: WARNING_ANNOTATIONS,
36
+ },
37
+ ];
38
+ }
39
+ /**
40
+ * Append config-warning blocks to an existing content array. Returns the
41
+ * same `content` reference for chainability (handlers typically build the
42
+ * array first, then call this once before returning).
43
+ */
44
+ export function appendConfigWarnings(content, warnings) {
45
+ const blocks = content;
46
+ blocks.push(...buildConfigWarningBlocks(warnings));
47
+ return content;
48
+ }
49
+ /**
50
+ * Diagnostic block exposing a config error, so `status` can report a degraded
51
+ * server over MCP without the user inspecting stderr.
52
+ */
53
+ export function buildConfigErrorBlock(message) {
54
+ return {
55
+ type: 'text',
56
+ text: `Configuration error: Tell the user to fix this. ${message}`,
57
+ annotations: CONFIG_ERROR_ANNOTATIONS,
58
+ };
59
+ }
60
+ /**
61
+ * Coerce a thrown value into an `Error`, preserving a real one unchanged and
62
+ * reconstructing from a `{ message: string }` shape. One rule for every boundary.
63
+ */
64
+ function toError(error) {
65
+ if (error instanceof Error) {
66
+ return error;
67
+ }
68
+ if (isRecord(error) && typeof error['message'] === 'string') {
69
+ return new Error(error['message']);
70
+ }
71
+ return new Error(String(error));
72
+ }
73
+ /**
74
+ * The controlled message sent to the MCP client: only `.message`, regardless
75
+ * of `NODE_ENV`, so no stack or cause chain can leak even in development.
76
+ */
77
+ export function formatErrorForClient(error) {
78
+ return toError(error).message;
79
+ }
80
+ /**
81
+ * Full diagnostic string for stderr: every `.cause` link with its stack. Never
82
+ * sent to the client — the log-side counterpart of {@link formatErrorForClient}.
83
+ */
84
+ export function formatErrorForLog(error) {
85
+ const err = toError(error);
86
+ return getCauseChain(err)
87
+ .map((link, index) => {
88
+ const header = index === 0 ? '' : 'Caused by: ';
89
+ return `${header}${link.stack || `${link.name}: ${link.message}`}`;
90
+ })
91
+ .join('\n');
92
+ }
93
+ /**
94
+ * Log an error to stderr with its operation context and full cause chain.
95
+ * The only side-effecting boundary function — the formatters are pure so they
96
+ * can be composed without emitting logs.
97
+ */
98
+ export function logError(context, error) {
99
+ console.error(`[${context}] ${formatErrorForLog(error)}`);
100
+ }
101
+ /**
102
+ * Map a handler error to an `McpError` for the client boundary.
103
+ *
104
+ * An existing `McpError` passes through, preserving hand-built validation
105
+ * codes. A recognized `AppError` maps by `kind` — `validation`/`config` to
106
+ * `InvalidParams`, else `InternalError` — and keeps its own message raw, with
107
+ * NO operation prefix even when `context.prefix` is set. Anything else becomes
108
+ * `InternalError` with the prefix applied. The cause chain is never included.
109
+ */
110
+ export function toMcpError(error, context) {
111
+ if (error instanceof McpError) {
112
+ return error;
113
+ }
114
+ if (isAppError(error)) {
115
+ const code = error.kind === 'validation' || error.kind === 'config'
116
+ ? ErrorCode.InvalidParams
117
+ : ErrorCode.InternalError;
118
+ return new McpError(code, formatErrorForClient(error));
119
+ }
120
+ const message = formatErrorForClient(error);
121
+ const clientMessage = context.prefix !== undefined ? `${context.prefix}: ${message}` : message;
122
+ return new McpError(ErrorCode.InternalError, clientMessage);
123
+ }
124
+ //# sourceMappingURL=error-utils.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"error-utils.js","sourceRoot":"","sources":["../../src/server/error-utils.ts"],"names":[],"mappings":"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"}