@kirjapro/mcp-server 0.6.3 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,120 @@
 # Changelog
 
+## [0.8.0] - 2026-08-30
+
+Safety and observability release for agent-driven accounting. This release has
+breaking input changes for write and batch tools and requires the paired
+database migrations plus an `mcp-auth` redeploy before the package is published.
+
+### Breaking changes
+
+- Every one of the 23 write tools now requires `idempotencyKey` as a UUID v4.
+  A write executes only after the database atomically confirms its claim. A
+  missing/unavailable claim fails closed; a crashed or uncertain operation is
+  permanently blocked from automatic re-execution instead of being recycled
+  after a timeout.
+- `kirjapro_create_transactions_batch` and
+  `kirjapro_create_from_template_batch` no longer expose `mode` or partial
+  success. They default to `dryRun: true`; committing with `dryRun: false` is
+  always atomic and any invalid member aborts the whole batch.
+- Invoice, offer, and recurring-invoice payloads are capped at 100 lines;
+  transactions are capped at 100 journal entries each and 500 entries across a
+  batch. Write annotations no longer claim unbounded MCP idempotence: the
+  completed-response replay contract remains 24 hours.
+- `kirjapro_get_general_ledger` is now seek-cursor paginated (`limit` 1–100).
+  The full-period summary remains exact while each entry page is bounded and
+  pinned to the first page's creation-time cutoff.
+- `kirjapro_get_ar_aging` now returns aggregate buckets only. Invoice/customer
+  rows are intentionally omitted; null due dates have an explicit bucket and
+  the weighted-age metric is no longer presented as revenue-based DSO.
+
+### Added
+
+- Metadata-only operational telemetry, enabled by default and explicitly
+  disableable with `KIRJAPRO_TELEMETRY=false`. It records tool/version/surface,
+  client, timing, outcome class, byte counts, batch/preview flags, idempotency
+  state, and company/API-key attribution. It never sends arguments, results,
+  prompts, accounting-record identifiers, names, or monetary values. Raw events
+  expire after 90 days.
+- Platform-admin MCP metrics panel with 7/30/90-day trends, tool adoption,
+  client/surface breakdowns, error classes, response-budget events, and
+  idempotency safety signals. Only aggregate data is exposed to the UI.
+- Soft 50 KiB response telemetry and a hard 200 KiB context-safety budget with
+  an actionable `RESPONSE_BUDGET_EXCEEDED` error. Write responses are shaped
+  before replay completion, so a committed operation cannot cache an envelope
+  different from the one returned to the client.
+- Full `tools/call` lifecycle instrumentation, including SDK input validation,
+  unknown tools, output-schema failures, and malformed protocol requests.
+- Stable, explicit registration order for all 52 tools and regression coverage
+  for the 27-tool `core` prefix.
+
+### Security
+
+- Idempotency state is server-owned: direct authenticated table access is
+  revoked, claim/complete require an AAL2 company-scoped JWT carrying a live
+  matching MCP API-key and write-protocol claims, request bodies are SHA-256
+  bound, and replay payloads have bounded JSONB storage headroom. Ordinary
+  browser sessions cannot reserve or
+  complete MCP replay keys. A registry-level boundary covers the complete
+  write handler, so state-dependent preflight reads cannot bypass replay.
+- Telemetry ingestion accepts only `mcp-auth` JWTs carrying a revalidated
+  `mcp_api_key_id` and protocol-2 claim; unknown event fields and tool names
+  outside the pinned 52-tool catalog plus the privacy-preserving unknown-tool
+  sentinel are rejected, and raw rows are not readable by authenticated users.
+- Tool fingerprints now cover public output schemas in addition to description,
+  annotations, and input schemas, using stable JSON Schema rather than mutable
+  Zod internals.
+
+### Server-side coupling
+
+1. After merge, redeploy `mcp-auth` through
+   `npm run functions:deploy -- mcp-auth` (the wrapper preserves
+   `--no-verify-jwt`). It rejects clients without write protocol 2 and records
+   successful v0.8 exchanges in the audit log.
+2. Deploy migrations `20260830120000_mcp_v08_idempotency_telemetry.sql` and
+   `20260830121000_mcp_v08_bounded_reports.sql` through `npm run db:deploy`.
+   The foundation migration denies every still-live pre-protocol company JWT
+   on the protected table/RPC paths used by MCP writes before it revokes the
+   legacy replay-table path. Deliberately unprotected bootstrap reads remain.
+3. Publish `@kirjapro/mcp-server@0.8.0` only after the backend checks pass.
+   No active-client restart inventory is part of the safety proof.
+
+## [0.7.1] - 2026-08-23
+
+Adds structured sales VAT treatment across invoice and offer creation.
+
+### Added
+
+- Invoice and offer tools accept VAT-inclusive unit prices, explicit 0 % treatment codes,
+  construction reverse-charge confirmation, and intra-EU goods transport confirmation.
+- Customer country/VAT identifier and seller registration are validated before special VAT
+  treatments are persisted; document delivery remains guarded by the server readiness RPC.
+
+### Fixed
+
+- VAT summary output now distinguishes official OmaVero purchase fields 318/320 from the
+  construction/scrap sales field 319 and exposes treatment-derived EU/zero-rate sales bases.
+- Tool fingerprint baseline regenerated for the intentional schema and description changes.
+
+## [0.7.0] - 2026-07-16
+
+Adds invoice delivery as a first-class MCP workflow.
+
+### Added
+
+- **`kirjapro_send_invoice`** sends a draft invoice through an explicit `email` or `einvoice` channel. The tool calls the authenticated `dispatch-invoice` Edge Function, keeps provider credentials server-side, and returns the delivery identifier.
+- Invoice create → send guidance now uses the delivery tool instead of redirecting users to the web UI.
+
+### Changed
+
+- The default `core` surface now contains 27 tools; the complete catalog remains 52 tools.
+- Package, server manifest, and MCPB versions are aligned at 0.7.0.
+- Client setup now documents native local `stdio` use with Mistral Vibe and ChatGPT access through OpenAI Secure MCP Tunnel. Mistral Le Chat is explicitly marked as requiring a separately hosted remote endpoint.
+
+### Fixed
+
+- Server instructions no longer list e-invoice sending as web-only now that `kirjapro_send_invoice` supports the explicit `einvoice` channel.
+
 ## [0.6.1] - 2026-05-29
 
 Hardening release from a full server audit (12 dimensions, adversarially verified). No new tools; tightens input validation, closes two security gaps, and corrects compliance guidance + tool descriptions. `tool-fingerprints.json` regenerated for the description/input-schema changes.

