@kirjapro/mcp-server 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,110 @@
 # Changelog
 
+## [0.19.0] - 2026-10-19
+
+PR C of the MCP audit of 18.10.2026 (batches 3 and 4: posting guards and e-invoice send-state
+guards). **Release order:** `npm run db:deploy` of `20261019120000`–`20261019120300` and
+`20261019130000` first (`kirjapro_get_invoice` fails against a database without
+`20261019130000`, and `check:types-drift` fails until it is live), then the Edge functions
+`dispatch-invoice`, `generate-recurring-invoices`, `process-dead-letters`,
+`send-einvoice-maventa`, `send-invoice-email` and `mcp`, then this package. Against 0.18.1,
+12 of the 56 tool fingerprints change: `kirjapro_book_purchase`,
+`kirjapro_create_from_template`, `kirjapro_create_invoice`, `kirjapro_create_transaction`,
+`kirjapro_create_transactions_batch`, `kirjapro_delete_invoice`, `kirjapro_get_invoice`,
+`kirjapro_link_bank_transaction`, `kirjapro_list_bank_link_candidates`,
+`kirjapro_match_bank_transaction`, `kirjapro_send_invoice` and
+`kirjapro_update_invoice_status`. The two sections below list the changes per batch.
+
+E-invoice send-state guards (MCP audit of 18.10.2026, PR C batch 4: T2-6, T3-53 to T3-57).
+**Needs migration `20261019130000` before the release:** `kirjapro_get_invoice` reads the
+computed field `invoice_delivery_in_progress`, which a database without the migration
+refuses (the call fails). Deploy the Edge functions before publishing: `dispatch-invoice`
+(names the channel of another delivery in `inProgressChannel`, re-reads the invoice after
+its attempt mark), `generate-recurring-invoices`, `process-dead-letters`,
+`send-einvoice-maventa`, `send-invoice-email` and `mcp` (the shared read definitions and the
+generated core).
+Four fingerprints change: `kirjapro_get_invoice`, `kirjapro_send_invoice`,
+`kirjapro_update_invoice_status` and `kirjapro_delete_invoice`.
+
+- `kirjapro_get_invoice` returns an optional `delivery` object once the invoice has a
+  delivery through Kirjapro: `in_progress` (with its `channel`) while a send is queued or
+  started and its outcome is not settled, or a draft was delivered but is not yet marked
+  sent; `einvoice_status` and `email_sent_at` as the providers reported them. Without
+  `delivery`, no delivery was started. A failed read of it fails the call. A client that
+  cached the previous output schema and checks results refuses the results that carry
+  `delivery` until it lists the tools again.
+- `kirjapro_update_invoice_status` does not cancel a draft whose delivery is in progress or
+  done: the database refuses it for every client and the tool answers `DELIVERY_IN_PROGRESS`.
+- `kirjapro_send_invoice` delivers an invoice once. A web, scheduled or earlier e-invoice
+  (pending or accepted) or a sent e-mail refuses another delivery, and another channel's
+  delivery in progress is now a definite, cached `DELIVERY_IN_PROGRESS` that names that
+  channel, not `IDEMPOTENCY_OUTCOME_UNKNOWN`. The outcome-unknown answer says not to cancel,
+  delete or use the other channel, points to `delivery` in `kirjapro_get_invoice` and says
+  that a new `idempotencyKey` for the same invoice and channel resumes the same delivery.
+- `kirjapro_send_invoice` of an invoice that is already sent (`sent`, `partial`, `paid` or
+  `overdue`), for example the retry of a send whose outcome was unknown but which in fact
+  delivered it, answers a cached success with `already_sent: true`, `email_sent_at` and
+  `einvoice_status`, without a second delivery; before, it was an error. Its `channel` is
+  the one the evidence shows (`email`, `einvoice`), and an invoice marked sent in the app
+  without a Kirjapro delivery answers `channel: null` and says that Kirjapro sent nothing.
+- `kirjapro_delete_invoice` does not delete a draft whose delivery is in progress or done
+  (a live e-invoice transmission, a sent e-mail, or an e-mail whose outcome a person has yet
+  to resolve): the database refuses it and the tool answers a cached `DELIVERY_IN_PROGRESS`.
+- The `vat_notice` of `kirjapro_send_invoice` for a sales credit note gives its effect on the
+  VAT payable as negative (the credit note is stored with positive amounts and reverses the
+  VAT); it was positive.
+
+MCP audit of 18.10.2026, batch 3 (posting guards). Needs the database migrations
+`20261019120000`–`20261019120300` first; nine tool fingerprints change
+(`kirjapro_book_purchase`, `kirjapro_create_from_template`, `kirjapro_create_transaction`,
+`kirjapro_create_transactions_batch`, `kirjapro_create_invoice`, `kirjapro_send_invoice`,
+`kirjapro_match_bank_transaction`, `kirjapro_list_bank_link_candidates`,
+`kirjapro_link_bank_transaction`).
+
+- A VAT posting dated in a VAT period already settled with `kirjapro_book_vat_settlement`
+  is still booked, and the result adds `vat_notice`, a Finnish note the agent relays to the
+  user: the period's settlement does not include this VAT (the note gives its net effect on
+  the VAT payable with its sign), so the period's VAT return is corrected in OmaVero and the
+  difference settled with a voucher (founder decision 19.10.2026, audit T3-16). Reductions
+  count too (a purchase credit note, a 4210 debit); VAT settlements, payments and refunds do
+  not. Covered: `kirjapro_book_purchase` (and its dry run), a purchase
+  template with VAT in `kirjapro_create_from_template`, `kirjapro_create_transaction` and
+  `kirjapro_create_transactions_batch` lines on 2320/4210 (preview and commit, one line per
+  voucher), and `kirjapro_send_invoice` (the sales journal is dated on the invoice date).
+- `kirjapro_create_invoice` takes an optional `deliveryDate` (supply date). VAT treatments
+  are judged by it, as the app and the database do, and it is stored on the invoice
+  (audit T3-17): food delivered in December 2025 and invoiced in January 2026 keeps 14 %.
+- `kirjapro_match_bank_transaction` refuses with `ALREADY_BOOKED` when a voucher already
+  moved the bank account by exactly the receipt's amount; link the line to that voucher
+  with `kirjapro_link_bank_transaction` instead (audit T3-19).
+- `kirjapro_link_bank_transaction` to a purchase invoice answers `ALREADY_BOOKED` when the
+  payment already has a voucher that debits the invoice's payable (the database refuses it,
+  audit T2-1), and `kirjapro_list_bank_link_candidates` lists vouchers first. A same-amount
+  voucher that does not touch the payable no longer blocks the invoice link, and a line with
+  a payment-batch EndToEndId links to the batch item's separate payment voucher. The refusal
+  text is built from structured fields (the voucher number wrapped, the supplier's invoice
+  number not echoed). An item accepted by hand without a bank line no longer closes the cap
+  for a line without its EndToEndId (audit T3-27).
+- An archived account is refused before any write with `ACCOUNT_ARCHIVED` in the voucher,
+  template and booking tools (audit T3-26).
+- The install examples use `@kirjapro/mcp-server@latest`, so an older npm does not reuse a
+  cached copy; the package updates when the app restarts the server.
+
+## [0.18.1] - 2026-10-19
+
+No database migration; one tool fingerprint changes (`kirjapro_book_sale`).
+
+- `kirjapro_book_sale` books the sale of a company outside the VAT register gross even when
+  the receipt or invoice it gave showed VAT (founder decision 19.10.2026, audit T2-3): a
+  `vatRate` above 0 is no longer refused with `NOT_VAT_REGISTERED_SALE`, it is the rate the
+  receipt showed. No VAT is booked (no 4210 line, `vat: 0`, `vat_rate: "0 %"`), and the
+  result and the dry run add `vat_notice`, a Finnish note the agent relays to the user: the
+  company charges no VAT, the sale was booked in full as revenue, and a receipt that showed
+  VAT is wrong and is replaced with a corrected receipt without VAT, attached as the voucher
+  in the Kirjapro app.
+- A sale template with VAT (`cash_sale_25` and the like) is still refused for such a
+  company, and the refusal now points to `kirjapro_book_sale` with the receipt's rate.
+
 ## [0.18.0] - 2026-10-19
 
 **Breaking: Node.js 22 or newer is required** (`engines.node` `>=22`; Node.js 20 reached its

package/README.md

@@ -39,6 +39,9 @@ sending, or when you automate Kirjapro from a local MCP client.
 
 ### 2. Configure your MCP client
 
+The examples use `@kirjapro/mcp-server@latest`: the package updates whenever your app
+restarts the server, and a running session keeps the version it started with.
+
 #### Claude Code
 
 Add the server with `claude mcp add`. User scope (every project) and local scope (this
@@ -47,7 +50,7 @@ project root:
 
 ```bash
 claude mcp add --transport stdio --env KIRJAPRO_API_KEY=kp_your_key_here --scope user \
-  kirjapro -- npx -y @kirjapro/mcp-server
+  kirjapro -- npx -y @kirjapro/mcp-server@latest
 ```
 
 A project-scope `.mcp.json` is usually committed, so reference the key from your
@@ -59,7 +62,7 @@ environment instead of pasting it:
     "kirjapro": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "@kirjapro/mcp-server"],
+      "args": ["-y", "@kirjapro/mcp-server@latest"],
       "env": {
         "KIRJAPRO_API_KEY": "${KIRJAPRO_API_KEY}"
       }
@@ -85,7 +88,7 @@ Add to `claude_desktop_config.json`:
   "mcpServers": {
     "kirjapro": {
       "command": "npx",
-      "args": ["-y", "@kirjapro/mcp-server"],
+      "args": ["-y", "@kirjapro/mcp-server@latest"],
       "env": {
         "KIRJAPRO_API_KEY": "kp_your_key_here"
       }
@@ -105,7 +108,7 @@ Add to `~/.vibe/config.toml`:
 name = "kirjapro"
 transport = "stdio"
 command = "npx"
-args = ["-y", "@kirjapro/mcp-server"]
+args = ["-y", "@kirjapro/mcp-server@latest"]
 env = { KIRJAPRO_API_KEY = "kp_your_key_here" }
 ```
 
@@ -113,7 +116,7 @@ Restart Vibe and verify the connection from `/mcp`.
 
 #### ChatGPT
 
-For read-only use, add the [remote endpoint](#remote-endpoint-no-install) as a connector instead. ChatGPT cannot launch this local `stdio` package directly; for write tools use [OpenAI Secure MCP Tunnel](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels) to bridge ChatGPT to `npx -y @kirjapro/mcp-server`. Full write/modify support currently requires ChatGPT Business or Enterprise/Edu; see the [full setup guide](https://kirjapro.fi/docs/mcp/) for the tunnel commands and plan limitations.
+For read-only use, add the [remote endpoint](#remote-endpoint-no-install) as a connector instead. ChatGPT cannot launch this local `stdio` package directly; for write tools use [OpenAI Secure MCP Tunnel](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels) to bridge ChatGPT to `npx -y @kirjapro/mcp-server@latest`. Full write/modify support currently requires ChatGPT Business or Enterprise/Edu; see the [full setup guide](https://kirjapro.fi/docs/mcp/) for the tunnel commands and plan limitations.
 
 Mistral Le Chat accepts only a remote MCP server URL, so it cannot launch this package; it can use the [remote endpoint](#remote-endpoint-no-install) for read-only access. The local npm package works directly with Mistral Vibe.
 
@@ -147,7 +150,7 @@ A few prompts to feel out the daily workflows the agent handles cleanly:
   "mcpServers": {
     "kirjapro": {
       "command": "npx",
-      "args": ["-y", "@kirjapro/mcp-server"],
+      "args": ["-y", "@kirjapro/mcp-server@latest"],
       "env": {
         "KIRJAPRO_API_KEY": "kp_your_key_here",
         "KIRJAPRO_MCP_SURFACE": "full"   // 56 tools instead of 29
@@ -201,9 +204,10 @@ See the [full tool reference](https://kirjapro.fi/docs/mcp/) for parameters, usa
   cents (`INVALID_AMOUNT` otherwise), and `documentNumber` is the company's own
   voucher number: leave it out for the next number (a supplier's receipt number
   belongs in the description).
-- A company outside the VAT register books its sales without VAT
-  (`kirjapro_book_sale` takes only `vatRate "0"`, and the sale templates with
-  VAT are not offered). Recurring invoice templates take prices of 0 or more
+- A company outside the VAT register books its sales without VAT: the sale
+  templates with VAT are not offered, and `kirjapro_book_sale` books the gross
+  amount as revenue. If the receipt showed VAT, the result's `vat_notice` tells
+  the user to give the customer a corrected receipt without VAT (0.18.1). Recurring invoice templates take prices of 0 or more
   (a discount is `discountPercent`) and a first date from today on.
 - Update tools are annotated `destructiveHint: true` and the recurring invoice
   writes `openWorldHint: true`, so a host that auto-approves non-destructive