@retiform/paperless-mcp 0.0.0-stage → 2.3.1
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/LICENSE +18 -0
- package/README.md +1004 -2
- package/build/api/PaperlessAPI.d.ts +63 -0
- package/build/api/PaperlessAPI.js +405 -0
- package/build/api/documentEnhancer.d.ts +24 -0
- package/build/api/documentEnhancer.js +111 -0
- package/build/api/documentEnhancer.test.d.ts +1 -0
- package/build/api/documentEnhancer.test.js +80 -0
- package/build/api/types.d.ts +203 -0
- package/build/api/types.js +15 -0
- package/build/api/utils.d.ts +16 -0
- package/build/api/utils.js +29 -0
- package/build/index.d.ts +2 -0
- package/build/index.js +189 -0
- package/build/resources/documents.d.ts +7 -0
- package/build/resources/documents.js +119 -0
- package/build/resources/documents.test.d.ts +1 -0
- package/build/resources/documents.test.js +124 -0
- package/build/server.d.ts +24 -0
- package/build/server.js +70 -0
- package/build/server.test.d.ts +1 -0
- package/build/server.test.js +54 -0
- package/build/test/mocks/paperlessApi.d.ts +4 -0
- package/build/test/mocks/paperlessApi.js +33 -0
- package/build/tools/boundedContent.test.d.ts +1 -0
- package/build/tools/boundedContent.test.js +544 -0
- package/build/tools/correspondents.d.ts +3 -0
- package/build/tools/correspondents.js +149 -0
- package/build/tools/customFields.d.ts +3 -0
- package/build/tools/customFields.js +142 -0
- package/build/tools/documentTypes.d.ts +3 -0
- package/build/tools/documentTypes.js +143 -0
- package/build/tools/documents.d.ts +134 -0
- package/build/tools/documents.js +814 -0
- package/build/tools/documents.test.d.ts +1 -0
- package/build/tools/documents.test.js +658 -0
- package/build/tools/mail.d.ts +3 -0
- package/build/tools/mail.js +187 -0
- package/build/tools/mail.test.d.ts +1 -0
- package/build/tools/mail.test.js +212 -0
- package/build/tools/notes.d.ts +3 -0
- package/build/tools/notes.js +55 -0
- package/build/tools/notes.test.d.ts +1 -0
- package/build/tools/notes.test.js +177 -0
- package/build/tools/schemaCompat.test.d.ts +1 -0
- package/build/tools/schemaCompat.test.js +59 -0
- package/build/tools/tags.d.ts +3 -0
- package/build/tools/tags.js +143 -0
- package/build/tools/utils/descriptions.d.ts +1 -0
- package/build/tools/utils/descriptions.js +4 -0
- package/build/tools/utils/documentQuery.d.ts +71 -0
- package/build/tools/utils/documentQuery.js +270 -0
- package/build/tools/utils/empty.d.ts +2 -0
- package/build/tools/utils/empty.js +7 -0
- package/build/tools/utils/matchingAlgorithm.d.ts +2 -0
- package/build/tools/utils/matchingAlgorithm.js +15 -0
- package/build/tools/utils/middlewares.d.ts +3 -0
- package/build/tools/utils/middlewares.js +31 -0
- package/build/tools/utils/monetary.d.ts +5 -0
- package/build/tools/utils/monetary.js +34 -0
- package/build/tools/utils/monetary.test.d.ts +1 -0
- package/build/tools/utils/monetary.test.js +25 -0
- package/build/tools/utils/queryString.d.ts +1 -0
- package/build/tools/utils/queryString.js +12 -0
- package/build/tools/utils/resourceUri.d.ts +29 -0
- package/build/tools/utils/resourceUri.js +37 -0
- package/build/tools/utils/resourceUri.test.d.ts +1 -0
- package/build/tools/utils/resourceUri.test.js +50 -0
- package/build/tools/utils/selectFields.d.ts +13 -0
- package/build/tools/utils/selectFields.js +91 -0
- package/build/tools/utils/selectFields.test.d.ts +1 -0
- package/build/tools/utils/selectFields.test.js +164 -0
- package/package.json +59 -4
- 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,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,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 {};
|