@codemill-solutions/yuki-mcp 1.1.0 → 1.2.0

package/dist/tools/accounting.js

@@ -80,6 +80,127 @@ export function registerAccountingTools(server, client) {
         }
     });
 }
+/**
+ * Register additional accounting tools (fiscal variants and revenue).
+ * Called separately from registerAccountingTools so each can be exported
+ * and imported individually if needed.
+ */
+export function registerAccountingExtendedTools(server, client) {
+    // ── get_gl_accounts_fiscal ─────────────────────────────────────────────────
+    /**
+     * get_gl_accounts_fiscal
+     *
+     * Retrieve all GL accounts with their balance at a given date, *including*
+     * fiscal corrections (e.g. end-of-year accruals, depreciation entries posted
+     * after the commercial year-end).
+     *
+     * Use this instead of get_gl_accounts when you need a balance that matches
+     * Yuki's fiscal reporting view rather than the commercial/operational view.
+     *
+     * Rate cost: 1 request.
+     */
+    server.registerTool('get_gl_accounts_fiscal', {
+        description: 'Retrieve all GL accounts with their balance including fiscal corrections (fiscale stand). ' +
+            'Use this for balance sheet and P&L views that must match Yuki fiscal reports. ' +
+            'For the commercial/operational view use get_gl_accounts instead.',
+        inputSchema: {
+            date: z
+                .string()
+                .optional()
+                .describe("Date for the balance snapshot in YYYY-MM-DD format. Defaults to today."),
+            administrationId: z
+                .string()
+                .optional()
+                .describe('Administration ID (GUID). Defaults to YUKI_DOMAIN_ID env var.'),
+        },
+    }, async ({ date, administrationId }) => {
+        try {
+            const adminId = administrationId ?? client.defaultDomainId;
+            if (!adminId)
+                throw new Error('administrationId is required (or set YUKI_DOMAIN_ID env var)');
+            const sessionID = await client.getSessionID();
+            const transactionDate = date ?? new Date().toISOString().split('T')[0];
+            const result = await client.callSoap({
+                service: 'Accounting.asmx',
+                method: 'GLAccountBalanceFiscal',
+                params: { sessionID, administrationID: adminId, transactionDate },
+            });
+            const accounts = normalizeGLAccounts(result);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ success: true, count: accounts.length, balanceDate: transactionDate, fiscal: true, accounts }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ success: false, error: message }, null, 2) }],
+                isError: true,
+            };
+        }
+    });
+    // ── get_net_revenue ────────────────────────────────────────────────────────
+    /**
+     * get_net_revenue
+     *
+     * Retrieve the net revenue (netto-omzet) for an administration within a
+     * date range. Optionally includes fiscal corrections.
+     *
+     * Use this for revenue dashboards, period comparisons, and quick P&L checks
+     * without having to sum individual GL account balances manually.
+     *
+     * Rate cost: 1 request.
+     */
+    server.registerTool('get_net_revenue', {
+        description: 'Retrieve net revenue (netto-omzet) for an administration within a date range. ' +
+            'Set fiscal=true to include fiscal corrections (matches Yuki fiscal reports).',
+        inputSchema: {
+            startDate: z.string().describe('Start date in YYYY-MM-DD format (inclusive)'),
+            endDate: z.string().describe('End date in YYYY-MM-DD format (inclusive)'),
+            fiscal: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe('Include fiscal corrections. Default false (commercial view).'),
+            administrationId: z
+                .string()
+                .optional()
+                .describe('Administration ID (GUID). Defaults to YUKI_DOMAIN_ID env var.'),
+        },
+    }, async ({ startDate, endDate, fiscal, administrationId }) => {
+        try {
+            const adminId = administrationId ?? client.defaultDomainId;
+            if (!adminId)
+                throw new Error('administrationId is required (or set YUKI_DOMAIN_ID env var)');
+            const sessionID = await client.getSessionID();
+            const method = fiscal ? 'NetRevenueFiscal' : 'NetRevenue';
+            const result = await client.callSoap({
+                service: 'Accounting.asmx',
+                method,
+                params: { sessionID, administrationID: adminId, StartDate: startDate, EndDate: endDate },
+            });
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ success: true, period: { startDate, endDate }, fiscal: fiscal ?? false, result }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ success: false, error: message }, null, 2) }],
+                isError: true,
+            };
+        }
+    });
+}
 /** Unwrap the parsed SOAP GL account balance result into a flat array. */
 function normalizeGLAccounts(result) {
     if (!result)

package/dist/tools/accounting.js.map

@@ -1 +1 @@
-{"version":3,"file":"accounting.js","sourceRoot":"","sources":["../../src/tools/accounting.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;GAQG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAAiB,EAAE,MAAkB;IAC3E;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,YAAY,CACjB,iBAAiB,EACjB;QACE,WAAW,EACT,qFAAqF;YACrF,wFAAwF;YACxF,kDAAkD;QACpD,WAAW,EAAE;YACX,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,wEAAwE,CAAC;YAC9G,gBAAgB,EAAE,CAAC;iBAChB,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CAAC,+DAA+D,CAAC;SAC7E;KACF,EACD,KAAK,EAAE,EAAE,IAAI,EAAE,gBAAgB,EAAE,EAAE,EAAE;QACnC,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,gBAAgB,IAAI,MAAM,CAAC,eAAe,CAAC;YAC3D,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,MAAM,IAAI,KAAK,CAAC,8DAA8D,CAAC,CAAC;YAClF,CAAC;YAED,MAAM,SAAS,GAAG,MAAM,MAAM,CAAC,YAAY,EAAE,CAAC;YAE9C,2DAA2D;YAC3D,MAAM,eAAe,GAAG,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;YAEvE,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC;gBACnC,OAAO,EAAE,iBAAiB;gBAC1B,MAAM,EAAE,kBAAkB;gBAC1B,MAAM,EAAE;oBACN,SAAS;oBACT,gBAAgB,EAAE,OAAO;oBACzB,eAAe;iBAChB;aACF,CAAC,CAAC;YAEH,MAAM,QAAQ,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAC;YAE7C,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAe;wBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAClB;4BACE,OAAO,EAAE,IAAI;4BACb,KAAK,EAAE,QAAQ,CAAC,MAAM;4BACtB,WAAW,EAAE,eAAe;4BAC5B,QAAQ;yBACT,EACD,IAAI,EACJ,CAAC,CACF;qBACF;iBACF;aACF,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACjE,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAe;wBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;qBAClE;iBACF;gBACD,OAAO,EAAE,IAAI;aACd,CAAC;QACJ,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC;AAED,0EAA0E;AAC1E,SAAS,mBAAmB,CAAC,MAAe;IAC1C,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,CAAC;IACvB,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,OAAO,MAAM,CAAC;IAEzC,MAAM,GAAG,GAAG,MAAiC,CAAC;IAE9C,MAAM,QAAQ,GAAG,CAAC,YAAY,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;IACpD,MAAM,QAAQ,GAAG,CAAC,WAAW,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC;IAEjD,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,CAAC,GAAG,GAAG,CAAC,OAAO,CAAC,CAAC;QACvB,IAAI,CAAC,CAAC;YAAE,SAAS;QACjB,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;YAAE,OAAO,CAAC,CAAC;QAC/B,MAAM,KAAK,GAAG,CAA4B,CAAC;QAC3C,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;YAC3B,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;gBAAE,OAAO,KAAK,CAAC,GAAG,CAAc,CAAC;YAC9D,IAAI,KAAK,CAAC,GAAG,CAAC;gBAAE,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;QACtC,CAAC;IACH,CAAC;IAED,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAAE,OAAO,GAAG,CAAC,GAAG,CAAc,CAAC;QAC1D,IAAI,GAAG,CAAC,GAAG,CAAC;YAAE,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;IAClC,CAAC;IAED,OAAO,CAAC,MAAM,CAAC,CAAC;AAClB,CAAC"}
+{"version":3,"file":"accounting.js","sourceRoot":"","sources":["../../src/tools/accounting.ts"],"names":[],"mappings":"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"}

package/dist/tools/administrations.d.ts

@@ -11,4 +11,14 @@ import { YukiClient } from '../yuki-client.js';
  * Auth flow:    Authenticate(accessKey) → sessionID → Administrations(sessionID)
  */
 export declare function registerAdministrationTools(server: McpServer, client: YukiClient): void;
+/**
+ * get_administration_id
+ *
+ * Look up an administration's GUID by its exact name.
+ * Useful when you know the administration name from the Yuki UI but don't
+ * have the GUID — avoids having to call get_administrations and scan the list.
+ *
+ * Rate cost: 1 request.
+ */
+export declare function registerAdministrationLookupTools(server: McpServer, client: YukiClient): void;
 //# sourceMappingURL=administrations.d.ts.map

package/dist/tools/administrations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"administrations.d.ts","sourceRoot":"","sources":["../../src/tools/administrations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE/C;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI,CAqDvF"}
+{"version":3,"file":"administrations.d.ts","sourceRoot":"","sources":["../../src/tools/administrations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE/C;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI,CAqDvF;AAED;;;;;;;;GAQG;AACH,wBAAgB,iCAAiC,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI,CAyC7F"}

package/dist/tools/administrations.js

@@ -1,3 +1,4 @@
+import { z } from 'zod';
 /**
  * Register tools related to Yuki administrations.
  *
@@ -55,6 +56,51 @@ export function registerAdministrationTools(server, client) {
         }
     });
 }
+/**
+ * get_administration_id
+ *
+ * Look up an administration's GUID by its exact name.
+ * Useful when you know the administration name from the Yuki UI but don't
+ * have the GUID — avoids having to call get_administrations and scan the list.
+ *
+ * Rate cost: 1 request.
+ */
+export function registerAdministrationLookupTools(server, client) {
+    server.registerTool('get_administration_id', {
+        description: 'Look up the GUID of a Yuki administration by its exact name. ' +
+            'Use this to resolve an administration name to the ID required by other tools. ' +
+            'For a full list of administrations and IDs use get_administrations.',
+        inputSchema: {
+            administrationName: z
+                .string()
+                .describe('Exact name of the administration as shown in Yuki (case-sensitive).'),
+        },
+    }, async ({ administrationName }) => {
+        try {
+            const sessionID = await client.getSessionID();
+            const result = await client.callSoap({
+                service: 'Accounting.asmx',
+                method: 'AdministrationID',
+                params: { sessionID, administrationName },
+            });
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ success: true, administrationName, administrationId: result }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ success: false, error: message }, null, 2) }],
+                isError: true,
+            };
+        }
+    });
+}
 /** Normalise the parsed SOAP result into a flat array of administration objects. */
 function normalizeAdministrations(result) {
     if (!result)

package/dist/tools/administrations.js.map

@@ -1 +1 @@
-{"version":3,"file":"administrations.js","sourceRoot":"","sources":["../../src/tools/administrations.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,MAAM,UAAU,2BAA2B,CAAC,MAAiB,EAAE,MAAkB;IAC/E;;;;;;;;OAQG;IACH,MAAM,CAAC,YAAY,CACjB,qBAAqB,EACrB;QACE,WAAW,EACT,oFAAoF;YACpF,iFAAiF;KACpF,EACD,KAAK,IAAI,EAAE;QACT,IAAI,CAAC;YACH,sDAAsD;YACtD,MAAM,SAAS,GAAG,MAAM,MAAM,CAAC,YAAY,EAAE,CAAC;YAE9C,kDAAkD;YAClD,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC;gBACnC,OAAO,EAAE,iBAAiB;gBAC1B,MAAM,EAAE,iBAAiB;gBACzB,MAAM,EAAE,EAAE,SAAS,EAAE;aACtB,CAAC,CAAC;YAEH,MAAM,eAAe,GAAG,wBAAwB,CAAC,MAAM,CAAC,CAAC;YAEzD,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAe;wBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,eAAe,CAAC,MAAM,EAAE,eAAe,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;qBACjG;iBACF;aACF,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACjE,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAe;wBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;qBAClE;iBACF;gBACD,OAAO,EAAE,IAAI;aACd,CAAC;QACJ,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC;AAED,oFAAoF;AACpF,SAAS,wBAAwB,CAAC,MAAe;IAC/C,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,CAAC;IACvB,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,OAAO,MAAM,CAAC;IAEzC,MAAM,GAAG,GAAG,MAAiC,CAAC;IAE9C,gFAAgF;IAChF,MAAM,UAAU,GAAG,CAAC,GAAG,CAAC,iBAAiB,CAAC,EAAE,GAAG,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC,CAAC;IAC5E,KAAK,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;QAC3B,IAAI,CAAC,CAAC;YAAE,SAAS;QACjB,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;YAAE,OAAO,CAAC,CAAC;QAC/B,MAAM,KAAK,GAAI,CAA6B,CAAC,gBAAgB,CAAC,CAAC;QAC/D,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC;QACvC,IAAI,KAAK;YAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IAC5B,CAAC;IAED,OAAO,CAAC,MAAM,CAAC,CAAC;AAClB,CAAC"}
+{"version":3,"file":"administrations.js","sourceRoot":"","sources":["../../src/tools/administrations.ts"],"names":[],"mappings":"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"}

package/dist/tools/documents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"documents.d.ts","sourceRoot":"","sources":["../../src/tools/documents.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAIpE,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE/C;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI,CAyTjF"}
+{"version":3,"file":"documents.d.ts","sourceRoot":"","sources":["../../src/tools/documents.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAIpE,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE/C;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI,CA0rBjF"}

package/dist/tools/documents.js

@@ -219,6 +219,344 @@ export function registerDocumentTools(server, client) {
             };
         }
     });
