@kirjapro/mcp-server 0.18.1 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,207 @@
 # Changelog
 
+## [0.20.0] - 2026-10-20
+
+PR D of the MCP audit of 18.10.2026 (batches 7 to 12 and 14). Against 0.19.0, 3 of the 56
+tool fingerprints change: `kirjapro_book_vat_settlement`, `kirjapro_send_invoice` and
+`kirjapro_send_offer`. The package now bundles its runtime dependencies (no `dependencies`
+in `package.json`).
+
+**PR D release order** (one checklist for every section below; the rollout runbook row 7d0b
+in `docs/guides/ai-workspace-rollout.md` is its source): (1) merge by hand, which deploys the
+web app (until step 2 its Settings page can neither create nor revoke an API key); (2) `npm
+run db:deploy` from clean `main` at low traffic, all six migrations `20261019140000`,
+`20261019150000`, `20261019150100`, `20261019164710`, `20261019170000` and `20261019180000`;
+(3) `npm run functions:deploy` of `dispatch-invoice`, `send-offer-email`, `prh-lookup`,
+`generate-recurring-invoices` and `send-payment-reminders`; (4) `mcp-auth`; (5) `mcp` last;
+(6) this package. For about 11 minutes after step 2 an OAuth connection of a user with MFA
+that was approved just before it may answer 401 once and authorize again.
+
+API key lifecycle and DB-boundary hygiene (MCP audit of 18.10.2026, PR D batch 9). Server
+side only: no tool, description or fingerprint changes, and every published package gets
+the behaviour once migrations `20261019150000` and `20261019150100` and the `mcp-auth`
+deploy are live (steps 2 and 4). `src/database.types.ts` gains `api_keys.membership_id`
+and the RPCs `create_api_key`, `revoke_api_key` and `mcp_api_key_access`.
+
+- A revoked or expired key's live token, or that of a key whose creator left the company,
+  now gets `CREDENTIAL_INVALID` from its next read instead of empty lists ("0 invoices",
+  "not found"): the Data API gate answers such a key token with 401 and a message that
+  starts with the code.
+- `mcp-auth` answers the key of a creator who was removed from the company (even if
+  invited again) with 401, which the server reads as a permanent `CREDENTIAL_INVALID`,
+  instead of the `API_ENTITLEMENT_REQUIRED` 403; a failed check is a transient 503.
+- A credential holds at most 1 000 unresolved idempotency claims. Beyond them a write is
+  refused before it runs (`IDEMPOTENCY_BACKEND_UNAVAILABLE`, the write was not executed).
+- Keys are created and revoked only in the Kirjapro app (Asetukset → MCP-palvelin), which
+  now generates the key in the database and, before revoking, lists the key's writes and
+  offers to pause the recurring invoices with automatic sending that it touched; the revoke
+  button waits for that list. A key stays bound to its creator's membership for good: no
+  later write, not even an operator's, moves or restores the binding.
+
+Untrusted text and send friction (MCP audit of 18.10.2026, PR D batch 7: T2-7, T2-8, T3-40,
+T3-42 to T3-45, T4-13, T4-18; T3-41 was fixed by PR A). Released by the PR D order above
+(the migration `20261019164710` and the Edge functions before this package). Three
+fingerprints change:
+`kirjapro_send_invoice`, `kirjapro_send_offer` and `kirjapro_book_vat_settlement`.
+
+- `kirjapro_send_invoice` and `kirjapro_send_offer` take `dryRun`: nothing is claimed or
+  sent, and the preview names the recipient (wrapped), the channel and the invoice or offer
+  number, with `recipient_confirmation_required`. The results name the recipient(s),
+  wrapped. The preview asks the Edge function with `previewInvoiceId` or `previewOfferId`,
+  never with `invoiceId` or `offerId`, so a function deployed before previews refuses it
+  (`PREVIEW_UNAVAILABLE: … Nothing was sent`) and a dry run can never deliver. The text says
+  `Nothing was sent` only for a refusal or a lost answer.
+- Recipient confirmation (founder decision 19.10.2026): when the customer's e-mail or
+  e-invoice address was created or changed through an MCP credential (an API key or an
+  OAuth connection) in the last 24 hours, the send is refused with a cached
+  `RECIPIENT_CONFIRMATION_REQUIRED` naming the address, unless the call passes
+  `confirmRecipient` equal to it (an e-mail address in any case). A person who saves the
+  customer in the Kirjapro app confirms it too. The rule runs in the Edge functions, so the
+  remote endpoint enforces it as well; signers configured for a contract in the app need no
+  confirmation. The tool descriptions and the server instructions ask the agent to show the
+  address to the user first. An e-invoice refusal also names the operator. The automatic
+  sends have nobody to confirm, so they hold any recipient an MCP credential set that no
+  person has saved since, however old: the daily recurring run leaves the invoice a draft
+  and the template's generation log says why, and the payment reminders skip the customer.
+  An offer without any recipient answers the missing e-mail address, not
+  `RECIPIENT_CONFIRMATION_REQUIRED`.
+- Invoice, reference, offer and customer numbers are no longer trusted as "generated": they
+  stay bare only in the shape Kirjapro allocates (`2026-0001`, digits, `TAR00001`/`SOP00001`,
+  `C00001`) and are wrapped otherwise, in the read tools (also the ALV reconciliation, the
+  offer events and the recurring invoice log) and in the write tools' results and messages
+  (a partial reversal of U-65). The company's own IBAN is bare only with a numeric account
+  part. The server instructions and `kirjapro://security/data-handling` say so.
+- Refusal texts of the bank reconciliation tools and of `kirjapro_book_vat_settlement` that
+  quote stored text (an e-invoice number, a voucher number, the line's currency) are wrapped.
+- An argument that contains `⟦redacted⟧`, which a read result shows in place of text that
+  looked like an instruction, is refused with `INVALID_ARGUMENTS` instead of being stored.
+- `kirjapro_get_received_invoice` wraps `pdf_storage_path` (the sender's file name).
+- `kirjapro_get_recurring_invoice` keeps a `template_data` code bare only when it is a VAT
+  treatment code, VAT category, price-entry mode or account id the server writes.
+- `kirjapro_get_general_ledger` echoes an unknown account wrapped unless it is a number;
+  `kirjapro_book_vat_settlement` takes a 4- or 5-digit `paymentAccount` only.
+- `kirjapro_get_offer` keeps the status codes `from_status` and `to_status` of an offer event
+  bare.
+
+PR D of the MCP audit of 18.10.2026 (batches 8, 11 and 14). No tool definition changes and
+no fingerprint changes. Released by the PR D order above (`20261019170000`, the server-side
+`batch_size` clamp, is in its `db:deploy`; the package does not need it). Before the first
+tag, run the publish workflow once by hand on `main`: its `publish` job now runs in the
+`npm-publish` environment.
+
+- **No runtime dependencies** (T3-58): `@modelcontextprotocol/sdk`, `zod` and
+  `@supabase/supabase-js` are bundled into `dist/index.js` (about 2.7 MB) and are
+  devDependencies; the optional `@supabase/supabase-js` peer dependency is gone. `npx -y
+  @kirjapro/mcp-server` installs this one package, so no unpinned third-party package or
+  install script runs with `KIRJAPRO_API_KEY` in its environment. Up to 0.19.0 about 105
+  packages were resolved at install time.
+- **Stable code for a schema refusal** (T4-16): arguments that fail a tool's input schema
+  answer `INVALID_ARGUMENTS: Input validation error: Invalid arguments for tool …` instead
+  of `MCP error -32602: Input validation error: …`, so every failed call starts with a code.
+  Telemetry already recorded these as `INVALID_ARGUMENTS`.
+- **Telemetry `batch_size`** (T3-60): only a transactions count within 1–250 is sent. A
+  batch call with `transactions: []` or more than 250 items (which the SDK then refuses)
+  made the database refuse the whole telemetry flush, its neighbours' events included.
+- **Release pipeline** (T2-12, T3-78; no package change): `publish-mcp.yml` builds and packs
+  in a job without secrets or publish rights, checks the live types in a job that holds
+  only the read token and installs nothing but the checksum-pinned Supabase CLI 2.111.0
+  release, and publishes the packed tarball from a job
+  in the `npm-publish` environment that installs nothing. `check:release-version` keeps
+  `package.json`, `server.json`, `mcpb/manifest.json` and this file's version heading in
+  step on every pull request; `mcpb:validate` and `mcpb:pack` pin `@anthropic-ai/mcpb@2.1.2`.
+  `check:types-drift` (also in `prepublishOnly`) runs `supabase` from `PATH` and fails unless
+  `supabase --version` is exactly 2.111.0; it no longer runs `npx -y supabase@latest`.
+
+## [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`).

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