@kirjapro/mcp-server 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -1,6 +1,62 @@
 # Changelog
 
-## [0.10.0] - Unreleased
+## [0.11.0] - Unreleased
+
+Requires the database migrations `20261002070106`–`20261002071619` (ALV report
+audit batch 2), in particular `book_purchase_with_vat`, and
+`20261002120000`–`20261002120001` (batch 3, the OmaVero field map); release it
+only after `db:deploy`. Version 0.10.0 keeps working against that database: its
+standard purchases book plain vouchers without a VAT fact (listed by the ALV
+reconciliation), the database applies the new sales-account rule, and its ALV
+summary passes the new `omavero` key through. Against a database without the
+batch 3 map, 0.11.0 derives the same fields from the older keys.
+
+- `kirjapro_book_purchase`: for a VAT-registered company a purchase with a rate
+  above 0 is booked with `book_purchase_with_vat`, which writes the voucher and
+  its VAT fact together, so the VAT reaches field 307. `reverseCharge` works
+  again with the new `reverseChargeCategory` (`eu_goods`, `eu_services`,
+  `non_eu_services`, `import`, `construction`, `scrap_metal`) and a Finnish
+  rate. A company that is not VAT-registered is refused a rate above 0 or a
+  reverse charge and books the purchase gross with `vatRate` `0`; the refusal
+  says that the VAT on a service from a foreign seller is still owed and goes
+  on a non-deductible Ostojen ALV row in the web app and on a voucher D expense
+  / K 4210 (Customs collects such a company's import VAT). New optional
+  `supplierName`; the result adds `vat_entry_ids`. The database refuses (P0001)
+  a deduction on law-based non-deductible accounts, a foreign rate and VAT rows
+  that do not match the 2320/4210 lines.
+- `kirjapro_create_from_template`: a purchase template that still debits 2320
+  books its domestic VAT fact through `book_purchase_with_vat`; for a company
+  that is not VAT-registered it is refused. `kirjapro_create_from_template_batch`
+  refuses purchase templates with VAT before any write (the atomic batch cannot
+  write VAT facts). `kirjapro_list_templates` hides `purchase_expense` and
+  `service_expense` from a company that is not VAT-registered.
+- `kirjapro_create_transaction(s_batch)` and the server instructions describe
+  the net sales-account rule (U-3): a net credit on 5000-5499, a sales line
+  with a 4210 or 2320 line and a net 4210 credit are refused; a transfer out of
+  a sales account without a VAT line, such as a fixed-asset disposal, is
+  allowed. They also say that a free 2320 line does not reach field 307.
+- `kirjapro_get_alv_summary` documents `output_vat_non_eu_services`, the VAT on
+  services bought from outside the EU that fields 301-303 now include.
+- `kirjapro_get_alv_summary` returns every official OmaVero field in
+  `omavero_fields` (VSRALVKV v1.10: 301-314 and 318-320) from the database's
+  `omavero` map: 307 is the total deductible VAT including reverse charge and
+  import VAT, 308 = 301+302+303+304+305+306+318 - 307, 309 excludes EU sales,
+  and 311 follows AVL 138 a §. The legacy keys `field_307`…`field_313` (and
+  their `_base` keys), `field_318`-`field_320`, `total_zero_rated` and
+  `reverse_charge_base` are no longer returned: `field_307` was only the
+  domestic deductible VAT and the others were purchase categories, not field
+  numbers. New `exempt_sales_base` (sales without a deduction right, in no
+  field); unclassified legacy reverse-charge invoice lines add a `warning`.
+- `kirjapro://compliance/*`: field 309 excludes EU sales (311, 312) and exempt
+  sales; cash-basis VAT needs no OmaVero opt-in and leaves EU and import items
+  on the accrual basis; a correction within 45 days carries no late-filing fee
+  regardless of the amount; the reverse-charge field list names 301-303 for
+  non-EU services, 304/310 for imports and the base fields.
+- Review the fingerprints of `kirjapro_book_purchase`,
+  `kirjapro_create_from_template(_batch)`, `kirjapro_list_templates`,
+  `kirjapro_create_transaction(s_batch)` and `kirjapro_get_alv_summary`.
+
+## [0.10.0] - 2026-10-02
 
 Requires the database migrations `20261001204555`–`20261001204559` (ALV report
 audit batch 1). Version 0.9.1 keeps working against that database: its sales

package/dist/index.js

@@ -35679,7 +35679,7 @@ var StdioServerTransport = class {
 import { createClient } from "@supabase/supabase-js";
 
 // src/version.ts
-var VERSION = "0.10.0";
+var VERSION = "0.11.0";
 
 // src/auth.ts
 var SUPABASE_PROJECT_URL = "https://tifewzsimmyoiepblhld.supabase.co";
@@ -36882,7 +36882,7 @@ function registerTransactionTools(server2) {
   server2.registerTool(
     "kirjapro_create_transaction",
     {
-      description: "Create a transaction (tosite) with journal entries. Entries must balance (debits = credits). Accepts account numbers resolved to UUIDs server-side. Prefer kirjapro_create_from_template for standard patterns. For a VAT-registered (ALV) company the database refuses lines on sales accounts 5000-5499 and a net 4210 credit: sales are invoices.",
+      description: "Create a transaction (tosite) with journal entries. Entries must balance (debits = credits). Accepts account numbers resolved to UUIDs server-side. Prefer kirjapro_create_from_template for standard patterns. For a VAT-registered (ALV) company the database refuses a net credit on sales accounts 5000-5499, a sales-account line together with a 4210 or 2320 line, and a net 4210 credit: sales are invoices. Moving an amount out of a sales account without a VAT line (e.g. a fixed-asset disposal D 5010 / K 1600) is allowed. A purchase with deductible VAT belongs in kirjapro_book_purchase so the VAT reaches field 307; a free 2320 line is listed by the ALV reconciliation.",
       inputSchema: {
         fiscalYearId: external_exports.string().uuid().optional().describe("Fiscal year UUID (auto-resolved if omitted)"),
         transactionDate: ISO_DATE_SCHEMA.describe("Transaction date (YYYY-MM-DD)"),
@@ -37021,7 +37021,7 @@ function registerTransactionTools(server2) {
   server2.registerTool(
     "kirjapro_create_transactions_batch",
     {
-      description: "Preview or atomically create multiple transactions in one call (up to 50). dryRun defaults to true. Commit is always all-or-nothing; partial/best-effort writes are intentionally unavailable. For a VAT-registered (ALV) company the database refuses lines on sales accounts 5000-5499 and a net 4210 credit: sales are invoices.",
+      description: "Preview or atomically create multiple transactions in one call (up to 50). dryRun defaults to true. Commit is always all-or-nothing; partial/best-effort writes are intentionally unavailable. For a VAT-registered (ALV) company the database refuses a net credit on sales accounts 5000-5499, a sales-account line together with a 4210 or 2320 line, and a net 4210 credit: sales are invoices. Moving an amount out of a sales account without a VAT line (e.g. a fixed-asset disposal D 5010 / K 1600) is allowed. A purchase with deductible VAT belongs in kirjapro_book_purchase so the VAT reaches field 307; a free 2320 line is listed by the ALV reconciliation.",
       inputSchema: {
         fiscalYearId: external_exports.string().uuid().optional().describe("Fiscal year UUID (auto-resolved if omitted)"),
         dryRun: external_exports.boolean().default(true).describe(
@@ -38439,6 +38439,83 @@ function registerCustomerTools(server2) {
   );
 }
 
+// src/compliance/omavero-fields.ts
+var OMAVERO_FIELD_NUMBERS = [
+  "301",
+  "302",
+  "303",
+  "304",
+  "305",
+  "306",
+  "307",
+  "308",
+  "309",
+  "310",
+  "311",
+  "312",
+  "313",
+  "314",
+  "318",
+  "319",
+  "320"
+];
+var LEGACY_ALV_SUMMARY_KEYS = [
+  "field_307",
+  "field_307_base",
+  "field_308",
+  "field_308_base",
+  "field_309",
+  "field_309_base",
+  "field_310",
+  "field_310_base",
+  "field_312",
+  "field_312_base",
+  "field_313",
+  "field_313_base",
+  "field_318",
+  "field_319",
+  "field_320",
+  "total_zero_rated",
+  "reverse_charge_base",
+  "omavero"
+];
+function cents(value) {
+  return Math.round(value * 100) / 100;
+}
+function num(value) {
+  const n = typeof value === "number" ? value : Number(value ?? 0);
+  return Number.isFinite(n) ? n : 0;
+}
+function omaveroFieldsFromSummary(s) {
+  const fields = {
+    "301": num(s.field_301),
+    "302": num(s.field_302),
+    "303": num(s.field_303),
+    "304": num(s.output_vat_import),
+    "305": num(s.output_vat_eu_goods),
+    "306": num(s.output_vat_eu_services),
+    "307": num(s.total_input_vat),
+    "308": num(s.net_vat_payable),
+    "309": num(s.zero_vat_turnover),
+    "310": num(s.field_312_base),
+    "311": num(s.eu_goods_sales_base),
+    "312": num(s.eu_service_sales_base),
+    "313": num(s.field_308_base),
+    "314": num(s.field_309_base),
+    "318": num(s.output_vat_construction_scrap),
+    "319": num(s.reverse_charge_sales_base),
+    "320": cents(num(s.field_310_base) + num(s.field_313_base))
+  };
+  const map2 = s.omavero;
+  if (map2 && typeof map2 === "object") {
+    const values = map2;
+    for (const field of OMAVERO_FIELD_NUMBERS) {
+      if (values[field] !== void 0 && values[field] !== null) fields[field] = num(values[field]);
+    }
+  }
+  return fields;
+}
+
 // src/lib/incomeStatementSynthesis.ts
 function synthesizeIncomeStatementLines(lineTypes, currentByLine, previousByLine) {
   const lineAmounts = new Map(currentByLine);
@@ -38593,18 +38670,28 @@ var ALV_SUMMARY_OUTPUT_SHAPE = {
   input_vat: external_exports.unknown().optional(),
   net_vat_payable: external_exports.number().optional(),
   net_vat_payable_formatted: external_exports.string().optional(),
-  omavero_fields: external_exports.record(external_exports.string(), external_exports.number()).optional(),
+  // Every official OmaVero field (VSRALVKV v1.10: 301-314, 318-320), ALV
+  // report audit 2026-10-01, T2-11. The only field-numbered output.
+  omavero_fields: external_exports.record(external_exports.string(), external_exports.number()).describe(
+    "Official OmaVero VAT-return fields 301-314 and 318-320. 307 is all deductible VAT; 308 = 301+302+303+304+305+306+318 - 307."
+  ).optional(),
+  // Sales without a deduction right: in no OmaVero field (informational).
+  exempt_sales_base: external_exports.number().optional(),
   zero_vat_turnover: external_exports.number().optional(),
   eu_goods_sales_base: external_exports.number().optional(),
   reverse_charge_sales_base: external_exports.number().optional(),
   eu_service_sales_base: external_exports.number().optional(),
   unclassified_legacy_reverse_charge_base: external_exports.number().optional(),
+  // VAT on services bought from outside the EU, already inside field_301-303
+  // and total_output_vat (ALV report audit 2026-10-01, T2-13).
+  output_vat_non_eu_services: external_exports.number().optional(),
   // get_alv_summary.reconciliation: the report against the 4210/2320 ledger
   // (ALV report audit 2026-10-01, T2-1). Absent on an older database.
   reconciliation: external_exports.object({ status: external_exports.enum(["match", "explained", "mismatch"]) }).passthrough().optional(),
   warning: external_exports.string().optional(),
   message: external_exports.string().optional()
 };
+var LEGACY_REVERSE_CHARGE_WARNING = "Legacy reverse-charge invoice lines must be reclassified before the fields are complete.";
 function alvReconciliationWarning(reconciliation) {
   if (!reconciliation || typeof reconciliation !== "object") return void 0;
   const r = reconciliation;
@@ -39087,7 +39174,7 @@ function registerReportTools(server2) {
   server2.registerTool(
     "kirjapro_get_alv_summary",
     {
-      description: "Get VAT (ALV) summary for a date range. Returns output/input VAT breakdown by rate and OmaVero field codes (301-320), and a reconciliation object comparing the 4210/2320 ledger with the report (status match, explained or mismatch, with the differences and the vouchers, invoices, fact mismatches and manual rows that explain them). A mismatch sets warning. For filing deadlines, read kirjapro://compliance/deadlines.",
+      description: "Get the VAT (ALV) summary for a date range. Returns `omavero_fields`, every official OmaVero VAT-return field (VSRALVKV v1.10: 301-314, 318-320). 307 is the total deductible VAT including reverse charge and import VAT; 308 = (301+302+303+304+305+306+318) - 307. 309 excludes 311/312 sales; exempt sales without a deduction right (`exempt_sales_base`) belong in no field. 311 follows AVL 138 a \xA7 (the delivery month when invoiced on or after the delivery in that month; otherwise, including an advance invoice, the next month). Fields 301-303 include the self-assessed VAT on services bought from outside the EU (output_vat_non_eu_services). Copy fields only from `omavero_fields`. Also returns a reconciliation object comparing the 4210/2320 ledger with the report (status match, explained or mismatch, with the differences and the vouchers, invoices, fact mismatches and manual rows that explain them); a mismatch or unclassified legacy reverse-charge lines set warning. For filing deadlines, read kirjapro://compliance/deadlines.",
       inputSchema: {
         dateFrom: ISO_DATE_SCHEMA.describe("Period start date (YYYY-MM-DD)"),
         dateTo: ISO_DATE_SCHEMA.describe("Period end date (YYYY-MM-DD)")
@@ -39127,26 +39214,21 @@ function registerReportTools(server2) {
         });
       }
       const raw = result;
-      const {
-        field_318: _legacyField318,
-        field_319: _legacyField319,
-        field_320: _legacyField320,
-        ...safeResult
-      } = raw;
-      const warning = alvReconciliationWarning(raw.reconciliation);
+      const omaveroFields = omaveroFieldsFromSummary(raw);
+      const legacyKeys = new Set(LEGACY_ALV_SUMMARY_KEYS);
+      const safeResult = Object.fromEntries(
+        Object.entries(raw).filter(([key]) => !legacyKeys.has(key))
+      );
+      const warnings = [
+        alvReconciliationWarning(raw.reconciliation),
+        Number(raw.unclassified_legacy_reverse_charge_base) ? LEGACY_REVERSE_CHARGE_WARNING : void 0
+      ].filter((text) => Boolean(text));
       return toResult({
         ...safeResult,
-        ...warning && { warning },
+        ...warnings.length > 0 && { warning: warnings.join(" ") },
         period: { from: params.dateFrom, to: params.dateTo },
         net_vat_payable_formatted: formatCurrency(result.net_vat_payable || 0),
-        omavero_fields: {
-          "309": Number(raw.zero_vat_turnover) || 0,
-          "311": Number(raw.eu_goods_sales_base) || 0,
-          "312": Number(raw.eu_service_sales_base) || 0,
-          "318": Number(raw.output_vat_construction_scrap) || 0,
-          "319": Number(raw.reverse_charge_sales_base) || 0,
-          "320": (Number(raw.field_310_base) || 0) + (Number(raw.field_313_base) || 0)
-        }
+        omavero_fields: omaveroFields
       });
     }
   );
@@ -39760,7 +39842,21 @@ var ACCOUNTS = {
 
 // src/compliance/vat-guard.ts
 var ALV_REGISTERED_SALE_REFUSAL = "This company is VAT-registered (ALV). A sale booked as a journal voucher never reaches the ALV report (fields 301-303 and 309), so Kirjapro refuses it. Create the sale with kirjapro_create_invoice, deliver it with kirjapro_send_invoice and record the payment with kirjapro_record_payment or bank matching.";
-var ALV_REGISTERED_REVERSE_CHARGE_REFUSAL = "Reverse-charge purchases must be booked as a received invoice in the Kirjapro web app or as a manual Ostojen ALV row so fields 305/306/313/314 are filled. MCP support follows in a later release.";
+var NOT_VAT_REGISTERED_PURCHASE_REFUSAL = 'This company is not VAT-registered (ALV), so it deducts no VAT on purchases: book the purchase gross with vatRate "0". A service bought from a foreign seller (in another EU country or outside the EU) still makes the company liable for the self-assessed VAT: tell the user to add it as a non-deductible row on the Ostojen ALV page of the Kirjapro web app, to book the same VAT as a voucher debiting the expense account and crediting 4210 (ALV-velka), for example with kirjapro_create_transaction, and to check whether the company must register for VAT. Customs (Tulli) collects the import VAT of such a company. If the company is VAT-registered, update its settings in the Kirjapro web app first.';
+var REVERSE_CHARGE_CATEGORIES = [
+  "eu_goods",
+  "eu_services",
+  "non_eu_services",
+  "import",
+  "construction",
+  "scrap_metal"
+];
+var REVERSE_CHARGE_CATEGORY_REQUIRED = "reverseChargeCategory is required: eu_goods (fields 305/313), eu_services (306/314), non_eu_services (301-303), import (304/310), construction or scrap_metal (318/320).";
+var REVERSE_CHARGE_RATE_REQUIRED = "A reverse-charge purchase needs the Finnish rate the buyer self-assesses (25.5, 13.5 or 10).";
+var PURCHASE_TEMPLATE_NOT_VAT_REGISTERED_REFUSAL = 'This company is not VAT-registered (ALV), so a purchase template with VAT (2320) cannot be used. Book the purchase gross with kirjapro_book_purchase and vatRate "0".';
+function purchaseTemplateBatchRefusal(indexes) {
+  return `Purchase templates with VAT (index ${indexes.join(", ")}) are booked one at a time with kirjapro_create_from_template or kirjapro_book_purchase so the VAT reaches the ALV report; nothing was written.`;
+}
 var NOT_VAT_REGISTERED_SETTLEMENT_REFUSAL = "This company is not VAT-registered (ALV), so it has no VAT settlement to book.";
 async function readCompanyVat(supabase2, companyId2) {
   const { data, error: error61 } = await supabase2.from("companies").select("alv_registered, vat_period").eq("id", companyId2).single();
@@ -40034,8 +40130,17 @@ var TEMPLATE_MAP = new Map(TEMPLATES.map((t) => [t.id, t]));
 function isSaleTemplate(templateId) {
   return TEMPLATE_MAP.get(templateId)?.kind === "sale";
 }
+function inputVatOf(entries) {
+  return roundCents(
+    entries.filter((e) => e.accountNumber === ACCOUNTS.ALV_SAAMISET).reduce((sum, e) => sum + e.debitAmount - e.creditAmount, 0)
+  );
+}
+function isVatPurchaseTemplate(templateId) {
+  const template = TEMPLATE_MAP.get(templateId);
+  return template?.kind === "purchase" && inputVatOf(template.expand(100)) !== 0;
+}
 function availableTemplates(alvRegistered) {
-  return alvRegistered ? TEMPLATES.filter((t) => t.kind !== "sale") : TEMPLATES;
+  return alvRegistered ? TEMPLATES.filter((t) => t.kind !== "sale") : TEMPLATES.filter((t) => !isVatPurchaseTemplate(t.id));
 }
 function expandTemplate(templateId, amount, opts) {
   const template = TEMPLATE_MAP.get(templateId);
@@ -40099,7 +40204,7 @@ function toJournalEntries(entries, accountMap) {
     credit_amount: e.creditAmount
   }));
 }
-async function resolveAndCreate(params) {
+async function preparePosting(params) {
   const supabase2 = getSupabase();
   const companyId2 = getCompanyId();
   let fiscalYearId = params.fiscalYearId;
@@ -40128,16 +40233,41 @@ async function resolveAndCreate(params) {
       `Template produced unbalanced entries: debits ${totalDebit.toFixed(2)} != credits ${totalCredit.toFixed(2)}.`
     );
   }
-  const journalEntries = toJournalEntries(params.entries, accountResult);
-  const { data: transactionId, error: txError } = await supabase2.rpc(
+  return { fiscalYearId, journalEntries: toJournalEntries(params.entries, accountResult) };
+}
+async function resolveAndCreatePurchase(params) {
+  const prepared = await preparePosting(params);
+  if ("isError" in prepared) return prepared;
+  const { data, error: error61 } = await getSupabase().rpc("book_purchase_with_vat", {
+    p_company_id: getCompanyId(),
+    p_fiscal_year_id: prepared.fiscalYearId,
+    p_transaction_date: params.transactionDate,
+    p_description: params.description,
+    p_document_number: params.documentNumber || "",
+    p_entries: prepared.journalEntries,
+    p_vat_rows: params.vatRows,
+    ...params.supplierName ? { p_supplier_name: params.supplierName } : {}
+  });
+  const result = data;
+  if (error61 || !result?.transaction_id) {
+    return toErrorContent(
+      error61 ? sanitizeDbError("Failed to book the purchase", error61) : "Failed to book the purchase: no ID returned."
+    );
+  }
+  return { id: result.transaction_id, vatEntryIds: result.vat_entry_ids ?? [] };
+}
+async function resolveAndCreate(params) {
+  const prepared = await preparePosting(params);
+  if ("isError" in prepared) return prepared;
+  const { data: transactionId, error: txError } = await getSupabase().rpc(
     "create_transaction_with_entries",
     {
-      p_company_id: companyId2,
-      p_fiscal_year_id: fiscalYearId,
+      p_company_id: getCompanyId(),
+      p_fiscal_year_id: prepared.fiscalYearId,
       p_transaction_date: params.transactionDate,
       p_description: params.description,
       p_document_number: params.documentNumber || "",
-      p_entries: journalEntries
+      p_entries: prepared.journalEntries
     }
   );
   if (txError || !transactionId) {
@@ -40151,7 +40281,7 @@ function registerTemplateTools(server2) {
   server2.registerTool(
     "kirjapro_list_templates",
     {
-      description: "List available transaction templates. Templates handle double-entry balancing and VAT splitting automatically. Sale templates are not listed for a VAT-registered (ALV) company: its sales are invoices.",
+      description: "List available transaction templates. Templates handle double-entry balancing and VAT splitting automatically. Sale templates are not listed for a VAT-registered (ALV) company: its sales are invoices. Purchase templates with VAT are not listed for a company that is not VAT-registered.",
       inputSchema: {},
       outputSchema: {
         templates: external_exports.array(external_exports.object({
@@ -40176,7 +40306,7 @@ function registerTemplateTools(server2) {
   server2.registerTool(
     "kirjapro_create_from_template",
     {
-      description: 'Create a transaction from a template. Use kirjapro_list_templates for available templates. accountOverrides swaps default accounts (e.g. {"2320": "2330"}). Sale templates are refused for a VAT-registered (ALV) company: create an invoice instead.',
+      description: 'Create a transaction from a template. Use kirjapro_list_templates for available templates. accountOverrides swaps default accounts (e.g. {"2320": "2330"}). Sale templates are refused for a VAT-registered (ALV) company: create an invoice instead. A purchase template with VAT (2320) books its VAT fact so the VAT reaches field 307; for a company that is not VAT-registered it is refused (book the purchase gross).',
       inputSchema: {
         template: external_exports.string().describe('Template ID (e.g. "cash_sale_25", "purchase_expense")'),
         fiscalYearId: external_exports.string().uuid().optional().describe("Fiscal year UUID (auto-resolved if omitted)"),
@@ -40192,10 +40322,15 @@ function registerTemplateTools(server2) {
     async (params) => {
       const supabase2 = getSupabase();
       const companyId2 = getCompanyId();
-      if (isSaleTemplate(params.template)) {
+      const template = TEMPLATE_MAP.get(params.template);
+      let alvRegistered = null;
+      if (template && (template.kind === "sale" || template.kind === "purchase")) {
         const companyVat = await readCompanyVat(supabase2, companyId2);
         if ("isError" in companyVat) return companyVat;
-        if (companyVat.alvRegistered) return toErrorContent(ALV_REGISTERED_SALE_REFUSAL);
+        alvRegistered = companyVat.alvRegistered;
+        if (template.kind === "sale" && alvRegistered) {
+          return toErrorContent(ALV_REGISTERED_SALE_REFUSAL);
+        }
       }
       return withIdempotency(
         supabase2,
@@ -40214,7 +40349,27 @@ function registerTemplateTools(server2) {
           if ("error" in result) {
             return toErrorContent(result.error);
           }
-          const createResult = await resolveAndCreate({
+          const inputVat = template?.kind === "purchase" ? inputVatOf(result.entries) : 0;
+          if (inputVat !== 0 && alvRegistered === false) {
+            return toErrorContent(PURCHASE_TEMPLATE_NOT_VAT_REGISTERED_REFUSAL);
+          }
+          const createResult = inputVat !== 0 ? await resolveAndCreatePurchase({
+            fiscalYearId: params.fiscalYearId,
+            transactionDate: params.transactionDate,
+            description: params.description,
+            documentNumber: params.documentNumber,
+            entries: result.entries,
+            vatRows: [
+              {
+                category: "domestic",
+                vat_rate: template?.vatRate ?? 0,
+                tax_base: roundCents(
+                  result.entries.filter((e) => e.accountNumber !== ACCOUNTS.ALV_SAAMISET).reduce((sum, e) => sum + e.debitAmount, 0)
+                ),
+                vat_amount: inputVat
+              }
+            ]
+          }) : await resolveAndCreate({
             fiscalYearId: params.fiscalYearId,
             transactionDate: params.transactionDate,
             description: params.description,
@@ -40228,7 +40383,8 @@ function registerTemplateTools(server2) {
             message: "Transaction created from template",
             template: params.template,
             transaction_id: createResult.id,
-            entries: result.entries
+            entries: result.entries,
+            ..."vatEntryIds" in createResult && { vat_entry_ids: createResult.vatEntryIds }
           });
         }
       );
@@ -40237,7 +40393,7 @@ function registerTemplateTools(server2) {
   server2.registerTool(
     "kirjapro_create_from_template_batch",
     {
-      description: "Preview or atomically create multiple template transactions in one call (up to 50). dryRun defaults to true. Commit is always all-or-nothing; partial/best-effort writes are intentionally unavailable. A batch with a sale template is refused for a VAT-registered (ALV) company before any write.",
+      description: "Preview or atomically create multiple template transactions in one call (up to 50). dryRun defaults to true. Commit is always all-or-nothing; partial/best-effort writes are intentionally unavailable. A batch with a sale template is refused for a VAT-registered (ALV) company before any write. Purchase templates with VAT (2320) are refused in a batch: book them one at a time with kirjapro_create_from_template so the VAT reaches the ALV report.",
       inputSchema: {
         fiscalYearId: external_exports.string().uuid().optional().describe("Fiscal year UUID (auto-resolved if omitted)"),
         dryRun: external_exports.boolean().default(true).describe(
@@ -40260,6 +40416,17 @@ function registerTemplateTools(server2) {
     async (params) => {
       const supabase2 = getSupabase();
       const companyId2 = getCompanyId();
+      const vatPurchaseIndexes = params.transactions.map((tx, index) => {
+        const template = TEMPLATE_MAP.get(tx.template);
+        if (template?.kind !== "purchase") return -1;
+        const expanded = expandTemplate(tx.template, tx.amount, {
+          accountOverrides: tx.accountOverrides
+        });
+        return "entries" in expanded && inputVatOf(expanded.entries) !== 0 ? index : -1;
+      }).filter((index) => index >= 0);
+      if (vatPurchaseIndexes.length > 0) {
+        return toErrorContent(purchaseTemplateBatchRefusal(vatPurchaseIndexes));
+      }
       const saleIndexes = params.transactions.map((tx, index) => isSaleTemplate(tx.template) ? index : -1).filter((index) => index >= 0);
       if (saleIndexes.length > 0) {
         const companyVat = await readCompanyVat(supabase2, companyId2);
@@ -40548,7 +40715,7 @@ function registerBookingTools(server2) {
   server2.registerTool(
     "kirjapro_book_purchase",
     {
-      description: "Book a purchase (osto) with automatic VAT splitting. Supports reverse charge (AVL 9\xA7) for companies that are not VAT-registered and entertainment (edustus, AVL 114\xA7). For a VAT-registered (ALV) company reverseCharge is refused: book it as a received invoice in the web app. Rate rules: food/restaurants 13.5%, insurance 0% (exempt), alcohol 25.5%.",
+      description: "Book a purchase (osto) with automatic VAT splitting. For a VAT-registered (ALV) company the VAT is recorded as a VAT fact, so it reaches field 307 (and the reverse-charge fields). Reverse charge (reverseCharge=true, with reverseChargeCategory) self-assesses the VAT for EU goods and services, services from outside the EU, import, construction and scrap metal. Entertainment (edustus, AVL 114\xA7) is booked gross. Statutorily non-deductible accounts (wages, insurance, interest, depreciation, taxes, representation) are refused with VAT: book them with vatRate 0. A company that is not VAT-registered books purchases gross with vatRate 0. Rate rules: food/restaurants 13.5%, insurance 0% (exempt), alcohol 25.5%.",
       inputSchema: {
         amount: external_exports.number().finite().positive().max(1e9).describe(
           "EUR amount. Standard purchase: GROSS (VAT-inclusive) \u2014 VAT is split out of this. Reverse charge (reverseCharge=true): NET foreign-invoice amount \u2014 the foreign supplier does not charge Finnish VAT, so the parameter must be net. VAT is self-assessed on top per AVL 9\xA7 producing equal debit to ALV-saamiset and credit to ALV-velka. Entertainment (edustus=true): GROSS (full amount to expense, no VAT deduction per AVL 114\xA7)."
@@ -40557,7 +40724,11 @@ function registerBookingTools(server2) {
         date: ISO_DATE_SCHEMA.describe("Transaction date (YYYY-MM-DD)"),
         vatRate: external_exports.enum(["25.5", "13.5", "10", "0"]).describe("Finnish VAT rate"),
         expenseAccount: external_exports.string().describe('Expense account number (e.g. "8080")'),
-        reverseCharge: external_exports.boolean().default(false).describe(`EU reverse charge: D expense + D ${ACCOUNTS.ALV_SAAMISET} ALV-saamiset + C ${ACCOUNTS.ALV_VELKA} ALV-velka + C bank`),
+        reverseCharge: external_exports.boolean().default(false).describe(`Reverse charge (k\xE4\xE4nnetty verovelvollisuus): D expense + D ${ACCOUNTS.ALV_SAAMISET} ALV-saamiset + C ${ACCOUNTS.ALV_VELKA} ALV-velka + C bank, with a VAT fact of reverseChargeCategory`),
+        reverseChargeCategory: external_exports.enum(REVERSE_CHARGE_CATEGORIES).optional().describe(
+          "Required with reverseCharge: eu_goods (fields 305/313), eu_services (306/314), non_eu_services (services from outside the EU, 301-303), import (304/310), construction or scrap_metal (318/320)"
+        ),
+        supplierName: external_exports.string().max(200).optional().describe("Supplier name, stored on the VAT fact"),
         edustus: external_exports.boolean().default(false).describe("Entertainment expense (AVL 114\xA7): 0% VAT deduction, full gross to expense"),
         paymentAccount: external_exports.string().default(ACCOUNTS.PANKKITILI).describe(`Payment account (default "${ACCOUNTS.PANKKITILI}" Pankkitili)`),
         fiscalYearId: external_exports.string().uuid().optional().describe("Fiscal year UUID (auto-resolved if omitted)"),
@@ -40571,10 +40742,15 @@ function registerBookingTools(server2) {
       const rate = Number.parseFloat(params.vatRate);
       const gross = roundCents(params.amount);
       let entries;
+      let vatRows = [];
+      const companyVat = await readCompanyVat(getSupabase(), getCompanyId());
+      if ("isError" in companyVat) return companyVat;
+      if (!params.edustus && !companyVat.alvRegistered && (rate !== 0 || params.reverseCharge)) {
+        return toErrorContent(NOT_VAT_REGISTERED_PURCHASE_REFUSAL);
+      }
       if (params.reverseCharge && !params.edustus) {
-        const vat = await readCompanyVat(getSupabase(), getCompanyId());
-        if ("isError" in vat) return vat;
-        if (vat.alvRegistered) return toErrorContent(ALV_REGISTERED_REVERSE_CHARGE_REFUSAL);
+        if (!params.reverseChargeCategory) return toErrorContent(REVERSE_CHARGE_CATEGORY_REQUIRED);
+        if (rate === 0) return toErrorContent(REVERSE_CHARGE_RATE_REQUIRED);
       }
       if (params.edustus) {
         entries = [
@@ -40591,6 +40767,14 @@ function registerBookingTools(server2) {
           // ALV-velka (output)
           { accountNumber: params.paymentAccount, debitAmount: 0, creditAmount: gross }
         ];
+        vatRows = [
+          {
+            category: params.reverseChargeCategory ?? "eu_services",
+            vat_rate: rate,
+            tax_base: gross,
+            vat_amount: vat
+          }
+        ];
       } else if (rate === 0) {
         entries = [
           { accountNumber: params.expenseAccount, debitAmount: gross, creditAmount: 0 },
@@ -40603,6 +40787,7 @@ function registerBookingTools(server2) {
           { accountNumber: ACCOUNTS.ALV_SAAMISET, debitAmount: vat, creditAmount: 0 },
           { accountNumber: params.paymentAccount, debitAmount: 0, creditAmount: gross }
         ];
+        vatRows = [{ category: "domestic", vat_rate: rate, tax_base: net, vat_amount: vat }];
       }
       const purchaseAccountWarning = expenseAccountWarning(params.expenseAccount);
       if (params.dryRun) {
@@ -40613,6 +40798,7 @@ function registerBookingTools(server2) {
           description: params.description,
           date: params.date,
           entries,
+          ...vatRows.length > 0 && { vat_rows: vatRows },
           ...purchaseAccountWarning && { account_warning: purchaseAccountWarning }
         });
       }
@@ -40623,18 +40809,24 @@ function registerBookingTools(server2) {
         params.idempotencyKey,
         params,
         async () => {
-          const result = await resolveAndCreate({
+          const posting = {
             fiscalYearId: params.fiscalYearId,
             transactionDate: params.date,
             description: params.description,
             documentNumber: params.documentNumber,
             entries
-          });
+          };
+          const result = vatRows.length > 0 ? await resolveAndCreatePurchase({
+            ...posting,
+            vatRows,
+            supplierName: params.supplierName
+          }) : await resolveAndCreate(posting);
           if ("isError" in result) return result;
           return toResult({
             message: "Purchase booked",
             transaction_id: result.id,
             entries,
+            ..."vatEntryIds" in result && { vat_entry_ids: result.vatEntryIds },
             ...purchaseAccountWarning && { warning: purchaseAccountWarning }
           });
         }
@@ -42308,7 +42500,7 @@ var VAT_COMPLIANCE = {
     ],
     booking: "4 entries: D expense + D ALV-saamiset + C bank + C ALV-velka (k\xE4\xE4nnetty)",
     note: "Net VAT effect is zero but BOTH must be reported on ALV-ilmoitus. Invoice must NOT show VAT rate or VAT amount",
-    omavero_fields: "Foreign: 305 (EU goods), 306 (EU services). Domestic construction/scrap: 318 (VAT amount), 319/320 (tax bases)"
+    omavero_fields: "EU goods: 305 (VAT) / 313 (base); EU services: 306 / 314; services from outside the EU: VAT in 301-303 by rate (no base field); imports: 304 / 310; domestic construction/scrap purchases: 318 / 320, sales 319. The deductible part of each is in 307."
   },
   common_mistakes: [
     "Food/coffee at 25.5% \u2014 should be 13.5% (AVL 85\xA7)",
@@ -42387,14 +42579,18 @@ var FILING_DEADLINES = {
   },
   maksuperusteinen_alv: {
     threshold: 5e5,
-    note: "Revenue under 500,000 \u20AC: may opt for cash-basis VAT (report when payment received/made, not when invoiced)",
-    application: "Opt-in via OmaVero"
+    note: "Turnover up to 500,000 \u20AC per calendar year: domestic sales VAT may be reported when payment is received and purchase VAT deducted when paid (cash basis), consistently for all domestic sales and purchases; imports, exports, intra-EU sales and acquisitions and cross-border reverse-charge services stay on the accrual basis. Kirjapro reports on the accrual basis only.",
+    application: "No application: the business applies the cash basis in its bookkeeping. Since 2025 the VAT return has no cash-basis field.",
+    source: "https://www.vero.fi/yritykset-ja-yhteisot/verot-ja-maksut/arvonlisaverotus/pienyrityksen-maksuperusteinen-alv/",
+    sources_verified_at: "2026-10-02"
   },
   late_penalties: {
-    myohastymismaksu: "3 \u20AC/day for days 1-45 (max 135 \u20AC), then +2% of tax amount (max 15,000 \u20AC per tax type)",
+    myohastymismaksu: "3 \u20AC/day for at most 45 days (135 \u20AC); more than 45 days late: 135 \u20AC + 2 % of the declared payable tax (max 15,000 \u20AC per tax type and period); also for returns with no tax payable",
     viivastyskorko_2026: "9.5% for most taxes, 4.5% for inheritance tax",
-    correction_grace: "Corrections within 45 days of original deadline: no penalty if change \u2264 500 \u20AC",
-    nil_return: "Even when no VAT activity occurred, a nil return must be filed for each verokausi"
+    correction_grace: "A correction return filed within 45 days of the original due date carries no late-filing fee (no amount condition). Later corrections: 2 % of the additional payable tax.",
+    nil_return: "Even when no VAT activity occurred, a nil return must be filed for each verokausi",
+    source: "https://www.vero.fi/syventavat-vero-ohjeet/ohje-hakusivu/48377/seuraamusmaksut-oma-aloitteisessa-verotuksessa5/",
+    sources_verified_at: "2026-10-02"
   },
   payment_deadline: "Same as filing deadline (12th of M+2 for monthly/quarterly, last day of Feb for annual)",
   omavero_field_codes: {
@@ -42412,16 +42608,17 @@ var FILING_DEADLINES = {
       318: "Vero rakentamispalvelun ja metalliromun ostoista (construction/scrap reverse charge VAT)"
     },
     tax_bases: {
-      309: "0-verokannan alainen liikevaihto (zero-rate turnover: exports, EU sales with deduction right)",
+      309: "0-verokannan alainen liikevaihto (zero-rate turnover, e.g. exports of goods outside the EU, AVL 55-72 h \xA7). Does NOT include EU goods sales (311) or EU service sales (312). Exempt sales without a deduction right (healthcare, education, finance, insurance) are reported in no field.",
       310: "Tavaroiden maahantuonnit EU:n ulkopuolelta (goods imports from outside EU)",
-      311: "Tavaroiden myynnit muihin EU-maihin (goods sales to EU)",
+      311: "Tavaroiden myynnit muihin EU-maihin (goods sales to EU; reported for the delivery month when invoiced on or after the delivery in that month, otherwise, including an advance invoice, the next month, AVL 138 a \xA7)",
       312: "Palveluiden myynnit muihin EU-maihin (service sales to EU)",
       313: "Tavaraostot muista EU-maista (goods purchases from EU)",
       314: "Palveluostot muista EU-maista (service purchases from EU)",
       319: "Rakentamispalvelun ja metalliromun myynnit (construction/scrap sales)",
       320: "Rakentamispalvelun ja metalliromun ostot (construction/scrap purchases)"
     },
-    removed_2025: "315, 316, 317 (alarajahuojennus fields) removed from 1.1.2025"
+    removed_2025: "315, 316, 317 (alarajahuojennus fields) removed from 1.1.2025",
+    sources_verified_at: "2026-10-02"
   }
 };
 var SOCIAL_INSURANCE_2026 = {
@@ -42702,7 +42899,7 @@ Do not invent a "closest match" tool for these tasks. A confidently wrong action
 A bank transaction that is already booked (a receipt or purchase booked as paid from the bank account, a manual invoice payment, a paid purchase invoice, a Kirjapro payment batch) is linked, never posted again: \`kirjapro_list_bank_link_candidates\` \u2192 \`kirjapro_link_bank_transaction\`. Never post a manual voucher for an already-booked or skipped bank transaction; a wrong reconciliation is undone in the Kirjapro app (Pankki \u2192 T\xE4sm\xE4ytys \u2192 T\xE4sm\xE4ytetyt \u2192 Pura t\xE4sm\xE4ytys) or, on the full surface, with \`kirjapro_unreconcile_bank_transaction\`, and then matched again.
 
 ### Reports
-\`kirjapro_get_dashboard\` (overview) | \`kirjapro_get_income_statement\` (tuloslaskelma) | \`kirjapro_get_balance_sheet\` (tase \u2014 \`equity.synthetic_tilikauden_tulos\` is the unclosed P/L residual already included in equity; never add it again. The cumulative report groups current earnings under 3600 and retained earnings under 3500. Report rows can differ from raw ledger account balances. Do not present book equity as an approved distribution limit) | \`kirjapro_get_ar_aging\` (bounded myyntisaamisten aggregate; weighted age is not revenue-based DSO) | \`kirjapro_get_alv_summary\` (ALV-yhteenveto with OmaVero field codes 301-320).
+\`kirjapro_get_dashboard\` (overview) | \`kirjapro_get_income_statement\` (tuloslaskelma) | \`kirjapro_get_balance_sheet\` (tase \u2014 \`equity.synthetic_tilikauden_tulos\` is the unclosed P/L residual already included in equity; never add it again. The cumulative report groups current earnings under 3600 and retained earnings under 3500. Report rows can differ from raw ledger account balances. Do not present book equity as an approved distribution limit) | \`kirjapro_get_ar_aging\` (bounded myyntisaamisten aggregate; weighted age is not revenue-based DSO) | \`kirjapro_get_alv_summary\` (ALV-yhteenveto; the official OmaVero fields are in \`omavero_fields\`).
 
 ## Safety Rules
 
@@ -42768,7 +42965,7 @@ var INSTRUCTIONS_CORE_ADDENDUM = `
 The following workflows are NOT exposed in the current (core) surface. When a user asks for them, redirect to the web UI rather than reaching for the closest available tool:
 
 - **Recurring invoice templates** \u2014 created and managed in the web app; cron generates the issued invoices
-- **Booking shortcuts** (book_purchase / book_sale / book_vat_settlement) \u2014 for these, you CAN compose the journal entries manually via \`kirjapro_create_transaction\` with explicit debit/credit lines if the user prefers; otherwise redirect. Exception: a VAT-registered (ALV) company books sales only as invoices (\`kirjapro_create_invoice\` + \`kirjapro_send_invoice\`) and reverse-charge purchases in the web app; the database refuses its vouchers with sales accounts 5000-5499 or a net 4210 credit
+- **Booking shortcuts** (book_purchase / book_sale / book_vat_settlement) \u2014 for these, you CAN compose the journal entries manually via \`kirjapro_create_transaction\` with explicit debit/credit lines if the user prefers; otherwise redirect. Exception: a VAT-registered (ALV) company books sales only as invoices (\`kirjapro_create_invoice\` + \`kirjapro_send_invoice\`) and reverse-charge purchases and purchases with deductible VAT in the web app (a free 2320 line on a voucher has no VAT fact and does not reach field 307); the database refuses its vouchers with a net credit on sales accounts 5000-5499, a sales-account line together with a 4210 or 2320 line, or a net 4210 credit; moving an amount out of a sales account without a VAT line (e.g. a fixed-asset disposal D 5010 / K 1600) is allowed
 - **Payroll (palkanlaskenta)** \u2014 Kirjapro does NOT calculate or book payroll. Direct the user to Palkkaus.fi or Palkka.fi for the calculation, then bring the resulting payslip back and book it via \`kirjapro_create_transaction\` with explicit debit/credit lines
 - **Transaction templates** \u2014 manual journal entries via \`kirjapro_create_transaction\`
 - **Manual offer status changes** \u2014 the customer's email-link click sets status server-side; just wait for the user to confirm acceptance

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kirjapro/mcp-server",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "MCP server for Finnish accounting — exposes Kirjapro bookkeeping, invoicing, and reporting tools to Claude, ChatGPT, Mistral, and other MCP clients.",
   "type": "module",
   "bin": {

package/server.json

@@ -2,7 +2,7 @@
   "name": "@kirjapro/mcp-server",
   "displayName": "Kirjapro - Finnish Accounting",
   "description": "Finnish double-entry bookkeeping, invoicing, and financial reporting for growing businesses. Create transactions, generate invoices with VAT calculation, produce income statements and balance sheets, and validate Finnish business identifiers.",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "homepage": "https://kirjapro.fi",
   "repository": "https://github.com/Jaollo/kirja-pro",
   "license": "MIT",

package/tool-fingerprints.json

@@ -2,7 +2,7 @@
   "fingerprints": [
     {
       "name": "kirjapro_book_purchase",
-      "hash": "ec096990916f5112"
+      "hash": "e6c7bfe42eedc619"
     },
     {
       "name": "kirjapro_book_sale",
@@ -22,11 +22,11 @@
     },
     {
       "name": "kirjapro_create_from_template",
-      "hash": "9e774f4f25c6ce93"
+      "hash": "d410e01e95e20227"
     },
     {
       "name": "kirjapro_create_from_template_batch",
-      "hash": "415d1d219c81467f"
+      "hash": "ff8fa037077fac9a"
     },
     {
       "name": "kirjapro_create_invoice",
@@ -42,11 +42,11 @@
     },
     {
       "name": "kirjapro_create_transaction",
-      "hash": "bea9ccf179928813"
+      "hash": "8b6a32983de69413"
     },
     {
       "name": "kirjapro_create_transactions_batch",
-      "hash": "160de9628d56e6be"
+      "hash": "a3e71d41bbf437e4"
     },
     {
       "name": "kirjapro_delete_invoice",
@@ -66,7 +66,7 @@
     },
     {
       "name": "kirjapro_get_alv_summary",
-      "hash": "1c225c5d61c0839f"
+      "hash": "a149fdcb6307923a"
     },
     {
       "name": "kirjapro_get_ar_aging",
@@ -162,7 +162,7 @@
     },
     {
       "name": "kirjapro_list_templates",
-      "hash": "7601b5d1da0d7283"
+      "hash": "91c70a7143aa96ac"
     },
     {
       "name": "kirjapro_list_transactions",