@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,124 @@
|
|
|
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 paperlessApi_1 = require("../test/mocks/paperlessApi");
|
|
20
|
+
const documents_1 = require("./documents");
|
|
21
|
+
class TestTransport {
|
|
22
|
+
start() {
|
|
23
|
+
return __awaiter(this, void 0, void 0, function* () { });
|
|
24
|
+
}
|
|
25
|
+
send(message) {
|
|
26
|
+
return __awaiter(this, void 0, void 0, function* () {
|
|
27
|
+
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); });
|
|
28
|
+
});
|
|
29
|
+
}
|
|
30
|
+
close() {
|
|
31
|
+
return __awaiter(this, void 0, void 0, function* () {
|
|
32
|
+
var _a;
|
|
33
|
+
(_a = this.onclose) === null || _a === void 0 ? void 0 : _a.call(this);
|
|
34
|
+
});
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
function createTransportPair() {
|
|
38
|
+
const clientTransport = new TestTransport();
|
|
39
|
+
const serverTransport = new TestTransport();
|
|
40
|
+
clientTransport.peer = serverTransport;
|
|
41
|
+
serverTransport.peer = clientTransport;
|
|
42
|
+
return { clientTransport, serverTransport };
|
|
43
|
+
}
|
|
44
|
+
function emptyPaginationResponse(results = [], all = []) {
|
|
45
|
+
return {
|
|
46
|
+
count: results.length,
|
|
47
|
+
next: null,
|
|
48
|
+
previous: null,
|
|
49
|
+
all,
|
|
50
|
+
results,
|
|
51
|
+
};
|
|
52
|
+
}
|
|
53
|
+
function createBinaryResponse(body, contentType) {
|
|
54
|
+
return {
|
|
55
|
+
data: Buffer.from(body),
|
|
56
|
+
status: 200,
|
|
57
|
+
statusText: "OK",
|
|
58
|
+
headers: {
|
|
59
|
+
"content-type": contentType,
|
|
60
|
+
},
|
|
61
|
+
config: {},
|
|
62
|
+
};
|
|
63
|
+
}
|
|
64
|
+
function withResourceClient(api, run) {
|
|
65
|
+
return __awaiter(this, void 0, void 0, function* () {
|
|
66
|
+
const server = new mcp_js_1.McpServer({ name: "paperless-test", version: "1.0.0" });
|
|
67
|
+
(0, documents_1.registerDocumentResources)(server, api);
|
|
68
|
+
const client = new index_js_1.Client({ name: "paperless-test-client", version: "1.0.0" });
|
|
69
|
+
const { clientTransport, serverTransport } = createTransportPair();
|
|
70
|
+
yield server.connect(serverTransport);
|
|
71
|
+
yield client.connect(clientTransport);
|
|
72
|
+
try {
|
|
73
|
+
yield run(client);
|
|
74
|
+
}
|
|
75
|
+
finally {
|
|
76
|
+
yield client.close();
|
|
77
|
+
yield server.close();
|
|
78
|
+
}
|
|
79
|
+
});
|
|
80
|
+
}
|
|
81
|
+
(0, node_test_1.test)("resources/list does not enumerate documents at startup", () => __awaiter(void 0, void 0, void 0, function* () {
|
|
82
|
+
// Documents are dynamic DMS data and must not be pre-registered as MCP
|
|
83
|
+
// resources: enumerating them floods `resources/list` and the LLM context
|
|
84
|
+
// window (issue #112). The list must stay empty even when documents exist;
|
|
85
|
+
// documents are reached on demand via tools + the `resources/read` template.
|
|
86
|
+
const api = {
|
|
87
|
+
getDocuments: () => __awaiter(void 0, void 0, void 0, function* () {
|
|
88
|
+
return emptyPaginationResponse([
|
|
89
|
+
(0, paperlessApi_1.createDocument)({
|
|
90
|
+
id: 1,
|
|
91
|
+
title: "Invoice",
|
|
92
|
+
mime_type: "application/pdf",
|
|
93
|
+
}),
|
|
94
|
+
(0, paperlessApi_1.createDocument)({
|
|
95
|
+
id: 2,
|
|
96
|
+
title: "Receipt",
|
|
97
|
+
mime_type: "image/png",
|
|
98
|
+
}),
|
|
99
|
+
], [1, 2, 3]);
|
|
100
|
+
}),
|
|
101
|
+
};
|
|
102
|
+
yield withResourceClient(api, (client) => __awaiter(void 0, void 0, void 0, function* () {
|
|
103
|
+
const result = yield client.listResources();
|
|
104
|
+
strict_1.default.deepEqual(result.resources, []);
|
|
105
|
+
}));
|
|
106
|
+
}));
|
|
107
|
+
(0, node_test_1.test)("resources/read returns text contents for text responses", () => __awaiter(void 0, void 0, void 0, function* () {
|
|
108
|
+
const api = {
|
|
109
|
+
getDocuments: () => __awaiter(void 0, void 0, void 0, function* () { return emptyPaginationResponse(); }),
|
|
110
|
+
downloadDocument: () => __awaiter(void 0, void 0, void 0, function* () { return createBinaryResponse("plain text", "text/plain; charset=utf-8"); }),
|
|
111
|
+
};
|
|
112
|
+
yield withResourceClient(api, (client) => __awaiter(void 0, void 0, void 0, function* () {
|
|
113
|
+
const result = yield client.readResource({
|
|
114
|
+
uri: "paperless://documents/4/download",
|
|
115
|
+
});
|
|
116
|
+
strict_1.default.deepEqual(result.contents, [
|
|
117
|
+
{
|
|
118
|
+
uri: "paperless://documents/4/download",
|
|
119
|
+
mimeType: "text/plain; charset=utf-8",
|
|
120
|
+
text: "plain text",
|
|
121
|
+
},
|
|
122
|
+
]);
|
|
123
|
+
}));
|
|
124
|
+
}));
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
|
2
|
+
import type express from "express";
|
|
3
|
+
export interface CreateMcpServerOptions {
|
|
4
|
+
baseUrl: string;
|
|
5
|
+
token: string;
|
|
6
|
+
version: string;
|
|
7
|
+
publicUrl: string;
|
|
8
|
+
}
|
|
9
|
+
export declare function createMcpServer({ baseUrl, token, version, publicUrl, }: CreateMcpServerOptions): McpServer;
|
|
10
|
+
export interface ResolveTokenOptions {
|
|
11
|
+
/**
|
|
12
|
+
* Server-configured token used as a fallback for unauthenticated requests.
|
|
13
|
+
* Only consulted when `allowAnonymous` is true.
|
|
14
|
+
*/
|
|
15
|
+
fallbackToken?: string;
|
|
16
|
+
/**
|
|
17
|
+
* When true, requests without a `Bearer` header fall back to `fallbackToken`
|
|
18
|
+
* (the legacy behaviour). When false (the default in HTTP mode), a request
|
|
19
|
+
* without a `Bearer` header is rejected and never uses the server token.
|
|
20
|
+
*/
|
|
21
|
+
allowAnonymous: boolean;
|
|
22
|
+
}
|
|
23
|
+
export declare function getBearerToken(req: express.Request, options: ResolveTokenOptions): string | undefined;
|
|
24
|
+
export declare function sendUnauthorized(res: express.Response): void;
|
package/build/server.js
ADDED
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.createMcpServer = createMcpServer;
|
|
4
|
+
exports.getBearerToken = getBearerToken;
|
|
5
|
+
exports.sendUnauthorized = sendUnauthorized;
|
|
6
|
+
const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
|
|
7
|
+
const PaperlessAPI_1 = require("./api/PaperlessAPI");
|
|
8
|
+
const documents_1 = require("./resources/documents");
|
|
9
|
+
const correspondents_1 = require("./tools/correspondents");
|
|
10
|
+
const customFields_1 = require("./tools/customFields");
|
|
11
|
+
const documents_2 = require("./tools/documents");
|
|
12
|
+
const documentTypes_1 = require("./tools/documentTypes");
|
|
13
|
+
const mail_1 = require("./tools/mail");
|
|
14
|
+
const notes_1 = require("./tools/notes");
|
|
15
|
+
const tags_1 = require("./tools/tags");
|
|
16
|
+
function createMcpServer({ baseUrl, token, version, publicUrl, }) {
|
|
17
|
+
const api = new PaperlessAPI_1.PaperlessAPI(baseUrl, token);
|
|
18
|
+
const server = new mcp_js_1.McpServer({ name: "paperless-ngx", version }, { instructions: buildInstructions(publicUrl) });
|
|
19
|
+
(0, documents_2.registerDocumentTools)(server, api);
|
|
20
|
+
(0, documents_1.registerDocumentResources)(server, api);
|
|
21
|
+
(0, notes_1.registerNoteTools)(server, api);
|
|
22
|
+
(0, tags_1.registerTagTools)(server, api);
|
|
23
|
+
(0, correspondents_1.registerCorrespondentTools)(server, api);
|
|
24
|
+
(0, documentTypes_1.registerDocumentTypeTools)(server, api);
|
|
25
|
+
(0, customFields_1.registerCustomFieldTools)(server, api);
|
|
26
|
+
(0, mail_1.registerMailTools)(server, api);
|
|
27
|
+
return server;
|
|
28
|
+
}
|
|
29
|
+
function getBearerToken(req, options) {
|
|
30
|
+
const authHeader = req.headers["authorization"];
|
|
31
|
+
if (authHeader && authHeader.startsWith("Bearer ")) {
|
|
32
|
+
return authHeader.slice(7);
|
|
33
|
+
}
|
|
34
|
+
if (options.allowAnonymous) {
|
|
35
|
+
return options.fallbackToken || undefined;
|
|
36
|
+
}
|
|
37
|
+
return undefined;
|
|
38
|
+
}
|
|
39
|
+
function sendUnauthorized(res) {
|
|
40
|
+
// Log operator-facing guidance server-side; keep the wire response minimal so
|
|
41
|
+
// we don't echo configuration hints back to unauthenticated callers.
|
|
42
|
+
console.error("[paperless-mcp] Rejected request with no 'Authorization: Bearer <paperless-ngx-api-token>' header. " +
|
|
43
|
+
"As of v2.0.0, HTTP mode requires a per-request Bearer token and no longer falls back to the " +
|
|
44
|
+
"server-configured token for unauthenticated requests. Have clients send their Paperless-NGX API " +
|
|
45
|
+
"token as a Bearer token, or restart the server with --no-auth to use the server token for " +
|
|
46
|
+
"unauthenticated requests (trusted/local networks only).");
|
|
47
|
+
res
|
|
48
|
+
.status(401)
|
|
49
|
+
.set("WWW-Authenticate", 'Bearer realm="paperless-mcp"')
|
|
50
|
+
.json({ error: "unauthorized" });
|
|
51
|
+
}
|
|
52
|
+
function buildInstructions(publicUrl) {
|
|
53
|
+
return `
|
|
54
|
+
Paperless-NGX MCP Server Instructions
|
|
55
|
+
|
|
56
|
+
⚠️ CRITICAL: Always differentiate between operations on specific documents vs operations on the entire system:
|
|
57
|
+
|
|
58
|
+
- REMOVE operations (e.g., remove_tag in bulk_edit_documents): Affect only the specified documents, items remain in the system
|
|
59
|
+
- DELETE operations (e.g., delete_tag, delete_correspondent): Permanently delete items from the entire system, affecting ALL documents that use them
|
|
60
|
+
|
|
61
|
+
When a user asks to "remove" something, prefer operations that affect specific documents. Only use DELETE operations when explicitly asked to delete from the system.
|
|
62
|
+
|
|
63
|
+
To view documents in your Paperless-NGX web interface, construct URLs using this pattern:
|
|
64
|
+
${publicUrl}/documents/{document_id}/
|
|
65
|
+
|
|
66
|
+
Example: If your base URL is "http://localhost:8000", the web interface URL would be "http://localhost:8000/documents/123/" for document ID 123.
|
|
67
|
+
|
|
68
|
+
The document tools return JSON data with document IDs that you can use to construct these URLs.
|
|
69
|
+
`;
|
|
70
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
var __importDefault = (this && this.__importDefault) || function (mod) {
|
|
3
|
+
return (mod && mod.__esModule) ? mod : { "default": mod };
|
|
4
|
+
};
|
|
5
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
6
|
+
const node_test_1 = require("node:test");
|
|
7
|
+
const strict_1 = __importDefault(require("node:assert/strict"));
|
|
8
|
+
const server_1 = require("./server");
|
|
9
|
+
function reqWith(authorization) {
|
|
10
|
+
return {
|
|
11
|
+
headers: authorization ? { authorization } : {},
|
|
12
|
+
};
|
|
13
|
+
}
|
|
14
|
+
(0, node_test_1.test)("client Bearer token takes precedence over the server token", () => {
|
|
15
|
+
const token = (0, server_1.getBearerToken)(reqWith("Bearer client-token"), {
|
|
16
|
+
fallbackToken: "server-token",
|
|
17
|
+
allowAnonymous: true,
|
|
18
|
+
});
|
|
19
|
+
strict_1.default.equal(token, "client-token");
|
|
20
|
+
});
|
|
21
|
+
(0, node_test_1.test)("client Bearer token is used even when anonymous access is disabled", () => {
|
|
22
|
+
const token = (0, server_1.getBearerToken)(reqWith("Bearer client-token"), {
|
|
23
|
+
fallbackToken: "server-token",
|
|
24
|
+
allowAnonymous: false,
|
|
25
|
+
});
|
|
26
|
+
strict_1.default.equal(token, "client-token");
|
|
27
|
+
});
|
|
28
|
+
(0, node_test_1.test)("falls back to the server token only when anonymous access is allowed", () => {
|
|
29
|
+
const token = (0, server_1.getBearerToken)(reqWith(), {
|
|
30
|
+
fallbackToken: "server-token",
|
|
31
|
+
allowAnonymous: true,
|
|
32
|
+
});
|
|
33
|
+
strict_1.default.equal(token, "server-token");
|
|
34
|
+
});
|
|
35
|
+
(0, node_test_1.test)("no header without anonymous access yields no token (request is rejected)", () => {
|
|
36
|
+
const token = (0, server_1.getBearerToken)(reqWith(), {
|
|
37
|
+
fallbackToken: "server-token",
|
|
38
|
+
allowAnonymous: false,
|
|
39
|
+
});
|
|
40
|
+
strict_1.default.equal(token, undefined);
|
|
41
|
+
});
|
|
42
|
+
(0, node_test_1.test)("non-Bearer Authorization scheme never leaks the server token by default", () => {
|
|
43
|
+
const token = (0, server_1.getBearerToken)(reqWith("Token server-token"), {
|
|
44
|
+
fallbackToken: "server-token",
|
|
45
|
+
allowAnonymous: false,
|
|
46
|
+
});
|
|
47
|
+
strict_1.default.equal(token, undefined);
|
|
48
|
+
});
|
|
49
|
+
(0, node_test_1.test)("anonymous access with no configured server token yields no token", () => {
|
|
50
|
+
const token = (0, server_1.getBearerToken)(reqWith(), {
|
|
51
|
+
allowAnonymous: true,
|
|
52
|
+
});
|
|
53
|
+
strict_1.default.equal(token, undefined);
|
|
54
|
+
});
|
|
@@ -0,0 +1,33 @@
|
|
|
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.createPaperlessApiMock = createPaperlessApiMock;
|
|
13
|
+
exports.createDocument = createDocument;
|
|
14
|
+
function emptyPaginationResponse(results = []) {
|
|
15
|
+
return {
|
|
16
|
+
count: results.length,
|
|
17
|
+
next: null,
|
|
18
|
+
previous: null,
|
|
19
|
+
all: [],
|
|
20
|
+
results,
|
|
21
|
+
};
|
|
22
|
+
}
|
|
23
|
+
function createPaperlessApiMock() {
|
|
24
|
+
return {
|
|
25
|
+
getCorrespondents: () => __awaiter(this, void 0, void 0, function* () { return emptyPaginationResponse(); }),
|
|
26
|
+
getDocumentTypes: () => __awaiter(this, void 0, void 0, function* () { return emptyPaginationResponse(); }),
|
|
27
|
+
getTags: () => __awaiter(this, void 0, void 0, function* () { return emptyPaginationResponse(); }),
|
|
28
|
+
getCustomFields: () => __awaiter(this, void 0, void 0, function* () { return emptyPaginationResponse(); }),
|
|
29
|
+
};
|
|
30
|
+
}
|
|
31
|
+
function createDocument(overrides = {}) {
|
|
32
|
+
return Object.assign({ id: 1, correspondent: null, document_type: null, storage_path: null, title: "Document 1", content: "OCR content", tags: [], created: "2026-01-01T00:00:00.000Z", created_date: "2026-01-01", modified: "2026-01-01T00:00:00.000Z", added: "2026-01-01T00:00:00.000Z", deleted_at: null, archive_serial_number: null, original_file_name: "doc1.pdf", archived_file_name: "2026/doc1.pdf", owner: null, user_can_change: true, is_shared_by_requester: false, notes: [], custom_fields: [], page_count: 1, mime_type: "application/pdf" }, overrides);
|
|
33
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|