+    // ── list_documents ──────────────────────────────────────────────────────────
+    /**
+     * list_documents
+     *
+     * List documents stored in a specific archive folder.
+     * Session-scoped: no administrationID needed (determined by the API key / domain).
+     *
+     * WSDL signature (Archive.asmx · DocumentsInFolder):
+     *   sessionID, folderID, sortOrder, startDate, endDate, numberOfRecords, startRecord
+     *
+     * Rate cost: 1 request.
+     */
+    server.registerTool('list_documents', {
+        description: 'List documents in a Yuki archive folder. ' +
+            'Returns document IDs, file names, dates, and amounts. ' +
+            'Call get_document_folders first to find the correct folder ID. ' +
+            'Use the returned document ID with get_document or download_document.',
+        inputSchema: {
+            folderId: z
+                .number()
+                .int()
+                .describe('Archive folder ID. Use get_document_folders to list available folders.'),
+            sortOrder: z
+                .enum(['DocumentDateDesc', 'DocumentDateAsc', 'CreatedDesc', 'CreatedAsc', 'ModifiedDesc', 'ModifiedAsc', 'ContactNameAsc', 'ContactNameDesc'])
+                .optional()
+                .default('DocumentDateDesc')
+                .describe('Sort order for results.'),
+            startDate: z
+                .string()
+                .optional()
+                .describe('Filter documents from this date (YYYY-MM-DD). Defaults to 2000-01-01.'),
+            endDate: z
+                .string()
+                .optional()
+                .describe('Filter documents up to this date (YYYY-MM-DD). Defaults to today.'),
+            numberOfRecords: z
+                .number()
+                .int()
+                .optional()
+                .default(50)
+                .describe('Maximum number of records to return (default 50).'),
+            startRecord: z
+                .number()
+                .int()
+                .optional()
+                .default(1)
+                .describe('1-based offset for pagination (default 1).'),
+        },
+    }, async ({ folderId, sortOrder, startDate, endDate, numberOfRecords, startRecord }) => {
+        try {
+            const sessionID = await client.getSessionID();
+            const start = startDate ? `${startDate}T00:00:00` : '0001-01-01T00:00:00';
+            const end = endDate ? `${endDate}T23:59:59` : `${new Date().toISOString().split('T')[0]}T23:59:59`;
+            const result = await client.callSoap({
+                service: 'Archive.asmx',
+                method: 'DocumentsInFolder',
+                params: {
+                    sessionID,
+                    folderID: folderId,
+                    sortOrder: sortOrder ?? 'DocumentDateDesc',
+                    startDate: start,
+                    endDate: end,
+                    numberOfRecords: numberOfRecords ?? 50,
+                    startRecord: startRecord ?? 1,
+                },
+            });
+            const documents = normalizeDocuments(result);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ success: true, folderId, count: documents.length, documents }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ success: false, error: message }, null, 2) }],
+                isError: true,
+            };
+        }
+    });
+    // ── search_documents ────────────────────────────────────────────────────────
+    /**
+     * search_documents
+     *
+     * Search archived documents by text within a specific folder (and optionally tab).
+     * Session-scoped: no administrationID needed.
+     *
+     * WSDL signature (Archive.asmx · SearchDocuments):
+     *   sessionID, searchOption, searchText, folderID, tabID,
+     *   sortOrder, startDate, endDate, numberOfRecords, startRecord
+     *
+     * SearchOption values: All, Creator, Contact, Subject, Tag, Type
+     * tabID: obtain valid IDs via get_document_folders (tab IDs are folder-specific).
+     *        Pass 0 to search all tabs within the folder.
+     *
+     * Rate cost: 1 request.
+     */
+    server.registerTool('search_documents', {
+        description: 'Search for documents in a Yuki archive folder by text. ' +
+            'Call get_document_folders first to find the folderID. ' +
+            'searchOption filters which field to match: All (default), Contact, Subject, Tag, Creator, or Type. ' +
+            'tabID scopes the search to a folder tab — use 0 to search all tabs.',
+        inputSchema: {
+            searchText: z
+                .string()
+                .describe('Text to search for (e.g. supplier name, invoice number, subject).'),
+            folderId: z
+                .number()
+                .int()
+                .optional()
+                .default(-1)
+                .describe('Archive folder ID to search within. Use -1 to search all folders (default). Use get_document_folders to find specific folder IDs.'),
+            tabId: z
+                .number()
+                .int()
+                .optional()
+                .default(-1)
+                .describe('Tab ID within the folder. Use -1 to search all tabs (default).'),
+            searchOption: z
+                .enum(['All', 'Creator', 'Contact', 'Subject', 'Tag', 'Type'])
+                .optional()
+                .default('All')
+                .describe("Field to search in. 'All' searches across all fields (default)."),
+            sortOrder: z
+                .enum(['DocumentDateDesc', 'DocumentDateAsc', 'CreatedDesc', 'CreatedAsc', 'ModifiedDesc', 'ModifiedAsc', 'ContactNameAsc', 'ContactNameDesc'])
+                .optional()
+                .default('DocumentDateDesc')
+                .describe('Sort order for results.'),
+            startDate: z
+                .string()
+                .optional()
+                .describe('Filter documents from this date (YYYY-MM-DD). Defaults to 2000-01-01.'),
+            endDate: z
+                .string()
+                .optional()
+                .describe('Filter documents up to this date (YYYY-MM-DD). Defaults to today.'),
+            numberOfRecords: z
+                .number()
+                .int()
+                .optional()
+                .default(50)
+                .describe('Maximum number of records to return (default 50).'),
+            startRecord: z
+                .number()
+                .int()
+                .optional()
+                .default(1)
+                .describe('1-based offset for pagination (default 1).'),
+        },
+    }, async ({ searchText, folderId, tabId, searchOption, sortOrder, startDate, endDate, numberOfRecords, startRecord }) => {
+        try {
+            const sessionID = await client.getSessionID();
+            // Use '0001-01-01' as Yuki's sentinel for "all dates" (no date filter).
+            // Use -1 for folderID/tabID to search across all folders/tabs.
+            const start = startDate ? `${startDate}T00:00:00` : '0001-01-01T00:00:00';
+            const end = endDate ? `${endDate}T23:59:59` : `${new Date().toISOString().split('T')[0]}T23:59:59`;
+            const result = await client.callSoap({
+                service: 'Archive.asmx',
+                method: 'SearchDocuments',
+                params: {
+                    sessionID,
+                    searchOption: searchOption ?? 'All',
+                    searchText,
+                    folderID: folderId ?? -1,
+                    tabID: tabId ?? -1,
+                    sortOrder: sortOrder ?? 'DocumentDateDesc',
+                    startDate: start,
+                    endDate: end,
+                    numberOfRecords: numberOfRecords ?? 50,
+                    startRecord: startRecord ?? 1,
+                },
+            });
+            const documents = normalizeDocuments(result);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ success: true, searchText, folderId, count: documents.length, documents }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ success: false, error: message }, null, 2) }],
+                isError: true,
+            };
+        }
+    });
+    // ── get_document ────────────────────────────────────────────────────────────
+    /**
+     * get_document
+     *
+     * Retrieve metadata for a single archived document by its ID.
+     * Returns file name, folder, date, amount, status, and other metadata.
+     *
+     * Use list_documents or search_documents to find document IDs.
+     * To download the actual file content, use download_document.
+     *
+     * Rate cost: 1 request.
+     */
+    server.registerTool('get_document', {
+        description: 'Retrieve metadata for a single archived document by its Yuki document ID. ' +
+            'Returns file name, folder, date, amount, and status. ' +
+            'Use list_documents or search_documents to find document IDs. ' +
+            'To download the file binary use download_document.',
+        inputSchema: {
+            documentId: z.string().describe('Yuki document ID (GUID or integer, from list_documents or search_documents).'),
+            administrationId: z
+                .string()
+                .optional()
+                .describe('Administration ID (GUID). Defaults to YUKI_DOMAIN_ID env var.'),
+        },
+    }, async ({ documentId, administrationId }) => {
+        try {
+            const adminId = administrationId ?? client.defaultDomainId;
+            if (!adminId)
+                throw new Error('administrationId is required (or set YUKI_DOMAIN_ID env var)');
+            const sessionID = await client.getSessionID();
+            const result = await client.callSoap({
+                service: 'Archive.asmx',
+                method: 'FindDocument',
+                params: { sessionID, administrationID: adminId, documentID: documentId },
+            });
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ success: true, documentId, result }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ success: false, error: message }, null, 2) }],
+                isError: true,
+            };
+        }
+    });
+    // ── download_document ───────────────────────────────────────────────────────
+    /**
+     * download_document
+     *
+     * Download the binary content of an archived document, returned as a
+     * base64-encoded string. The caller can decode and save the file.
+     *
+     * Rate cost: 1 request.
+     */
+    server.registerTool('download_document', {
+        description: 'Download an archived document from Yuki as a base64-encoded string. ' +
+            'Use list_documents or search_documents to find the document ID first. ' +
+            'Returns fileName and fileDataBase64.',
+        inputSchema: {
+            documentId: z.string().describe('Yuki document ID (from list_documents or search_documents).'),
+        },
+    }, async ({ documentId }) => {
+        try {
+            const sessionID = await client.getSessionID();
+            // DocumentBinaryData does not take administrationID
+            const result = await client.callSoap({
+                service: 'Archive.asmx',
+                method: 'DocumentBinaryData',
+                params: { sessionID, documentID: documentId },
+            });
+            const doc = result;
+            const fileName = doc['fileName'] ?? doc['FileName'] ?? null;
+            const fileData = doc['fileData'] ?? doc['filedata'] ?? doc['FileData'] ?? result;
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ success: true, documentId, fileName, fileDataBase64: fileData }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ success: false, error: message }, null, 2) }],
+                isError: true,
+            };
+        }
+    });
+    // ── get_cost_categories ──────────────────────────────────────────────────────
+    /**
+     * get_cost_categories
+     *
+     * Retrieve the available cost categories (kostenrekeningen) for document
+     * uploads. These are the GL account codes that can be passed as
+     * `costCategory` when calling upload_document or upload_document_from_path.
+     *
+     * Rate cost: 1 request.
+     */
+    server.registerTool('get_cost_categories', {
+        description: 'List available cost categories (GL cost accounts) for document uploads. ' +
+            'Use the returned GL codes as the costCategory parameter in upload_document.',
+        inputSchema: {
+            administrationId: z
+                .string()
+                .optional()
+                .describe('Administration ID (GUID). Defaults to YUKI_DOMAIN_ID env var.'),
+        },
+    }, async ({ administrationId }) => {
+        try {
+            const adminId = administrationId ?? client.defaultDomainId;
+            if (!adminId)
+                throw new Error('administrationId is required (or set YUKI_DOMAIN_ID env var)');
+            const sessionID = await client.getSessionID();
+            const result = await client.callSoap({
+                service: 'Archive.asmx',
+                method: 'CostCategories',
+                params: { sessionID, administrationID: adminId },
+            });
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ success: true, result }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ success: false, error: message }, null, 2) }],
+                isError: true,
+            };
+        }
+    });
     /**
      * get_document_folders
      *
@@ -274,4 +612,35 @@ export function registerDocumentTools(server, client) {
         }
     });
 }
+/** Unwrap a parsed SOAP documents result into a flat array. */
+function normalizeDocuments(result) {
+    if (!result)
+        return [];
+    if (Array.isArray(result))
+        return result;
+    const rec = result;
+    const wrappers = ['Documents', 'SearchResults', 'Rows'];
+    const itemTags = ['Document', 'SearchResult', 'Row'];
+    for (const wrapper of wrappers) {
+        const c = rec[wrapper];
+        if (!c)
+            continue;
+        if (Array.isArray(c))
+            return c;
+        const inner = c;
+        for (const tag of itemTags) {
+            if (Array.isArray(inner[tag]))
+                return inner[tag];
+            if (inner[tag])
+                return [inner[tag]];
+        }
+    }
+    for (const tag of itemTags) {
+        if (Array.isArray(rec[tag]))
+            return rec[tag];
+        if (rec[tag])
+            return [rec[tag]];
+    }
+    return [result];
+}
 //# sourceMappingURL=documents.js.map