e-arveldaja-mcp 0.3.0 → 0.3.2

package/CLAUDE.md

@@ -1,7 +1,7 @@
 # e-arveldaja MCP Server
 
 TypeScript MCP server for the Estonian e-arveldaja (RIK e-Financials) REST API.
-84 tools across 11 modules + 6 resources. Supports multiple companies/accounts.
+85 tools, 7 workflow prompts, 12 resources across 11 modules. Supports multiple companies/accounts.
 
 ## Quick Start
 
@@ -165,5 +165,5 @@ import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js"
 const transport = new StdioClientTransport({ command: "node", args: ["dist/index.js"] });
 const client = new Client({ name: "test", version: "1.0.0" });
 await client.connect(transport);
-const { tools } = await client.listTools(); // 82 tools
+const { tools } = await client.listTools(); // 85 tools
 ```

package/README.md

@@ -2,7 +2,7 @@
 
 [![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.
+MCP server for the Estonian e-arveldaja (RIK e-Financials) REST API. 85 tools, 7 workflow prompts, 12 resources. Works with any MCP client — Claude Code, Codex CLI, Gemini CLI, Cursor, Windsurf, Cline, and others.
 
 ## Disclaimer
 
@@ -31,31 +31,20 @@ For the demo server, set the environment variable `EARVELDAJA_SERVER=demo`.
 
 ## Setup
 
-### Option A: npx (no install needed)
+### 1. Add the MCP server
 
-Just reference `npx e-arveldaja-mcp` in your MCP config — no cloning or building required. See configuration examples below.
+Most AI assistants can set this up for you — just ask:
 
-### Option B: From source
+> "Add the e-arveldaja-mcp npm package as an MCP server"
 
+If you prefer to do it manually:
+
+**Claude Code:**
 ```bash
