@codemill-solutions/yuki-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 CodeMill Solutions B.V.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,240 @@
+# yuki-mcp
+
+A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that connects AI agents to [Yuki](https://www.yukiworks.nl) accounting via Yuki's SOAP API.
+
+Built with Node.js, TypeScript, and [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-sdk).
+
+---
+
+## Installation
+
+```bash
+npm install @codemill-solutions/yuki-mcp
+```
+
+Then add it to your MCP host configuration (e.g. `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "yuki": {
+      "command": "node",
+      "args": ["node_modules/@codemill-solutions/yuki-mcp/dist/index.js"],
+      "env": {
+        "YUKI_API_KEY": "your-api-key-here",
+        "YUKI_DOMAIN_ID": "your-administration-guid-here"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Prerequisites
+
+- Node.js 20+
+- A Yuki account with API access enabled
+- Your Yuki API key (Yuki → Settings → API)
+
+---
+
+## Setup
+
+### 1. Install dependencies
+
+```bash
+npm install
+```
+
+### 2. Configure environment variables
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env`:
+
+```env
+YUKI_API_KEY=your-api-key-here
+YUKI_DOMAIN_ID=your-administration-guid-here  # optional at startup
+```
+
+`YUKI_DOMAIN_ID` can be left empty — the server starts without it. Call `get_administrations` to discover the correct GUID, then pass it via the `administrationId` parameter on individual tools.
+
+### 3. Build
+
+```bash
+npm run build
+```
+
+### 4. Connect to an MCP host
+
+Add to your MCP host configuration (e.g. `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "yuki": {
+      "command": "node",
+      "args": ["/absolute/path/to/yuki-mcp/dist/index.js"],
+      "env": {
+        "YUKI_API_KEY": "your-api-key-here",
+        "YUKI_DOMAIN_ID": "your-administration-guid-here"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Available tools
+
+### Administrations
+
+| Tool | Description |
+|------|-------------|
+| `get_administrations` | List all administrations (companies) for this API key. **Run this first** to find the correct `administrationId`. |
+
+### Relations
+
+| Tool | Key parameters | Description |
+|------|----------------|-------------|
+| `search_relations` | `searchValue`, `searchOption?`, `active?`, `pageNumber?` | Search customers and suppliers by name, code, VAT number, email, etc. Returns up to 100 results per page. |
+| `upsert_contact` | `fullName`, `contactCode?`, `contactType?`, … | Create or update a contact. When `contactCode` matches an existing record it is updated; otherwise a new contact is created. |
+
+### Sales invoices
+
+| Tool | Key parameters | Description |
+|------|----------------|-------------|
+| `get_sales_invoices` | `dateOutstanding?`, `sortOrder?`, `includeBankTransactions?` | Retrieve outstanding (unpaid) sales invoices. |
+| `process_sales_invoice` | `reference`, `subject`, `date`, `dueDate`, `contact`, `lines` | Create and book a new sales invoice. Optionally email it to the customer. |
+
+### Purchase invoices
+
+| Tool | Key parameters | Description |
+|------|----------------|-------------|
+| `get_purchase_invoices` | `dateOutstanding?`, `sortOrder?`, `includeBankTransactions?` | Retrieve outstanding (unpaid) purchase invoices. |
+| `process_purchase_invoice` | `date`, `invoiceAmount`, `invoiceVatAmount`, `contact`, `lines` | Book an incoming purchase invoice. Accepts an optional PDF as base64. |
+
+### Transactions & bank
+
+| Tool | Key parameters | Description |
+|------|----------------|-------------|
+| `get_transactions` | `glAccountCode`, `startDate`, `endDate` | Retrieve journal entries for a GL account (e.g. a bank account) in a date range. Use `get_gl_accounts` to find the right code. |
+| `get_transaction_details` | `reference` | Check if an outstanding item still exists and retrieve its current status. |
+| `process_journal` | `subject`, `entries[]` | Post a general journal entry (memoriaal). All entry amounts must sum to exactly 0. Used for bank reconciliation, corrections, and custom bookings. |
+
+### Accounting
+
+| Tool | Key parameters | Description |
+|------|----------------|-------------|
+| `get_gl_accounts` | `date?` | Retrieve all GL accounts with their balance at a given date. Use this to find bank account codes before calling `get_transactions`. |
+
+### Documents
+
+| Tool | Key parameters | Description |
+|------|----------------|-------------|
+| `upload_document` | `fileName`, `dataBase64`, `folder?`, `amount?` | Upload a PDF to the Yuki archive by passing its content as a base64 string. Use `get_document_folders` first to find the right folder ID. |
+| `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. |
+
+---
+
+## Testing
+
+### Option 1 — MCP Inspector (tool-level, no LLM)
+
+```bash
+npm run inspect
+```
+
+Opens a browser UI at `http://localhost:5173` where you can call individual tools and inspect raw responses.
+
+### Option 2 — Agent test harness (with Claude)
+
+Runs a full agentic loop: Claude reasons about the task, calls tools, and returns a final answer — exactly as an AI agent would use this MCP.
+
+Add your Anthropic API key to `.env`:
+
+```env
+ANTHROPIC_API_KEY=sk-ant-...
+```
+
+Then run a scenario:
+
+```bash
+npm run agent                                              # default: get_administrations
+npm run agent -- --scenario outstanding-invoices
+npm run agent -- --scenario search-relations --arg "Bedrijf BV"
+npm run agent -- --scenario gl-accounts
+npm run agent -- --scenario bank-transactions --arg "1200"
+npm run agent -- --scenario full-workflow
+```
+
+Available scenarios: `get-administrations`, `search-relations`, `outstanding-invoices`, `outstanding-payables`, `gl-accounts`, `bank-transactions`, `full-workflow`.
+
+---
+
+## Architecture
+
+```
+src/
+├── index.ts              # Entry point — loads env, registers tools, starts stdio transport
+├── yuki-client.ts        # SOAP client: envelope builder, axios HTTP, fast-xml-parser, XmlValue
+└── tools/
+    ├── administrations.ts  # get_administrations
+    ├── relations.ts        # search_relations, upsert_contact
+    ├── invoices.ts         # get_sales_invoices, get_purchase_invoices,
+    │                       # 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
+
+scripts/
+└── test-agent.ts         # Agent test harness (Claude + MCP client loop)
+```
+
+### Auth flow
+
+Yuki uses a two-step authentication pattern:
+
+1. `Authenticate(accessKey)` → returns a temporary `sessionID`
+2. All subsequent calls include that `sessionID`
+
+`YukiClient.getSessionID()` handles this transparently and caches the session for the lifetime of the process.
+
+> **Note:** Parameter casing differs across Yuki's services — `sessionId` (lowercase d) on `Sales.asmx` and `Purchase.asmx`; `sessionID` (uppercase D) on `Accounting.asmx`, `Contact.asmx`, and `Archive.asmx`. This is handled per-tool.
+
+### XML documents
+
+Write tools (`process_sales_invoice`, `process_purchase_invoice`, `process_journal`, `upsert_contact`) pass structured data to Yuki as an XML string inside the `xmlDoc` SOAP parameter. The `XmlValue` wrapper ensures this XML is embedded raw (not entity-encoded) in the SOAP envelope. All user-supplied values are XML-escaped via `escapeXml()`.
+
+---
+
+## Rate limits
+
+Yuki enforces **1,000 API requests per day**. Each tool call is 1 request. The session ID is cached so `Authenticate` is only called once per server process, not once per tool call.
+
+Design agent workflows to fetch broad lists once and reference them from the agent's context window rather than re-fetching on every step.
+
+---
+
+## Troubleshooting
+
+| Error | Likely cause |
+|-------|-------------|
+| `SOAP Fault: Authentication failed` | `YUKI_API_KEY` is incorrect or API access is not enabled in Yuki Settings |
+| `SOAP Fault: Administration not found` | Wrong `administrationId` — run `get_administrations` to get the correct GUID |
+| `Journal entries do not balance` | Amounts in `process_journal` don't sum to 0 — check debit/credit signs |
+| `HTTP 500 from api.yukiworks.nl` | Usually a wrong XML namespace or malformed `xmlDoc` — check the WSDL at `https://api.yukiworks.nl/ws/{Service}.asmx?wsdl` |
+| `File does not appear to be a PDF` | The file at `filePath` does not start with the `%PDF` magic bytes — check you're pointing at a valid PDF |
+| `File not found` | `filePath` passed to `upload_document_from_path` does not exist or is inaccessible |
+| `Network error` | No connectivity to `api.yukiworks.nl` — requests time out after 30 seconds |
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import "dotenv/config";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,49 @@
+import "dotenv/config";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { YukiClient } from "./yuki-client.js";
+// Read tools
+import { registerAdministrationTools } from "./tools/administrations.js";
+import { registerRelationTools } from "./tools/relations.js";
+import { registerInvoiceTools } from "./tools/invoices.js";
+import { registerTransactionTools } from "./tools/transactions.js";
+import { registerAccountingTools } from "./tools/accounting.js";
+// Write tools
+import { registerInvoiceWriteTools } from "./tools/invoices.js";
+import { registerJournalWriteTools } from "./tools/transactions.js";
+import { registerContactWriteTools } from "./tools/relations.js";
+import { registerDocumentTools } from "./tools/documents.js";
+// ── Environment validation ────────────────────────────────────────────────────
+const apiKey = process.env["YUKI_API_KEY"];
+const domainId = process.env["YUKI_DOMAIN_ID"] ?? "";
+if (!apiKey) {
+    // Write to stderr so the MCP host can surface the message without corrupting
+    // the stdio JSON-RPC stream used by the MCP protocol.
+    process.stderr.write("[yuki-mcp] Fatal: YUKI_API_KEY environment variable is not set.\n");
+    process.exit(1);
+}
+// ── Yuki SOAP client ──────────────────────────────────────────────────────────
+const yukiClient = new YukiClient(apiKey, domainId);
+// ── MCP server ────────────────────────────────────────────────────────────────
+const server = new McpServer({
+    name: "yuki-mcp",
+    version: "1.0.0",
+});
+// ── Read tools ────────────────────────────────────────────────────────────────
+registerAdministrationTools(server, yukiClient);
+registerRelationTools(server, yukiClient);
+registerInvoiceTools(server, yukiClient);
+registerTransactionTools(server, yukiClient);
+registerAccountingTools(server, yukiClient);
+// ── Write tools ───────────────────────────────────────────────────────────────
+registerInvoiceWriteTools(server, yukiClient);
+registerJournalWriteTools(server, yukiClient);
+registerContactWriteTools(server, yukiClient);
+registerDocumentTools(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. ` +
+    `Domain ID: ${domainId || "(none — run get_administrations to discover)"}\n`);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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,CAClB,mEAAmE,CACpE,CAAC;IACF,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"}

package/dist/tools/accounting.d.ts

@@ -0,0 +1,13 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { YukiClient } from "../yuki-client.js";
+/**
+ * Register tools for working with the Yuki chart of accounts.
+ *
+ * GLAccountBalance returns all GL accounts with their balance at a given date.
+ * This is the closest the Yuki SOAP API comes to a "list all GL accounts" call.
+ *
+ * Yuki service: Accounting.asmx
+ * Method:       GLAccountBalance(sessionID, administrationID, transactionDate)
+ */
+export declare function registerAccountingTools(server: McpServer, client: YukiClient): void;
+//# sourceMappingURL=accounting.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"accounting.d.ts","sourceRoot":"","sources":["../../src/tools/accounting.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,CACrC,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,UAAU,GACjB,IAAI,CA2FN"}

package/dist/tools/accounting.js

@@ -0,0 +1,117 @@
+import { z } from "zod";
+/**
+ * Register tools for working with the Yuki chart of accounts.
+ *
+ * GLAccountBalance returns all GL accounts with their balance at a given date.
+ * This is the closest the Yuki SOAP API comes to a "list all GL accounts" call.
+ *
+ * Yuki service: Accounting.asmx
+ * Method:       GLAccountBalance(sessionID, administrationID, transactionDate)
+ */
+export function registerAccountingTools(server, client) {
+    /**
+     * get_gl_accounts
+     *
+     * Retrieve all GL accounts (grootboekrekeningen) with their balance at a
+     * given date. Returns account code, name, and debit/credit balance.
+     *
+     * Use this to:
+     *   - Find the GL account code for a bank account before calling get_transactions
+     *   - Understand the account structure before booking a journal entry
+     *   - Get a financial snapshot (balance sheet / P&L) at a specific date
+     *
+     * Rate cost: 1 request.
+     */
+    server.registerTool("get_gl_accounts", {
+        description: "Retrieve all GL accounts (grootboekrekeningen) with their balance at a given date. " +
+            "Use this to find account codes (e.g. bank account codes) or get a financial snapshot. " +
+            "Defaults to today's date if no date is provided.",
+        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();
+            // Default to today's date in ISO format when not specified
+            const transactionDate = date ?? new Date().toISOString().split("T")[0];
+            const result = await client.callSoap({
+                service: "Accounting.asmx",
+                method: "GLAccountBalance",
+                params: {
+                    sessionID,
+                    administrationID: adminId,
+                    transactionDate,
+                },
+            });
+            const accounts = normalizeGLAccounts(result);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            count: accounts.length,
+                            balanceDate: transactionDate,
+                            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,
+            };
+        }
+    });
+}
+/** Unwrap the parsed SOAP GL account balance result into a flat array. */
+function normalizeGLAccounts(result) {
+    if (!result)
+        return [];
+    if (Array.isArray(result))
+        return result;
+    const rec = result;
+    const wrappers = ["GLAccounts", "Accounts", "Rows"];
+    const itemTags = ["GLAccount", "Account", "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=accounting.js.map

package/dist/tools/accounting.js.map

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

package/dist/tools/administrations.d.ts

@@ -0,0 +1,14 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { YukiClient } from "../yuki-client.js";
+/**
+ * Register tools related to Yuki administrations.
+ *
+ * A Yuki account can contain multiple administrations (companies/entities).
+ * Use get_administrations to discover the correct administrationID / domainID
+ * to pass to all other tools.
+ *
+ * Yuki service: Accounting.asmx
+ * Auth flow:    Authenticate(accessKey) → sessionID → Administrations(sessionID)
+ */
+export declare function registerAdministrationTools(server: McpServer, client: YukiClient): void;
+//# sourceMappingURL=administrations.d.ts.map

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

@@ -0,0 +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,CACzC,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,UAAU,GACjB,IAAI,CAyDN"}

package/dist/tools/administrations.js

@@ -0,0 +1,80 @@
+/**
+ * Register tools related to Yuki administrations.
+ *
+ * A Yuki account can contain multiple administrations (companies/entities).
+ * Use get_administrations to discover the correct administrationID / domainID
+ * to pass to all other tools.
+ *
+ * Yuki service: Accounting.asmx
+ * Auth flow:    Authenticate(accessKey) → sessionID → Administrations(sessionID)
+ */
+export function registerAdministrationTools(server, client) {
+    /**
+     * get_administrations
+     *
+     * List all administrations accessible with the current API key.
+     * Always run this first to find the correct administrationID (GUID).
+     *
+     * Rate cost: 2 requests (1× Authenticate + 1× Administrations).
+     * On subsequent calls within the same session, Authenticate is skipped: 1 request.
+     */
+    server.registerTool("get_administrations", {
+        description: "List all Yuki administrations (companies) accessible with the configured API key. " +
+            "Run this first to discover the correct administrationID to pass to other tools.",
+    }, async () => {
+        try {
+            // Step 1 — Authenticate and obtain (cached) sessionID
+            const sessionID = await client.getSessionID();
+            // Step 2 — Fetch administrations for this session
+            const result = await client.callSoap({
+                service: "Accounting.asmx",
+                method: "Administrations",
+                params: { sessionID },
+            });
+            const administrations = normalizeAdministrations(result);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ success: true, count: administrations.length, administrations }, 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)
+        return [];
+    if (Array.isArray(result))
+        return result;
+    const rec = result;
+    // The Administrations response wraps items in <Administrations><Administration>
+    const containers = [rec["Administrations"], rec["administrations"], result];
+    for (const c of containers) {
+        if (!c)
+            continue;
+        if (Array.isArray(c))
+            return c;
+        const inner = c["Administration"];
+        if (Array.isArray(inner))
+            return inner;
+        if (inner)
+            return [inner];
+    }
+    return [result];
+}
+//# sourceMappingURL=administrations.js.map

package/dist/tools/administrations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"administrations.js","sourceRoot":"","sources":["../../src/tools/administrations.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,MAAM,UAAU,2BAA2B,CACzC,MAAiB,EACjB,MAAkB;IAElB;;;;;;;;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,CAClB,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,eAAe,CAAC,MAAM,EAAE,eAAe,EAAE,EACjE,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,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"}

package/dist/tools/documents.d.ts

@@ -0,0 +1,18 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { YukiClient } from "../yuki-client.js";
+/**
+ * Register tools for uploading documents to the Yuki archive.
+ *
+ * The Yuki Archive service stores source documents (PDFs) alongside
+ * their financial data. Attaching a PDF to a purchase invoice is
+ * strongly recommended for audit compliance.
+ *
+ * Yuki service: Archive.asmx
+ * Method:       UploadDocumentWithData(sessionID, fileName, data, folder,
+ *                                      administrationID, currency, amount,
+ *                                      costCategory, paymentMethod, project, remarks)
+ *
+ * Note: Archive.asmx uses sessionID / administrationID (uppercase D).
+ */
+export declare function registerDocumentTools(server: McpServer, client: YukiClient): void;
+//# sourceMappingURL=documents.d.ts.map

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

@@ -0,0 +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,CACnC,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,UAAU,GACjB,IAAI,CAySN"}