@retiform/paperless-mcp 0.0.0-stage → 2.3.2

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 (74) hide show
  1. package/LICENSE +18 -0
  2. package/README.md +1005 -2
  3. package/build/api/PaperlessAPI.d.ts +63 -0
  4. package/build/api/PaperlessAPI.js +405 -0
  5. package/build/api/documentEnhancer.d.ts +24 -0
  6. package/build/api/documentEnhancer.js +111 -0
  7. package/build/api/documentEnhancer.test.d.ts +1 -0
  8. package/build/api/documentEnhancer.test.js +80 -0
  9. package/build/api/types.d.ts +203 -0
  10. package/build/api/types.js +15 -0
  11. package/build/api/utils.d.ts +16 -0
  12. package/build/api/utils.js +29 -0
  13. package/build/index.d.ts +2 -0
  14. package/build/index.js +189 -0
  15. package/build/resources/documents.d.ts +7 -0
  16. package/build/resources/documents.js +119 -0
  17. package/build/resources/documents.test.d.ts +1 -0
  18. package/build/resources/documents.test.js +124 -0
  19. package/build/server.d.ts +24 -0
  20. package/build/server.js +70 -0
  21. package/build/server.test.d.ts +1 -0
  22. package/build/server.test.js +54 -0
  23. package/build/test/mocks/paperlessApi.d.ts +4 -0
  24. package/build/test/mocks/paperlessApi.js +33 -0
  25. package/build/tools/boundedContent.test.d.ts +1 -0
  26. package/build/tools/boundedContent.test.js +544 -0
  27. package/build/tools/correspondents.d.ts +3 -0
  28. package/build/tools/correspondents.js +149 -0
  29. package/build/tools/customFields.d.ts +3 -0
  30. package/build/tools/customFields.js +142 -0
  31. package/build/tools/documentTypes.d.ts +3 -0
  32. package/build/tools/documentTypes.js +143 -0
  33. package/build/tools/documents.d.ts +134 -0
  34. package/build/tools/documents.js +814 -0
  35. package/build/tools/documents.test.d.ts +1 -0
  36. package/build/tools/documents.test.js +658 -0
  37. package/build/tools/mail.d.ts +3 -0
  38. package/build/tools/mail.js +187 -0
  39. package/build/tools/mail.test.d.ts +1 -0
  40. package/build/tools/mail.test.js +212 -0
  41. package/build/tools/notes.d.ts +3 -0
  42. package/build/tools/notes.js +55 -0
  43. package/build/tools/notes.test.d.ts +1 -0
  44. package/build/tools/notes.test.js +177 -0
  45. package/build/tools/schemaCompat.test.d.ts +1 -0
  46. package/build/tools/schemaCompat.test.js +59 -0
  47. package/build/tools/tags.d.ts +3 -0
  48. package/build/tools/tags.js +143 -0
  49. package/build/tools/utils/descriptions.d.ts +1 -0
  50. package/build/tools/utils/descriptions.js +4 -0
  51. package/build/tools/utils/documentQuery.d.ts +71 -0
  52. package/build/tools/utils/documentQuery.js +270 -0
  53. package/build/tools/utils/empty.d.ts +2 -0
  54. package/build/tools/utils/empty.js +7 -0
  55. package/build/tools/utils/matchingAlgorithm.d.ts +2 -0
  56. package/build/tools/utils/matchingAlgorithm.js +15 -0
  57. package/build/tools/utils/middlewares.d.ts +3 -0
  58. package/build/tools/utils/middlewares.js +31 -0
  59. package/build/tools/utils/monetary.d.ts +5 -0
  60. package/build/tools/utils/monetary.js +34 -0
  61. package/build/tools/utils/monetary.test.d.ts +1 -0
  62. package/build/tools/utils/monetary.test.js +25 -0
  63. package/build/tools/utils/queryString.d.ts +1 -0
  64. package/build/tools/utils/queryString.js +12 -0
  65. package/build/tools/utils/resourceUri.d.ts +29 -0
  66. package/build/tools/utils/resourceUri.js +37 -0
  67. package/build/tools/utils/resourceUri.test.d.ts +1 -0
  68. package/build/tools/utils/resourceUri.test.js +50 -0
  69. package/build/tools/utils/selectFields.d.ts +13 -0
  70. package/build/tools/utils/selectFields.js +91 -0
  71. package/build/tools/utils/selectFields.test.d.ts +1 -0
  72. package/build/tools/utils/selectFields.test.js +164 -0
  73. package/package.json +59 -4
  74. package/paperless-mcp.dxt +0 -0
