@kirjapro/mcp-server 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,101 @@
 # 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.

package/README.md

@@ -7,7 +7,7 @@ MCP server for Finnish accounting. Exposes Kirjapro bookkeeping, invoicing, and
 ## 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
@@ -133,7 +133,12 @@ A few prompts to feel out the daily workflows the agent handles cleanly:
 }
 ```
 
-**Why default to 27 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`.
 
@@ -152,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