@baruchiro/paperless-mcp 0.5.0 → 0.5.1

package/build/tools/documents.js

@@ -28,6 +28,7 @@ const empty_1 = require("./utils/empty");
 const middlewares_1 = require("./utils/middlewares");
 const monetary_1 = require("./utils/monetary");
 const descriptions_1 = require("./utils/descriptions");
+const resourceUri_1 = require("./utils/resourceUri");
 /**
  * Builds Paperless-NGX bulk edit parameters from base parameters plus optional
  * custom field updates.
@@ -282,7 +283,7 @@ function registerDocumentTools(server, api) {
                 {
                     type: "resource",
                     resource: {
-                        uri: filename,
+                        uri: (0, resourceUri_1.buildDocumentResourceUri)(args.id, filename),
                         blob: Buffer.from(response.data).toString("base64"),
                         mimeType: "application/pdf",
                     },
@@ -301,7 +302,7 @@ function registerDocumentTools(server, api) {
                 {
                     type: "resource",
                     resource: {
-                        uri: `document-${args.id}-thumb.webp`,
+                        uri: (0, resourceUri_1.buildThumbnailResourceUri)(args.id),
                         blob: Buffer.from(response.data).toString("base64"),
                         mimeType: "image/webp",
                     },

package/build/tools/utils/resourceUri.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Resource URI builders for document/thumbnail downloads.
+ *
+ * URIs mirror the Paperless REST API paths under a custom `paperless://`
+ * scheme, so the same identifiers can later back proper MCP resources
+ * (`resources/list` / `resources/read`) without a second naming scheme.
+ *
+ * The scheme also keeps the URI well-formed regardless of filename
+ * content, which Python MCP clients (pydantic-validated) require.
+ */
+/**
+ * Builds a resource URI for a downloaded document.
+ *
+ * Mirrors `GET /api/documents/{id}/download/`. The original filename is
+ * preserved as a `filename` query parameter (URL-encoded) so clients
+ * that need the human-readable name can still recover it.
+ */
+export declare function buildDocumentResourceUri(id: number, filename: string): string;
+/**
+ * Builds a resource URI for a document thumbnail.
+ *
+ * Mirrors `GET /api/documents/{id}/thumb/`.
+ */
+export declare function buildThumbnailResourceUri(id: number): string;

package/build/tools/utils/resourceUri.js

@@ -0,0 +1,32 @@
+"use strict";
+/**
+ * Resource URI builders for document/thumbnail downloads.
+ *
+ * URIs mirror the Paperless REST API paths under a custom `paperless://`
+ * scheme, so the same identifiers can later back proper MCP resources
+ * (`resources/list` / `resources/read`) without a second naming scheme.
+ *
+ * The scheme also keeps the URI well-formed regardless of filename
+ * content, which Python MCP clients (pydantic-validated) require.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildDocumentResourceUri = buildDocumentResourceUri;
+exports.buildThumbnailResourceUri = buildThumbnailResourceUri;
+/**
+ * Builds a resource URI for a downloaded document.
+ *
+ * Mirrors `GET /api/documents/{id}/download/`. The original filename is
+ * preserved as a `filename` query parameter (URL-encoded) so clients
+ * that need the human-readable name can still recover it.
+ */
+function buildDocumentResourceUri(id, filename) {
+    return `paperless://documents/${id}/download?filename=${encodeURIComponent(filename)}`;
+}
+/**
+ * Builds a resource URI for a document thumbnail.
+ *
+ * Mirrors `GET /api/documents/{id}/thumb/`.
+ */
+function buildThumbnailResourceUri(id) {
+    return `paperless://documents/${id}/thumb`;
+}

package/build/tools/utils/resourceUri.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/tools/utils/resourceUri.test.js

@@ -0,0 +1,50 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_test_1 = require("node:test");
+const strict_1 = __importDefault(require("node:assert/strict"));
+const resourceUri_1 = require("./resourceUri");
+(0, node_test_1.test)("buildDocumentResourceUri mirrors the REST download path", () => {
+    const uri = (0, resourceUri_1.buildDocumentResourceUri)(1, "doc.pdf");
+    strict_1.default.match(uri, /^paperless:\/\/documents\/1\/download(\?|$)/);
+});
+(0, node_test_1.test)("buildDocumentResourceUri puts the filename in a query parameter", () => {
+    const uri = (0, resourceUri_1.buildDocumentResourceUri)(1, "invoice 2026.pdf");
+    strict_1.default.equal(uri, "paperless://documents/1/download?filename=invoice%202026.pdf");
+});
+(0, node_test_1.test)("buildDocumentResourceUri encodes RFC-3986 reserved chars in the filename", () => {
+    const uri = (0, resourceUri_1.buildDocumentResourceUri)(42, "weird ?#&=+name.pdf");
+    const url = new URL(uri);
+    // The path stays canonical — only the literal `?` that separates
+    // path from query is allowed; nothing from the filename should
+    // bleed into the path or break query parsing.
+    strict_1.default.equal(url.pathname, "/42/download");
+    strict_1.default.equal(url.searchParams.get("filename"), "weird ?#&=+name.pdf");
+});
+(0, node_test_1.test)("buildDocumentResourceUri encodes path separators inside filename", () => {
+    // A filename containing a slash must not become an extra path segment.
+    const uri = (0, resourceUri_1.buildDocumentResourceUri)(7, "sub/dir/file.pdf");
+    const url = new URL(uri);
+    strict_1.default.equal(url.pathname, "/7/download");
+    strict_1.default.equal(url.searchParams.get("filename"), "sub/dir/file.pdf");
+});
+(0, node_test_1.test)("buildDocumentResourceUri preserves unicode filenames", () => {
+    const original = "Rechnüng — März.pdf";
+    const uri = (0, resourceUri_1.buildDocumentResourceUri)(1, original);
+    // Roundtrip via URL parsing should recover the original name.
+    const url = new URL(uri);
+    strict_1.default.equal(url.searchParams.get("filename"), original);
+});
+(0, node_test_1.test)("buildDocumentResourceUri produces a valid URL", () => {
+    const uri = (0, resourceUri_1.buildDocumentResourceUri)(1, "Some File.pdf");
+    strict_1.default.doesNotThrow(() => new URL(uri));
+});
+(0, node_test_1.test)("buildThumbnailResourceUri mirrors the REST thumb path", () => {
+    strict_1.default.equal((0, resourceUri_1.buildThumbnailResourceUri)(1), "paperless://documents/1/thumb");
+    strict_1.default.equal((0, resourceUri_1.buildThumbnailResourceUri)(123), "paperless://documents/123/thumb");
+});
+(0, node_test_1.test)("buildThumbnailResourceUri produces a valid URL", () => {
+    strict_1.default.doesNotThrow(() => new URL((0, resourceUri_1.buildThumbnailResourceUri)(99)));
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@baruchiro/paperless-mcp",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Model Context Protocol (MCP) server for interacting with Paperless-NGX document management system. Enables AI assistants to manage documents, tags, correspondents, and document types through the Paperless-NGX API.",
   "main": "build/index.js",
   "bin": {