e-arveldaja-mcp 0.2.0 → 0.3.0

package/.claude/commands/book-invoice.md

@@ -71,6 +71,21 @@ If no past invoices exist, call `list_purchase_articles` and choose the most app
 - 49 (Consultation/Konsultatsioon, acct 5340)
 - 62 (Other operating/Muud tegevuskulud, acct 5990)
 
+### Step 5b: Determine reverse charge VAT (pöördkäibemaks)
+
+ALWAYS check if reverse charge applies. Set `reversed_vat_id: 1` on items when:
+- Supplier is **outside Estonia** (EU or non-EU) AND provides services
+- Invoice mentions "reverse charge", "Article 196", "pöördkäibemaks", or has 0% VAT with a foreign supplier
+- Supplier country is NOT Estonia (check cl_code_country, VAT number prefix, or address)
+
+When reverse charge applies:
+- `vat_rate_dropdown`: "0"
+- `reversed_vat_id`: 1
+
+When supplier is Estonian with regular VAT:
+- `vat_rate_dropdown`: the VAT rate (e.g. "24")
+- `reversed_vat_id`: null (don't set)
+
 ### Step 6: Create the purchase invoice
 
 Call `create_purchase_invoice_from_pdf`:
@@ -84,7 +99,8 @@ Call `create_purchase_invoice_from_pdf`:
   - cl_purchase_articles_id: from step 5
   - purchase_accounts_id: from step 5
   - total_net_price: net amount
-  - vat_rate_dropdown: VAT rate as string (e.g. "24")
+  - vat_rate_dropdown: VAT rate as string (e.g. "24", or "0" for reverse charge)
+  - reversed_vat_id: 1 if reverse charge applies (see step 5b)
   - amount: quantity
 - vat_price: EXACT total VAT from the original invoice
 - gross_price: EXACT total gross from the original invoice

package/README.md

@@ -138,6 +138,14 @@ Download your Lightyear account statement CSV and capital gains report, then:
 
 The assistant will parse the trades, pair foreign currency conversions, calculate capital gains from the FIFO report, and create journal entries with the correct securities accounts.
 
+### Import Wise bank transactions
+
+Download your Wise transaction history CSV (Account → Statements → CSV), then:
+
+> "Import my Wise transactions from transaction-history.csv into e-arveldaja"
+
+The assistant will parse the CSV, create bank transactions with correct amounts, and separate Wise fees into their own entries for proper expense accounting. Supports EUR and foreign currency card payments (USD etc.).
+
 ### Generate financial reports
 
 > "Generate a P&L and balance sheet as of 28.02.2026"

package/dist/annotations.d.ts

@@ -0,0 +1,43 @@
+/** MCP tool annotation presets for e-arveldaja tools. */
+/** Read-only data retrieval — safe to auto-approve. */
+export declare const readOnly: {
+    readonly readOnlyHint: true;
+    readonly destructiveHint: false;
+    readonly idempotentHint: true;
+    readonly openWorldHint: true;
+};
+/** Creates a new record (draft). Not destructive but not idempotent. */
+export declare const create: {
+    readonly readOnlyHint: false;
+    readonly destructiveHint: false;
+    readonly idempotentHint: false;
+    readonly openWorldHint: true;
+};
+/** Updates an existing record. Reversible. */
+export declare const mutate: {
+    readonly readOnlyHint: false;
+    readonly destructiveHint: false;
+    readonly idempotentHint: true;
+    readonly openWorldHint: true;
+};
+/** Irreversible action: confirm, delete. Requires user confirmation. */
+export declare const destructive: {
+    readonly readOnlyHint: false;
+    readonly destructiveHint: true;
+    readonly idempotentHint: true;
+    readonly openWorldHint: true;
+};
+/** Sends data externally (email, e-invoice). Irreversible and not idempotent. */
+export declare const send: {
+    readonly readOnlyHint: false;
+    readonly destructiveHint: true;
+    readonly idempotentHint: false;
+    readonly openWorldHint: true;
+};
+/** Batch operation that modifies multiple records. Not idempotent. */
+export declare const batch: {
+    readonly readOnlyHint: false;
+    readonly destructiveHint: true;
+    readonly idempotentHint: false;
+    readonly openWorldHint: true;
+};

package/dist/annotations.js

@@ -0,0 +1,14 @@
+/** MCP tool annotation presets for e-arveldaja tools. */
+const base = { openWorldHint: true };
+/** Read-only data retrieval — safe to auto-approve. */
+export const readOnly = { ...base, readOnlyHint: true, destructiveHint: false, idempotentHint: true };
+/** Creates a new record (draft). Not destructive but not idempotent. */
+export const create = { ...base, readOnlyHint: false, destructiveHint: false, idempotentHint: false };
+/** Updates an existing record. Reversible. */
+export const mutate = { ...base, readOnlyHint: false, destructiveHint: false, idempotentHint: true };
+/** Irreversible action: confirm, delete. Requires user confirmation. */
+export const destructive = { ...base, readOnlyHint: false, destructiveHint: true, idempotentHint: true };
+/** Sends data externally (email, e-invoice). Irreversible and not idempotent. */
+export const send = { ...base, readOnlyHint: false, destructiveHint: true, idempotentHint: false };
+/** Batch operation that modifies multiple records. Not idempotent. */
+export const batch = { ...base, readOnlyHint: false, destructiveHint: true, idempotentHint: false };

package/dist/api/base-resource.d.ts

@@ -9,8 +9,7 @@ export interface ListParams {
 export declare class BaseResource<T> {
     protected client: HttpClient;
     protected basePath: string;
-    protected idParam: string;
-    constructor(client: HttpClient, basePath: string, idParam: string);
+    constructor(client: HttpClient, basePath: string);
     protected cacheKey(key: string): string;
     protected invalidateCache(pattern?: string): void;
     list(params?: ListParams): Promise<PaginatedResponse<T>>;

package/dist/api/base-resource.js

@@ -1,13 +1,12 @@
 import { Cache } from "../cache.js";
+import { log } from "../logger.js";
 export const cache = new Cache(300);
 export class BaseResource {
     client;
     basePath;
-    idParam;
-    constructor(client, basePath, idParam) {
+    constructor(client, basePath) {
         this.client = client;
         this.basePath = basePath;
-        this.idParam = idParam;
     }
     cacheKey(key) {
         return `${this.client.cacheNamespace}:${key}`;
@@ -36,6 +35,9 @@ export class BaseResource {
             const response = await this.list({ ...params, page });
             allItems.push(...response.items);
             totalPages = response.total_pages;
+            if (totalPages > 1 && page === 1) {
+                log("info", `${this.basePath}: fetching ${totalPages} pages...`);
+            }
             page++;
         } while (page <= totalPages);
         return allItems;

package/dist/api/clients.api.js

@@ -1,7 +1,7 @@
 import { BaseResource } from "./base-resource.js";
 export class ClientsApi extends BaseResource {
     constructor(client) {
-        super(client, "/clients", "clients_id");
+        super(client, "/clients");
     }
     async deactivate(id) {
         this.invalidateCache();

package/dist/api/journals.api.d.ts

@@ -10,6 +10,7 @@ export declare class JournalsApi extends BaseResource<Journal> {
      */
     listAllWithPostings(): Promise<Journal[]>;
     confirm(id: number): 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/journals.api.js

@@ -1,7 +1,7 @@
 import { BaseResource, cache } from "./base-resource.js";
 export class JournalsApi extends BaseResource {
     constructor(client) {
-        super(client, "/journals", "journals_id");
+        super(client, "/journals");
     }
     /**
      * Load all journals with postings guaranteed to be populated.
@@ -38,6 +38,10 @@ export class JournalsApi extends BaseResource {
         this.invalidateCache();
         return this.client.patch(`/journals/${id}/register`, {});
     }
+    async invalidate(id) {
+        this.invalidateCache();
+        return this.client.patch(`/journals/${id}/invalidate`, {});
+    }
     async getDocument(id) {
         return this.client.get(`/journals/${id}/document_user`);
     }

package/dist/api/products.api.js

@@ -1,7 +1,7 @@
 import { BaseResource } from "./base-resource.js";
 export class ProductsApi extends BaseResource {
     constructor(client) {
-        super(client, "/products", "products_id");
+        super(client, "/products");
     }
     async deactivate(id) {
         this.invalidateCache();

package/dist/api/purchase-invoices.api.js

@@ -1,5 +1,5 @@
 import { BaseResource } from "./base-resource.js";
-const roundMoney = (v) => Math.round(v * 100) / 100;
+import { roundMoney } from "../money.js";
 /**
  * For non-VAT (mitte-KMD) companies: set project_no_vat_gross_price on items
  * so the API computes item-level vat_amount for informational tracking.
@@ -31,7 +31,7 @@ function normalizeItemsForNonVat(items, isVatRegistered, grossPrice) {
 }
 export class PurchaseInvoicesApi extends BaseResource {
     constructor(client) {
-        super(client, "/purchase_invoices", "purchase_invoices_id");
+        super(client, "/purchase_invoices");
     }
     /**
      * Create a purchase invoice and set invoice-level totals.
@@ -55,8 +55,8 @@ export class PurchaseInvoicesApi extends BaseResource {
         // Read back to get item-level VAT computed by API
         const invoice = await this.get(id);
         const items = invoice.items;
-        const itemVat = items ? Math.round(items.reduce((s, i) => s + (i.vat_amount ?? 0), 0) * 100) / 100 : 0;
-        const itemNet = items ? Math.round(items.reduce((s, i) => s + (i.total_net_price ?? 0), 0) * 100) / 100 : 0;
+        const itemVat = items ? roundMoney(items.reduce((s, i) => s + (i.vat_amount ?? 0), 0)) : 0;
+        const itemNet = items ? roundMoney(items.reduce((s, i) => s + (i.total_net_price ?? 0), 0)) : 0;
         // Invoice-level VAT: explicit value wins for VAT-registered companies.
         // Non-KMD companies must keep invoice-level vat_price at 0 even if item VAT is tracked.
         const vat = isVatRegistered
@@ -65,7 +65,7 @@ export class PurchaseInvoicesApi extends BaseResource {
         // Invoice-level gross: explicit value wins, otherwise net + actual item VAT
         const gross = grossPrice !== undefined
             ? grossPrice
-            : Math.round((itemNet + itemVat) * 100) / 100;
+            : roundMoney(itemNet + itemVat);
         if (vat > 0 || gross > 0) {
             await this.update(id, { vat_price: vat, gross_price: gross, items: invoice.items });
             this.invalidateCache();
@@ -80,10 +80,10 @@ export class PurchaseInvoicesApi extends BaseResource {
         const invoice = await this.get(id);
         const items = invoice.items;
         if (items) {
-            const itemVat = Math.round(items.reduce((s, i) => s + (i.vat_amount ?? 0), 0) * 100) / 100;
-            const net = Math.round(items.reduce((s, i) => s + (i.total_net_price ?? 0), 0) * 100) / 100;
+            const itemVat = roundMoney(items.reduce((s, i) => s + (i.vat_amount ?? 0), 0));
+            const net = roundMoney(items.reduce((s, i) => s + (i.total_net_price ?? 0), 0));
             const vat = isVatRegistered ? itemVat : 0;
-            const gross = Math.round((net + itemVat) * 100) / 100;
+            const gross = roundMoney(net + itemVat);
             const currentGross = invoice.gross_price;
             const shouldRepair = !currentGross || Math.abs(currentGross - gross) > 0.02;
             if (shouldRepair) {

package/dist/api/sale-invoices.api.js

@@ -1,7 +1,7 @@
 import { BaseResource } from "./base-resource.js";
 export class SaleInvoicesApi extends BaseResource {
     constructor(client) {
-        super(client, "/sale_invoices", "sale_invoices_id");
+        super(client, "/sale_invoices");
     }
     async confirm(id) {
         this.invalidateCache();

package/dist/api/transactions.api.js

@@ -1,7 +1,7 @@
 import { BaseResource } from "./base-resource.js";
 export class TransactionsApi extends BaseResource {
     constructor(client) {
-        super(client, "/transactions", "transactions_id");
+        super(client, "/transactions");
     }
     /**
      * Confirm a transaction with distribution rows.

package/dist/file-validation.js

@@ -1,17 +1,25 @@
 import { stat, realpath } from "fs/promises";
 import { resolve, extname, isAbsolute } from "path";
-import { existsSync } from "fs";
+import { existsSync, realpathSync } from "fs";
 import { homedir } from "os";
 /**
  * Allowed root directories for file reads. Configurable via EARVELDAJA_ALLOWED_PATHS
  * (colon-separated list). Defaults to $HOME and /tmp.
+ * Roots are resolved through symlinks so that the check works even if
+ * e.g. /tmp is a symlink to /private/tmp (macOS).
  */
 function getAllowedRoots() {
-    const envPaths = process.env.EARVELDAJA_ALLOWED_PATHS;
-    if (envPaths) {
-        return envPaths.split(":").map(p => resolve(p));
-    }
-    return [homedir(), "/tmp"];
+    const raw = process.env.EARVELDAJA_ALLOWED_PATHS
+        ? process.env.EARVELDAJA_ALLOWED_PATHS.split(":").map(p => resolve(p))
+        : [homedir(), "/tmp"];
+    return raw.map(root => {
+        try {
+            return realpathSync(root);
+        }
+        catch {
+            return root;
+        }
+    });
 }
 /**
  * Get the project root (directory containing package.json).

package/dist/index.js

@@ -25,6 +25,11 @@ 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";
+import { registerDynamicResources } from "./resources/dynamic-resources.js";
+import { registerPrompts } from "./prompts.js";
+import { toolError } from "./tool-error.js";
+import { setLogger } from "./logger.js";
+import { readOnly, mutate } from "./annotations.js";
 function buildApiContext(httpClient) {
     return {
         clients: new ClientsApi(httpClient),
@@ -87,7 +92,7 @@ async function main() {
     const api = createScopedApiContext(connectionState, connectionContexts, invocationStorage);
     const server = new McpServer({
         name: "e-arveldaja",
-        version: "1.0.0",
+        version: "0.3.0",
         description: "EXPERIMENTAL, UNOFFICIAL MCP server for the Estonian e-arveldaja (e-Financials) API. " +
             "NOT affiliated with or endorsed by RIK. Use entirely at your own risk — " +
             "this software interacts with live financial data and can create, modify, and delete accounting records. " +
@@ -98,7 +103,7 @@ async function main() {
     });
     // --- Multi-account tools ---
     server.tool("list_connections", "List all available e-arveldaja connections (API key files). " +
-        "Shows which connection is currently active.", {}, async () => {
+        "Shows which connection is currently active.", {}, readOnly, async () => {
         const connections = allConfigs.map((nc, i) => ({
             index: i,
             name: nc.name,
@@ -121,7 +126,7 @@ async function main() {
         "Clears cached data atomically. Use list_connections to see available indices. " +
         "In-flight tool calls will fail fast and should be retried on the intended connection.", {
         index: z.number().describe("Connection index from list_connections"),
-    }, async ({ index }) => {
+    }, mutate, async ({ index }) => {
         if (index < 0 || index >= allConfigs.length) {
             return {
                 content: [{
@@ -160,60 +165,68 @@ async function main() {
                 }],
         };
     });
-    const originalTool = server.tool.bind(server);
-    const wrapToolHandler = (handler) => {
-        if (typeof handler !== "function") {
-            return handler;
-        }
-        return async (...handlerArgs) => {
+    // Wrap server.tool to pin each handler to a connection snapshot via AsyncLocalStorage.
+    // The wrapper captures the active connection at invocation time, runs the handler
+    // inside that snapshot, and asserts the connection hasn't changed on return.
+    function wrapHandler(handler) {
+        return (async (...args) => {
             const snapshot = captureSnapshot(connectionState);
-            return invocationStorage.run(snapshot, async () => {
-                const result = await handler(...handlerArgs);
-                assertSnapshotCurrent(connectionState, snapshot);
-                return result;
-            });
-        };
-    };
-    server.tool = ((...toolArgs) => {
-        if (toolArgs.length === 4) {
-            const [name, descriptionOrParamsSchema, paramsSchemaOrAnnotations, handler] = toolArgs;
-            return originalTool(name, descriptionOrParamsSchema, paramsSchemaOrAnnotations, wrapToolHandler(handler));
-        }
-        if (toolArgs.length === 3) {
-            const [name, descriptionOrParamsSchema, handler] = toolArgs;
-            return originalTool(name, descriptionOrParamsSchema, wrapToolHandler(handler));
-        }
-        if (toolArgs.length === 5) {
-            const [name, description, paramsSchema, annotations, handler] = toolArgs;
-            return originalTool(name, description, paramsSchema, annotations, wrapToolHandler(handler));
-        }
-        if (toolArgs.length === 2) {
-            const [name, handler] = toolArgs;
-            return originalTool(name, wrapToolHandler(handler));
-        }
-        return originalTool(...toolArgs);
+            try {
+                return await invocationStorage.run(snapshot, async () => {
+                    const result = await handler(...args);
+                    assertSnapshotCurrent(connectionState, snapshot);
+                    return result;
+                });
+            }
+            catch (error) {
+                return toolError(error);
+            }
+        });
+    }
+    // Create a proxy that intercepts server.tool() calls and wraps the last function argument.
+    // This is forward-compatible with any overload signature the SDK may add.
+    const scopedServer = new Proxy(server, {
+        get(target, prop, receiver) {
+            if (prop !== "tool")
+                return Reflect.get(target, prop, receiver);
+            return (...toolArgs) => {
+                // The handler is always the last argument and always a function
+                const lastIdx = toolArgs.length - 1;
+                if (lastIdx >= 0 && typeof toolArgs[lastIdx] === "function") {
+                    toolArgs[lastIdx] = wrapHandler(toolArgs[lastIdx]);
+                }
+                return target.tool(...toolArgs);
+            };
+        },
     });
-    // Register all tools
-    registerCrudTools(server, api);
-    registerAccountBalanceTools(server, api);
-    registerPdfWorkflowTools(server, api);
-    registerBankReconciliationTools(server, api);
-    registerFinancialStatementTools(server, api);
-    registerAgingTools(server, api);
-    registerRecurringInvoiceTools(server, api);
-    registerEstonianTaxTools(server, api);
-    registerDocumentAuditTools(server, api);
-    registerLightyearTools(server, api);
-    registerWiseImportTools(server, api);
+    // Register all tools (via scopedServer so handlers get connection-pinned)
+    registerCrudTools(scopedServer, api);
+    registerAccountBalanceTools(scopedServer, api);
+    registerPdfWorkflowTools(scopedServer, api);
+    registerBankReconciliationTools(scopedServer, api);
+    registerFinancialStatementTools(scopedServer, api);
+    registerAgingTools(scopedServer, api);
+    registerRecurringInvoiceTools(scopedServer, api);
+    registerEstonianTaxTools(scopedServer, api);
+    registerDocumentAuditTools(scopedServer, api);
+    registerLightyearTools(scopedServer, api);
+    registerWiseImportTools(scopedServer, api);
     // Register resources
     registerResources(server, api);
+    registerDynamicResources(server, api);
+    // Register prompts
+    registerPrompts(server);
     // Start server
     const transport = new StdioServerTransport();
     await server.connect(transport);
+    // Route log output through MCP logging protocol
+    setLogger((level, message) => {
+        server.sendLoggingMessage({ level, data: message });
+    });
     const names = allConfigs.map(c => c.name).join(", ");
-    console.error(`e-arveldaja MCP server started (${allConfigs.length} connection(s): ${names})`);
+    process.stderr.write(`e-arveldaja MCP server started (${allConfigs.length} connection(s): ${names})\n`);
 }
 main().catch((err) => {
-    console.error("Fatal error:", err);
+    process.stderr.write(`Fatal error: ${err instanceof Error ? err.message : String(err)}\n`);
     process.exit(1);
 });

package/dist/logger.d.ts

@@ -0,0 +1,4 @@
+type LogFn = (level: "debug" | "info" | "warning" | "error", message: string) => void;
+export declare function setLogger(fn: LogFn): void;
+export declare function log(level: "debug" | "info" | "warning" | "error", message: string): void;
+export {};

package/dist/logger.js

@@ -0,0 +1,9 @@
+let _log = (_level, message) => {
+    process.stderr.write(`${message}\n`);
+};
+export function setLogger(fn) {
+    _log = fn;
+}
+export function log(level, message) {
+    _log(level, message);
+}

package/dist/money.d.ts

@@ -0,0 +1,2 @@
+/** Round to 2 decimal places (cents). Use for all monetary arithmetic. */
+export declare const roundMoney: (v: number) => number;

package/dist/money.js

@@ -0,0 +1,2 @@
+/** Round to 2 decimal places (cents). Use for all monetary arithmetic. */
+export const roundMoney = (v) => Math.round(v * 100) / 100;

package/dist/prompts.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerPrompts(server: McpServer): void;