@@ -0,0 +1,149 @@
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 __rest = (this && this.__rest) || function (s, e) {
12
+ var t = {};
13
+ for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
14
+ t[p] = s[p];
15
+ if (s != null && typeof Object.getOwnPropertySymbols === "function")
16
+ for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
17
+ if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
18
+ t[p[i]] = s[p[i]];
19
+ }
20
+ return t;
21
+ };
22
+ Object.defineProperty(exports, "__esModule", { value: true });
23
+ exports.registerCorrespondentTools = registerCorrespondentTools;
24
+ const zod_1 = require("zod");
25
+ const utils_1 = require("../api/utils");
26
+ const matchingAlgorithm_1 = require("./utils/matchingAlgorithm");
27
+ const middlewares_1 = require("./utils/middlewares");
28
+ const queryString_1 = require("./utils/queryString");
29
+ function registerCorrespondentTools(server, api) {
30
+ server.tool("list_correspondents", "List all correspondents with optional filtering and pagination. Correspondents represent entities that send or receive documents.", {
31
+ page: zod_1.z.number().optional(),
32
+ page_size: zod_1.z.number().optional(),
33
+ name__icontains: zod_1.z.string().optional(),
34
+ name__iendswith: zod_1.z.string().optional(),
35
+ name__iexact: zod_1.z.string().optional(),
36
+ name__istartswith: zod_1.z.string().optional(),
37
+ ordering: zod_1.z.string().optional(),
38
+ }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
39
+ if (!api)
40
+ throw new Error("Please configure API connection first");
41
+ const queryString = (0, queryString_1.buildQueryString)(args);
42
+ const response = yield api.getCorrespondents(queryString);
43
+ const enhancedResults = (0, utils_1.enhanceMatchingAlgorithmArray)(response.results || []);
44
+ return {
45
+ content: [
46
+ {
47
+ type: "text",
48
+ text: JSON.stringify(Object.assign(Object.assign({}, response), { results: enhancedResults })),
49
+ },
50
+ ],
51
+ };
52
+ })));
53
+ server.tool("get_correspondent", "Get a specific correspondent by ID with full details including matching rules.", { id: zod_1.z.number() }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
54
+ if (!api)
55
+ throw new Error("Please configure API connection first");
56
+ const response = yield api.getCorrespondent(args.id);
57
+ const enhancedCorrespondent = (0, utils_1.enhanceMatchingAlgorithm)(response);
58
+ return {
59
+ content: [
60
+ { type: "text", text: JSON.stringify(enhancedCorrespondent) },
61
+ ],
62
+ };
63
+ })));
64
+ server.tool("create_correspondent", "Create a new correspondent with optional matching pattern and algorithm for automatic document assignment.", {
65
+ name: zod_1.z.string(),
66
+ match: zod_1.z.string().optional(),
67
+ matching_algorithm: matchingAlgorithm_1.matchingAlgorithmSchema.optional(),
68
+ }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
69
+ if (!api)
70
+ throw new Error("Please configure API connection first");
71
+ const response = yield api.createCorrespondent(args);
72
+ const enhancedCorrespondent = (0, utils_1.enhanceMatchingAlgorithm)(response);
73
+ return {
74
+ content: [
75
+ { type: "text", text: JSON.stringify(enhancedCorrespondent) },
76
+ ],
77
+ };
78
+ })));
79
+ server.tool("update_correspondent", "Update an existing correspondent's name, matching pattern, or matching algorithm.", {
80
+ id: zod_1.z.number(),
81
+ name: zod_1.z.string(),
82
+ match: zod_1.z.string().optional(),
83
+ matching_algorithm: matchingAlgorithm_1.matchingAlgorithmSchema.optional(),
84
+ }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
85
+ if (!api)
86
+ throw new Error("Please configure API connection first");
87
+ const { id } = args, data = __rest(args, ["id"]);
88
+ const response = yield api.updateCorrespondent(id, data);
89
+ const enhancedCorrespondent = (0, utils_1.enhanceMatchingAlgorithm)(response);
90
+ return {
91
+ content: [
92
+ { type: "text", text: JSON.stringify(enhancedCorrespondent) },
93
+ ],
94
+ };
95
+ })));
96
+ server.tool("delete_correspondent", "⚠️ DESTRUCTIVE: Permanently delete a correspondent from the entire system. This will affect ALL documents that use this correspondent.", {
97
+ id: zod_1.z.number(),
98
+ confirm: zod_1.z
99
+ .boolean()
100
+ .describe("Must be true to confirm this destructive operation"),
101
+ }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
102
+ if (!api)
103
+ throw new Error("Please configure API connection first");
104
+ if (!args.confirm) {
105
+ throw new Error("Confirmation required for destructive operation. Set confirm: true to proceed.");
106
+ }
107
+ yield api.deleteCorrespondent(args.id);
108
+ return {
109
+ content: [
110
+ { type: "text", text: JSON.stringify({ status: "deleted" }) },
111
+ ],
112
+ };
113
+ })));
114
+ server.tool("bulk_edit_correspondents", "Bulk edit correspondents. ⚠️ WARNING: 'delete' operation permanently removes correspondents from the entire system.", {
115
+ correspondent_ids: zod_1.z.array(zod_1.z.number()),
116
+ operation: zod_1.z.enum(["set_permissions", "delete"]),
117
+ confirm: zod_1.z
118
+ .boolean()
119
+ .optional()
120
+ .describe("Must be true when operation is 'delete' to confirm destructive operation"),
121
+ owner: zod_1.z.number().optional(),
122
+ permissions: zod_1.z
123
+ .object({
124
+ view: zod_1.z.object({
125
+ users: zod_1.z.array(zod_1.z.number()).optional(),
126
+ groups: zod_1.z.array(zod_1.z.number()).optional(),
127
+ }),
128
+ change: zod_1.z.object({
129
+ users: zod_1.z.array(zod_1.z.number()).optional(),
130
+ groups: zod_1.z.array(zod_1.z.number()).optional(),
131
+ }),
132
+ })
133
+ .optional(),
134
+ merge: zod_1.z.boolean().optional(),
135
+ }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
136
+ if (!api)
137
+ throw new Error("Please configure API connection first");
138
+ if (args.operation === "delete" && !args.confirm) {
139
+ throw new Error("Confirmation required for destructive operation. Set confirm: true to proceed.");
140
+ }
141
+ return api.bulkEditObjects(args.correspondent_ids, "correspondents", args.operation, args.operation === "set_permissions"
142
+ ? {
143
+ owner: args.owner,
144
+ permissions: args.permissions,
145
+ merge: args.merge,
146
+ }
147
+ : {});
148
+ })));
149
+ }
@@ -0,0 +1,3 @@
1
+ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp";
2
+ import { PaperlessAPI } from "../api/PaperlessAPI";
3
+ export declare function registerCustomFieldTools(server: McpServer, api: PaperlessAPI): void;
@@ -0,0 +1,142 @@
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 __rest = (this && this.__rest) || function (s, e) {
12
+ var t = {};
13
+ for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
14
+ t[p] = s[p];
15
+ if (s != null && typeof Object.getOwnPropertySymbols === "function")
16
+ for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
17
+ if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
18
+ t[p[i]] = s[p[i]];
19
+ }
20
+ return t;
21
+ };
22
+ Object.defineProperty(exports, "__esModule", { value: true });
23
+ exports.registerCustomFieldTools = registerCustomFieldTools;
24
+ const zod_1 = require("zod");
25
+ const middlewares_1 = require("./utils/middlewares");
26
+ const queryString_1 = require("./utils/queryString");
27
+ function registerCustomFieldTools(server, api) {
28
+ server.tool("list_custom_fields", "List all custom fields. IMPORTANT: When a user query may refer to a custom field, you should fetch all custom fields up front (with a large enough page_size), cache them for the session, and search locally for matches by name before making further API calls. This reduces redundant requests and handles ambiguity efficiently.", {
29
+ page: zod_1.z.number().optional(),
30
+ page_size: zod_1.z.number().optional(),
31
+ name__icontains: zod_1.z.string().optional(),
32
+ name__iendswith: zod_1.z.string().optional(),
33
+ name__iexact: zod_1.z.string().optional(),
34
+ name__istartswith: zod_1.z.string().optional(),
35
+ ordering: zod_1.z.string().optional(),
36
+ }, (0, middlewares_1.withErrorHandling)((args) => __awaiter(this, void 0, void 0, function* () {
37
+ if (!api)
38
+ throw new Error("Please configure API connection first");
39
+ const queryString = (0, queryString_1.buildQueryString)(args);
40
+ const response = yield api.request(`/custom_fields/${queryString ? `?${queryString}` : ""}`);
41
+ return {
42
+ content: [
43
+ {
44
+ type: "text",
45
+ text: JSON.stringify(response),
46
+ },
47
+ ],
48
+ };
49
+ })));
50
+ server.tool("get_custom_field", "Get a specific custom field by ID with full details including data type and extra configuration.", { id: zod_1.z.number() }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
51
+ if (!api)
52
+ throw new Error("Please configure API connection first");
53
+ const response = yield api.getCustomField(args.id);
54
+ return {
55
+ content: [{ type: "text", text: JSON.stringify(response) }],
56
+ };
57
+ })));
58
+ server.tool("create_custom_field", "Create a new custom field with a specified data type (string, url, date, boolean, integer, float, monetary, documentlink, or select). For monetary fields, values must use currency code prefix format (e.g., USD10.00, GBP123.45) — NOT trailing symbol format (e.g., 10.00$).", {
59
+ name: zod_1.z.string(),
60
+ data_type: zod_1.z.enum([
61
+ "string",
62
+ "url",
63
+ "date",
64
+ "boolean",
65
+ "integer",
66
+ "float",
67
+ "monetary",
68
+ "documentlink",
69
+ "select",
70
+ ]),
71
+ extra_data: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).nullable().optional(),
72
+ }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
73
+ if (!api)
74
+ throw new Error("Please configure API connection first");
75
+ const response = yield api.createCustomField(args);
76
+ return {
77
+ content: [{ type: "text", text: JSON.stringify(response) }],
78
+ };
79
+ })));
80
+ server.tool("update_custom_field", "Update an existing custom field's name, data type, or extra configuration data.", {
81
+ id: zod_1.z.number(),
82
+ name: zod_1.z.string().optional(),
83
+ data_type: zod_1.z
84
+ .enum([
85
+ "string",
86
+ "url",
87
+ "date",
88
+ "boolean",
89
+ "integer",
90
+ "float",
91
+ "monetary",
92
+ "documentlink",
93
+ "select",
94
+ ])
95
+ .optional(),
96
+ extra_data: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).nullable().optional(),
97
+ }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
98
+ if (!api)
99
+ throw new Error("Please configure API connection first");
100
+ const { id } = args, data = __rest(args, ["id"]);
101
+ const response = yield api.updateCustomField(id, data);
102
+ return {
103
+ content: [{ type: "text", text: JSON.stringify(response) }],
104
+ };
105
+ })));
106
+ server.tool("delete_custom_field", "⚠️ DESTRUCTIVE: Permanently delete a custom field from the entire system. This will remove the field from ALL documents that use it.", {
107
+ id: zod_1.z.number(),
108
+ confirm: zod_1.z.boolean().describe("Must be true to confirm this destructive operation"),
109
+ }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
110
+ if (!api)
111
+ throw new Error("Please configure API connection first");
112
+ if (!args.confirm) {
113
+ throw new Error("Confirmation required for destructive operation. Set confirm: true to proceed.");
114
+ }
115
+ yield api.deleteCustomField(args.id);
116
+ return {
117
+ content: [
118
+ { type: "text", text: JSON.stringify({ status: "deleted" }) },
119
+ ],
120
+ };
121
+ })));
122
+ server.tool("bulk_edit_custom_fields", "Bulk edit custom fields. ⚠️ WARNING: 'delete' operation permanently removes custom fields from the entire system.", {
123
+ custom_fields: zod_1.z.array(zod_1.z.number()),
124
+ operation: zod_1.z.enum(["delete"]),
125
+ confirm: zod_1.z.boolean().optional().describe("Must be true when operation is 'delete' to confirm destructive operation"),
126
+ }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
127
+ if (!api)
128
+ throw new Error("Please configure API connection first");
129
+ if (args.operation === "delete" && !args.confirm) {
130
+ throw new Error("Confirmation required for destructive operation. Set confirm: true to proceed.");
131
+ }
132
+ const response = yield api.bulkEditObjects(args.custom_fields, "custom_field", args.operation);
133
+ return {
134
+ content: [
135
+ {
136
+ type: "text",
137
+ text: JSON.stringify(response),
138
+ },
139
+ ],
140
+ };
141
+ })));
142
+ }
@@ -0,0 +1,3 @@
1
+ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp";
2
+ import { PaperlessAPI } from "../api/PaperlessAPI";
3
+ export declare function registerDocumentTypeTools(server: McpServer, api: PaperlessAPI): void;
@@ -0,0 +1,143 @@
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 __rest = (this && this.__rest) || function (s, e) {
12
+ var t = {};
13
+ for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
14
+ t[p] = s[p];
15
+ if (s != null && typeof Object.getOwnPropertySymbols === "function")
16
+ for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
17
+ if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
18
+ t[p[i]] = s[p[i]];
19
+ }
20
+ return t;
21
+ };
22
+ Object.defineProperty(exports, "__esModule", { value: true });
23
+ exports.registerDocumentTypeTools = registerDocumentTypeTools;
24
+ const zod_1 = require("zod");
25
+ const utils_1 = require("../api/utils");
26
+ const matchingAlgorithm_1 = require("./utils/matchingAlgorithm");
27
+ const middlewares_1 = require("./utils/middlewares");
28
+ const queryString_1 = require("./utils/queryString");
29
+ function registerDocumentTypeTools(server, api) {
30
+ server.tool("list_document_types", "List all document types. IMPORTANT: When a user query may refer to a document type or tag, you should fetch all document types and all tags up front (with a large enough page_size), cache them for the session, and search locally for matches by name or slug before making further API calls. This reduces redundant requests and handles ambiguity between tags and document types efficiently.", {
31
+ page: zod_1.z.number().optional(),
32
+ page_size: zod_1.z.number().optional(),
33
+ name__icontains: zod_1.z.string().optional(),
34
+ name__iendswith: zod_1.z.string().optional(),
35
+ name__iexact: zod_1.z.string().optional(),
36
+ name__istartswith: zod_1.z.string().optional(),
37
+ ordering: zod_1.z.string().optional(),
38
+ }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
39
+ if (!api)
40
+ throw new Error("Please configure API connection first");
41
+ const queryString = (0, queryString_1.buildQueryString)(args);
42
+ const response = yield api.request(`/document_types/${queryString ? `?${queryString}` : ""}`);
43
+ const enhancedResults = (0, utils_1.enhanceMatchingAlgorithmArray)(response.results || []);
44
+ return {
45
+ content: [
46
+ {
47
+ type: "text",
48
+ text: JSON.stringify(Object.assign(Object.assign({}, response), { results: enhancedResults })),
49
+ },
50
+ ],
51
+ };
52
+ })));
53
+ server.tool("get_document_type", "Get a specific document type by ID with full details including matching rules.", { id: zod_1.z.number() }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
54
+ if (!api)
55
+ throw new Error("Please configure API connection first");
56
+ const response = yield api.request(`/document_types/${args.id}/`);
57
+ const enhancedDocumentType = (0, utils_1.enhanceMatchingAlgorithm)(response);
58
+ return {
59
+ content: [{ type: "text", text: JSON.stringify(enhancedDocumentType) }],
60
+ };
61
+ })));
62
+ server.tool("create_document_type", "Create a new document type with optional matching pattern and algorithm for automatic document classification.", {
63
+ name: zod_1.z.string(),
64
+ match: zod_1.z.string().optional(),
65
+ matching_algorithm: matchingAlgorithm_1.matchingAlgorithmSchema.optional(),
66
+ }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
67
+ if (!api)
68
+ throw new Error("Please configure API connection first");
69
+ const response = yield api.createDocumentType(args);
70
+ const enhancedDocumentType = (0, utils_1.enhanceMatchingAlgorithm)(response);
71
+ return {
72
+ content: [{ type: "text", text: JSON.stringify(enhancedDocumentType) }],
73
+ };
74
+ })));
75
+ server.tool("update_document_type", "Update an existing document type's name, matching pattern, or matching algorithm.", {
76
+ id: zod_1.z.number(),
77
+ name: zod_1.z.string(),
78
+ match: zod_1.z.string().optional(),
79
+ matching_algorithm: matchingAlgorithm_1.matchingAlgorithmSchema.optional(),
80
+ }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
81
+ if (!api)
82
+ throw new Error("Please configure API connection first");
83
+ const { id } = args, payloadWithoutId = __rest(args, ["id"]);
84
+ const response = yield api.updateDocumentType(id, payloadWithoutId);
85
+ const enhancedDocumentType = (0, utils_1.enhanceMatchingAlgorithm)(response);
86
+ return {
87
+ content: [{ type: "text", text: JSON.stringify(enhancedDocumentType) }],
88
+ };
89
+ })));
90
+ server.tool("delete_document_type", "⚠️ DESTRUCTIVE: Permanently delete a document type from the entire system. This will affect ALL documents that use this type.", {
91
+ id: zod_1.z.number(),
92
+ confirm: zod_1.z
93
+ .boolean()
94
+ .describe("Must be true to confirm this destructive operation"),
95
+ }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
96
+ if (!api)
97
+ throw new Error("Please configure API connection first");
98
+ if (!args.confirm) {
99
+ throw new Error("Confirmation required for destructive operation. Set confirm: true to proceed.");
100
+ }
101
+ yield api.deleteDocumentType(args.id);
102
+ return {
103
+ content: [
104
+ { type: "text", text: JSON.stringify({ status: "deleted" }) },
105
+ ],
106
+ };
107
+ })));
108
+ server.tool("bulk_edit_document_types", "Bulk edit document types. ⚠️ WARNING: 'delete' operation permanently removes document types from the entire system.", {
109
+ document_type_ids: zod_1.z.array(zod_1.z.number()),
110
+ operation: zod_1.z.enum(["set_permissions", "delete"]),
111
+ confirm: zod_1.z
112
+ .boolean()
113
+ .optional()
114
+ .describe("Must be true when operation is 'delete' to confirm destructive operation"),
115
+ owner: zod_1.z.number().optional(),
116
+ permissions: zod_1.z
117
+ .object({
118
+ view: zod_1.z.object({
119
+ users: zod_1.z.array(zod_1.z.number()).optional(),
120
+ groups: zod_1.z.array(zod_1.z.number()).optional(),
121
+ }),
122
+ change: zod_1.z.object({
123
+ users: zod_1.z.array(zod_1.z.number()).optional(),
124
+ groups: zod_1.z.array(zod_1.z.number()).optional(),
125
+ }),
126
+ })
127
+ .optional(),
128
+ merge: zod_1.z.boolean().optional(),
129
+ }, (0, middlewares_1.withErrorHandling)((args, extra) => __awaiter(this, void 0, void 0, function* () {
130
+ if (!api)
131
+ throw new Error("Please configure API connection first");
132
+ if (args.operation === "delete" && !args.confirm) {
133
+ throw new Error("Confirmation required for destructive operation. Set confirm: true to proceed.");
134
+ }
135
+ return api.bulkEditObjects(args.document_type_ids, "document_types", args.operation, args.operation === "set_permissions"
136
+ ? {
137
+ owner: args.owner,
138
+ permissions: args.permissions,
139
+ merge: args.merge,
140
+ }
141
+ : {});
142
+ })));
143
+ }
@@ -0,0 +1,134 @@
1
+ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp";
2
+ import { Document, DocumentsResponse, SearchHit } from "../api/types";
3
+ import { PaperlessAPI } from "../api/PaperlessAPI";
4
+ import { BuildDocumentQueryArgs } from "./utils/documentQuery";
5
+ export type BulkCustomFieldValue = string | number | boolean | number[] | null;
6
+ export type BulkCustomFieldUpdate = {
7
+ field: number;
8
+ value: BulkCustomFieldValue;
9
+ };
10
+ export type BulkCustomFieldParameters = {
11
+ add_custom_fields?: Record<string, BulkCustomFieldValue>;
12
+ remove_custom_fields?: number[];
13
+ };
14
+ /** Default number of characters returned by a bounded content read. */
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;
18
+ /** Default passage size for search_passages. */
19
+ export declare const DEFAULT_PASSAGE_WINDOW = 800;
20
+ /** Default maximum number of passages returned by search_passages. */
21
+ export declare const DEFAULT_MAX_PASSAGES = 5;
22
+ /**
23
+ * Reads the inline budget from the environment at call time (not module
24
+ * load), so tests can exercise different budgets without re-importing.
25
+ */
26
+ export declare function getMaxInlineChars(): number;
27
+ /**
28
+ * Normalizes bounded-read arguments into a validated {offset, maxChars} pair.
29
+ *
30
+ * Invariants:
31
+ * - offset must be >= 0 and inside the document;
32
+ * - maxChars is clamped to [1, budget] where budget is the inline budget;
33
+ * - a caller-requested window beyond the budget fails loudly instead of
34
+ * silently shrinking (never silently slice what the caller asked for).
35
+ */
36
+ export declare function resolveBoundedRead(offset: number | undefined, maxChars: number | undefined, contentLength: number, budget?: number): {
37
+ offset: number;
38
+ maxChars: number;
39
+ };
40
+ /**
41
+ * Extracts a bounded window of document content and describes it.
42
+ *
43
+ * The window is always derived from the stored content server-side; the full
44
+ * text never crosses this boundary un-sliced.
45
+ */
46
+ export declare function sliceDocumentContent(doc: Pick<Document, "id" | "title" | "content">, offset: number, maxChars: number): {
47
+ id: number;
48
+ title: string;
49
+ content: string;
50
+ offset: number;
51
+ returned_chars: number;
52
+ content_length: number;
53
+ truncated: boolean;
54
+ has_more: boolean;
55
+ };
56
+ /**
57
+ * Builds one bounded passage of document content centered on the actual hit.
58
+ *
59
+ * The window is cut from the stored content server-side; the full text never
60
+ * crosses this boundary un-sliced. Anchoring prefers the server's own
61
+ * highlighted phrase — the only anchor that survives whoosh stemming, since
62
+ * the index may match word variants the stored text does not contain
63
+ * verbatim — then falls back to the first verbatim term occurrence, and
64
+ * finally to the head of the document rather than returning nothing.
65
+ */
66
+ export declare function buildSearchPassage(doc: Pick<Document, "id" | "title" | "content">, terms: string[], window: number, searchHit?: Pick<SearchHit, "score" | "highlights">): {
67
+ id: number;
68
+ title: string;
69
+ score?: number;
70
+ highlights?: string;
71
+ passage: string;
72
+ offset: number;
73
+ content_length: number;
74
+ };
75
+ /**
76
+ * Extracts candidate anchor phrases from the server's highlight HTML: markup
77
+ * stripped, HTML entities decoded, whitespace collapsed. Phrases shorter than
78
+ * four characters cannot anchor a window reliably and are skipped so stray
79
+ * short matches never drag the window to a wrong position.
80
+ */
81
+ export declare function extractHighlightPhrases(highlights: string): string[];
82
+ /**
83
+ * Splits a full-text query into lowercase search terms for passage location.
84
+ * Extracts letter/number runs (Unicode-aware, so accented and non-Latin terms
85
+ * survive intact) so operators and quoting from the query syntax do not
86
+ * pollute the verbatim lookup.
87
+ */
88
+ export declare function extractSearchTerms(query: string): string[];
89
+ /** Validates that a file path is safe to read for document upload. */
90
+ export declare function validateFilePath(filePath: string): Promise<void>;
91
+ /**
92
+ * Builds Paperless-NGX bulk edit parameters from base parameters plus optional
93
+ * custom field updates.
94
+ *
95
+ * Paperless-NGX expects custom field bulk updates as an `add_custom_fields`
96
+ * record keyed by custom field id. `addCustomFields` is accepted as an array for
97
+ * the MCP tool schema and transformed into that id-to-value record while
98
+ * preserving supported value types, including `number[]` document links and
99
+ * `null` resets. Passing an empty `addCustomFields` array intentionally produces
100
+ * an empty `add_custom_fields` record.
101
+ *
102
+ * When `includeCustomFieldDefaults` is true, the function also initializes
103
+ * `add_custom_fields` and `remove_custom_fields` with empty defaults using
104
+ * nullish coalescing (`??=`). This keeps the `modify_custom_fields` method's
105
+ * payload shape acceptable to Paperless even when no field values are supplied.
106
+ *
107
+ * @param parameters - Base bulk edit parameters to include in the result.
108
+ * @param addCustomFields - Optional custom field updates to map by field id.
109
+ * @param includeCustomFieldDefaults - Whether to include empty custom field
110
+ * defaults required by `modify_custom_fields`.
111
+ * @returns The merged API parameters with custom field updates transformed into
112
+ * Paperless-NGX's `add_custom_fields` record shape.
113
+ */
114
+ export declare function buildBulkEditParameters<T extends Record<string, unknown>>(parameters: T, addCustomFields?: BulkCustomFieldUpdate[], includeCustomFieldDefaults?: boolean, includeTagDefaults?: boolean): T & BulkCustomFieldParameters;
115
+ /**
116
+ * Defensive rewrite for django-watson full-text queries: strips apostrophes
117
+ * (a known server-side 400 trigger) and rebalances double quotes. Returns
118
+ * null when the rewrite leaves nothing searchable (caller should not retry).
119
+ */
120
+ export declare function sanitizeFullTextQuery(query: string): string | null;
121
+ interface SanitizedSearch {
122
+ response: DocumentsResponse;
123
+ querySanitized: boolean;
124
+ }
125
+ /**
126
+ * Executes a full-text search with one sanitized retry: django-watson rejects
127
+ * some syntactically valid queries with an opaque HTTP 400, so on a 400 the
128
+ * query is defensively rewritten and attempted once more. Django-ORM filter
129
+ * values are never rewritten — only the full-text query string. A persistent
130
+ * failure rethrows the original error with the attempted queries attached.
131
+ */
132
+ export declare function runDocumentSearch(api: PaperlessAPI, query: string, queryParams?: BuildDocumentQueryArgs): Promise<SanitizedSearch>;
133
+ export declare function registerDocumentTools(server: McpServer, api: PaperlessAPI): void;
134
+ export {};