@codemill-solutions/yuki-mcp 1.0.1 → 1.1.0

package/README.md

@@ -140,6 +140,13 @@ Add to your MCP host configuration (e.g. `claude_desktop_config.json`):
 | `upload_document_from_path` | `filePath`, `fileName?`, `folder?`, `amount?` | Upload a PDF from a local file path. Reads and encodes the file internally — preferred over `upload_document` when the file is available on disk. Validates that the file exists and is a valid PDF before uploading. |
 | `get_document_folders` | — | List all archive folders available in the administration. |
 
+### Backoffice
+
+| Tool | Key parameters | Description |
+|------|----------------|-------------|
+| `get_workflow` | `administrationId?` | Retrieve backoffice workflow items — documents that could not be processed automatically and are awaiting review by the accountant. |
+| `get_outstanding_questions` | `administrationId?` | Retrieve outstanding questions raised by the accountant that require a response before the related documents can be processed. |
+
 ---
 
 ## Testing
@@ -190,7 +197,8 @@ src/
     │                       # process_sales_invoice, process_purchase_invoice
     ├── transactions.ts     # get_transactions, get_transaction_details, process_journal
     ├── accounting.ts       # get_gl_accounts
-    └── documents.ts        # upload_document, upload_document_from_path, get_document_folders
+    ├── documents.ts        # upload_document, upload_document_from_path, get_document_folders
+    └── backoffice.ts       # get_workflow, get_outstanding_questions
 
 scripts/
 └── test-agent.ts         # Agent test harness (Claude + MCP client loop)

package/dist/index.js

@@ -13,6 +13,8 @@ import { registerInvoiceWriteTools } from './tools/invoices.js';
 import { registerJournalWriteTools } from './tools/transactions.js';
 import { registerContactWriteTools } from './tools/relations.js';
 import { registerDocumentTools } from './tools/documents.js';
+// Backoffice tools
+import { registerBackofficeTools } from './tools/backoffice.js';
 // ── Environment validation ────────────────────────────────────────────────────
 const apiKey = process.env['YUKI_API_KEY'];
 const domainId = process.env['YUKI_DOMAIN_ID'] ?? '';
@@ -40,10 +42,12 @@ registerInvoiceWriteTools(server, yukiClient);
 registerJournalWriteTools(server, yukiClient);
 registerContactWriteTools(server, yukiClient);
 registerDocumentTools(server, yukiClient);
+// ── Backoffice tools ──────────────────────────────────────────────────────────
+registerBackofficeTools(server, yukiClient);
 // ── Start ─────────────────────────────────────────────────────────────────────
 const transport = new StdioServerTransport();
 await server.connect(transport);
 // Log startup info to stderr only (stdout is reserved for JSON-RPC)
