@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,187 @@
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.registerMailTools = registerMailTools;
24
+ const zod_1 = require("zod");
25
+ const middlewares_1 = require("./utils/middlewares");
26
+ const queryString_1 = require("./utils/queryString");
27
+ const MAIL_RULE_ACTION_DESCRIPTION = "Mail rule action: 1=Delete, 2=Move to specified folder, 3=Mark as read/don't process read mails, 4=Flag/don't process flagged mails, 5=Tag/don't process tagged mails";
28
+ const ASSIGN_TITLE_FROM_DESCRIPTION = "Title assignment: 1=Use subject as title, 2=Use attachment filename as title, 3=Do not assign title from rule";
29
+ const ASSIGN_CORRESPONDENT_FROM_DESCRIPTION = "Correspondent assignment: 1=Do not assign, 2=Use mail address, 3=Use sender name or address, 4=Use assign_correspondent";
30
+ const ATTACHMENT_TYPE_DESCRIPTION = "Attachment type: 1=Only process attachments, 2=Process all files including inline attachments";
31
+ const CONSUMPTION_SCOPE_DESCRIPTION = "Consumption scope: 1=Only process attachments, 2=Process full mail as .eml, 3=Process full mail and attachments separately";
32
+ const PDF_LAYOUT_DESCRIPTION = "PDF layout for full-mail consumption: 0=System default, 1=Text then HTML, 2=HTML then text, 3=HTML only, 4=Text only";
33
+ const mailRuleFields = {
34
+ name: zod_1.z.string().optional(),
35
+ account: zod_1.z.number().int().optional(),
36
+ enabled: zod_1.z.boolean().optional(),
37
+ folder: zod_1.z.string().optional(),
38
+ filter_from: zod_1.z.string().max(256).nullable().optional(),
39
+ filter_to: zod_1.z.string().max(256).nullable().optional(),
40
+ filter_subject: zod_1.z.string().max(256).nullable().optional(),
41
+ filter_body: zod_1.z.string().max(256).nullable().optional(),
42
+ filter_attachment_filename_include: zod_1.z.string().nullable().optional(),
43
+ filter_attachment_filename_exclude: zod_1.z.string().nullable().optional(),
44
+ maximum_age: zod_1.z.number().int().min(0).optional(),
45
+ action: zod_1.z
46
+ .number()
47
+ .int()
48
+ .min(1)
49
+ .max(5)
50
+ .optional()
51
+ .describe(MAIL_RULE_ACTION_DESCRIPTION),
52
+ action_parameter: zod_1.z.string().nullable().optional(),
53
+ assign_title_from: zod_1.z
54
+ .number()
55
+ .int()
56
+ .min(1)
57
+ .max(3)
58
+ .optional()
59
+ .describe(ASSIGN_TITLE_FROM_DESCRIPTION),
60
+ assign_tags: zod_1.z.array(zod_1.z.number().int().nullable()).optional(),
61
+ assign_correspondent_from: zod_1.z
62
+ .number()
63
+ .int()
64
+ .min(1)
65
+ .max(4)
66
+ .optional()
67
+ .describe(ASSIGN_CORRESPONDENT_FROM_DESCRIPTION),
68
+ assign_correspondent: zod_1.z.number().int().nullable().optional(),
69
+ assign_document_type: zod_1.z.number().int().nullable().optional(),
70
+ assign_owner_from_rule: zod_1.z.boolean().optional(),
71
+ order: zod_1.z.number().int().optional(),
72
+ attachment_type: zod_1.z
73
+ .number()
74
+ .int()
75
+ .min(1)
76
+ .max(2)
77
+ .optional()
78
+ .describe(ATTACHMENT_TYPE_DESCRIPTION),
79
+ consumption_scope: zod_1.z
80
+ .number()
81
+ .int()
82
+ .min(1)
83
+ .max(3)
84
+ .optional()
85
+ .describe(CONSUMPTION_SCOPE_DESCRIPTION),
86
+ pdf_layout: zod_1.z
87
+ .number()
88
+ .int()
89
+ .min(0)
90
+ .max(4)
91
+ .optional()
92
+ .describe(PDF_LAYOUT_DESCRIPTION),
93
+ owner: zod_1.z.number().int().nullable().optional(),
94
+ };
95
+ function registerMailTools(server, api) {
96
+ server.tool("list_mail_accounts", "List Paperless mail accounts for selecting the account ID needed by mail rules. Does not expose account passwords.", {
97
+ page: zod_1.z.number().optional(),
98
+ page_size: zod_1.z.number().optional(),
99
+ }, (0, middlewares_1.withErrorHandling)((args) => __awaiter(this, void 0, void 0, function* () {
100
+ if (!api)
101
+ throw new Error("Please configure API connection first");
102
+ const queryString = (0, queryString_1.buildQueryString)(args);
103
+ const response = yield api.getMailAccounts(queryString);
104
+ const sanitizedResults = (response.results || []).map((account) => (Object.assign(Object.assign({}, account), { password: undefined })));
105
+ return {
106
+ content: [
107
+ {
108
+ type: "text",
109
+ text: JSON.stringify(Object.assign(Object.assign({}, response), { results: sanitizedResults })),
110
+ },
111
+ ],
112
+ };
113
+ })));
114
+ server.tool("get_mail_account", "Get one Paperless mail account by ID. Password/token fields are redacted if the server returns them.", { id: zod_1.z.number().int() }, (0, middlewares_1.withErrorHandling)((args) => __awaiter(this, void 0, void 0, function* () {
115
+ if (!api)
116
+ throw new Error("Please configure API connection first");
117
+ const _a = yield api.getMailAccount(args.id), { password } = _a, account = __rest(_a, ["password"]);
118
+ return {
119
+ content: [{ type: "text", text: JSON.stringify(account) }],
120
+ };
121
+ })));
122
+ server.tool("process_mail_account", "Manually run Paperless mail processing for one account. This can consume matching mails according to enabled Paperless mail rules.", { id: zod_1.z.number().int() }, (0, middlewares_1.withErrorHandling)((args) => __awaiter(this, void 0, void 0, function* () {
123
+ if (!api)
124
+ throw new Error("Please configure API connection first");
125
+ yield api.processMailAccount(args.id);
126
+ return {
127
+ content: [
128
+ { type: "text", text: JSON.stringify({ status: "processed" }) },
129
+ ],
130
+ };
131
+ })));
132
+ server.tool("list_mail_rules", "List Paperless mail rules with optional pagination.", {
133
+ page: zod_1.z.number().optional(),
134
+ page_size: zod_1.z.number().optional(),
135
+ }, (0, middlewares_1.withErrorHandling)((args) => __awaiter(this, void 0, void 0, function* () {
136
+ if (!api)
137
+ throw new Error("Please configure API connection first");
138
+ const queryString = (0, queryString_1.buildQueryString)(args);
139
+ const response = yield api.getMailRules(queryString);
140
+ return {
141
+ content: [{ type: "text", text: JSON.stringify(response) }],
142
+ };
143
+ })));
144
+ server.tool("get_mail_rule", "Get one Paperless mail rule by ID.", { id: zod_1.z.number().int() }, (0, middlewares_1.withErrorHandling)((args) => __awaiter(this, void 0, void 0, function* () {
145
+ if (!api)
146
+ throw new Error("Please configure API connection first");
147
+ const response = yield api.getMailRule(args.id);
148
+ return {
149
+ content: [{ type: "text", text: JSON.stringify(response) }],
150
+ };
151
+ })));
152
+ server.tool("create_mail_rule", "Create a Paperless mail rule. Use list_mail_accounts first to choose account. Prefer attachment-only rules for invoices unless the full mail must be archived.", Object.assign(Object.assign({}, mailRuleFields), { name: zod_1.z.string(), account: zod_1.z.number().int(), folder: zod_1.z.string() }), (0, middlewares_1.withErrorHandling)((args) => __awaiter(this, void 0, void 0, function* () {
153
+ if (!api)
154
+ throw new Error("Please configure API connection first");
155
+ const response = yield api.createMailRule(args);
156
+ return {
157
+ content: [{ type: "text", text: JSON.stringify(response) }],
158
+ };
159
+ })));
160
+ server.tool("update_mail_rule", "Patch an existing Paperless mail rule. Only supplied fields are changed.", Object.assign({ id: zod_1.z.number().int() }, mailRuleFields), (0, middlewares_1.withErrorHandling)((args) => __awaiter(this, void 0, void 0, function* () {
161
+ if (!api)
162
+ throw new Error("Please configure API connection first");
163
+ const { id } = args, data = __rest(args, ["id"]);
164
+ const response = yield api.updateMailRule(id, data);
165
+ return {
166
+ content: [{ type: "text", text: JSON.stringify(response) }],
167
+ };
168
+ })));
169
+ server.tool("delete_mail_rule", "Delete one Paperless mail rule. This changes future mail ingestion behavior but does not delete documents.", {
170
+ id: zod_1.z.number().int(),
171
+ confirm: zod_1.z
172
+ .boolean()
173
+ .describe("Must be true to confirm deleting the rule"),
174
+ }, (0, middlewares_1.withErrorHandling)((args) => __awaiter(this, void 0, void 0, function* () {
175
+ if (!api)
176
+ throw new Error("Please configure API connection first");
177
+ if (!args.confirm) {
178
+ throw new Error("Confirmation required. Set confirm: true to delete the mail rule.");
179
+ }
180
+ yield api.deleteMailRule(args.id);
181
+ return {
182
+ content: [
183
+ { type: "text", text: JSON.stringify({ status: "deleted" }) },
184
+ ],
185
+ };
186
+ })));
187
+ }
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,212 @@
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 __importDefault = (this && this.__importDefault) || function (mod) {
12
+ return (mod && mod.__esModule) ? mod : { "default": mod };
13
+ };
14
+ Object.defineProperty(exports, "__esModule", { value: true });
15
+ const strict_1 = __importDefault(require("node:assert/strict"));
16
+ const node_test_1 = require("node:test");
17
+ const index_js_1 = require("@modelcontextprotocol/sdk/client/index.js");
18
+ const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
19
+ const mail_1 = require("./mail");
20
+ class TestTransport {
21
+ start() {
22
+ return __awaiter(this, void 0, void 0, function* () { });
23
+ }
24
+ send(message) {
25
+ return __awaiter(this, void 0, void 0, function* () {
26
+ queueMicrotask(() => { var _a, _b; return (_b = (_a = this.peer) === null || _a === void 0 ? void 0 : _a.onmessage) === null || _b === void 0 ? void 0 : _b.call(_a, message); });
27
+ });
28
+ }
29
+ close() {
30
+ return __awaiter(this, void 0, void 0, function* () {
31
+ var _a;
32
+ (_a = this.onclose) === null || _a === void 0 ? void 0 : _a.call(this);
33
+ });
34
+ }
35
+ }
36
+ function createTransportPair() {
37
+ const clientTransport = new TestTransport();
38
+ const serverTransport = new TestTransport();
39
+ clientTransport.peer = serverTransport;
40
+ serverTransport.peer = clientTransport;
41
+ return { clientTransport, serverTransport };
42
+ }
43
+ function parseToolText(result) {
44
+ var _a;
45
+ const item = (_a = result.content) === null || _a === void 0 ? void 0 : _a[0];
46
+ if (!item || item.type !== "text") {
47
+ throw new Error("Expected text tool response");
48
+ }
49
+ return JSON.parse(item.text);
50
+ }
51
+ function withMailClient(api, run) {
52
+ return __awaiter(this, void 0, void 0, function* () {
53
+ const server = new mcp_js_1.McpServer({ name: "paperless-mail-test", version: "1.0.0" });
54
+ (0, mail_1.registerMailTools)(server, api);
55
+ const client = new index_js_1.Client({
56
+ name: "paperless-mail-test-client",
57
+ version: "1.0.0",
58
+ });
59
+ const { clientTransport, serverTransport } = createTransportPair();
60
+ yield server.connect(serverTransport);
61
+ yield client.connect(clientTransport);
62
+ try {
63
+ yield run(client);
64
+ }
65
+ finally {
66
+ yield client.close();
67
+ yield server.close();
68
+ }
69
+ });
70
+ }
71
+ (0, node_test_1.test)("mail tools are registered", () => __awaiter(void 0, void 0, void 0, function* () {
72
+ yield withMailClient({}, (client) => __awaiter(void 0, void 0, void 0, function* () {
73
+ const result = yield client.listTools();
74
+ const names = result.tools.map((tool) => tool.name).sort();
75
+ strict_1.default.deepEqual(names, [
76
+ "create_mail_rule",
77
+ "delete_mail_rule",
78
+ "get_mail_account",
79
+ "get_mail_rule",
80
+ "list_mail_accounts",
81
+ "list_mail_rules",
82
+ "process_mail_account",
83
+ "update_mail_rule",
84
+ ]);
85
+ }));
86
+ }));
87
+ (0, node_test_1.test)("list_mail_accounts redacts returned passwords", () => __awaiter(void 0, void 0, void 0, function* () {
88
+ const api = {
89
+ getMailAccounts: (queryString) => __awaiter(void 0, void 0, void 0, function* () {
90
+ return ({
91
+ count: 1,
92
+ next: null,
93
+ previous: null,
94
+ results: [
95
+ {
96
+ id: 1,
97
+ name: "Inbox",
98
+ username: "paperless@example.test",
99
+ password: "secret",
100
+ queryString,
101
+ },
102
+ ],
103
+ });
104
+ }),
105
+ };
106
+ yield withMailClient(api, (client) => __awaiter(void 0, void 0, void 0, function* () {
107
+ const result = (yield client.callTool({
108
+ name: "list_mail_accounts",
109
+ arguments: { page: 2, page_size: 10 },
110
+ }));
111
+ const response = parseToolText(result);
112
+ strict_1.default.equal(response.results[0].password, undefined);
113
+ strict_1.default.equal(response.results[0].queryString, "page=2&page_size=10");
114
+ }));
115
+ }));
116
+ (0, node_test_1.test)("get_mail_account redacts returned password", () => __awaiter(void 0, void 0, void 0, function* () {
117
+ const api = {
118
+ getMailAccount: (id) => __awaiter(void 0, void 0, void 0, function* () {
119
+ return ({
120
+ id,
121
+ name: "Inbox",
122
+ username: "paperless@example.test",
123
+ password: "secret",
124
+ });
125
+ }),
126
+ };
127
+ yield withMailClient(api, (client) => __awaiter(void 0, void 0, void 0, function* () {
128
+ const result = (yield client.callTool({
129
+ name: "get_mail_account",
130
+ arguments: { id: 7 },
131
+ }));
132
+ const account = parseToolText(result);
133
+ strict_1.default.deepEqual(account, {
134
+ id: 7,
135
+ name: "Inbox",
136
+ username: "paperless@example.test",
137
+ });
138
+ }));
139
+ }));
140
+ (0, node_test_1.test)("process_mail_account reports success after processing", () => __awaiter(void 0, void 0, void 0, function* () {
141
+ const calls = [];
142
+ const api = {
143
+ processMailAccount: (id) => __awaiter(void 0, void 0, void 0, function* () {
144
+ calls.push(["process", id]);
145
+ }),
146
+ };
147
+ yield withMailClient(api, (client) => __awaiter(void 0, void 0, void 0, function* () {
148
+ const result = (yield client.callTool({
149
+ name: "process_mail_account",
150
+ arguments: { id: 5 },
151
+ }));
152
+ const response = parseToolText(result);
153
+ strict_1.default.deepEqual(response, { status: "processed" });
154
+ }));
155
+ strict_1.default.deepEqual(calls, [["process", 5]]);
156
+ }));
157
+ (0, node_test_1.test)("mail rule write tools pass through payloads", () => __awaiter(void 0, void 0, void 0, function* () {
158
+ const calls = [];
159
+ const api = {
160
+ createMailRule: (data) => __awaiter(void 0, void 0, void 0, function* () {
161
+ calls.push(["create", data]);
162
+ return Object.assign({ id: 3 }, data);
163
+ }),
164
+ updateMailRule: (id, data) => __awaiter(void 0, void 0, void 0, function* () {
165
+ calls.push(["update", id, data]);
166
+ return Object.assign({ id }, data);
167
+ }),
168
+ deleteMailRule: (id) => __awaiter(void 0, void 0, void 0, function* () {
169
+ calls.push(["delete", id]);
170
+ }),
171
+ };
172
+ yield withMailClient(api, (client) => __awaiter(void 0, void 0, void 0, function* () {
173
+ yield client.callTool({
174
+ name: "create_mail_rule",
175
+ arguments: {
176
+ name: "Invoices",
177
+ account: 1,
178
+ folder: "INBOX",
179
+ filter_from: "billing@example.test",
180
+ assign_tags: [3, 15],
181
+ },
182
+ });
183
+ yield client.callTool({
184
+ name: "update_mail_rule",
185
+ arguments: {
186
+ id: 3,
187
+ enabled: false,
188
+ },
189
+ });
190
+ yield client.callTool({
191
+ name: "delete_mail_rule",
192
+ arguments: {
193
+ id: 3,
194
+ confirm: true,
195
+ },
196
+ });
197
+ }));
198
+ strict_1.default.deepEqual(calls, [
199
+ [
200
+ "create",
201
+ {
202
+ name: "Invoices",
203
+ account: 1,
204
+ folder: "INBOX",
205
+ filter_from: "billing@example.test",
206
+ assign_tags: [3, 15],
207
+ },
208
+ ],
209
+ ["update", 3, { enabled: false }],
210
+ ["delete", 3],
211
+ ]);
212
+ }));
@@ -0,0 +1,3 @@
1
+ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp";
2
+ import { PaperlessAPI } from "../api/PaperlessAPI";
3
+ export declare function registerNoteTools(server: McpServer, api: PaperlessAPI): void;
@@ -0,0 +1,55 @@
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
+ Object.defineProperty(exports, "__esModule", { value: true });
12
+ exports.registerNoteTools = registerNoteTools;
13
+ const zod_1 = require("zod");
14
+ const middlewares_1 = require("./utils/middlewares");
15
+ function notesResult(notes) {
16
+ return {
17
+ content: [
18
+ {
19
+ type: "text",
20
+ text: JSON.stringify(notes),
21
+ },
22
+ ],
23
+ };
24
+ }
25
+ function registerNoteTools(server, api) {
26
+ server.tool("list_document_notes", "List all notes attached to a document. Notes are free-text comments on a document and are the natural place for an audit trail (e.g. \"invoice paid on X from account Y\") or progress notes on an action item.", {
27
+ id: zod_1.z.number().describe("The document ID"),
28
+ }, (0, middlewares_1.withErrorHandling)((args) => __awaiter(this, void 0, void 0, function* () {
29
+ if (!api)
30
+ throw new Error("Please configure API connection first");
31
+ return notesResult(yield api.getDocumentNotes(args.id));
32
+ })));
33
+ server.tool("create_document_note", "Add a note to a document. Use this to record an audit trail or progress note directly on the document. Returns the document's full list of notes after the note is added.", {
34
+ id: zod_1.z.number().describe("The document ID"),
35
+ note: zod_1.z.string().min(1).describe("The note text to add"),
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
+ return notesResult(yield api.createDocumentNote(args.id, args.note));
40
+ })));
41
+ server.tool("delete_document_note", "⚠️ DESTRUCTIVE: Permanently delete a single note from a document by its note ID. This operation is irreversible. Returns the document's remaining notes.", {
42
+ id: zod_1.z.number().describe("The document ID"),
43
+ note_id: zod_1.z.number().describe("The ID of the note to delete"),
44
+ confirm: zod_1.z
45
+ .boolean()
46
+ .describe("Must be true to confirm this destructive operation"),
47
+ }, (0, middlewares_1.withErrorHandling)((args) => __awaiter(this, void 0, void 0, function* () {
48
+ if (!api)
49
+ throw new Error("Please configure API connection first");
50
+ if (!args.confirm) {
51
+ throw new Error("Confirmation required for destructive operation. Set confirm: true to proceed.");
52
+ }
53
+ return notesResult(yield api.deleteDocumentNote(args.id, args.note_id));
54
+ })));
55
+ }
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,177 @@
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 __importDefault = (this && this.__importDefault) || function (mod) {
12
+ return (mod && mod.__esModule) ? mod : { "default": mod };
13
+ };
14
+ Object.defineProperty(exports, "__esModule", { value: true });
15
+ const strict_1 = __importDefault(require("node:assert/strict"));
16
+ const node_test_1 = require("node:test");
17
+ const index_js_1 = require("@modelcontextprotocol/sdk/client/index.js");
18
+ const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
19
+ const notes_1 = require("./notes");
20
+ class TestTransport {
21
+ start() {
22
+ return __awaiter(this, void 0, void 0, function* () { });
23
+ }
24
+ send(message) {
25
+ return __awaiter(this, void 0, void 0, function* () {
26
+ queueMicrotask(() => { var _a, _b; return (_b = (_a = this.peer) === null || _a === void 0 ? void 0 : _a.onmessage) === null || _b === void 0 ? void 0 : _b.call(_a, message); });
27
+ });
28
+ }
29
+ close() {
30
+ return __awaiter(this, void 0, void 0, function* () {
31
+ var _a;
32
+ (_a = this.onclose) === null || _a === void 0 ? void 0 : _a.call(this);
33
+ });
34
+ }
35
+ }
36
+ function createTransportPair() {
37
+ const clientTransport = new TestTransport();
38
+ const serverTransport = new TestTransport();
39
+ clientTransport.peer = serverTransport;
40
+ serverTransport.peer = clientTransport;
41
+ return { clientTransport, serverTransport };
42
+ }
43
+ function parseToolText(result) {
44
+ var _a;
45
+ const item = (_a = result.content) === null || _a === void 0 ? void 0 : _a[0];
46
+ if (!item || item.type !== "text") {
47
+ throw new Error("Expected text tool response");
48
+ }
49
+ return JSON.parse(item.text);
50
+ }
51
+ function createNoteApi(notes = []) {
52
+ const calls = {
53
+ getDocumentNotes: [],
54
+ createDocumentNote: [],
55
+ deleteDocumentNote: [],
56
+ };
57
+ const api = {
58
+ getDocumentNotes: (id) => __awaiter(this, void 0, void 0, function* () {
59
+ calls.getDocumentNotes.push(id);
60
+ return notes;
61
+ }),
62
+ createDocumentNote: (id, note) => __awaiter(this, void 0, void 0, function* () {
63
+ calls.createDocumentNote.push([id, note]);
64
+ return notes;
65
+ }),
66
+ deleteDocumentNote: (id, noteId) => __awaiter(this, void 0, void 0, function* () {
67
+ calls.deleteDocumentNote.push([id, noteId]);
68
+ return notes;
69
+ }),
70
+ };
71
+ return { api, calls };
72
+ }
73
+ function withNoteClient(api, run) {
74
+ return __awaiter(this, void 0, void 0, function* () {
75
+ const server = new mcp_js_1.McpServer({ name: "paperless-note-test", version: "1.0.0" });
76
+ (0, notes_1.registerNoteTools)(server, api);
77
+ const client = new index_js_1.Client({
78
+ name: "paperless-note-test-client",
79
+ version: "1.0.0",
80
+ });
81
+ const { clientTransport, serverTransport } = createTransportPair();
82
+ yield server.connect(serverTransport);
83
+ yield client.connect(clientTransport);
84
+ try {
85
+ yield run(client);
86
+ }
87
+ finally {
88
+ yield client.close();
89
+ yield server.close();
90
+ }
91
+ });
92
+ }
93
+ (0, node_test_1.describe)("document note tools", () => {
94
+ const sampleNotes = [
95
+ {
96
+ id: 5,
97
+ note: "Paid 2026-06-30",
98
+ created: "2026-06-30T10:00:00Z",
99
+ user: { id: 3, username: "nick" },
100
+ },
101
+ ];
102
+ (0, node_test_1.test)("create_document_note posts the note text to the document", () => __awaiter(void 0, void 0, void 0, function* () {
103
+ const { api, calls } = createNoteApi(sampleNotes);
104
+ yield withNoteClient(api, (client) => __awaiter(void 0, void 0, void 0, function* () {
105
+ var _a;
106
+ const result = (yield client.callTool({
107
+ name: "create_document_note",
108
+ arguments: { id: 1740, note: "Antwort an Finanzamt versendet" },
109
+ }));
110
+ strict_1.default.ok(!result.isError, (_a = parseToolText(result)) === null || _a === void 0 ? void 0 : _a.error);
111
+ strict_1.default.deepEqual(parseToolText(result), sampleNotes);
112
+ }));
113
+ strict_1.default.deepEqual(calls.createDocumentNote, [
114
+ [1740, "Antwort an Finanzamt versendet"],
115
+ ]);
116
+ }));
117
+ (0, node_test_1.test)("list_document_notes fetches notes for the document", () => __awaiter(void 0, void 0, void 0, function* () {
118
+ const { api, calls } = createNoteApi(sampleNotes);
119
+ yield withNoteClient(api, (client) => __awaiter(void 0, void 0, void 0, function* () {
120
+ var _a;
121
+ const result = (yield client.callTool({
122
+ name: "list_document_notes",
123
+ arguments: { id: 42 },
124
+ }));
125
+ strict_1.default.ok(!result.isError, (_a = parseToolText(result)) === null || _a === void 0 ? void 0 : _a.error);
126
+ strict_1.default.deepEqual(parseToolText(result), sampleNotes);
127
+ }));
128
+ strict_1.default.deepEqual(calls.getDocumentNotes, [42]);
129
+ }));
130
+ (0, node_test_1.test)("delete_document_note removes a note by its note ID when confirmed", () => __awaiter(void 0, void 0, void 0, function* () {
131
+ const { api, calls } = createNoteApi([]);
132
+ yield withNoteClient(api, (client) => __awaiter(void 0, void 0, void 0, function* () {
133
+ var _a;
134
+ const result = (yield client.callTool({
135
+ name: "delete_document_note",
136
+ arguments: { id: 42, note_id: 5, confirm: true },
137
+ }));
138
+ strict_1.default.ok(!result.isError, (_a = parseToolText(result)) === null || _a === void 0 ? void 0 : _a.error);
139
+ }));
140
+ strict_1.default.deepEqual(calls.deleteDocumentNote, [[42, 5]]);
141
+ }));
142
+ (0, node_test_1.test)("delete_document_note refuses to delete without confirmation", () => __awaiter(void 0, void 0, void 0, function* () {
143
+ const { api, calls } = createNoteApi([]);
144
+ yield withNoteClient(api, (client) => __awaiter(void 0, void 0, void 0, function* () {
145
+ var _a, _b;
146
+ const result = (yield client.callTool({
147
+ name: "delete_document_note",
148
+ arguments: { id: 42, note_id: 5, confirm: false },
149
+ }));
150
+ strict_1.default.ok(result.isError, "expected an error when confirm is false");
151
+ strict_1.default.match((_b = (_a = parseToolText(result)) === null || _a === void 0 ? void 0 : _a.error) !== null && _b !== void 0 ? _b : "", /confirm/i);
152
+ }));
153
+ strict_1.default.equal(calls.deleteDocumentNote.length, 0, "no delete should be sent without confirmation");
154
+ }));
155
+ (0, node_test_1.test)("create_document_note rejects an empty note", () => __awaiter(void 0, void 0, void 0, function* () {
156
+ const { api, calls } = createNoteApi(sampleNotes);
157
+ yield withNoteClient(api, (client) => __awaiter(void 0, void 0, void 0, function* () {
158
+ // Depending on the installed MCP SDK version, an input-schema (zod)
159
+ // violation either rejects with a protocol error (-32602) or resolves
160
+ // with a CallToolResult carrying isError: true. Accept both so the test
161
+ // stays correct across SDK versions.
162
+ let rejected = false;
163
+ let result;
164
+ try {
165
+ result = (yield client.callTool({
166
+ name: "create_document_note",
167
+ arguments: { id: 1, note: "" },
168
+ }));
169
+ }
170
+ catch (_a) {
171
+ rejected = true;
172
+ }
173
+ strict_1.default.ok(rejected || (result === null || result === void 0 ? void 0 : result.isError), "expected an empty note to be rejected");
174
+ }));
175
+ strict_1.default.equal(calls.createDocumentNote.length, 0, "no note should be created when validation fails");
176
+ }));
177
+ });
@@ -0,0 +1 @@
1
+ export {};