package/README.md

@@ -1,13 +1,13 @@
 # @kirjapro/mcp-server
 
-MCP server for Finnish accounting. Exposes Kirjapro bookkeeping, invoicing, and reporting tools to Claude Code, Claude Desktop, and any MCP client.
+MCP server for Finnish accounting. Exposes Kirjapro bookkeeping, invoicing, and reporting tools to Claude Code, Claude Desktop, Mistral Vibe, ChatGPT through Secure MCP Tunnel, and other MCP clients.
 
 **Full documentation:** [kirjapro.fi/docs/mcp](https://kirjapro.fi/docs/mcp/)
 
 ## Requirements
 
 - Node.js 20+
-- Kirjapro account on a paid tier with API access — **Yrittäjä** or **Kasvu**
+- Kirjapro account on a paid tier with API access — **Yrittäjä**, **Kasvu**, **Tilitoimisto**, or **Räätälöity**
 - API key (generate at Settings > API-avaimet)
 
 ## Quick Start
@@ -72,9 +72,30 @@ Add to `claude_desktop_config.json`:
 
 Restart Claude Desktop after saving.
 
+#### Mistral Vibe
+
+Add to `~/.vibe/config.toml`:
+
+```toml
+[[mcp_servers]]
+name = "kirjapro"
+transport = "stdio"
+command = "npx"
+args = ["-y", "@kirjapro/mcp-server"]
+env = { KIRJAPRO_API_KEY = "kp_your_key_here" }
+```
+
+Restart Vibe and verify the connection from `/mcp`.
+
+#### ChatGPT
+
+ChatGPT requires a remote MCP connection and cannot launch this local `stdio` package directly. 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.
+
+Mistral Le Chat likewise requires a remote MCP server URL. The local npm package works directly with Mistral Vibe; Le Chat support requires a separately hosted remote endpoint.
+
 #### Other clients
 
-See [full setup guide](https://kirjapro.fi/docs/mcp/) for Cursor, VS Code / Copilot, Windsurf, and generic stdio.
+See [full setup guide](https://kirjapro.fi/docs/mcp/) for ChatGPT, Mistral Vibe, Cursor, VS Code / Copilot, Windsurf, and generic stdio.
 
 ### 3. Verify
 
@@ -86,6 +107,7 @@ A few prompts to feel out the daily workflows the agent handles cleanly:
 
 - *"Show my dashboard"* — financial snapshot of the current fiscal year
 - *"Create an invoice for Acme Oy, 5000 € for consulting in March"* — full lifecycle from customer lookup to draft invoice
+- *"Send invoice #42 by email"* — server-rendered PDF delivery with an explicit channel
 - *"Draft a contract for Acme Oy and email it to john@acme.fi, 3-month retainer at 5000 € / month"* — `tarjous`/`sopimus` create + customer-visible email link
 - *"Record that invoice #42 was paid yesterday"* — payment recording + auto status transition
 - *"What's my VAT for this quarter?"* — `kirjapro_get_alv_summary` with OmaVero field codes
@@ -94,7 +116,7 @@ A few prompts to feel out the daily workflows the agent handles cleanly:
 
 ## What's included
 
-**26 tools** in the default `core` surface, focused on the daily-use workflows: read your books, invoice flow, transactions + banking, contract create / send / convert, Finnish validators. The full 52-tool catalog (booking shortcuts, recurring invoices, templates, batch tools, etc.) is available via opt-in:
+**27 tools** in the default `core` surface, focused on the daily-use workflows: read your books, invoice flow, transactions + banking, contract create / send / convert, Finnish validators. The full 52-tool catalog (booking shortcuts, recurring invoices, templates, batch tools, etc.) is available via opt-in:
 
 ```jsonc
 {
@@ -104,14 +126,19 @@ A few prompts to feel out the daily workflows the agent handles cleanly:
       "args": ["-y", "@kirjapro/mcp-server"],
       "env": {
         "KIRJAPRO_API_KEY": "kp_your_key_here",
-        "KIRJAPRO_MCP_SURFACE": "full"   // 52 tools instead of 26
+        "KIRJAPRO_MCP_SURFACE": "full"   // 52 tools instead of 27
       }
     }
   }
 }
 ```
 
-**Why default to 26 instead of 52:** 2025-2026 SOTA research on tool catalog scaling (Anthropic, OpenAI, MCP authors) shows tool-selection accuracy degrades between 25-50 tools per catalog. A focused surface produces better first-call selections for the daily workflows. As real usage data informs which deferred tools matter most, they'll be promoted into core.
+**Why default to 27 instead of 52:** large catalogs with overlapping tools cost
+more context and can make selection harder, but there is no universal tool-count
+cliff that applies to every model and task. Twenty-seven is a conservative
+launch default for Kirjapro's daily workflows. Its own usage and error data,
+not an industry magic number, will determine which deferred tools move into
+core.
 
 **Payroll is intentionally not exposed.** Kirjapro does not calculate or book salaries. Direct users to a dedicated payroll service (such as [Palkkaus.fi](https://www.palkkaus.fi) or [Palkka.fi](https://www.palkka.fi)) for the calculation — these services hold the regulated responsibility for Tulorekisteri-ilmoitus, TyEL/TVR raportointi, and ennakonpidätys-tilitys. Once the payslip is calculated externally, book it manually via `kirjapro_create_transaction`.
 
@@ -119,7 +146,7 @@ A few prompts to feel out the daily workflows the agent handles cleanly:
 |---|---|
 | Read your books | `list_fiscal_years`, `list_accounts`, `get_dashboard`, `get_income_statement`, `get_balance_sheet`, `get_alv_summary`, `get_ar_aging` |
 | Customers | `list_customers`, `get_customer`, `create_customer`, `lookup_business` (PRH) |
-| Invoice lifecycle | `list_invoices`, `get_invoice`, `create_invoice`, `record_payment`, `update_invoice_status` |
+| Invoice lifecycle | `list_invoices`, `get_invoice`, `create_invoice`, `send_invoice`, `record_payment`, `update_invoice_status` |
 | Transactions + banking | `list_transactions`, `create_transaction`, `list_bank_transactions`, `match_bank_transaction` |
 | Contracts | `create_offer` (`tarjous` / `sopimus`), `send_offer` (email link), `convert_offer_to_invoice` |
 | Validators (free) | `validate_business_id`, `validate_iban`, `generate_reference` |
@@ -130,15 +157,52 @@ A few prompts to feel out the daily workflows the agent handles cleanly:
 
 See the [full tool reference](https://kirjapro.fi/docs/mcp/) for parameters, usage examples, and error handling.
 
+## Write safety contract
+
+- Every write requires a fresh UUID-v4 `idempotencyKey`. Reuse that key only
+  for an exact retry of the same tool and arguments.
+- Writes fail closed if the atomic database claim cannot be confirmed. An
+  `IDEMPOTENCY_OUTCOME_UNKNOWN` response means the earlier operation may have
+  completed: reconcile with a read tool or the Kirjapro UI and do not invent a
+  new key.
+- Dry runs have no side effects and are not cached. The two batch tools default
+  to `dryRun: true`; `dryRun: false` commits the complete batch atomically.
+- Tool responses have a 200 KiB hard context budget. Narrow a range, lower a
+  limit, or follow the returned cursor if `RESPONSE_BUDGET_EXCEEDED` appears.
+  For writes, the bounded envelope is cached before completion, so the response
+  returned now is also the response replayed by the same key.
+- Invoice/offer/recurring-document writes accept at most 100 lines. A direct
+  transaction accepts at most 100 journal entries; a transaction batch accepts
+  at most 500 entries across its 50 transactions.
+
+## Operational telemetry
+
+Kirjapro records bounded first-party operational metadata by default: company
+and API-key identifiers, tool/server/client names and versions, timing, outcome
+class, request/response byte counts, surface, batch/preview flags, idempotency
+state, and response-budget state. Tool arguments, results, and prompts are
+never sent, nor are accounting-record identifiers, names, or monetary values.
+Raw events are deleted after 90 days and application users cannot read them.
+
+Set `KIRJAPRO_TELEMETRY=false` in the MCP environment to opt out. See the
+[privacy notice](https://kirjapro.fi/tietosuoja) for the complete contract.
+Opting out disables metadata delivery only; the 200 KiB local context-safety
+limit remains active.
+
 ## Security
 
 - API keys are hashed with SHA-256; the full key is never stored
-- Keys exchange for short-lived JWTs (1 hour) via the `mcp-auth` edge function
+- Keys exchange for short-lived JWTs (1 hour) via the `mcp-auth` edge function;
+  the exchange and guarded write RPCs require write protocol 2
 - All queries use Row Level Security (RLS) — users can only access their own company's data
 - Each API key is scoped to a single company — the issued JWT carries a company claim enforced by RESTRICTIVE row-level security, so a key for one company cannot read another's data even via raw database access (not just application-layer filtering)
 - Automatic token refresh keeps long-running sessions alive
 - Rate limiting: 10 auth requests per minute per key
-- **Tool description fingerprint guard** — every tool's `description + annotations + inputSchema` is hashed and shipped as `tool-fingerprints.json`. Downstream operators who want supply-chain pinning can verify the running MCP matches the known-good fingerprint set, defending against silent description tampering between releases.
+- Every write is guarded by a server-owned atomic idempotency claim; direct authenticated access to the replay table is denied
+- Write tools advertise `idempotentHint: false` because completed replay lasts
+  24 hours rather than forever; exact retries remain protected inside that
+  documented window
+- **Tool contract fingerprint guard** — every tool's `description + annotations + inputSchema + outputSchema` is hashed and shipped as `tool-fingerprints.json`. Downstream operators who want supply-chain pinning can verify the running MCP matches the known-good fingerprint set, defending against silent contract tampering between releases.
 
 ## License