-process.stderr.write(`[yuki-mcp] Server started — 14 tools registered. ` +
+process.stderr.write(`[yuki-mcp] Server started — 16 tools registered. ` +
     `Domain ID: ${domainId || '(none — run get_administrations to discover)'}\n`);
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,eAAe,CAAC;AACvB,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,aAAa;AACb,OAAO,EAAE,2BAA2B,EAAE,MAAM,4BAA4B,CAAC;AACzE,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AACnE,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAEhE,cAAc;AACd,OAAO,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAC;AACpE,OAAO,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,iFAAiF;AAEjF,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;AAC3C,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,IAAI,EAAE,CAAC;AAErD,IAAI,CAAC,MAAM,EAAE,CAAC;IACZ,6EAA6E;IAC7E,sDAAsD;IACtD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,mEAAmE,CAAC,CAAC;IAC1F,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,iFAAiF;AAEjF,MAAM,UAAU,GAAG,IAAI,UAAU,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;AAEpD,iFAAiF;AAEjF,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;IAC3B,IAAI,EAAE,UAAU;IAChB,OAAO,EAAE,OAAO;CACjB,CAAC,CAAC;AAEH,iFAAiF;AACjF,2BAA2B,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAChD,qBAAqB,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAC1C,oBAAoB,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AACzC,wBAAwB,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAC7C,uBAAuB,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAE5C,iFAAiF;AACjF,yBAAyB,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAC9C,yBAAyB,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAC9C,yBAAyB,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAC9C,qBAAqB,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAE1C,iFAAiF;AAEjF,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;AAE7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAEhC,oEAAoE;AACpE,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,mDAAmD;IACjD,cAAc,QAAQ,IAAI,8CAA8C,IAAI,CAC/E,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,eAAe,CAAC;AACvB,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,aAAa;AACb,OAAO,EAAE,2BAA2B,EAAE,MAAM,4BAA4B,CAAC;AACzE,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AACnE,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAEhE,cAAc;AACd,OAAO,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAC;AACpE,OAAO,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,mBAAmB;AACnB,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAEhE,iFAAiF;AAEjF,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;AAC3C,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,IAAI,EAAE,CAAC;AAErD,IAAI,CAAC,MAAM,EAAE,CAAC;IACZ,6EAA6E;IAC7E,sDAAsD;IACtD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,mEAAmE,CAAC,CAAC;IAC1F,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,iFAAiF;AAEjF,MAAM,UAAU,GAAG,IAAI,UAAU,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;AAEpD,iFAAiF;AAEjF,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;IAC3B,IAAI,EAAE,UAAU;IAChB,OAAO,EAAE,OAAO;CACjB,CAAC,CAAC;AAEH,iFAAiF;AACjF,2BAA2B,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAChD,qBAAqB,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAC1C,oBAAoB,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AACzC,wBAAwB,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAC7C,uBAAuB,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAE5C,iFAAiF;AACjF,yBAAyB,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAC9C,yBAAyB,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAC9C,yBAAyB,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAC9C,qBAAqB,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAE1C,iFAAiF;AACjF,uBAAuB,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAE5C,iFAAiF;AAEjF,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;AAE7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAEhC,oEAAoE;AACpE,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,mDAAmD;IACjD,cAAc,QAAQ,IAAI,8CAA8C,IAAI,CAC/E,CAAC"}

package/dist/tools/backoffice.d.ts

@@ -0,0 +1,13 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { YukiClient } from '../yuki-client.js';
+/**
+ * Register tools for the Yuki Backoffice service.
+ *
+ * Backoffice.asmx exposes documents and questions that require manual
+ * review by the accountant before they can be processed.
+ *
+ * Yuki service: Backoffice.asmx
+ * Note: uses sessionID / administrationID (uppercase D), same as Accounting.asmx.
+ */
+export declare function registerBackofficeTools(server: McpServer, client: YukiClient): void;
+//# sourceMappingURL=backoffice.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"backoffice.d.ts","sourceRoot":"","sources":["../../src/tools/backoffice.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE/C;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI,CAiInF"}

package/dist/tools/backoffice.js

@@ -0,0 +1,126 @@
+import { z } from 'zod';
+/**
+ * Register tools for the Yuki Backoffice service.
+ *
+ * Backoffice.asmx exposes documents and questions that require manual
+ * review by the accountant before they can be processed.
+ *
+ * Yuki service: Backoffice.asmx
+ * Note: uses sessionID / administrationID (uppercase D), same as Accounting.asmx.
+ */
+export function registerBackofficeTools(server, client) {
+    /**
+     * get_workflow
+     *
+     * Retrieve backoffice workflow items — documents (purchase and sales invoices)
+     * that could not be processed automatically and are waiting to be reviewed
+     * and booked by the accountant.
+     *
+     * Rate cost: 1 request.
+     */
+    server.registerTool('get_workflow', {
+        description: 'Retrieve the Yuki backoffice workflow items for an administration. ' +
+            'These are documents (purchase and sales invoices) that could not be processed ' +
+            'automatically and are waiting to be reviewed and booked by the accountant.',
+        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();
+            // Backoffice.asmx uses sessionID / administrationID (uppercase D)
+            const result = await client.callSoap({
+                service: 'Backoffice.asmx',
+                method: 'GetWorkflow',
+                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_outstanding_questions
+     *
+     * Retrieve outstanding backoffice questions for an administration.
+     * These are questions raised by the accountant that require a response
+     * before the related documents can be processed.
+     *
+     * Rate cost: 1 request.
+     */
+    server.registerTool('get_outstanding_questions', {
+        description: 'Retrieve outstanding backoffice questions for an administration in Yuki. ' +
+            'These are questions raised by the accountant that require a response ' +
+            'before the related documents can be processed.',
+        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: 'Backoffice.asmx',
+                method: 'GetOutstandingQuestions',
+                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,
+            };
+        }
+    });
+}
+//# sourceMappingURL=backoffice.js.map

package/dist/tools/backoffice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backoffice.js","sourceRoot":"","sources":["../../src/tools/backoffice.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemill-solutions/yuki-mcp",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "MCP server for the Yuki accounting SOAP API",
   "repository": {
     "type": "git",
@@ -33,7 +33,7 @@
     "@modelcontextprotocol/sdk": "^1.10.1",
     "axios": "^1.7.9",
     "dotenv": "^16.4.7",
-    "fast-xml-parser": "^5.5.3",
+    "fast-xml-parser": "^5.5.8",
     "zod": "^3.24.1"
   },
   "devDependencies": {