-git clone https://github.com/iseppo/e-arveldaja-mcp.git
-cd e-arveldaja-mcp
-npm install
-npm run build          # tsc -> dist/
+claude mcp add e-arveldaja -- npx -y e-arveldaja-mcp
 ```
 
-### Connecting to your AI assistant
-
-This is a standard MCP server using stdio transport. Most AI assistants can set this up themselves — just ask:
-
-> "Add the e-arveldaja-mcp npm package as an MCP server to my configuration, using npx"
-
-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:
-
-**JSON-based config** (Claude Code, Cursor, Windsurf, Cline, Gemini CLI, Antigravity):
-
+**Other tools** (Cursor, Windsurf, Cline, Gemini CLI, Codex CLI, Antigravity) — add to your MCP config:
 ```json
 {
   "mcpServers": {
@@ -67,58 +56,65 @@ If you prefer to configure manually:
 }
 ```
 
-**TOML-based config** (Codex CLI):
-
-```toml
-[mcp_servers.e-arveldaja]
-command = "npx"
-args = ["-y", "e-arveldaja-mcp"]
-```
-
-If running from source, replace `"npx", "-y", "e-arveldaja-mcp"` with `"node", "/path/to/e-arveldaja-mcp/dist/index.js"`.
-
-Where this config file lives depends on your tool:
+<details>
+<summary>Config file locations by tool</summary>
 
 | Tool | Config file |
 |---|---|
 | **Claude Code** | `~/.claude/settings.json` or project `.claude/settings.json` |
-| **Codex CLI** | `~/.codex/config.toml` or project `.codex/config.toml` |
-| **Gemini CLI** | `~/.gemini/settings.json` or project `.gemini/settings.json` |
-| **Google Antigravity** | MCP Store UI → Manage MCP Servers → View raw config (`mcp_config.json`) |
+| **Codex CLI** | `~/.codex/config.toml` (TOML format) |
+| **Gemini CLI** | `~/.gemini/settings.json` |
+| **Google Antigravity** | MCP Store UI → Manage MCP Servers → raw config |
 | **Cursor** | `.cursor/mcp.json` in your project |
 | **Windsurf** | `~/.codeium/windsurf/mcp_config.json` |
 | **Cline** | VS Code settings under `cline.mcpServers` |
 
-See [CLAUDE.md](CLAUDE.md) for architecture details and full API documentation.
+</details>
 
-## Workflows
+### 2. Place your API key
 
-The project includes step-by-step workflow guides in [`workflows/`](workflows/) that orchestrate multiple MCP tools into complete accounting tasks. These work with any MCP client — just paste the workflow into your AI assistant's prompt or follow the steps manually.
+Put the downloaded `apikey.txt` in the working directory where you run your AI assistant. That's it — the server finds it automatically.
 
-| Workflow | Description |
-|---|---|
-| [book-invoice](workflows/book-invoice.md) | Book a purchase invoice from PDF: extract data, validate, find/create supplier, suggest accounts, create invoice, upload PDF, confirm |
-| [reconcile-bank](workflows/reconcile-bank.md) | Match unconfirmed bank transactions to open invoices and confirm matches |
-| [month-end](workflows/month-end.md) | Run month-end close checklist: blockers, missing docs, duplicates, trial balance, P&L, balance sheet |
-| [new-supplier](workflows/new-supplier.md) | Create a supplier with Estonian business registry lookup and dedup check |
+For multiple companies, place multiple files (`apikey.txt`, `apikey-company2.txt`, etc.) and use `list_connections` / `switch_connection` to switch between them.
 
-### Claude Code slash commands
+<details>
+<summary>Alternative: environment variables</summary>
 
-If you use Claude Code, the same workflows are also available as slash commands in `.claude/commands/`. To install:
+```bash
+export EARVELDAJA_API_KEY_ID=...
+export EARVELDAJA_API_PUBLIC_VALUE=...
+export EARVELDAJA_API_PASSWORD=...
+```
 
-**Option A:** Run Claude Code from the `e-arveldaja-mcp` directory — skills are auto-detected.
+</details>
 
-**Option B:** Symlink or copy to your global commands:
+<details>
+<summary>Building from source</summary>
 
 ```bash
-# Symlink (stays up to date)
-ln -s /path/to/e-arveldaja-mcp/.claude/commands/*.md ~/.claude/commands/
-
-# Or copy
-cp /path/to/e-arveldaja-mcp/.claude/commands/*.md ~/.claude/commands/
+git clone https://github.com/iseppo/e-arveldaja-mcp.git
+cd e-arveldaja-mcp
+npm install && npm run build
+# Then use: "node", "/path/to/e-arveldaja-mcp/dist/index.js" instead of npx
 ```
 
-Then use `/book-invoice`, `/reconcile-bank`, `/month-end`, `/new-supplier` in any conversation.
+</details>
+
+## Workflows (MCP Prompts)
+
+The server includes 7 built-in workflow prompts that any MCP client can discover and use. These guide the AI assistant through multi-step accounting tasks:
+
+| Prompt | Description |
+|---|---|
+| `book-invoice` | Book a purchase invoice from PDF: extract, validate, resolve supplier, create, upload, confirm |
+| `reconcile-bank` | Match bank transactions to invoices, auto-confirm or review manually |
+| `month-end-close` | Blockers, missing docs, duplicates, trial balance, P&L, balance sheet |
+| `new-supplier` | Create supplier with Estonian business registry lookup |
+| `company-overview` | Financial dashboard: balance sheet, P&L, receivables, payables |
+| `quarterly-vat` | Prepare KMD (VAT return) data for a quarter |
+| `lightyear-booking` | Book Lightyear investment trades and distributions from CSV |
+
+**Claude Code** also has these as slash commands: `/book-invoice`, `/reconcile-bank`, `/month-end`, `/new-supplier`.
 
 ## Usage Examples
 

package/dist/api/base-resource.js

@@ -1,5 +1,6 @@
 import { Cache } from "../cache.js";
 import { log } from "../logger.js";
+import { reportProgress } from "../progress.js";
 export const cache = new Cache(300);
 export class BaseResource {
     client;
@@ -38,6 +39,9 @@ export class BaseResource {
             if (totalPages > 1 && page === 1) {
                 log("info", `${this.basePath}: fetching ${totalPages} pages...`);
             }
+            if (totalPages > 1) {
+                await reportProgress(page - 1, totalPages);
+            }
             page++;
         } while (page <= totalPages);
         return allItems;

package/dist/index.js

@@ -4,6 +4,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { loadAllConfigs } from "./config.js";
+import { toolExtraStorage } from "./progress.js";
 import { HttpClient } from "./http-client.js";
 import { ClientsApi } from "./api/clients.api.js";
 import { ProductsApi } from "./api/products.api.js";
@@ -92,7 +93,7 @@ async function main() {
     const api = createScopedApiContext(connectionState, connectionContexts, invocationStorage);
     const server = new McpServer({
         name: "e-arveldaja",
-        version: "0.3.0",
+        version: "0.3.2",
         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. " +
@@ -100,10 +101,27 @@ async function main() {
             "sale/purchase invoices. Includes account balance computation (D/C logic), " +
             "PDF invoice extraction, supplier resolution with business registry lookup, " +
             "and smart booking suggestions based on past invoices.",
+    }, {
+        instructions: `Purchase invoices:
+- Before booking, call get_vat_info to check VAT registration status.
+- Before creating, call detect_duplicate_purchase_invoice.
+- Pass original vat_price and gross_price exactly — do not recalculate.
+- Use list_purchase_articles to resolve cl_purchase_articles_id.
+- For non-Estonian suppliers, check if reverse charge applies (reversed_vat_id=1).
+- PDF flow: extract_pdf_invoice → validate_invoice_data → resolve_supplier → suggest_booking → create_purchase_invoice_from_pdf → upload_invoice_document → confirm_purchase_invoice.
+
+Bank reconciliation:
+- Run reconcile_transactions first, then auto_confirm_exact_matches with dry_run before executing.
+
+Reporting:
+- Confirm all journals/invoices/transactions first for accurate financial reports.
+- list_connections / switch_connection for multi-company; switching clears caches.
+- Batch tools default to dry_run — preview before execute=true.
+- Amounts are EUR unless cl_currencies_id specifies otherwise.`,
     });
     // --- Multi-account tools ---
     server.tool("list_connections", "List all available e-arveldaja connections (API key files). " +
-        "Shows which connection is currently active.", {}, readOnly, async () => {
+        "Shows which connection is currently active.", {}, { ...readOnly, title: "List Connections" }, async () => {
         const connections = allConfigs.map((nc, i) => ({
             index: i,
             name: nc.name,
@@ -126,7 +144,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"),
-    }, mutate, async ({ index }) => {
+    }, { ...mutate, title: "Switch Connection" }, async ({ index }) => {
         if (index < 0 || index >= allConfigs.length) {
             return {
                 content: [{
@@ -171,9 +189,13 @@ async function main() {
     function wrapHandler(handler) {
         return (async (...args) => {
             const snapshot = captureSnapshot(connectionState);
+            const extra = args.length >= 2 ? args[1] : undefined;
             try {
                 return await invocationStorage.run(snapshot, async () => {
-                    const result = await handler(...args);
+                    const runInExtra = extra
+                        ? () => toolExtraStorage.run(extra, () => handler(...args))
+                        : () => handler(...args);
+                    const result = await runInExtra();
                     assertSnapshotCurrent(connectionState, snapshot);
                     return result;
                 });

package/dist/progress.d.ts

@@ -0,0 +1,13 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+export interface ToolExtra {
+    sendNotification: (notification: unknown) => Promise<void>;
+    _meta?: {
+        progressToken?: string | number;
+    };
+}
+export declare const toolExtraStorage: AsyncLocalStorage<ToolExtra>;
+/**
+ * Report progress for long-running operations.
+ * No-op if the client didn't supply a progress token.
+ */
+export declare function reportProgress(progress: number, total?: number): Promise<void>;

package/dist/progress.js

@@ -0,0 +1,24 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+export const toolExtraStorage = new AsyncLocalStorage();
+/**
+ * Report progress for long-running operations.
+ * No-op if the client didn't supply a progress token.
+ */
+export async function reportProgress(progress, total) {
+    const extra = toolExtraStorage.getStore();
+    if (!extra?._meta?.progressToken)
+        return;
+    try {
+        await extra.sendNotification({
+            method: "notifications/progress",
+            params: {
+                progressToken: extra._meta.progressToken,
+                progress,
+                ...(total !== undefined && { total }),
+            },
+        });
+    }
+    catch {
+        // Client may not support progress — ignore
+    }
+}

package/dist/tools/account-balance.js

@@ -62,16 +62,13 @@ async function computeAccountBalance(api, accountId, clientId, dateFrom, dateTo,
     };
 }
 export function registerAccountBalanceTools(server, api) {
-    server.tool("compute_account_balance", "Compute account balance from journal postings (D/C logic). " +
-        "For liability accounts (C-type): balance = credits - debits. " +
-        "For asset accounts (D-type): balance = debits - credits. " +
-        "Can filter by client and date range.", {
+    server.tool("compute_account_balance", "Compute an account balance from journal postings, with optional client and date filters. Applies the account's debit/credit direction automatically.", {
         account_id: z.number().describe("Account number (e.g. 2110 for short-term loans)"),
         client_id: z.number().optional().describe("Filter by client ID"),
         date_from: z.string().optional().describe("Start date (YYYY-MM-DD)"),
         date_to: z.string().optional().describe("End date (YYYY-MM-DD)"),
         include_entries: z.boolean().optional().describe("Include individual entries in response (default false)"),
-    }, readOnly, async ({ account_id, client_id, date_from, date_to, include_entries }) => {
+    }, { ...readOnly, title: "Compute Account Balance" }, async ({ account_id, client_id, date_from, date_to, include_entries }) => {
         const result = await computeAccountBalance(api, account_id, client_id, date_from, date_to);
         const summary = {
             account_id,
@@ -88,12 +85,10 @@ export function registerAccountBalanceTools(server, api) {
         };
         return { content: [{ type: "text", text: JSON.stringify(summary, null, 2) }] };
     });
-    server.tool("compute_client_debt", "Compute how much the company owes to a specific client (or vice versa). " +
-        "Checks accounts 2110 (short-term loans), 2310 (accounts payable), 1210 (accounts receivable) by default. " +
-        "Override account_ids for other accounts. Uses journal D/C postings.", {
+    server.tool("compute_client_debt", "Compute how much the company owes the client and vice versa across selected accounts (default: 2110, 2310, 1210). Uses journal D/C postings.", {
         client_id: z.number().describe("Client ID"),
         account_ids: z.string().optional().describe("Comma-separated account IDs to check (default: 2110,2310,1210)"),
-    }, readOnly, async ({ client_id, account_ids }) => {
+    }, { ...readOnly, title: "Compute Client Net Position" }, async ({ client_id, account_ids }) => {
         const ids = account_ids
             ? account_ids.split(",").map(s => parseInt(s.trim()))
             : [2110, 2310, 1210]; // short-term loans, accounts payable, accounts receivable

package/dist/tools/aging-analysis.js

@@ -27,7 +27,7 @@ export function registerAgingTools(server, api) {
     server.tool("compute_receivables_aging", "Compute receivables aging report (nõuete vanusanalüüs). " +
         "Groups unpaid sale invoices into aging buckets by client.", {
         as_of_date: z.string().optional().describe("Aging date (YYYY-MM-DD, default today)"),
-    }, readOnly, async ({ as_of_date }) => {
+    }, { ...readOnly, title: "Receivables Aging Report" }, async ({ as_of_date }) => {
         const today = as_of_date ?? new Date().toISOString().split("T")[0];
         const usesDefaultUtcDate = !as_of_date;
         const allSales = await api.saleInvoices.listAll();
@@ -92,7 +92,7 @@ export function registerAgingTools(server, api) {
     server.tool("compute_payables_aging", "Compute payables aging report (kohustuste vanusanalüüs). " +
         "Groups unpaid purchase invoices into aging buckets by supplier.", {
         as_of_date: z.string().optional().describe("Aging date (YYYY-MM-DD, default today)"),
-    }, readOnly, async ({ as_of_date }) => {
+    }, { ...readOnly, title: "Payables Aging Report" }, async ({ as_of_date }) => {
         const today = as_of_date ?? new Date().toISOString().split("T")[0];
         const usesDefaultUtcDate = !as_of_date;
         const allPurchases = await api.purchaseInvoices.listAll();

package/dist/tools/bank-reconciliation.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { readOnly, batch } from "../annotations.js";
+import { reportProgress } from "../progress.js";
 function matchScore(tx, invoice, txAmount) {
     let confidence = 0;
     const reasons = [];
@@ -48,7 +49,7 @@ export function registerBankReconciliationTools(server, api) {
     server.tool("reconcile_transactions", "Match unconfirmed bank transactions to open sale/purchase invoices. " +
         "Returns suggested matches with confidence scores and ready-to-use distribution data.", {
         min_confidence: z.number().optional().describe("Minimum confidence threshold 0-100 (default 50)"),
-    }, readOnly, async ({ min_confidence }) => {
+    }, { ...readOnly, title: "Reconcile Transactions" }, async ({ min_confidence }) => {
         const threshold = min_confidence ?? 50;
         // Get all unconfirmed transactions
         const allTx = await api.transactions.listAll();
@@ -135,11 +136,10 @@ export function registerBankReconciliationTools(server, api) {
                 }],
         };
     });
-    server.tool("auto_confirm_exact_matches", "Automatically confirm bank transactions that have a single high-confidence match (>=90). " +
-        "DRY RUN by default - set execute=true to actually confirm.", {
+    server.tool("auto_confirm_exact_matches", "Batch-confirm bank transactions with a single high-confidence match (>=90). DRY RUN by default — set execute=true to confirm.", {
         execute: z.boolean().optional().describe("Actually confirm transactions (default false = dry run)"),
         min_confidence: z.number().optional().describe("Minimum confidence (default 90)"),
-    }, batch, async ({ execute, min_confidence }) => {
+    }, { ...batch, title: "Auto-Confirm Bank Matches" }, async ({ execute, min_confidence }) => {
         const threshold = min_confidence ?? 90;
         const dryRun = execute !== true;
         // Get all unconfirmed transactions across pages
@@ -153,7 +153,10 @@ export function registerBankReconciliationTools(server, api) {
         const skipped = [];
         // Track consumed invoices to avoid double-matching (keyed by type:id to prevent cross-table collisions)
         const consumedInvoiceKeys = new Set();
-        for (const tx of unconfirmed) {
+        const total = unconfirmed.length;
+        for (let i = 0; i < unconfirmed.length; i++) {
+            const tx = unconfirmed[i];
+            await reportProgress(i, total);
             // Only process known transaction types
             if (tx.type !== "D" && tx.type !== "C") {
                 skipped.push({ transaction_id: tx.id, reason: `Unknown transaction type "${tx.type}"` });

package/dist/tools/crud-tools.js

@@ -83,11 +83,11 @@ export function registerCrudTools(server, api) {
     // =====================
     // CLIENTS
     // =====================
-    server.tool("list_clients", "List all clients (buyers/suppliers). Paginated.", pageParam.shape, readOnly, async (params) => {
+    server.tool("list_clients", "List all clients (buyers/suppliers). Paginated.", pageParam.shape, { ...readOnly, title: "List Clients" }, async (params) => {
         const result = await api.clients.list(params);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
-    server.tool("get_client", "Get a single client by ID", idParam.shape, readOnly, async ({ id }) => {
+    server.tool("get_client", "Get a single client by ID", idParam.shape, { ...readOnly, title: "Get Client" }, async ({ id }) => {
         const result = await api.clients.get(id);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
@@ -105,7 +105,7 @@ export function registerCrudTools(server, api) {
         bank_account_no: z.string().optional().describe("Bank account (IBAN)"),
         invoice_vat_no: z.string().optional().describe("VAT number"),
         notes: z.string().optional().describe("Notes"),
-    }, create, async (params) => {
+    }, { ...create, title: "Create Client" }, async (params) => {
         const result = await api.clients.create({
             ...params,
             cl_code_country: params.cl_code_country ?? "EST",
@@ -118,38 +118,38 @@ export function registerCrudTools(server, api) {
     server.tool("update_client", "Update an existing client", {
         id: z.number().describe("Client ID"),
         data: z.string().describe("JSON object with fields to update"),
-    }, mutate, async ({ id, data }) => {
+    }, { ...mutate, title: "Update Client" }, async ({ id, data }) => {
         const result = await api.clients.update(id, parseJsonObject(data, "data"));
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
-    server.tool("deactivate_client", "Deactivate a client (can be restored with restore_client)", idParam.shape, mutate, async ({ id }) => {
+    server.tool("deactivate_client", "Deactivate a client (can be restored with restore_client)", idParam.shape, { ...mutate, title: "Deactivate Client" }, async ({ id }) => {
         const result = await api.clients.deactivate(id);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
-    server.tool("restore_client", "Reactivate a deleted client", idParam.shape, mutate, async ({ id }) => {
+    server.tool("restore_client", "Reactivate a deactivated client", idParam.shape, { ...mutate, title: "Restore Client" }, async ({ id }) => {
         const result = await api.clients.restore(id);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
     server.tool("search_client", "Search clients by name (fuzzy match)", {
         name: z.string().describe("Name to search for"),
-    }, readOnly, async ({ name }) => {
+    }, { ...readOnly, title: "Search Clients" }, async ({ name }) => {
         const results = await api.clients.findByName(name);
         return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
     });
-    server.tool("find_client_by_code", "Find client by registry code", {
+    server.tool("find_client_by_code", "Find a client by business registry code or personal ID", {
         code: z.string().describe("Business registry code or personal ID"),
-    }, readOnly, async ({ code }) => {
+    }, { ...readOnly, title: "Find Client by Registry Code" }, async ({ code }) => {
         const result = await api.clients.findByCode(code);
         return { content: [{ type: "text", text: result ? JSON.stringify(result, null, 2) : "Not found" }] };
     });
     // =====================
     // PRODUCTS
     // =====================
-    server.tool("list_products", "List all products/services. Paginated.", pageParam.shape, readOnly, async (params) => {
+    server.tool("list_products", "List all products/services. Paginated.", pageParam.shape, { ...readOnly, title: "List Products" }, async (params) => {
         const result = await api.products.list(params);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
-    server.tool("get_product", "Get a single product by ID", idParam.shape, readOnly, async ({ id }) => {
+    server.tool("get_product", "Get a single product by ID", idParam.shape, { ...readOnly, title: "Get Product" }, async ({ id }) => {
         const result = await api.products.get(id);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
@@ -160,33 +160,33 @@ export function registerCrudTools(server, api) {
         cl_purchase_articles_id: z.number().optional().describe("Purchase article ID"),
         sales_price: z.number().optional().describe("Sales price"),
         unit: z.string().optional().describe("Unit (e.g. tk, h, km)"),
-    }, create, async (params) => {
+    }, { ...create, title: "Create Product" }, async (params) => {
         const result = await api.products.create(params);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
     server.tool("update_product", "Update a product", {
         id: z.number().describe("Product ID"),
         data: z.string().describe("JSON object with fields to update"),
-    }, mutate, async ({ id, data }) => {
+    }, { ...mutate, title: "Update Product" }, async ({ id, data }) => {
         const result = await api.products.update(id, parseJsonObject(data, "data"));
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
-    server.tool("deactivate_product", "Deactivate a product (can be restored with restore_product)", idParam.shape, mutate, async ({ id }) => {
+    server.tool("deactivate_product", "Deactivate a product (can be restored with restore_product)", idParam.shape, { ...mutate, title: "Deactivate Product" }, async ({ id }) => {
         const result = await api.products.deactivate(id);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
-    server.tool("restore_product", "Reactivate a deleted product", idParam.shape, mutate, async ({ id }) => {
+    server.tool("restore_product", "Reactivate a deactivated product", idParam.shape, { ...mutate, title: "Restore Product" }, async ({ id }) => {
         const result = await api.products.restore(id);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
     // =====================
     // JOURNALS
     // =====================
-    server.tool("list_journals", "List journal entries. Paginated.", pageParam.shape, readOnly, async (params) => {
+    server.tool("list_journals", "List journal entries. Paginated.", pageParam.shape, { ...readOnly, title: "List Journals" }, async (params) => {
         const result = await api.journals.list(params);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
-    server.tool("get_journal", "Get a journal entry by ID (includes postings)", idParam.shape, readOnly, async ({ id }) => {
+    server.tool("get_journal", "Get a journal entry by ID (includes postings)", idParam.shape, { ...readOnly, title: "Get Journal" }, async ({ id }) => {
         const result = await api.journals.get(id);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
@@ -197,7 +197,7 @@ export function registerCrudTools(server, api) {
         document_number: z.string().optional().describe("Document number"),
         cl_currencies_id: z.string().optional().describe("Currency (default EUR)"),
         postings: z.string().describe("JSON array of postings: [{accounts_id, type: 'D'|'C', amount, accounts_dimensions_id?, ...}]"),
-    }, create, async (params) => {
+    }, { ...create, title: "Create Journal" }, async (params) => {
         const result = await api.journals.create({
             ...params,
             cl_currencies_id: params.cl_currencies_id ?? "EUR",
@@ -208,30 +208,30 @@ export function registerCrudTools(server, api) {
     server.tool("update_journal", "Update a journal entry", {
         id: z.number().describe("Journal ID"),
         data: z.string().describe("JSON object with fields to update"),
-    }, mutate, async ({ id, data }) => {
+    }, { ...mutate, title: "Update Journal" }, async ({ id, data }) => {
         const result = await api.journals.update(id, parseJsonObject(data, "data"));
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
-    server.tool("delete_journal", "Delete a journal entry", idParam.shape, destructive, async ({ id }) => {
+    server.tool("delete_journal", "Delete a journal entry", idParam.shape, { ...destructive, title: "Delete Journal" }, async ({ id }) => {
         const result = await api.journals.delete(id);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
-    server.tool("confirm_journal", "Confirm/register a journal entry. IRREVERSIBLE — use invalidate_journal to reverse if needed.", idParam.shape, destructive, async ({ id }) => {
+    server.tool("confirm_journal", "Confirm/register a journal entry. IRREVERSIBLE — use invalidate_journal to reverse if needed.", idParam.shape, { ...destructive, title: "Confirm Journal" }, async ({ id }) => {
         const result = await api.journals.confirm(id);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
-    server.tool("invalidate_journal", "Invalidate (reverse) a confirmed journal entry. Returns it to unconfirmed status for editing or deletion.", idParam.shape, mutate, async ({ id }) => {
+    server.tool("invalidate_journal", "Invalidate (reverse) a confirmed journal entry. Returns it to unconfirmed status for editing or deletion.", idParam.shape, { ...mutate, title: "Invalidate Journal" }, async ({ id }) => {
         const result = await api.journals.invalidate(id);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
     // =====================
     // TRANSACTIONS
     // =====================
-    server.tool("list_transactions", "List bank transactions. Paginated.", pageParam.shape, readOnly, async (params) => {
+    server.tool("list_transactions", "List bank transactions. Paginated.", pageParam.shape, { ...readOnly, title: "List Transactions" }, async (params) => {
         const result = await api.transactions.list(params);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
-    server.tool("get_transaction", "Get a transaction by ID", idParam.shape, readOnly, async ({ id }) => {
+    server.tool("get_transaction", "Get a transaction by ID", idParam.shape, { ...readOnly, title: "Get Transaction" }, async ({ id }) => {
         const result = await api.transactions.get(id);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
@@ -245,37 +245,37 @@ export function registerCrudTools(server, api) {
         clients_id: z.number().optional().describe("Related client ID"),
         bank_account_name: z.string().optional().describe("Remitter/beneficiary name"),
         ref_number: z.string().optional().describe("Reference number"),
-    }, create, async (params) => {
+    }, { ...create, title: "Create Transaction" }, async (params) => {
         const result = await api.transactions.create({
             ...params,
             cl_currencies_id: params.cl_currencies_id ?? "EUR",
         });
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
-    server.tool("confirm_transaction", "Confirm a transaction with distribution rows", {
+    server.tool("confirm_transaction", "Confirm a bank transaction by providing distribution rows", {
         id: z.number().describe("Transaction ID"),
         distributions: z.string().optional().describe("JSON array of distribution rows: [{related_table, related_id?, amount}]"),
-    }, destructive, async ({ id, distributions }) => {
+    }, { ...destructive, title: "Confirm Transaction" }, async ({ id, distributions }) => {
         const dist = distributions ? parseTransactionDistributions(distributions) : undefined;
         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, mutate, async ({ id }) => {
+    server.tool("invalidate_transaction", "Invalidate (unconfirm) a confirmed transaction. Returns it to unconfirmed status for editing or deletion.", idParam.shape, { ...mutate, title: "Invalidate Transaction" }, 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, destructive, async ({ id }) => {
+    server.tool("delete_transaction", "Delete a transaction", idParam.shape, { ...destructive, title: "Delete Transaction" }, async ({ id }) => {
         const result = await api.transactions.delete(id);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
     // =====================
     // SALE INVOICES
     // =====================
-    server.tool("list_sale_invoices", "List sales invoices. Paginated.", pageParam.shape, readOnly, async (params) => {
+    server.tool("list_sale_invoices", "List sales invoices. Paginated.", pageParam.shape, { ...readOnly, title: "List Sale Invoices" }, async (params) => {
         const result = await api.saleInvoices.list(params);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
-    server.tool("get_sale_invoice", "Get a sales invoice by ID (includes items, deliveries)", idParam.shape, readOnly, async ({ id }) => {
+    server.tool("get_sale_invoice", "Get a sales invoice by ID (includes items, deliveries)", idParam.shape, { ...readOnly, title: "Get Sale Invoice" }, async ({ id }) => {
         const result = await api.saleInvoices.get(id);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
@@ -292,7 +292,7 @@ export function registerCrudTools(server, api) {
         show_client_balance: z.boolean().optional().describe("Show client balance on invoice"),
         items: z.string().describe("JSON array of invoice items: [{products_id, custom_title, amount, unit_net_price, ...}]"),
         notes: z.string().optional().describe("Internal notes"),
-    }, create, async (params) => {
+    }, { ...create, title: "Create Sale Invoice" }, async (params) => {
         const result = await api.saleInvoices.create({
             ...params,
             number_suffix: params.number_suffix ?? "",
@@ -307,19 +307,19 @@ export function registerCrudTools(server, api) {
     server.tool("update_sale_invoice", "Update a sales invoice", {
         id: z.number().describe("Invoice ID"),
         data: z.string().describe("JSON with fields to update"),
-    }, mutate, async ({ id, data }) => {
+    }, { ...mutate, title: "Update Sale Invoice" }, async ({ id, data }) => {
         const result = await api.saleInvoices.update(id, parseJsonObject(data, "data"));
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
-    server.tool("delete_sale_invoice", "Delete a sales invoice", idParam.shape, destructive, async ({ id }) => {
+    server.tool("delete_sale_invoice", "Delete a sales invoice", idParam.shape, { ...destructive, title: "Delete Sale Invoice" }, async ({ id }) => {
         const result = await api.saleInvoices.delete(id);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
-    server.tool("confirm_sale_invoice", "Confirm a sales invoice. IRREVERSIBLE — locks the invoice for editing.", idParam.shape, destructive, async ({ id }) => {
+    server.tool("confirm_sale_invoice", "Confirm a sales invoice. IRREVERSIBLE — locks the invoice for editing.", idParam.shape, { ...destructive, title: "Confirm Sale Invoice" }, async ({ id }) => {
         const result = await api.saleInvoices.confirm(id);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
-    server.tool("get_sale_invoice_delivery_options", "Get delivery options for a sales invoice", idParam.shape, readOnly, async ({ id }) => {
+    server.tool("get_sale_invoice_delivery_options", "Get available delivery methods for a sales invoice (e-invoice or email)", idParam.shape, { ...readOnly, title: "Get Sale Invoice Delivery Options" }, async ({ id }) => {
         const result = await api.saleInvoices.getDeliveryOptions(id);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
@@ -330,29 +330,26 @@ export function registerCrudTools(server, api) {
         email_addresses: z.string().optional().describe("Email addresses"),
         email_subject: z.string().optional().describe("Email subject"),
         email_body: z.string().optional().describe("Email body"),
-    }, send, async ({ id, ...request }) => {
+    }, { ...send, title: "Send Sale Invoice" }, async ({ id, ...request }) => {
         const result = await api.saleInvoices.sendEinvoice(id, request);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
-    server.tool("get_sale_invoice_document", "Download sales invoice PDF (base64)", idParam.shape, readOnly, async ({ id }) => {
+    server.tool("get_sale_invoice_document", "Download sales invoice PDF (base64)", idParam.shape, { ...readOnly, title: "Download Invoice PDF" }, async ({ id }) => {
         const result = await api.saleInvoices.getDocument(id);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
     // =====================
     // PURCHASE INVOICES
     // =====================
-    server.tool("list_purchase_invoices", "List purchase invoices. Paginated.", pageParam.shape, readOnly, async (params) => {
+    server.tool("list_purchase_invoices", "List purchase invoices. Paginated.", pageParam.shape, { ...readOnly, title: "List Purchase Invoices" }, async (params) => {
         const result = await api.purchaseInvoices.list(params);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
-    server.tool("get_purchase_invoice", "Get a purchase invoice by ID", idParam.shape, readOnly, async ({ id }) => {
+    server.tool("get_purchase_invoice", "Get a purchase invoice by ID", idParam.shape, { ...readOnly, title: "Get Purchase Invoice" }, async ({ id }) => {
         const result = await api.purchaseInvoices.get(id);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
-    server.tool("create_purchase_invoice", "Create a purchase invoice. Pass the EXACT vat_price and gross_price from the original invoice " +
-        "to ensure amounts match for payment reconciliation. " +
-        "Items require cl_purchase_articles_id (use list_purchase_articles). " +
-        "cl_fringe_benefits_id defaults to 1 (not a fringe benefit).", {
+    server.tool("create_purchase_invoice", "Create a draft purchase invoice with line items. Requires cl_purchase_articles_id (use list_purchase_articles). Pass EXACT vat_price and gross_price from the original invoice.", {
         clients_id: z.number().describe("Supplier client ID"),
         client_name: z.string().describe("Supplier name"),
         number: z.string().describe("Invoice number"),
@@ -367,7 +364,7 @@ export function registerCrudTools(server, api) {
         notes: z.string().optional().describe("Notes"),
         bank_ref_number: z.string().optional().describe("Payment reference number"),
         bank_account_no: z.string().optional().describe("Supplier bank account"),
-    }, create, async (params) => {
+    }, { ...create, title: "Create Purchase Invoice" }, async (params) => {
         const isVatReg = await isCompanyVatRegistered(api);
         const purchaseArticles = await getPurchaseArticlesWithVat(api);
         const rawItems = parsePurchaseInvoiceItems(params.items);
@@ -391,65 +388,64 @@ export function registerCrudTools(server, api) {
     server.tool("update_purchase_invoice", "Update a purchase invoice", {
         id: z.number().describe("Invoice ID"),
         data: z.string().describe("JSON with fields to update"),
-    }, mutate, async ({ id, data }) => {
+    }, { ...mutate, title: "Update Purchase Invoice" }, async ({ id, data }) => {
         const result = await api.purchaseInvoices.update(id, parseJsonObject(data, "data"));
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
-    server.tool("delete_purchase_invoice", "Delete a purchase invoice", idParam.shape, destructive, async ({ id }) => {
+    server.tool("delete_purchase_invoice", "Delete a purchase invoice", idParam.shape, { ...destructive, title: "Delete Purchase Invoice" }, async ({ id }) => {
         const result = await api.purchaseInvoices.delete(id);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
-    server.tool("confirm_purchase_invoice", "Confirm a purchase invoice. IRREVERSIBLE — locks the invoice for editing. " +
-        "Automatically fixes vat_price/gross_price if they are missing or inconsistent with the item totals.", idParam.shape, destructive, async ({ id }) => {
+    server.tool("confirm_purchase_invoice", "Confirm and lock a purchase invoice. Automatically fixes vat_price/gross_price if missing or inconsistent with item totals.", idParam.shape, { ...destructive, title: "Confirm Purchase Invoice" }, async ({ id }) => {
         const isVatReg = await isCompanyVatRegistered(api);
         const result = await api.purchaseInvoices.confirmWithTotals(id, isVatReg);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
-    server.tool("invalidate_purchase_invoice", "Invalidate (reverse) a confirmed purchase invoice. Returns it to PROJECT status for editing.", idParam.shape, mutate, async ({ id }) => {
+    server.tool("invalidate_purchase_invoice", "Return a confirmed purchase invoice to draft status for editing.", idParam.shape, { ...mutate, title: "Invalidate Purchase Invoice" }, async ({ id }) => {
         const result = await api.purchaseInvoices.invalidate(id);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
     // =====================
     // REFERENCE DATA (read-only)
     // =====================
-    server.tool("list_accounts", "Get chart of accounts (kontoplaani kontod)", {}, readOnly, async () => {
+    server.tool("list_accounts", "Get chart of accounts (kontoplaani kontod)", {}, { ...readOnly, title: "List Accounts" }, async () => {
         const result = await api.readonly.getAccounts();
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
-    server.tool("list_account_dimensions", "Get account dimensions (alamkontod)", {}, readOnly, async () => {
+    server.tool("list_account_dimensions", "Get account dimensions (alamkontod)", {}, { ...readOnly, title: "List Account Dimensions" }, async () => {
         const result = await api.readonly.getAccountDimensions();
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
-    server.tool("list_currencies", "Get available currencies", {}, readOnly, async () => {
+    server.tool("list_currencies", "Get available currencies", {}, { ...readOnly, title: "List Currencies" }, async () => {
         const result = await api.readonly.getCurrencies();
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
-    server.tool("list_sale_articles", "Get sales articles (müügiartiklid)", {}, readOnly, async () => {
+    server.tool("list_sale_articles", "Get sales articles (müügiartiklid)", {}, { ...readOnly, title: "List Sale Articles" }, async () => {
         const result = await api.readonly.getSaleArticles();
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
-    server.tool("list_purchase_articles", "Get purchase articles (ostuartiklid)", {}, readOnly, async () => {
+    server.tool("list_purchase_articles", "Get purchase articles (ostuartiklid)", {}, { ...readOnly, title: "List Purchase Articles" }, async () => {
         const result = await api.readonly.getPurchaseArticles();
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
-    server.tool("list_templates", "Get sales invoice templates", {}, readOnly, async () => {
+    server.tool("list_templates", "Get sales invoice templates", {}, { ...readOnly, title: "List Invoice Templates" }, async () => {
         const result = await api.readonly.getTemplates();
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
-    server.tool("list_projects", "Get cost/profit centers (projektid)", {}, readOnly, async () => {
+    server.tool("list_projects", "Get cost/profit centers (projektid)", {}, { ...readOnly, title: "List Projects" }, async () => {
         const result = await api.readonly.getProjects();
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
-    server.tool("get_invoice_info", "Get company invoice settings", {}, readOnly, async () => {
+    server.tool("get_invoice_info", "Get company invoice settings", {}, { ...readOnly, title: "Get Invoice Settings" }, async () => {
         const result = await api.readonly.getInvoiceInfo();
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
-    server.tool("get_vat_info", "Get company VAT information (KMKR)", {}, readOnly, async () => {
+    server.tool("get_vat_info", "Get company VAT information (KMKR)", {}, { ...readOnly, title: "Get VAT Info" }, async () => {
         const result = await api.readonly.getVatInfo();
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
     // Invoice series CRUD
-    server.tool("list_invoice_series", "Get invoice numbering series", {}, readOnly, async () => {
+    server.tool("list_invoice_series", "Get invoice numbering series", {}, { ...readOnly, title: "List Invoice Series" }, async () => {
         const result = await api.readonly.getInvoiceSeries();
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
@@ -460,12 +456,12 @@ export function registerCrudTools(server, api) {
         is_active: z.boolean().describe("Is active"),
         is_default: z.boolean().describe("Is default series"),
         overdue_charge: z.number().optional().describe("Delinquency charge per day"),
-    }, create, async (params) => {
+    }, { ...create, title: "Create Invoice Series" }, async (params) => {
         const result = await api.readonly.createInvoiceSeries(params);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
     // Bank accounts CRUD
-    server.tool("list_bank_accounts", "Get company bank accounts", {}, readOnly, async () => {
+    server.tool("list_bank_accounts", "Get company bank accounts", {}, { ...readOnly, title: "List Bank Accounts" }, async () => {
         const result = await api.readonly.getBankAccounts();
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
@@ -475,7 +471,7 @@ export function registerCrudTools(server, api) {
         cl_banks_id: z.number().optional().describe("Bank ID"),
         swift_code: z.string().optional().describe("SWIFT/BIC code"),
         show_in_sale_invoices: z.boolean().optional().describe("Show on invoices"),
-    }, create, async (params) => {
+    }, { ...create, title: "Create Bank Account" }, async (params) => {
         const result = await api.readonly.createBankAccount(params);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });

package/dist/tools/document-audit.js

@@ -5,7 +5,7 @@ export function registerDocumentAuditTools(server, api) {
         "Important for audit trail compliance.", {
         date_from: z.string().optional().describe("Start date (YYYY-MM-DD)"),
         date_to: z.string().optional().describe("End date (YYYY-MM-DD)"),
-    }, readOnly, async ({ date_from, date_to }) => {
+    }, { ...readOnly, title: "Find Missing Documents" }, async ({ date_from, date_to }) => {
         // Journals without documents
         const allJournals = await api.journals.listAll();
         const journalsWithout = allJournals.filter(j => {
@@ -82,11 +82,11 @@ export function registerDocumentAuditTools(server, api) {
                 }],
         };
     });
-    server.tool("detect_duplicate_purchase_invoice", "Check for potential duplicate purchase invoices based on supplier, invoice number, amount, and date.", {
+    server.tool("detect_duplicate_purchase_invoice", "Check for duplicate purchase invoices by supplier + invoice number, and by supplier + amount + date.", {
         clients_id: z.number().optional().describe("Filter by supplier ID"),
         date_from: z.string().optional().describe("Start date"),
         date_to: z.string().optional().describe("End date"),
-    }, readOnly, async ({ clients_id, date_from, date_to }) => {
+    }, { ...readOnly, title: "Detect Duplicate Purchase Invoices" }, async ({ clients_id, date_from, date_to }) => {
         const allPurchases = await api.purchaseInvoices.listAll();
         const filtered = allPurchases.filter((inv) => {
             if (inv.status === "DELETED" || inv.status === "INVALIDATED")

package/dist/tools/estonian-tax.js

@@ -48,10 +48,7 @@ async function computeRetainedEarningsBalance(api, accountId, asOfDate) {
     return roundMoney(credit - debit);
 }
 export function registerEstonianTaxTools(server, api) {
-    server.tool("prepare_dividend_package", "Calculate dividend distribution and create draft journal entries. " +
-        "Estonian CIT on dividends: 22/78 (from 2025). " +
-        "Creates a debit to retained earnings and credit to payable + tax liability. " +
-        "Validates accounts exist and checks retained earnings balance before posting.", {
+    server.tool("prepare_dividend_package", "Calculate dividend tax (22/78 CIT) and create draft journal entries for dividend payable and tax liability. Validates retained earnings balance and net assets.", {
         net_dividend: z.number().describe("Net dividend amount to shareholder (EUR)"),
         shareholder_client_id: z.number().describe("Shareholder client ID"),
         effective_date: z.string().describe("Distribution date (YYYY-MM-DD)"),
@@ -60,7 +57,7 @@ export function registerEstonianTaxTools(server, api) {
         tax_payable_account: z.number().optional().describe("CIT payable account (default 2540)"),
         share_capital_account: z.number().optional().describe("Share capital account for ÄS §157 net-assets check (default 3000)"),
         force: z.boolean().optional().describe("Create journal even if retained earnings are insufficient (default false)"),
-    }, create, async ({ net_dividend, shareholder_client_id, effective_date, retained_earnings_account, dividend_payable_account, tax_payable_account, share_capital_account, force }) => {
+    }, { ...create, title: "Prepare Dividend Distribution" }, async ({ net_dividend, shareholder_client_id, effective_date, retained_earnings_account, dividend_payable_account, tax_payable_account, share_capital_account, force }) => {
         const retainedAccount = retained_earnings_account ?? 3020;
         const payableAccount = dividend_payable_account ?? 2370;
         const taxAccount = tax_payable_account ?? 2540;
@@ -172,9 +169,7 @@ export function registerEstonianTaxTools(server, api) {
                 }],
         };
     });
-    server.tool("create_owner_expense_reimbursement", "Book an owner-paid business expense: expense account + VAT + payable to owner. " +
-        "Common for micro-OÜs where the owner pays with personal funds. " +
-        "Books input VAT separately only for VAT-registered companies and validates accounts in chart of accounts.", {
+    server.tool("create_owner_expense_reimbursement", "Create a journal for a business expense paid personally by the owner. Splits input VAT for VAT-registered companies.", {
         owner_client_id: z.number().describe("Owner/shareholder client ID"),
         effective_date: z.string().describe("Expense date (YYYY-MM-DD)"),
         description: z.string().describe("Expense description"),
@@ -185,7 +180,7 @@ export function registerEstonianTaxTools(server, api) {
         vat_account: z.number().optional().describe("Input VAT account (default 1510)"),
         payable_account: z.number().optional().describe("Payable to owner account (default 2110)"),
         document_number: z.string().optional().describe("Receipt/document number"),
-    }, create, async ({ owner_client_id, effective_date, description, net_amount, vat_rate, vat_amount, expense_account, vat_account, payable_account, document_number }) => {
+    }, { ...create, title: "Book Owner-Paid Expense" }, async ({ owner_client_id, effective_date, description, net_amount, vat_rate, vat_amount, expense_account, vat_account, payable_account, document_number }) => {
         const vatRegistered = await isCompanyVatRegistered(api);
         const vatAcc = vat_account ?? 1510;
         const payAcc = payable_account ?? 2110;

package/dist/tools/financial-statements.js

@@ -80,7 +80,7 @@ export function registerFinancialStatementTools(server, api) {
         "Shows debit/credit totals and balance for each account.", {
         date_from: z.string().optional().describe("Period start (YYYY-MM-DD)"),
         date_to: z.string().optional().describe("Period end (YYYY-MM-DD)"),
-    }, readOnly, async ({ date_from, date_to }) => {
+    }, { ...readOnly, title: "Compute Trial Balance" }, async ({ date_from, date_to }) => {
         const balances = await computeAllBalances(api, date_from, date_to);
         const totalDebit = balances.reduce((s, b) => s + b.debit_total, 0);
         const totalCredit = balances.reduce((s, b) => s + b.credit_total, 0);
@@ -103,7 +103,7 @@ export function registerFinancialStatementTools(server, api) {
     server.tool("compute_balance_sheet", "Compute balance sheet (bilanss) from journal postings. " +
         "Groups accounts into Varad (Assets) and Kohustused+Omakapital (Liabilities+Equity).", {
         date_to: z.string().optional().describe("Balance sheet date (YYYY-MM-DD, default: today)"),
-    }, readOnly, async ({ date_to }) => {
+    }, { ...readOnly, title: "Compute Balance Sheet" }, async ({ date_to }) => {
         const balances = await computeAllBalances(api, undefined, date_to);
         const assets = balances.filter(b => b.account_type_est === "Varad");
         const liabilities = balances.filter(b => b.account_type_est === "Kohustused");
@@ -160,7 +160,7 @@ export function registerFinancialStatementTools(server, api) {
         "Shows revenue minus expenses.", {
         date_from: z.string().describe("Period start (YYYY-MM-DD)"),
         date_to: z.string().describe("Period end (YYYY-MM-DD)"),
-    }, readOnly, async ({ date_from, date_to }) => {
+    }, { ...readOnly, title: "Compute Profit and Loss" }, async ({ date_from, date_to }) => {
         const balances = await computeAllBalances(api, date_from, date_to);
         const revenue = balances.filter(b => b.account_type_est === "Tulud");
         const expenses = balances.filter(b => b.account_type_est === "Kulud");
@@ -187,7 +187,7 @@ export function registerFinancialStatementTools(server, api) {
     server.tool("month_end_close_checklist", "Generate month-end close checklist: unconfirmed journals/invoices, " +
         "unreconciled bank transactions, overdue receivables/payables.", {
         month: z.string().describe("Month to check (YYYY-MM, e.g. 2026-02)"),
-    }, readOnly, async ({ month }) => {
+    }, { ...readOnly, title: "Month-End Close Checklist" }, async ({ month }) => {
         const dateFrom = `${month}-01`;
         const lastDay = getMonthLastDay(month);
         const dateTo = `${month}-${String(lastDay).padStart(2, "0")}`;

package/dist/tools/lightyear-investments.js

@@ -3,6 +3,7 @@ import { readFile } from "fs/promises";
 import { validateFilePath } from "../file-validation.js";
 import { roundMoney } from "../money.js";
 import { readOnly, batch } from "../annotations.js";
+import { reportProgress } from "../progress.js";
 const MAX_CSV_SIZE = 10 * 1024 * 1024; // 10 MB
 // BRICEKSP is Lightyear's money market cash fund - not a real investment
 const CASH_FUND_TICKER = "BRICEKSP";
@@ -304,7 +305,7 @@ export function registerLightyearTools(server, api) {
         "distributions, deposits, withdrawals. Filters out BRICEKSP money market fund trades. " +
         "Pairs foreign currency trades with their FX conversion entries.", {
         file_path: z.string().describe("Absolute path to Lightyear AccountStatement CSV file"),
-    }, readOnly, async ({ file_path }) => {
+    }, { ...readOnly, title: "Parse Lightyear Account Statement" }, async ({ file_path }) => {
         const csv = await readCsvFile(file_path);
         const rows = parseAccountStatement(csv);
         const { trades, warnings: fxWarnings } = extractTrades(rows);
@@ -377,7 +378,7 @@ export function registerLightyearTools(server, api) {
     server.tool("parse_lightyear_capital_gains", "Parse a Lightyear Capital Gains Statement CSV (FIFO method). " +
         "Shows cost basis, proceeds, and realized capital gains per sale.", {
         file_path: z.string().describe("Absolute path to Lightyear CapitalGainsStatement CSV file"),
-    }, readOnly, async ({ file_path }) => {
+    }, { ...readOnly, title: "Parse Lightyear Capital Gains" }, async ({ file_path }) => {
         const csv = await readCsvFile(file_path);
         const gains = parseCapitalGains(csv);
         const totalGains = gains.reduce((s, g) => s + g.capital_gains_eur, 0);
@@ -425,7 +426,7 @@ export function registerLightyearTools(server, api) {
         fee_account: z.number().optional().describe("Fee expense account (default: fees included in investment cost)"),
         skip_tickers: z.string().optional().describe("Comma-separated tickers to skip (default: BRICEKSP)"),
         dry_run: z.boolean().optional().describe("Preview without creating entries (default true)"),
-    }, batch, async ({ file_path, capital_gains_file, investment_account, investment_dimension_id, broker_account, broker_dimension_id, gain_loss_account, loss_account, fee_account, skip_tickers, dry_run }) => {
+    }, { ...batch, title: "Book Lightyear Trades" }, async ({ file_path, capital_gains_file, investment_account, investment_dimension_id, broker_account, broker_dimension_id, gain_loss_account, loss_account, fee_account, skip_tickers, dry_run }) => {
         const isDryRun = dry_run !== false;
         const skipSet = new Set((skip_tickers ?? CASH_FUND_TICKER).split(",").map(t => t.trim()));
         // Validate accounts exist and are active
@@ -481,7 +482,10 @@ export function registerLightyearTools(server, api) {
         const duplicates = trades.filter(t => existingRefs.has(t.reference));
         const results = [];
         const warnings = [...extraction.warnings, ...gainsWarnings];
-        for (const trade of newTrades) {
+        const totalNewTrades = newTrades.length;
+        for (let tradeIdx = 0; tradeIdx < newTrades.length; tradeIdx++) {
+            const trade = newTrades[tradeIdx];
+            await reportProgress(tradeIdx, totalNewTrades);
             // Skip unmatched FX trades
             if (trade.ccy !== "EUR" && trade.eur_amount === 0) {
                 results.push({
@@ -657,11 +661,7 @@ export function registerLightyearTools(server, api) {
                 }],
         };
     });
-    server.tool("book_lightyear_distributions", "Create journal entries for Lightyear dividend/interest distributions. " +
-        "Checks for duplicates using reference IDs. " +
-        "Books: Debit broker account (net received), Credit income account. " +
-        "Income = gross (net + tax + fee). " +
-        "Withheld tax (tax_amount) booked to tax_account. Platform fee booked to fee_account (default 8610).", {
+    server.tool("book_lightyear_distributions", "Create journal entries for Lightyear dividend and interest distributions, including withheld tax. DRY RUN by default.", {
         file_path: z.string().describe("Absolute path to Lightyear AccountStatement CSV file"),
         broker_account: z.number().describe("Broker cash account (e.g. 1120 Lightyear konto)"),
         broker_dimension_id: z.number().optional().describe("Dimension ID for broker account (accounts_dimensions_id)"),
@@ -669,7 +669,7 @@ export function registerLightyearTools(server, api) {
         tax_account: z.number().optional().describe("Withheld tax receivable/expense account (for tax_amount from CSV)"),
         fee_account: z.number().optional().describe("Platform fee expense account (default 8610 Muud finantskulud)"),
         dry_run: z.boolean().optional().describe("Preview without creating entries (default true)"),
-    }, batch, async ({ file_path, broker_account, broker_dimension_id, income_account, tax_account, fee_account: fee_account_param, dry_run }) => {
+    }, { ...batch, title: "Book Lightyear Distributions" }, async ({ file_path, broker_account, broker_dimension_id, income_account, tax_account, fee_account: fee_account_param, dry_run }) => {
         const isDryRun = dry_run !== false;
         const fee_account = fee_account_param ?? 8610;
         // Validate accounts exist and are active
@@ -785,11 +785,9 @@ export function registerLightyearTools(server, api) {
                 }],
         };
     });
-    server.tool("lightyear_portfolio_summary", "Compute current portfolio holdings and cost basis from Lightyear account statement. " +
-        "Uses weighted average cost method. Properly reduces cost basis on sells. " +
-        "Useful for verifying investment account balance.", {
+    server.tool("lightyear_portfolio_summary", "Compute current holdings and cost basis from a Lightyear account statement. Useful for verifying investment account balance.", {
         file_path: z.string().describe("Absolute path to Lightyear AccountStatement CSV file"),
-    }, readOnly, async ({ file_path }) => {
+    }, { ...readOnly, title: "Lightyear Portfolio Summary" }, async ({ file_path }) => {
         const csv = await readCsvFile(file_path);
         const rows = parseAccountStatement(csv);
         const { trades, warnings: fxWarnings } = extractTrades(rows);

package/dist/tools/pdf-workflow.js

@@ -46,12 +46,9 @@ function extractPdfHints(text) {
     return result;
 }
 export function registerPdfWorkflowTools(server, api) {
-    server.tool("extract_pdf_invoice", "Extract text and machine-readable identifiers from a PDF invoice. " +
-        "Returns raw text + detected IBAN, registry code, VAT number, reference number. " +
-        "YOU must read the raw_text and extract: supplier name, invoice number, dates, " +
-        "amounts (net, VAT, gross), and line items. Then call validate_invoice_data to verify.", {
+    server.tool("extract_pdf_invoice", "Extract text and key identifiers from a supplier invoice PDF. Returns raw text + detected IBAN, registry code, VAT number, reference number. Read raw_text to extract all invoice fields, then call validate_invoice_data.", {
         file_path: z.string().describe("Absolute path to the PDF file"),
-    }, readOnly, async ({ file_path }) => {
+    }, { ...readOnly, title: "Extract Supplier Invoice PDF" }, async ({ file_path }) => {
         const resolved = await validatePdfPath(file_path);
         const buffer = await readFile(resolved);
         const pdfData = await pdf(buffer);
@@ -79,7 +76,7 @@ export function registerPdfWorkflowTools(server, api) {
         items: z.string().describe("JSON array of items with at least {total_net_price, vat_rate_dropdown?} each"),
         invoice_date: z.string().optional().describe("Invoice date (YYYY-MM-DD)"),
         due_date: z.string().optional().describe("Due date (YYYY-MM-DD)"),
-    }, readOnly, async ({ total_net, total_vat, total_gross, items, invoice_date, due_date }) => {
+    }, { ...readOnly, title: "Validate Invoice Data" }, async ({ total_net, total_vat, total_gross, items, invoice_date, due_date }) => {
         const errors = [];
         const warnings = [];
         const parsed = safeJsonParse(items, "items");
@@ -187,9 +184,7 @@ export function registerPdfWorkflowTools(server, api) {
                 }],
         };
     });
-    server.tool("resolve_supplier", "Find or create a supplier in e-arveldaja. First searches by registry code, " +
-        "then VAT number, then name (fuzzy). If not found, optionally creates a new client. " +
-        "Also looks up business registry (äriregister) data if available.", {
+    server.tool("resolve_supplier", "Match a supplier to an existing client by registry code, VAT number, or name (fuzzy). Optionally creates a new client. Looks up Estonian business registry data.", {
         name: z.string().optional().describe("Supplier name from invoice"),
         reg_code: z.string().optional().describe("Registry code (registrikood)"),
         vat_no: z.string().optional().describe("VAT number (KMKR)"),
@@ -197,7 +192,7 @@ export function registerPdfWorkflowTools(server, api) {
         auto_create: z.boolean().optional().describe("Create client if not found (default false)"),
         country: z.string().optional().describe("Country code for auto-create (default EST)"),
         is_physical_entity: z.boolean().optional().describe("Natural person (default false = legal entity)"),
-    }, create, async ({ name, reg_code, vat_no, iban, auto_create, country, is_physical_entity }) => {
+    }, { ...create, title: "Find or Create Supplier" }, async ({ name, reg_code, vat_no, iban, auto_create, country, is_physical_entity }) => {
         // 1. Search by registry code
         if (reg_code) {
             const byCode = await api.clients.findByCode(reg_code);
@@ -308,12 +303,11 @@ export function registerPdfWorkflowTools(server, api) {
                 }],
         };
     });
-    server.tool("suggest_booking", "Find similar past purchase invoices from the same supplier to suggest " +
-        "how to book a new invoice (which accounts, articles, etc).", {
+    server.tool("suggest_booking", "Suggest purchase articles and accounts for a new invoice based on similar confirmed invoices from the same supplier.", {
         clients_id: z.number().describe("Supplier client ID"),
         description: z.string().optional().describe("Invoice item description to match"),
         limit: z.number().optional().describe("Max past invoices to return (default 3)"),
-    }, readOnly, async ({ clients_id, description, limit }) => {
+    }, { ...readOnly, title: "Suggest Purchase Booking" }, async ({ clients_id, description, limit }) => {
         const maxResults = limit ?? 3;
         const allInvoices = await api.purchaseInvoices.listAll();
         // Filter by supplier
@@ -364,9 +358,7 @@ export function registerPdfWorkflowTools(server, api) {
                 }],
         };
     });
-    server.tool("create_purchase_invoice_from_pdf", "Full workflow: create a purchase invoice from extracted PDF data. " +
-        "Resolves supplier, suggests booking, creates the invoice as DRAFT. " +
-        "Pass EXACT vat_price and gross_price from the original invoice for payment matching.", {
+    server.tool("create_purchase_invoice_from_pdf", "Create a draft purchase invoice from extracted and validated PDF data. Pass EXACT vat_price and gross_price from the original invoice for payment matching.", {
         supplier_client_id: z.number().describe("Supplier client ID (from resolve_supplier)"),
         invoice_number: z.string().describe("Invoice number"),
         invoice_date: z.string().describe("Invoice date (YYYY-MM-DD)"),
@@ -379,7 +371,7 @@ export function registerPdfWorkflowTools(server, api) {
         notes: z.string().optional().describe("Notes (e.g. PDF filename)"),
         ref_number: z.string().optional().describe("Reference number"),
         bank_account_no: z.string().optional().describe("Supplier bank account"),
-    }, create, async (params) => {
+    }, { ...create, title: "Create Purchase Invoice from PDF" }, async (params) => {
         const supplier = await api.clients.get(params.supplier_client_id);
         const isVatReg = await isCompanyVatRegistered(api);
         const purchaseArticles = await getPurchaseArticlesWithVat(api);
@@ -413,7 +405,7 @@ export function registerPdfWorkflowTools(server, api) {
     server.tool("upload_invoice_document", "Upload a PDF document to an existing purchase invoice", {
         invoice_id: z.number().describe("Purchase invoice ID"),
         file_path: z.string().describe("Absolute path to the PDF file"),
-    }, mutate, async ({ invoice_id, file_path }) => {
+    }, { ...mutate, title: "Upload Purchase Invoice PDF" }, async ({ invoice_id, file_path }) => {
         const resolved = await validatePdfPath(file_path);
         const buffer = await readFile(resolved);
         const base64 = buffer.toString("base64");

package/dist/tools/recurring-invoices.js

@@ -9,7 +9,7 @@ export function registerRecurringInvoiceTools(server, api) {
         target_journal_date: z.string().describe("New turnover date (YYYY-MM-DD)"),
         invoice_ids: z.string().optional().describe("Comma-separated source invoice IDs to copy (default: all confirmed from source month)"),
         auto_confirm: z.boolean().optional().describe("Confirm created invoices (default false)"),
-    }, batch, async ({ source_month, target_date, target_journal_date, invoice_ids, auto_confirm }) => {
+    }, { ...batch, title: "Create Recurring Sale Invoices" }, async ({ source_month, target_date, target_journal_date, invoice_ids, auto_confirm }) => {
         // Get source invoices
         const allSales = await api.saleInvoices.listAll();
         const sourceFrom = `${source_month}-01`;

package/dist/tools/wise-import.js

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { readFile } from "fs/promises";
 import { validateFilePath } from "../file-validation.js";
 import { batch } from "../annotations.js";
+import { reportProgress } from "../progress.js";
 const EXPECTED_HEADERS = [
     "ID", "Status", "Direction", "Created on", "Finished on",
     "Source fee amount", "Source fee currency", "Target fee amount", "Target fee currency",
@@ -89,7 +90,7 @@ export function registerWiseImportTools(server, api) {
         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)"),
-    }, batch, async ({ file_path, accounts_dimensions_id, fee_account_relation_id, execute, date_from, date_to }) => {
+    }, { ...batch, title: "Import Wise Transactions" }, 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);
@@ -126,7 +127,10 @@ export function registerWiseImportTools(server, api) {
             .map(tx => tx.description.split(" ")[0]));
         const created = [];
         const skipped = [];
-        for (const row of eligible) {
+        const totalEligible = eligible.length;
+        for (let i = 0; i < eligible.length; i++) {
+            const row = eligible[i];
+            await reportProgress(i, totalEligible);
             const date = wiseDate(row.finishedOn || row.createdOn);
             const type = "C"; // e-arveldaja uses type C for all bank transactions
             const amount = row.sourceAmount;

package/package.json

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