Fix monetary custom field UX: clarify currency format and catch trailing-symbol mistakes early

.changeset/improve-monetary-field-ux.md

@@ -0,0 +1,5 @@
+---
+"@baruchiro/paperless-mcp": patch
+---
+
+Improve UX for monetary custom fields: clarify currency format in tool descriptions, and add client-side validation that catches common mistakes (e.g., trailing `$` like `10.00$`) with actionable error messages suggesting the correct format (e.g., `USD10.00`).

.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version-file: ".node-version"
+      - name: Install dependencies
+        run: npm ci
+      - name: Run tests
+        run: npm test

package.json

@@ -7,7 +7,7 @@
     "paperless-mcp": "build/index.js"
   },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
+    "test": "node --require ts-node/register --test src/**/*.test.ts",
     "start": "ts-node src/index.ts",
     "build": "tsc",
     "dxt-pack": "dxt pack",

src/tools/customFields.ts

@@ -49,7 +49,7 @@ export function registerCustomFieldTools(server: McpServer, api: PaperlessAPI) {
 
   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).",
+    "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$).",
     {
       name: z.string(),
       data_type: z.enum([

src/tools/documents.ts

@@ -4,6 +4,8 @@ import { convertDocsWithNames } from "../api/documentEnhancer";
 import { PaperlessAPI } from "../api/PaperlessAPI";
 import { arrayNotEmpty, objectNotEmpty } from "./utils/empty";
 import { withErrorHandling } from "./utils/middlewares";
+import { validateCustomFields } from "./utils/monetary";
+import { CUSTOM_FIELD_VALUE_DESCRIPTION } from "./utils/descriptions";
 
 export function registerDocumentTools(server: McpServer, api: PaperlessAPI) {
   server.tool(
@@ -43,7 +45,7 @@ export function registerDocumentTools(server: McpServer, api: PaperlessAPI) {
               z.boolean(),
               z.array(z.number()),
               z.null(),
-            ]),
+            ]).describe(CUSTOM_FIELD_VALUE_DESCRIPTION),
           })
         )
         .optional()
@@ -91,6 +93,8 @@ export function registerDocumentTools(server: McpServer, api: PaperlessAPI) {
       }
       const { documents, method, add_custom_fields, ...parameters } = args;
 
+      validateCustomFields(add_custom_fields);
+
       // Transform add_custom_fields into the two separate API parameters
       const apiParameters = { ...parameters };
       if (add_custom_fields && add_custom_fields.length > 0) {
@@ -365,9 +369,7 @@ export function registerDocumentTools(server: McpServer, api: PaperlessAPI) {
                 z.array(z.number()),
                 z.null(),
               ])
-              .describe(
-                "The value for the custom field. For documentlink fields, use a single document ID (e.g., 123) or an array of document IDs (e.g., [123, 456])."
-              ),
+              .describe(CUSTOM_FIELD_VALUE_DESCRIPTION),
           })
         )
         .optional()
@@ -376,6 +378,9 @@ export function registerDocumentTools(server: McpServer, api: PaperlessAPI) {
     withErrorHandling(async (args, extra) => {
       if (!api) throw new Error("Please configure API connection first");
       const { id, ...updateData } = args;
+
+      validateCustomFields(updateData.custom_fields);
+
       const response = await api.updateDocument(id, updateData);
 
       return convertDocsWithNames(response, api);

src/tools/utils/descriptions.ts

@@ -0,0 +1,2 @@
+export const CUSTOM_FIELD_VALUE_DESCRIPTION =
+  "The value for the custom field. For monetary fields, use currency code prefix format (e.g., USD10.00, GBP123.45, EUR9.99) — NOT trailing symbol format (e.g., 10.00$). For documentlink fields, use a single document ID (e.g., 123) or an array of document IDs (e.g., [123, 456]).";

src/tools/utils/monetary.test.ts

@@ -0,0 +1,53 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { getMonetaryValidationError } from "./monetary";
+
+test("returns null for non-monetary strings", () => {
+  assert.equal(getMonetaryValidationError("hello"), null);
+  assert.equal(getMonetaryValidationError("some text"), null);
+  assert.equal(getMonetaryValidationError(""), null);
+});
+
+test("returns null for valid monetary prefix format", () => {
+  assert.equal(getMonetaryValidationError("USD10.00"), null);
+  assert.equal(getMonetaryValidationError("GBP123.45"), null);
+  assert.equal(getMonetaryValidationError("EUR9.99"), null);
+  assert.equal(getMonetaryValidationError("ILS50.00"), null);
+});
+
+test("returns error for trailing dollar sign", () => {
+  const err = getMonetaryValidationError("10.00$");
+  assert.ok(err);
+  assert.match(err, /USD10\.00/);
+  assert.match(err, /currency code as a prefix/);
+});
+
+test("returns error for trailing euro sign", () => {
+  const err = getMonetaryValidationError("123€");
+  assert.ok(err);
+  assert.match(err, /EUR123\.00/);
+});
+
+test("returns error for trailing pound sign", () => {
+  const err = getMonetaryValidationError("50£");
+  assert.ok(err);
+  assert.match(err, /GBP50\.00/);
+});
+
+test("returns error for trailing shekel sign", () => {
+  const err = getMonetaryValidationError("100₪");
+  assert.ok(err);
+  assert.match(err, /ILS100\.00/);
+});
+
+test("returns error for trailing rupee sign", () => {
+  const err = getMonetaryValidationError("200₹");
+  assert.ok(err);
+  assert.match(err, /INR200\.00/);
+});
+
+test("returns error for trailing yen sign", () => {
+  const err = getMonetaryValidationError("500¥");
+  assert.ok(err);
+  assert.match(err, /JPY500\.00/);
+});

src/tools/utils/monetary.ts

@@ -0,0 +1,41 @@
+const SYMBOL_TO_CODE: Record<string, string> = {
+  $: "USD",
+  "€": "EUR",
+  "£": "GBP",
+  "¥": "JPY",
+  "₹": "INR",
+  "₪": "ILS",
+};
+
+const TRAILING_SYMBOL_REGEX = new RegExp(
+  `^(\\d+(?:\\.\\d+)?)[${Object.keys(SYMBOL_TO_CODE).join("")}]$`
+);
+
+export function getMonetaryValidationError(value: string): string | null {
+  const trailingMatch = TRAILING_SYMBOL_REGEX.exec(value);
+  if (trailingMatch) {
+    const amount = trailingMatch[1];
+    const symbol = value.slice(-1);
+    const code = SYMBOL_TO_CODE[symbol] || "USD";
+    const numericAmount = parseFloat(amount);
+    const formattedAmount = isNaN(numericAmount) ? amount : numericAmount.toFixed(2);
+    return (
+      `Invalid monetary format "${value}". ` +
+      `Paperless-NGX requires the currency code as a prefix, e.g. "${code}${formattedAmount}". ` +
+      `Use the format: {CURRENCY_CODE}{amount} (e.g., USD10.00, GBP123.45, EUR9.99).`
+    );
+  }
+
+  return null;
+}
+
+export function validateCustomFields(
+  custom_fields: { field: number; value: unknown }[] | undefined
+) {
+  custom_fields
+    ?.filter((cf) => typeof cf.value === "string")
+    .forEach((cf) => {
+      const monetaryError = getMonetaryValidationError(cf.value as string);
+      if (monetaryError) throw new Error(monetaryError);
+    });
+}