@kirjapro/mcp-server 0.9.1 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## [0.10.0] - Unreleased
+
+Requires the database migrations `20261001204555`–`20261001204559` (ALV report
+audit batch 1). Version 0.9.1 keeps working against that database: its sales
+and reverse-charge vouchers of a VAT-registered company are refused by the
+database with the same guidance, and its settlement default date stays the
+old one.
+
+- `kirjapro_book_sale`, the sale templates (`cash_sale_*`, `bank_sale_*`,
+  `invoice_sale_25`) of `kirjapro_create_from_template(_batch)` and
+  `kirjapro_book_purchase` with `reverseCharge` are refused for a
+  VAT-registered (ALV) company before any write: a journal voucher never
+  reaches the ALV report. Sales are created with `kirjapro_create_invoice` and
+  delivered with `kirjapro_send_invoice`; reverse-charge purchases are booked
+  as received invoices in the web app for now. `kirjapro_list_templates` no
+  longer lists the sale templates for such a company. Other companies are
+  unchanged.
+- `kirjapro_create_transaction(s_batch)`: the database refuses lines on sales
+  accounts 5000-5499 and a net 4210 credit for a VAT-registered company; the
+  descriptions say so.
+- `kirjapro_book_vat_settlement` settles the company's VAT period (month,
+  quarter or year from `companies.vat_period`) containing `month`. The default
+  date is the statutory due date (12th of the second month after the period;
+  annual period: end of February), and the fiscal year defaults to the open
+  year containing that date, so a December settlement is booked in the next
+  year. The database now excludes earlier settlements, closing entries and the
+  previous-year import, refuses a settled period, a period whose ledger does
+  not match the ALV report and negative balances, and books only non-zero
+  lines. The result and the dry run name the period. A company that is not
+  VAT-registered is refused.
+- `kirjapro_get_alv_summary` returns `reconciliation`: the 4210/2320 ledger
+  against the report (status `match`, `explained` or `mismatch`, the
+  differences and the explaining vouchers, invoices, fact mismatches and
+  manual rows), and sets `warning` on a mismatch.
+- The server instructions (core and full surface) say that a VAT-registered
+  company books sales as invoices, that `kirjapro_create_transaction` cannot
+  replace `kirjapro_book_sale` for it, and that its sale templates are hidden.
+- Review the fingerprints of `kirjapro_book_sale`, `kirjapro_book_purchase`,
+  `kirjapro_book_vat_settlement`, `kirjapro_create_from_template`,
+  `kirjapro_create_from_template_batch`, `kirjapro_list_templates`,
+  `kirjapro_create_transaction`, `kirjapro_create_transactions_batch` and
+  `kirjapro_get_alv_summary` for their changed descriptions and schemas.
+
 ## [0.9.1] - 2026-09-29
 
 Requires the database migration `20260929120200` (bank reconciliation

package/dist/index.js

@@ -4148,13 +4148,14 @@ var require_fast_uri = __commonJS({
         if (!malformedIPLiteral) {
           malformedHost = canonicalizeHost(parsed, options, schemeHandler, isIP);
         }
-        if (!schemeHandler || schemeHandler && !schemeHandler.skipNormalize) {
-          if (uri.indexOf("%") !== -1) {
-            if (parsed.host !== void 0 && !malformedIPLiteral) {
-              const host = isIP ? parsed.host : normalizePercentEncoding(parsed.host, true);
-              parsed.host = reescapeHostDelimiters(host, isIP);
-            }
+        if (uri.indexOf("%") !== -1 && parsed.host !== void 0 && !malformedIPLiteral) {
+          let host = isIP ? parsed.host : normalizePercentEncoding(parsed.host, true);
+          if (!isIP) {
+            host = normalizePercentEncoding(host.toLowerCase());
           }
+          parsed.host = reescapeHostDelimiters(host, isIP);
+        }
+        if (!schemeHandler || schemeHandler && !schemeHandler.skipNormalize) {
           if (parsed.path) {
             parsed.path = normalizePathEncoding(parsed.path);
           }
@@ -35678,7 +35679,7 @@ var StdioServerTransport = class {
 import { createClient } from "@supabase/supabase-js";
 
 // src/version.ts
-var VERSION = "0.9.1";
+var VERSION = "0.10.0";
 
 // src/auth.ts
 var SUPABASE_PROJECT_URL = "https://tifewzsimmyoiepblhld.supabase.co";
@@ -36881,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.",
+      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.",
       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)"),
@@ -37020,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.",
+      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.",
       inputSchema: {
         fiscalYearId: external_exports.string().uuid().optional().describe("Fiscal year UUID (auto-resolved if omitted)"),
         dryRun: external_exports.boolean().default(true).describe(
@@ -38598,9 +38599,19 @@ var ALV_SUMMARY_OUTPUT_SHAPE = {
   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(),
+  // 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()
 };
+function alvReconciliationWarning(reconciliation) {
+  if (!reconciliation || typeof reconciliation !== "object") return void 0;
+  const r = reconciliation;
+  if (r.status !== "mismatch") return void 0;
+  const amount = (value) => (Number(value) || 0).toFixed(2);
+  return `Ledger accounts 4210/2320 differ from the ALV report (output VAT difference ${amount(r.output_difference)} \u20AC, input VAT difference ${amount(r.input_difference)} \u20AC). Review reconciliation before filing.`;
+}
 var BALANCE_SHEET_ROW_SHAPE = external_exports.object({
   account_number: external_exports.string(),
   name: external_exports.string(),
@@ -39076,7 +39087,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). For filing deadlines, read kirjapro://compliance/deadlines.",
+      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.",
       inputSchema: {
         dateFrom: ISO_DATE_SCHEMA.describe("Period start date (YYYY-MM-DD)"),
         dateTo: ISO_DATE_SCHEMA.describe("Period end date (YYYY-MM-DD)")
@@ -39122,8 +39133,10 @@ function registerReportTools(server2) {
         field_320: _legacyField320,
         ...safeResult
       } = raw;
+      const warning = alvReconciliationWarning(raw.reconciliation);
       return toResult({
         ...safeResult,
+        ...warning && { warning },
         period: { from: params.dateFrom, to: params.dateTo },
         net_vat_payable_formatted: formatCurrency(result.net_vat_payable || 0),
         omavero_fields: {
@@ -39745,6 +39758,21 @@ var ACCOUNTS = {
   VAKUUTUKSET: "7970"
 };
 
+// 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_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();
+  if (error61 || !data) {
+    return toErrorContent(
+      error61 ? sanitizeDbError("Failed to verify the company VAT registration", error61) : "Failed to verify the company VAT registration."
+    );
+  }
+  const row = data;
+  return { alvRegistered: row.alv_registered === true, vatPeriod: row.vat_period ?? "monthly" };
+}
+
 // src/tools/templates.ts
 function splitVat(gross, vatRate) {
   if (vatRate === 0) return { net: roundCents(gross), vat: 0 };
@@ -39844,24 +39872,28 @@ var TEMPLATES = [
   // Cash sales
   {
     id: "cash_sale_25",
+    kind: "sale",
     description: "K\xE4teismyynti ALV 25,5%",
     vatRate: 25.5,
     expand: saleCashTemplate(ACCOUNTS.MYYNTI_25_5, 25.5)
   },
   {
     id: "cash_sale_13_5",
+    kind: "sale",
     description: "K\xE4teismyynti ALV 13,5%",
     vatRate: 13.5,
     expand: saleCashTemplate(ACCOUNTS.MYYNTI_13_5, 13.5)
   },
   {
     id: "cash_sale_10",
+    kind: "sale",
     description: "K\xE4teismyynti ALV 10%",
     vatRate: 10,
     expand: saleCashTemplate(ACCOUNTS.MYYNTI_10, 10)
   },
   {
     id: "cash_sale_0",
+    kind: "sale",
     description: "K\xE4teismyynti ALV 0%",
     vatRate: 0,
     expand: saleCashTemplate(ACCOUNTS.MYYNTI_0, 0)
@@ -39869,18 +39901,21 @@ var TEMPLATES = [
   // Bank sales
   {
     id: "bank_sale_25",
+    kind: "sale",
     description: "Pankkimyynti ALV 25,5%",
     vatRate: 25.5,
     expand: saleBankTemplate(ACCOUNTS.MYYNTI_25_5, 25.5)
   },
   {
     id: "bank_sale_13_5",
+    kind: "sale",
     description: "Pankkimyynti ALV 13,5%",
     vatRate: 13.5,
     expand: saleBankTemplate(ACCOUNTS.MYYNTI_13_5, 13.5)
   },
   {
     id: "bank_sale_10",
+    kind: "sale",
     description: "Pankkimyynti ALV 10%",
     vatRate: 10,
     expand: saleBankTemplate(ACCOUNTS.MYYNTI_10, 10)
@@ -39888,6 +39923,7 @@ var TEMPLATES = [
   // Invoice sale
   {
     id: "invoice_sale_25",
+    kind: "sale",
     description: "Laskumyynti ALV 25,5% (myyntisaamiset)",
     vatRate: 25.5,
     expand: (amount, opts) => {
@@ -39909,6 +39945,7 @@ var TEMPLATES = [
   // Purchase expenses
   {
     id: "purchase_expense",
+    kind: "purchase",
     description: "Osto ALV 25,5% (pankkitililt\xE4)",
     vatRate: 25.5,
     expand: (amount, opts) => {
@@ -39929,6 +39966,7 @@ var TEMPLATES = [
   },
   {
     id: "service_expense",
+    kind: "purchase",
     description: "Ulkopuolinen palvelu ALV 25,5%",
     vatRate: 25.5,
     expand: (amount, opts) => {
@@ -39950,6 +39988,7 @@ var TEMPLATES = [
   // Rent (no VAT)
   {
     id: "rent_payment",
+    kind: "other",
     description: "Vuokranmaksu (pankkitililt\xE4)",
     vatRate: null,
     expand: (amount, opts) => applyOverrides(
@@ -39971,6 +40010,7 @@ var TEMPLATES = [
   // Bank transfer
   {
     id: "bank_transfer",
+    kind: "other",
     description: "Tilisiirto kassasta pankkitilille",
     vatRate: null,
     expand: (amount, opts) => applyOverrides(
@@ -39991,6 +40031,12 @@ var TEMPLATES = [
   }
 ];
 var TEMPLATE_MAP = new Map(TEMPLATES.map((t) => [t.id, t]));
+function isSaleTemplate(templateId) {
+  return TEMPLATE_MAP.get(templateId)?.kind === "sale";
+}
+function availableTemplates(alvRegistered) {
+  return alvRegistered ? TEMPLATES.filter((t) => t.kind !== "sale") : TEMPLATES;
+}
 function expandTemplate(templateId, amount, opts) {
   const template = TEMPLATE_MAP.get(templateId);
   if (!template) {
@@ -40105,7 +40151,7 @@ function registerTemplateTools(server2) {
   server2.registerTool(
     "kirjapro_list_templates",
     {
-      description: "List available transaction templates. Templates handle double-entry balancing and VAT splitting automatically.",
+      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.",
       inputSchema: {},
       outputSchema: {
         templates: external_exports.array(external_exports.object({
@@ -40117,7 +40163,9 @@ function registerTemplateTools(server2) {
       annotations: READ_ONLY_ANNOTATIONS
     },
     async () => {
-      const list = TEMPLATES.map((t) => ({
+      const companyVat = await readCompanyVat(getSupabase(), getCompanyId());
+      if ("isError" in companyVat) return companyVat;
+      const list = availableTemplates(companyVat.alvRegistered).map((t) => ({
         id: t.id,
         description: t.description,
         vatRate: t.vatRate
@@ -40128,7 +40176,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"}).',
+      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.',
       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)"),
@@ -40144,6 +40192,11 @@ function registerTemplateTools(server2) {
     async (params) => {
       const supabase2 = getSupabase();
       const companyId2 = getCompanyId();
+      if (isSaleTemplate(params.template)) {
+        const companyVat = await readCompanyVat(supabase2, companyId2);
+        if ("isError" in companyVat) return companyVat;
+        if (companyVat.alvRegistered) return toErrorContent(ALV_REGISTERED_SALE_REFUSAL);
+      }
       return withIdempotency(
         supabase2,
         companyId2,
@@ -40184,7 +40237,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.",
+      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.",
       inputSchema: {
         fiscalYearId: external_exports.string().uuid().optional().describe("Fiscal year UUID (auto-resolved if omitted)"),
         dryRun: external_exports.boolean().default(true).describe(
@@ -40207,6 +40260,16 @@ function registerTemplateTools(server2) {
     async (params) => {
       const supabase2 = getSupabase();
       const companyId2 = getCompanyId();
+      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);
+        if ("isError" in companyVat) return companyVat;
+        if (companyVat.alvRegistered) {
+          return toErrorContent(
+            `${ALV_REGISTERED_SALE_REFUSAL} Sale templates at index ${saleIndexes.join(", ")}; nothing was written.`
+          );
+        }
+      }
       return withIdempotency(
         supabase2,
         companyId2,
@@ -40430,6 +40493,35 @@ function freshnessMeta(rates = FINNISH_RATES_2026, today = /* @__PURE__ */ new D
   };
 }
 
+// src/compliance/vat-settlement-date.ts
+var pad = (value) => String(value).padStart(2, "0");
+function vatPeriodRange(month, vatPeriod) {
+  const [yearText, monthText] = month.split("-");
+  const year = Number(yearText);
+  const monthNumber = Number(monthText);
+  const period = vatPeriod ?? "monthly";
+  const startMonth = period === "yearly" ? 1 : period === "quarterly" ? Math.floor((monthNumber - 1) / 3) * 3 + 1 : monthNumber;
+  const endMonth = period === "yearly" ? 12 : period === "quarterly" ? startMonth + 2 : monthNumber;
+  const lastDay = new Date(Date.UTC(year, endMonth, 0)).getUTCDate();
+  const label = period === "yearly" ? String(year) : period === "quarterly" ? `${year}-Q${(startMonth + 2) / 3}` : month;
+  return {
+    start: `${year}-${pad(startMonth)}-01`,
+    end: `${year}-${pad(endMonth)}-${pad(lastDay)}`,
+    label
+  };
+}
+function defaultSettlementDate(month, vatPeriod) {
+  const { end } = vatPeriodRange(month, vatPeriod);
+  const [endYear, endMonth] = end.split("-").map(Number);
+  if ((vatPeriod ?? "monthly") === "yearly") {
+    const februaryDays = new Date(Date.UTC(endYear + 1, 2, 0)).getUTCDate();
+    return `${endYear + 1}-02-${pad(februaryDays)}`;
+  }
+  const dueMonthIndex = endMonth - 1 + 2;
+  const dueYear = endYear + Math.floor(dueMonthIndex / 12);
+  return `${dueYear}-${pad(dueMonthIndex % 12 + 1)}-12`;
+}
+
 // src/tools/bookings.ts
 function expenseAccountWarning(account) {
   const first = account.trim().charAt(0);
@@ -40456,7 +40548,7 @@ function registerBookingTools(server2) {
   server2.registerTool(
     "kirjapro_book_purchase",
     {
-      description: "Book a purchase (osto) with automatic VAT splitting. Supports reverse charge (AVL 9\xA7) and entertainment (edustus, AVL 114\xA7). Rate rules: food/restaurants 13.5%, insurance 0% (exempt), alcohol 25.5%.",
+      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%.",
       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)."
@@ -40479,6 +40571,11 @@ function registerBookingTools(server2) {
       const rate = Number.parseFloat(params.vatRate);
       const gross = roundCents(params.amount);
       let entries;
+      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.edustus) {
         entries = [
           { accountNumber: params.expenseAccount, debitAmount: gross, creditAmount: 0 },
@@ -40547,11 +40644,11 @@ function registerBookingTools(server2) {
   server2.registerTool(
     "kirjapro_book_vat_settlement",
     {
-      description: `Book ALV-tilitys (VAT settlement) for a month. Calculates net from ALV accounts (${ACCOUNTS.ALV_SAAMISET}/${ACCOUNTS.ALV_VELKA}) and creates settlement. Default date: 12th of month+1.`,
+      description: `Book ALV-tilitys (VAT settlement) for the company's VAT period that contains the given month. Settles the period's net from ALV accounts (${ACCOUNTS.ALV_SAAMISET}/${ACCOUNTS.ALV_VELKA}) by voucher date, excluding earlier settlements, closing entries and the previous-year import. Default date: the statutory due date (12th of the second month after the period; annual period: end of February), not moved to a business day. The period follows the company's VAT period. Refuses a period already settled, a period whose ledger does not match the ALV report, and negative balances.`,
       inputSchema: {
-        month: external_exports.string().regex(/^\d{4}-\d{2}$/).describe("Settlement month (YYYY-MM)"),
-        fiscalYearId: external_exports.string().uuid().optional().describe("Fiscal year UUID (auto-resolved if omitted)"),
-        settlementDate: ISO_DATE_SCHEMA.optional().describe("Settlement date (default: 12th of month+1)"),
+        month: external_exports.string().regex(/^\d{4}-(0[1-9]|1[0-2])$/).describe("A month of the VAT period to settle (YYYY-MM); a quarterly or annual company settles the whole period containing it"),
+        fiscalYearId: external_exports.string().uuid().optional().describe("Fiscal year UUID of the settlement date (default: the open fiscal year containing the settlement date)"),
+        settlementDate: ISO_DATE_SCHEMA.optional().describe("Settlement date (default: the statutory due date, 12th of the second month after the period; annual period: end of February)"),
         paymentAccount: external_exports.string().default(ACCOUNTS.PANKKITILI).describe(`Bank account (default "${ACCOUNTS.PANKKITILI}" Pankkitili)`),
         idempotencyKey: IDEMPOTENCY_KEY_SCHEMA,
         dryRun: DRY_RUN_SCHEMA
@@ -40561,16 +40658,25 @@ function registerBookingTools(server2) {
     async (params) => {
       const supabase2 = getSupabase();
       const companyId2 = getCompanyId();
+      const companyVat = await readCompanyVat(supabase2, companyId2);
+      if ("isError" in companyVat) return companyVat;
+      if (!companyVat.alvRegistered) return toErrorContent(NOT_VAT_REGISTERED_SETTLEMENT_REFUSAL);
+      const period = vatPeriodRange(params.month, companyVat.vatPeriod);
+      const dueDate = defaultSettlementDate(params.month, companyVat.vatPeriod);
+      const settlementDate = params.settlementDate ?? dueDate;
       let fiscalYearId = params.fiscalYearId;
       if (!fiscalYearId) {
-        const resolved = await resolveOpenFiscalYear(supabase2, companyId2);
-        if ("isError" in resolved) return resolved;
-        fiscalYearId = resolved.id;
+        const { data: years, error: yearsError } = await supabase2.from("fiscal_years").select("id").eq("company_id", companyId2).eq("is_closed", false).lte("start_date", settlementDate).gte("end_date", settlementDate).order("start_date", { ascending: false }).limit(1);
+        if (yearsError) {
+          return toErrorContent(sanitizeDbError("Failed to query fiscal years", yearsError));
+        }
+        if (!years || years.length === 0) {
+          return toErrorContent(
+            `No open fiscal year contains the settlement date ${settlementDate} (statutory due date for ${period.label}: ${dueDate}). Create that fiscal year or pass settlementDate inside an open fiscal year.`
+          );
+        }
+        fiscalYearId = years[0].id;
       }
-      const [year, monthStr] = params.month.split("-");
-      const monthNum = Number.parseInt(monthStr, 10);
-      const nextMonth = monthNum === 12 ? `${Number.parseInt(year, 10) + 1}-01` : `${year}-${String(monthNum + 1).padStart(2, "0")}`;
-      const settlementDate = params.settlementDate ?? `${nextMonth}-12`;
       const { data: fy } = await supabase2.from("fiscal_years").select("start_date, end_date, is_closed").eq("id", fiscalYearId).eq("company_id", companyId2).single();
       if (!fy) {
         return toErrorContent(
@@ -40584,7 +40690,7 @@ function registerBookingTools(server2) {
       }
       if (settlementDate > fy.end_date) {
         return toErrorContent(
-          `Settlement date ${settlementDate} is after fiscal year end ${fy.end_date}. Pass an explicit settlementDate within ${fy.start_date}..${fy.end_date} (typical: ${fy.end_date}) \u2014 silent clamping would shift the ALV-kausi.`
+          `Settlement date ${settlementDate} is after fiscal year end ${fy.end_date}. Pass an explicit settlementDate within ${fy.start_date}..${fy.end_date} or the fiscal year that contains ${settlementDate} \u2014 silent clamping would shift the ALV-kausi.`
         );
       }
       if (settlementDate < fy.start_date) {
@@ -40596,9 +40702,14 @@ function registerBookingTools(server2) {
         return toDryRunResponse("kirjapro_book_vat_settlement", {
           action: "book_vat_settlement",
           month: params.month,
+          vat_period: companyVat.vatPeriod,
+          period_start: period.start,
+          period_end: period.end,
           settlement_date: settlementDate,
+          statutory_due_date: dueDate,
+          fiscal_year_id: fiscalYearId,
           payment_account: params.paymentAccount,
-          hint: "Call kirjapro_get_alv_summary with the same month to preview the concrete net VAT before committing."
+          hint: `Call kirjapro_get_alv_summary for ${period.start}..${period.end} to preview the net VAT and its reconciliation before committing.`
         });
       }
       return withIdempotency(
@@ -40621,20 +40732,27 @@ function registerBookingTools(server2) {
             );
           }
           const result = data;
+          const periodStart = result.period_start ?? period.start;
+          const periodEnd = result.period_end ?? period.end;
           if (result.direction === "none") {
             return toResult({
-              message: result.message ?? `No VAT entries found for ${params.month}. Nothing to settle.`,
+              message: result.message ?? `No VAT entries found for ${period.label}. Nothing to settle.`,
               alv_saamiset: 0,
-              alv_velka: 0
+              alv_velka: 0,
+              period_start: periodStart,
+              period_end: periodEnd
             });
           }
           return toResult({
-            message: `VAT settlement booked for ${params.month}`,
+            message: `VAT settlement booked for ${period.label}`,
             transaction_id: result.transaction_id,
             alv_saamiset: result.alv_saamiset,
             alv_velka: result.alv_velka,
             net_vat: result.net_vat,
-            direction: result.direction
+            direction: result.direction,
+            period_start: periodStart,
+            period_end: periodEnd,
+            settlement_date: settlementDate
           });
         }
       );
@@ -40643,7 +40761,7 @@ function registerBookingTools(server2) {
   server2.registerTool(
     "kirjapro_book_sale",
     {
-      description: "Book a sale (myynti) with automatic VAT splitting. Payment types: invoice (default, D Myyntisaamiset), cash (D bank), prepaid.",
+      description: "Book a sale (myynti) with automatic VAT splitting for a company that is not VAT-registered. Payment types: invoice (default, D Myyntisaamiset), cash (D bank), prepaid. A VAT-registered (ALV) company is refused: its sales reach the ALV report only as invoices (kirjapro_create_invoice + kirjapro_send_invoice).",
       inputSchema: {
         amount: external_exports.number().finite().positive().max(1e9).describe("Gross EUR amount (VAT-inclusive)"),
         description: external_exports.string().min(1).max(500).describe('Transaction description (e.g. "Konsultointi Acme Oy, 40h \xD7 95 \u20AC")'),
@@ -40660,6 +40778,9 @@ function registerBookingTools(server2) {
       annotations: WRITE_ANNOTATIONS
     },
     async (params) => {
+      const companyVat = await readCompanyVat(getSupabase(), getCompanyId());
+      if ("isError" in companyVat) return companyVat;
+      if (companyVat.alvRegistered) return toErrorContent(ALV_REGISTERED_SALE_REFUSAL);
       const rate = Number.parseFloat(params.vatRate);
       const gross = roundCents(params.amount);
       let entries;
@@ -42647,7 +42768,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
+- **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
 - **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
@@ -42666,10 +42787,10 @@ var INSTRUCTIONS_FULL_ADDENDUM = `
 
 ### Booking Shortcuts
 Faster than composing journal entries via \`kirjapro_create_transaction\`:
-- \`kirjapro_book_sale\` / \`kirjapro_book_purchase\` \u2014 one-liner with auto VAT splitting
-- \`kirjapro_book_vat_settlement\` \u2014 reads ALV-saamiset/ALV-velka, creates settlement entry. Call \`kirjapro_get_alv_summary\` first to preview.
+- \`kirjapro_book_sale\` / \`kirjapro_book_purchase\` \u2014 one-liner with auto VAT splitting. A VAT-registered (ALV) company books sales as invoices (\`kirjapro_create_invoice\` + \`kirjapro_send_invoice\`): \`kirjapro_book_sale\` and \`kirjapro_book_purchase\` with \`reverseCharge\` are refused for it
+- \`kirjapro_book_vat_settlement\` \u2014 settles the company's VAT period from ALV-saamiset/ALV-velka. Call \`kirjapro_get_alv_summary\` for the period first to preview the net and its reconciliation.
 - **Payroll is intentionally NOT exposed.** Direct users to Palkkaus.fi / Palkka.fi for salary calculation; the payslip can then be booked manually via \`kirjapro_create_transaction\`.
-- \`kirjapro_list_templates\` \u2192 \`kirjapro_create_from_template\` for common patterns (13 built-in templates)
+- \`kirjapro_list_templates\` \u2192 \`kirjapro_create_from_template\` for common patterns (built-in templates; the sale templates are hidden and refused for a VAT-registered company)
 
 ### Manual Offer Status
 - \`kirjapro_update_offer_status\` \u2014 manual override; usually the customer's email-link click handles accept/reject server-side

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kirjapro/mcp-server",
-  "version": "0.9.1",
+  "version": "0.10.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.9.1",
+  "version": "0.10.0",
   "homepage": "https://kirjapro.fi",
   "repository": "https://github.com/Jaollo/kirja-pro",
   "license": "MIT",

package/tool-fingerprints.json

@@ -2,15 +2,15 @@
   "fingerprints": [
     {
       "name": "kirjapro_book_purchase",
-      "hash": "21897b2fd6bd8809"
+      "hash": "ec096990916f5112"
     },
     {
       "name": "kirjapro_book_sale",
-      "hash": "a7ad4daef0e9947b"
+      "hash": "6868bdf46073f442"
     },
     {
       "name": "kirjapro_book_vat_settlement",
-      "hash": "48ab541acbce9e66"
+      "hash": "39f807857fb81e5d"
     },
     {
       "name": "kirjapro_convert_offer_to_invoice",
@@ -22,11 +22,11 @@
     },
     {
       "name": "kirjapro_create_from_template",
-      "hash": "62d7241dbdba511c"
+      "hash": "9e774f4f25c6ce93"
     },
     {
       "name": "kirjapro_create_from_template_batch",
-      "hash": "f10cad13dc519c7c"
+      "hash": "415d1d219c81467f"
     },
     {
       "name": "kirjapro_create_invoice",
@@ -42,11 +42,11 @@
     },
     {
       "name": "kirjapro_create_transaction",
-      "hash": "88b052da9babfc50"
+      "hash": "bea9ccf179928813"
     },
     {
       "name": "kirjapro_create_transactions_batch",
-      "hash": "da853c41adf6e4dd"
+      "hash": "160de9628d56e6be"
     },
     {
       "name": "kirjapro_delete_invoice",
@@ -66,7 +66,7 @@
     },
     {
       "name": "kirjapro_get_alv_summary",
-      "hash": "139628cea5a3df31"
+      "hash": "1c225c5d61c0839f"
     },
     {
       "name": "kirjapro_get_ar_aging",
@@ -162,7 +162,7 @@
     },
     {
       "name": "kirjapro_list_templates",
-      "hash": "e07b6d21afbccce9"
+      "hash": "7601b5d1da0d7283"
     },
     {
       "name": "kirjapro_list_transactions",