e-arveldaja-mcp 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,8 @@
 # e-arveldaja MCP Server
 
-MCP (Model Context Protocol) server for the Estonian e-arveldaja (RIK e-Financials) REST API. Works with any MCP-compatible AI assistant — Claude Code, Cursor, Windsurf, Cline, and others.
+[![npm](https://img.shields.io/npm/v/e-arveldaja-mcp)](https://www.npmjs.com/package/e-arveldaja-mcp)
+
+MCP (Model Context Protocol) server for the Estonian e-arveldaja (RIK e-Financials) REST API. Works with any MCP-compatible AI assistant — Claude Code, Codex CLI, Gemini CLI, Google Antigravity, Cursor, Windsurf, Cline, and others.
 
 ## Disclaimer
 
@@ -19,7 +21,7 @@ By using this software you acknowledge that:
 2. Go to **Seadistused** → **Üldised seadistused** → **Lisa uus juurdepääsuluba** (Settings → General settings → Add new access token)
 3. Enter any name for the token
 4. Find your public IP address (e.g. at [whatismyipaddress.com](https://whatismyipaddress.com/)) and enter it in the allowed IP field. Multiple IPs can be separated by `;`
-5. Save — download the `apikey.txt` file and place it next to the project directory (i.e. in the parent folder)
+5. Save — download the `apikey.txt` file and place it in the working directory where you run your AI assistant
 
 If you don't have a static IP address, you will need to update the allowed IP in e-arveldaja settings whenever your IP changes.
 
@@ -46,11 +48,9 @@ npm run build          # tsc -> dist/
 
 This is a standard MCP server using stdio transport. Most AI assistants can set this up themselves — just ask:
 
-> "Add the e-arveldaja MCP server from /path/to/e-arveldaja-mcp to my MCP configuration"
-
-The assistant will read the config format it needs and add the server entry. You can also ask it to install the workflows:
+> "Add the e-arveldaja-mcp npm package as an MCP server to my configuration, using npx"
 
-> "Copy the workflow files from /path/to/e-arveldaja-mcp/workflows/ into your commands so I can use them"
+The assistant will add `{"command": "npx", "args": ["-y", "e-arveldaja-mcp"]}` to its MCP config. No cloning or paths needed.
 
 If you prefer to configure manually:
 

package/dist/api/transactions.api.d.ts

@@ -10,6 +10,7 @@ export declare class TransactionsApi extends BaseResource<Transaction> {
      * rejects confirmation with "buyer or supplier is missing".
      */
     confirm(id: number, distributions?: TransactionDistribution[]): Promise<ApiResponse>;
+    invalidate(id: number): Promise<ApiResponse>;
     getDocument(id: number): Promise<ApiFile>;
     uploadDocument(id: number, name: string, contents: string): Promise<ApiResponse>;
     deleteDocument(id: number): Promise<ApiResponse>;

package/dist/api/transactions.api.js

@@ -36,6 +36,10 @@ export class TransactionsApi extends BaseResource {
         }
         return this.client.patch(`/transactions/${id}/register`, body);
     }
+    async invalidate(id) {
+        this.invalidateCache();
+        return this.client.patch(`/transactions/${id}/invalidate`, {});
+    }
     async getDocument(id) {
         return this.client.get(`/transactions/${id}/document_user`);
     }

package/dist/index.js

@@ -23,6 +23,7 @@ import { registerRecurringInvoiceTools } from "./tools/recurring-invoices.js";
 import { registerEstonianTaxTools } from "./tools/estonian-tax.js";
 import { registerDocumentAuditTools } from "./tools/document-audit.js";
 import { registerLightyearTools } from "./tools/lightyear-investments.js";
+import { registerWiseImportTools } from "./tools/wise-import.js";
 import { registerResources } from "./resources/static-resources.js";
 function buildApiContext(httpClient) {
     return {
@@ -203,6 +204,7 @@ async function main() {
     registerEstonianTaxTools(server, api);
     registerDocumentAuditTools(server, api);
     registerLightyearTools(server, api);
+    registerWiseImportTools(server, api);
     // Register resources
     registerResources(server, api);
     // Start server

package/dist/tools/crud-tools.js

@@ -255,6 +255,10 @@ export function registerCrudTools(server, api) {
         const result = await api.transactions.confirm(id, dist);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
+    server.tool("invalidate_transaction", "Invalidate (unconfirm) a confirmed transaction. Returns it to unconfirmed status for editing or deletion.", idParam.shape, async ({ id }) => {
+        const result = await api.transactions.invalidate(id);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
     server.tool("delete_transaction", "Delete a transaction", idParam.shape, async ({ id }) => {
         const result = await api.transactions.delete(id);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };

package/dist/tools/wise-import.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ApiContext } from "./crud-tools.js";
+export declare function registerWiseImportTools(server: McpServer, api: ApiContext): void;

package/dist/tools/wise-import.js

@@ -0,0 +1,264 @@
+import { z } from "zod";
+import { readFile } from "fs/promises";
+import { validateFilePath } from "../file-validation.js";
+const EXPECTED_HEADERS = [
+    "ID", "Status", "Direction", "Created on", "Finished on",
+    "Source fee amount", "Source fee currency", "Target fee amount", "Target fee currency",
+    "Source name", "Source amount (after fees)", "Source currency",
+    "Target name", "Target amount (after fees)", "Target currency",
+    "Exchange rate", "Reference", "Batch", "Created by", "Category", "Note",
+];
+function parseCSVLine(line) {
+    const fields = [];
+    let current = "";
+    let inQuotes = false;
+    for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+        if (ch === '"') {
+            if (inQuotes && line[i + 1] === '"') {
+                current += '"';
+                i++;
+            }
+            else {
+                inQuotes = !inQuotes;
+            }
+        }
+        else if (ch === "," && !inQuotes) {
+            fields.push(current);
+            current = "";
+        }
+        else {
+            current += ch;
+        }
+    }
+    fields.push(current);
+    return fields;
+}
+function parseWiseCSV(csv) {
+    const lines = csv.trim().split("\n").filter(l => l.trim());
+    if (lines.length < 2)
+        throw new Error("CSV has no data rows");
+    const headers = parseCSVLine(lines[0]);
+    // Validate key headers exist
+    for (const expected of ["ID", "Status", "Direction", "Source amount (after fees)"]) {
+        if (!headers.includes(expected)) {
+            throw new Error(`Missing expected header "${expected}". Found: ${headers.slice(0, 10).join(", ")}`);
+        }
+    }
+    const idx = (name) => headers.indexOf(name);
+    const rows = [];
+    for (let i = 1; i < lines.length; i++) {
+        const fields = parseCSVLine(lines[i]);
+        if (fields.length < headers.length - 2)
+            continue; // allow slightly short rows
+        rows.push({
+            id: fields[idx("ID")] ?? "",
+            status: fields[idx("Status")] ?? "",
+            direction: fields[idx("Direction")] ?? "",
+            createdOn: fields[idx("Created on")] ?? "",
+            finishedOn: fields[idx("Finished on")] ?? "",
+            sourceFeeAmount: parseFloat(fields[idx("Source fee amount")] || "0") || 0,
+            sourceFeeCurrency: fields[idx("Source fee currency")] ?? "EUR",
+            sourceAmount: parseFloat(fields[idx("Source amount (after fees)")] || "0") || 0,
+            sourceCurrency: fields[idx("Source currency")] ?? "EUR",
+            targetName: fields[idx("Target name")] ?? "",
+            targetAmount: parseFloat(fields[idx("Target amount (after fees)")] || "0") || 0,
+            targetCurrency: fields[idx("Target currency")] ?? "EUR",
+            exchangeRate: parseFloat(fields[idx("Exchange rate")] || "1") || 1,
+            reference: fields[idx("Reference")] ?? "",
+            category: fields[idx("Category")] ?? "",
+            note: fields[idx("Note")] ?? "",
+        });
+    }
+    return rows;
+}
+function wiseDate(dateStr) {
+    // "2026-01-19 17:59:56" → "2026-01-19"
+    return dateStr.split(" ")[0] ?? dateStr;
+}
+export function registerWiseImportTools(server, api) {
+    server.tool("import_wise_transactions", "Parse a Wise transaction history CSV and create bank transactions in e-arveldaja. " +
+        "Skips REFUNDED, NEUTRAL, and zero-amount entries. " +
+        "All transactions use type C (e-arveldaja convention). " +
+        "Wise fees are created as separate transactions (for correct VAT/expense treatment). " +
+        "DRY RUN by default — set execute=true to actually create transactions.", {
+        file_path: z.string().describe("Absolute path to Wise transaction-history.csv"),
+        accounts_dimensions_id: z.number().describe("Bank account dimension ID for the Wise account in e-arveldaja"),
+        fee_account_relation_id: z.number().optional().describe("Relation ID for fee account distribution (default 861012637379 = 8610 Muud finantskulud)"),
+        execute: z.boolean().optional().describe("Actually create transactions (default false = dry run)"),
+        date_from: z.string().optional().describe("Only import transactions from this date (YYYY-MM-DD)"),
+        date_to: z.string().optional().describe("Only import transactions up to this date (YYYY-MM-DD)"),
+    }, async ({ file_path, accounts_dimensions_id, fee_account_relation_id, execute, date_from, date_to }) => {
+        const resolved = await validateFilePath(file_path, [".csv"], 10 * 1024 * 1024);
+        const csv = await readFile(resolved, "utf-8");
+        const rows = parseWiseCSV(csv);
+        const dryRun = execute !== true;
+        const feeRelationId = fee_account_relation_id ?? 861012637379; // 8610 Muud finantskulud
+        // Find Wise client for fee transactions
+        let wiseClientId;
+        if (!dryRun) {
+            const allClients = await api.clients.listAll();
+            const wiseClient = allClients.find(c => c.name?.toUpperCase() === "WISE" || c.name?.toUpperCase() === "TRANSFERWISE");
+            wiseClientId = wiseClient?.id;
+        }
+        // Filter rows
+        const eligible = rows.filter(r => {
+            if (r.status !== "COMPLETED")
+                return false;
+            if (r.direction === "NEUTRAL")
+                return false;
+            if (r.sourceAmount === 0 && r.targetAmount === 0)
+                return false;
+            const date = wiseDate(r.finishedOn || r.createdOn);
+            if (date_from && date < date_from)
+                return false;
+            if (date_to && date > date_to)
+                return false;
+            return true;
+        });
+        // Get existing transactions for duplicate detection
+        const existingTx = await api.transactions.listAll();
+        const existingDescs = new Set(existingTx.map(tx => `${tx.date}|${tx.amount}|${tx.description ?? ""}`));
+        // Also check by Wise ID in description
+        const existingByWiseId = new Set(existingTx
+            .filter(tx => tx.description?.startsWith("WISE:"))
+            .map(tx => tx.description.split(" ")[0]));
+        const created = [];
+        const skipped = [];
+        for (const row of eligible) {
+            const date = wiseDate(row.finishedOn || row.createdOn);
+            const type = "C"; // e-arveldaja uses type C for all bank transactions
+            const amount = row.sourceAmount;
+            const fee = row.sourceFeeAmount;
+            const wiseIdTag = `WISE:${row.id}`;
+            // Build description
+            let desc = wiseIdTag;
+            if (row.targetName)
+                desc += ` ${row.targetName}`;
+            if (row.category && row.category !== "General")
+                desc += ` (${row.category})`;
+            if (row.targetCurrency !== "EUR" && row.targetCurrency !== row.sourceCurrency) {
+                desc += ` [${row.targetAmount} ${row.targetCurrency} @ ${row.exchangeRate}]`;
+            }
+            // Duplicate check
+            if (existingByWiseId.has(wiseIdTag)) {
+                skipped.push({ wise_id: row.id, reason: "Already imported (Wise ID match)" });
+                continue;
+            }
+            // Create the main transaction (net amount, without fee)
+            if (dryRun) {
+                created.push({
+                    wise_id: row.id,
+                    date,
+                    type,
+                    amount,
+                    description: desc,
+                    status: "would_create",
+                });
+            }
+            else {
+                try {
+                    const result = await api.transactions.create({
+                        accounts_dimensions_id,
+                        type,
+                        amount,
+                        cl_currencies_id: "EUR",
+                        date,
+                        description: desc,
+                        bank_account_name: row.targetName || undefined,
+                        ref_number: row.reference || undefined,
+                    });
+                    created.push({
+                        wise_id: row.id,
+                        date,
+                        type,
+                        amount,
+                        description: desc,
+                        status: "created",
+                        api_id: result.created_object_id,
+                    });
+                }
+                catch (err) {
+                    skipped.push({ wise_id: row.id, reason: err.message });
+                }
+            }
+            // Create separate fee transaction if fee > 0
+            if (fee > 0) {
+                const feeDesc = `WISE:FEE:${row.id} Wise teenustasu`;
+                if (dryRun) {
+                    created.push({
+                        wise_id: `FEE:${row.id}`,
+                        date,
+                        type,
+                        amount: fee,
+                        description: feeDesc,
+                        status: "would_create",
+                    });
+                }
+                else {
+                    try {
+                        const feeResult = await api.transactions.create({
+                            accounts_dimensions_id,
+                            type,
+                            amount: fee,
+                            cl_currencies_id: "EUR",
+                            date,
+                            description: feeDesc,
+                            bank_account_name: "Wise",
+                            clients_id: wiseClientId,
+                        });
+                        const feeId = feeResult.created_object_id;
+                        // Auto-confirm fee to expense account
+                        if (feeId && wiseClientId) {
+                            try {
+                                await api.transactions.confirm(feeId, [
+                                    { related_table: "accounts", related_id: feeRelationId, amount: fee },
+                                ]);
+                                created.push({
+                                    wise_id: `FEE:${row.id}`,
+                                    date, type, amount: fee, description: feeDesc,
+                                    status: "created_and_confirmed",
+                                    api_id: feeId,
+                                });
+                            }
+                            catch (confErr) {
+                                created.push({
+                                    wise_id: `FEE:${row.id}`,
+                                    date, type, amount: fee, description: feeDesc,
+                                    status: "created (confirm failed: " + confErr.message + ")",
+                                    api_id: feeId,
+                                });
+                            }
+                        }
+                        else {
+                            created.push({
+                                wise_id: `FEE:${row.id}`,
+                                date, type, amount: fee, description: feeDesc,
+                                status: "created (needs manual confirm)",
+                                api_id: feeId,
+                            });
+                        }
+                    }
+                    catch (err) {
+                        skipped.push({ wise_id: `FEE:${row.id}`, reason: err.message });
+                    }
+                }
+            }
+        }
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        mode: dryRun ? "DRY_RUN" : "EXECUTED",
+                        total_csv_rows: rows.length,
+                        eligible: eligible.length,
+                        filtered_out: rows.length - eligible.length,
+                        created: created.length,
+                        skipped: skipped.length,
+                        results: created,
+                        skipped_details: skipped,
+                    }, null, 2),
+                }],
+        };
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "e-arveldaja-mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "MCP server for Estonian e-arveldaja (e-Financials) API",
   "type": "module",
   "main": "dist/index.js",