@kirjapro/mcp-server 0.5.0 → 0.5.6

package/CHANGELOG.md

@@ -1,5 +1,257 @@
 # Changelog
 
+## [0.5.5] - 2026-04-11
+
+Tool-annotation sweep: every remaining `server.tool()` call migrated to
+`server.registerTool()` and tagged with MCP tool annotations. No behavioural
+changes — clients get richer `list_tools` metadata and `destructiveHint`
+now flags the three `delete_*` tools so UIs can warn before invoking them.
+
+### registerTool() migration
+
+- **All 43 remaining tools migrated** — `customers`, `invoices`, `bookings`,
+  `offers`, `recurring-invoices`, `templates`, `accounts`, `received-invoices`,
+  `banking`, `validation`, `fiscal-years`, and `transactions` now exclusively
+  use `server.registerTool(name, { description, inputSchema, annotations }, cb)`.
+  The deprecated `server.tool()` overload is no longer called anywhere in the
+  codebase (verified by test guard — see below).
+- **Shared annotation constants** (`src/utils.ts`) — `READ_ONLY_ANNOTATIONS`,
+  `READ_ONLY_EXTERNAL_ANNOTATIONS`, `WRITE_ANNOTATIONS`,
+  `WRITE_EXTERNAL_ANNOTATIONS`, `DESTRUCTIVE_ANNOTATIONS`. The five constants
+  cover the read/write × local/external × destructive matrix, so individual
+  tool files don't re-declare the hint bags inline.
+- **`destructiveHint: true`** on `kirjapro_delete_invoice`,
+  `kirjapro_delete_offer`, and `kirjapro_delete_recurring_invoice`. MCP
+  clients that support the annotation can now show a distinct confirmation
+  prompt before executing irreversible operations.
+- **`openWorldHint: true`** on `kirjapro_lookup_business` (PRH API) and
+  `kirjapro_send_offer` (sends customer-visible email via Maventa). Everything
+  else sets `openWorldHint: false` since the operation is confined to the
+  caller's own Supabase tenant.
+- **Inline annotation block in `list_transactions`** replaced with the shared
+  `READ_ONLY_ANNOTATIONS` constant — single source of truth for hint values.
+- **`reports.ts` local annotation const** removed; imports from `utils.js`.
+  Drops one duplicate definition that was introduced in v0.5.2.
+
+### Test infrastructure
+
+- **`tools-registry.test.ts` guard tests added:**
+  - `declares annotations on every registered tool` — iterates the full
+    52-tool list and asserts `annotations` is defined. Any regression that
+    forgets to pass annotations (or accidentally re-introduces
+    `server.tool()`) fails CI.
+  - `flags delete_* tools as destructive` — asserts every tool whose name
+    starts with `kirjapro_delete_` has `destructiveHint: true` and
+    `readOnlyHint: false`. Prevents a delete tool from being silently
+    labelled safe.
+- **Full suite: 111 passing (was 109 in v0.5.4).** 7 test files, same auth
+  DNS warning as before (benign — `test.supabase.co` resolution in legacy
+  env-var test).
+
+### Notes
+
+- `outputSchema` on write tools is intentionally NOT added in this pass.
+  Write payloads are complex (invoice line refinements, journal entries
+  with balanced debit/credit tuples) and declaring them risks runtime
+  validation surprises on real rows. Deferred to v0.5.6+ as an incremental
+  per-tool exercise.
+- The `WRITE_EXTERNAL_ANNOTATIONS` constant is exported but currently only
+  used by `kirjapro_send_offer`. Kept in `utils.ts` for future e-invoice
+  tools that hit Maventa directly.
+
+## [0.5.4] - 2026-04-11
+
+M6 tail: the three remaining read tools now declare `outputSchema`.
+
+### Structured output
+
+- **`registerTool()` + `outputSchema` on `get_balance_sheet`,
+  `get_ar_aging`, `get_general_ledger`** — all 9 read tools in the
+  reports / invoices / transactions surface now expose typed response
+  contracts at `list_tools` time and carry the `readOnlyHint` /
+  `idempotentHint` / `openWorldHint: false` annotation set. Inner row
+  shapes use `.passthrough()` / `z.unknown()` to stay permissive on
+  real-world rows.
+
+### Test infrastructure
+
+- **Snapshot assertion widened** — `tools-registry.test.ts` now checks
+  `outputSchema` presence on all 9 read tools (was 6 in v0.5.3). Any
+  future migration that drops a schema fails CI.
+
+## [0.5.3] - 2026-04-11
+
+Audit follow-through: schema contracts on hot read tools, registration
+drift guard, and test-suite widening.
+
+### Structured output
+
+- **`registerTool()` migration + `outputSchema` on 6 hot read tools**
+  (M6 completion) — `kirjapro_list_invoices`, `kirjapro_get_invoice`,
+  `kirjapro_list_transactions`, `kirjapro_get_dashboard`,
+  `kirjapro_get_income_statement`, and `kirjapro_get_alv_summary` now
+  register via the modern `server.registerTool()` API, declare typed
+  `outputSchema` (zod raw shapes), and carry `readOnlyHint` /
+  `idempotentHint` / `openWorldHint: false` annotations. MCP clients
+  see the schemas at `list_tools` time — agents can validate return
+  shapes without "forgot field name" loops.
+
+### Test infrastructure
+
+- **Tool registration snapshot test** (M16 follow-through) — new
+  `tools/tools-registry.test.ts` asserts that exactly 52 tool names
+  are registered (catches accidental unregister or rename drift) and
+  that the 6 hot read tools all declare `outputSchema`. Verifies
+  `kirjapro_send_offer` and `kirjapro_convert_offer_to_invoice` are
+  in the bundle (closes the M16 regression concern).
+
+### Notes
+
+- Output schemas are intentionally lax on row-level fields (use
+  `.passthrough()` or `z.unknown()` for nested shapes) to avoid
+  runtime validation failures on edge-case rows. The envelope shape
+  (`results` / `total_count` / `has_more` / `next_offset`) and the
+  top-level report blocks are precise; inner rows are descriptive
+  rather than strict. Tighten over time as real usage reveals stable
+  shapes.
+- Write tools still use `server.tool()`. Migrating writes to
+  `registerTool()` is deferred — the annotations (`destructiveHint`)
+  would be valuable, but the schema complexity (zod refinements on
+  invoice line items, etc.) needs a dedicated pass.
+
+## [0.5.2] - 2026-04-11
+
+Round 3 of `ENHANCEMENT-AUDIT-2026-04-11.md`: idempotency + dry-run on
+writes, structured content on hot read tools, atomic booking RPCs, and a
+salary rounding fix.
+
+### Reliability
+
+- **Idempotency keys on every write tool** (M4) — new
+  `mcp_idempotency_keys` table (`20260411132733_add_mcp_idempotency_keys.sql`)
+  stores `(company_id, key) → response_payload` with a 24h TTL. Every write
+  tool now accepts an optional `idempotencyKey` (8–128 chars). Retries with
+  the same key return the cached response verbatim — a retried
+  `kirjapro_create_invoice` on a transient network blip will no longer
+  create a duplicate invoice. Cache misses pass through; infra errors
+  fall through (the wrapper never masks a write). Covered by the new
+  `withIdempotency()` helper in `utils.ts`.
+- **Dry-run previews on destructive tools** (M4) — `kirjapro_delete_invoice`,
+  `kirjapro_delete_offer`, `kirjapro_delete_recurring_invoice`, and
+  `kirjapro_update_offer_status` now accept `dryRun: true`. They validate
+  the operation and return `{ dry_run: true, requires_confirmation: true,
+  message, preview }` without writing. Agents should always call with
+  `dryRun: true` first for irreversible actions, relay the preview to the
+  user, and only re-call with `dryRun: false` after confirmation.
+- **Atomic `book_salary` + `book_vat_settlement`** (M9) — both booking
+  tools now call `book_salary_atomic` / `book_vat_settlement_atomic`
+  SECURITY DEFINER RPCs guarded by `pg_advisory_xact_lock`. Serializes
+  concurrent callers per `(company, fiscal_year, period)` so parallel
+  tool invocations cannot each write a salary journal for the same pay
+  period.
+- **`book_salary` rounding residual** (M15) — employer's TyEL + employee's
+  TyEL now use residual-method rounding (last group = total − sum of
+  others) so the journal balances to the cent. Parametrized test added
+  covering 2026 rates + a handful of adversarial gross amounts.
+
+### Structured output
+
+- **`structuredContent` on 6 hot read tools** (M6) — new `toResult<T>()`
+  helper returns both the JSON-stringified `content` (backward compat)
+  and a typed `structuredContent` object. Rolled out to
+  `kirjapro_list_invoices`, `kirjapro_get_invoice`,
+  `kirjapro_list_transactions`, `kirjapro_get_dashboard`,
+  `kirjapro_get_income_statement`, and `kirjapro_get_alv_summary`. Modern
+  MCP clients consume `structuredContent` without `JSON.parse`. Declaring
+  `outputSchema` via `registerTool()` is deferred to a later version
+  since it requires migrating away from the deprecated `server.tool()`
+  overload.
+
+### Migrations
+
+- `20260411132733_add_mcp_idempotency_keys.sql` — `mcp_idempotency_keys`
+  table, RLS (`private.has_company_access`), and
+  `cleanup_expired_mcp_idempotency_keys()` maintenance function.
+
+## [0.5.1] - 2026-04-11
+
+Security + compliance + race hardening bundle. Based on
+`ENHANCEMENT-AUDIT-2026-04-11.md` — Round 1 (M1/M2/M5/M8/M10/M14/M16) and
+Round 2 (M3/M7/M11/M12/M13).
+
+### Security
+
+- **Prompt injection defense** (M3) — new `tagUntrusted()` utility wraps
+  attacker-controlled free text in `<untrusted-external>...</untrusted-external>`
+  tags. Applied to `kirjapro_list_bank_transactions` (counterparty_name,
+  reference, message), `kirjapro_list_received_invoices` /
+  `kirjapro_get_received_invoice` (sender_name, sender_business_id,
+  invoice_number, payment_reference), and `kirjapro_lookup_business`
+  (PRH free-text fields). The helper also strips zero-width characters,
+  control chars, and common injection markers (`system:`,
+  `<|im_start|>`, "ignore previous", etc.) before wrapping.
+- **`kirjapro://security/data-handling` resource** (M3) — documents the
+  wrapper contract, lists every wrapped field per tool, and gives safe
+  handling rules. Intended as a session-start read.
+- **Multi-company JWT scoping guard** (M1) — every tool call verifies
+  the JWT's `company_id` matches the MCP session's selected company
+  before executing, closing the cross-company data leak described in
+  CLAUDE.md pitfall #13.
+- **Stdio token-refresh hardening** (M2) — mutex + single-flight refresh
+  prevents race between concurrent tool calls and the background refresh
+  timer; all 401s now retry once with a fresh token.
+
+### Correctness
+
+- **Advisory-locked number generators** (M12) — new migration
+  `20260411120919_add_next_customer_offer_number_rpcs` adds
+  `get_next_customer_number(company_id)` and
+  `get_next_offer_number(company_id, type)` RPCs mirroring the
+  `pg_advisory_xact_lock(hashtext(...))` pattern from
+  `get_next_invoice_number`. `customers.ts` and `offers.ts` now call the
+  RPCs instead of read-then-write — fixes 23505 unique-index collisions
+  under concurrent creates.
+- **Compliance rates single source of truth** (M7) — new
+  `src/compliance/rates.ts` exports `FINNISH_RATES_2026` (VAT, TyEL,
+  sotu, TTV, tapaturma, ryhmähenki) with a validity window.
+  `bookings.ts`, `templates.ts`, and `resources/compliance.ts` now
+  import from it instead of duplicating literals. Every compliance
+  resource emits an `_meta` envelope (`published_at`, `valid_through`,
+  `stale`, `days_until_expiry`); new `kirjapro://compliance/_freshness`
+  index resource lets the agent detect expired rates in one read at
+  session start.
+- **Report tools auto-resolve fiscal year** (M11) — `get_dashboard`,
+  `get_income_statement`, `get_balance_sheet`, and `get_general_ledger`
+  now accept `fiscalYearId` as optional. When omitted, the single open
+  fiscal year is resolved via `resolveOpenFiscalYear()`; tools error
+  with a clear hint when multiple fiscal years are open.
+
+### Fixed
+
+- Various small bugs (M5/M8/M10/M14/M16) — field selection drift,
+  error-message sanitization, pagination off-by-ones, and type narrowing
+  cleanups from Round 1 of the audit.
+
+### Internal
+
+- New helper: `tagUntrusted(value, maxLen)` in `src/utils.ts`
+- New helper: `resolveOpenFiscalYear(supabase, companyId)` in
+  `src/utils.ts`
+- New module: `src/compliance/rates.ts` with `FINNISH_RATES_2026` +
+  `freshnessMeta()`
+- New resource module: `src/resources/security.ts`
+- `database.types.ts` augmented with `get_next_customer_number` and
+  `get_next_offer_number` RPC signatures
+
+### Notes
+
+- M13 (`record_payment` TOCTOU) reviewed and downgraded to a nit — the
+  existing `record_invoice_payment` and `confirm_reconciliation_match`
+  RPCs already `SELECT … FOR UPDATE` the invoice row, so concurrent
+  callers are serialized at the DB layer.
+- Verified: `tsc --noEmit` clean, 101/101 unit tests pass, `esbuild`
+  bundle clean (885 KB).
+
 ## [0.5.0] - 2026-03-28
 
 ### Added

package/README.md

@@ -2,32 +2,38 @@
 
 MCP server for Finnish accounting. Exposes Kirjapro bookkeeping, invoicing, and reporting tools to Claude Code, Claude Desktop, and any MCP client.
 
-> **Full documentation:** [docs/mcp-server.md](../docs/mcp-server.md) — complete tool reference with parameters, usage examples, error guide, and multi-client setup.
+**Full documentation:** [kirjapro.fi/docs/mcp](https://kirjapro.fi/docs/mcp/)
 
 ## Requirements
 
 - Node.js 20+
-- Kirjapro account with **Company** or **Custom** subscription tier
+- Kirjapro account with **Entrepreneur**, **Company**, or **Custom** subscription tier
 - API key (generate at Settings > API-avaimet)
 
 ## Quick Start
 
 ### 1. Generate an API Key
 
-1. Go to **Settings > API-avaimet** in the Kirjapro app
+1. Go to **Asetukset > API-avaimet** in the [Kirjapro app](https://kirjapro.fi)
 2. Click **"Luo uusi avain"**
-3. Copy the key (shown only once)
+3. Copy the key (starts with `kp_`, shown only once)
 
 ### 2. Configure your MCP client
 
 #### Claude Code
 
-Add to `.claude/mcp.json`:
+Add to your project's `.mcp.json` (recommended) or global config:
+
+| OS | Project-level (recommended) | Global |
+|----|----------------------------|--------|
+| macOS / Linux | `.mcp.json` in project root | `~/.claude/mcp.json` |
+| Windows | `.mcp.json` in project root | `%USERPROFILE%\.claude\mcp.json` |
 
 ```json
 {
   "mcpServers": {
     "kirjapro": {
+      "type": "stdio",
       "command": "npx",
       "args": ["-y", "@kirjapro/mcp-server"],
       "env": {
@@ -38,10 +44,18 @@ Add to `.claude/mcp.json`:
 }
 ```
 
+Verify with `/mcp` in Claude Code.
+
 #### Claude Desktop
 
 Add to `claude_desktop_config.json`:
 
+| OS | Path |
+|----|------|
+| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
+| Linux | `~/.config/Claude/claude_desktop_config.json` |
+
 ```json
 {
   "mcpServers": {
@@ -56,119 +70,48 @@ Add to `claude_desktop_config.json`:
 }
 ```
 
+Restart Claude Desktop after saving.
+
+#### Other clients
+
+See [full setup guide](https://kirjapro.fi/docs/mcp/) for Cursor, VS Code / Copilot, Windsurf, and generic stdio.
+
 ### 3. Verify
 
-In Claude Code, run `/mcp` to see the available Kirjapro tools.
-
-## Environment Variables
-
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `KIRJAPRO_API_KEY` | Yes* | API key from Settings > API-avaimet |
-
-### Legacy (development only)
-
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `SUPABASE_URL` | Yes* | Supabase project URL |
-| `SUPABASE_ACCESS_TOKEN` | Yes* | User's JWT access token |
-| `KIRJAPRO_COMPANY_ID` | Yes* | Company UUID to operate on |
-
-*Either `KIRJAPRO_API_KEY` or all three legacy variables must be set.
-
-## Tools (40)
-
-### Read Tools
-
-| Tool | Description |
-|------|-------------|
-| `kirjapro_list_accounts` | List chart of accounts with filtering by type |
-| `kirjapro_list_transactions` | List transactions with journal entries for a fiscal year |
-| `kirjapro_search_transactions` | Search transactions by text, date range, or amount |
-| `kirjapro_get_transaction` | Get single transaction with journal entries and account details |
-| `kirjapro_list_invoices` | List invoices with customer names, filter by status |
-| `kirjapro_get_invoice` | Get single invoice with lines, payments, and VAT breakdown |
-| `kirjapro_list_customers` | List customers with search |
-| `kirjapro_get_customer` | Get single customer with invoice stats |
-| `kirjapro_list_bank_accounts` | List active bank accounts with balances |
-| `kirjapro_list_bank_transactions` | List bank transactions with filtering |
-| `kirjapro_list_fiscal_years` | List fiscal years with open/closed status |
-| `kirjapro_get_dashboard` | Financial dashboard: revenue, expenses, invoice stats, bank balances |
-| `kirjapro_get_income_statement` | Income statement (tuloslaskelma) for a date range |
-| `kirjapro_get_balance_sheet` | Balance sheet (tase) as of a specific date |
-| `kirjapro_get_ar_aging` | Accounts receivable aging (0-30, 31-60, 61-90, 90+ days) |
-| `kirjapro_get_general_ledger` | General ledger (pääkirja) for one account with running balance |
-| `kirjapro_list_templates` | List transaction templates for common bookkeeping patterns |
-| `kirjapro_list_offers` | List offers/contracts with customer names |
-| `kirjapro_get_offer` | Get offer detail with lines, events, and VAT breakdown |
-
-### Write Tools
-
-| Tool | Description |
-|------|-------------|
-| `kirjapro_create_transaction` | Create an accounting transaction with journal entries |
-| `kirjapro_create_transactions_batch` | Bulk create up to 50 transactions (partial success) |
-| `kirjapro_create_invoice` | Create invoice with auto-generated number and reference |
-| `kirjapro_create_customer` | Create customer with Y-tunnus validation |
-| `kirjapro_update_customer` | Update customer fields (partial update, re-validates Y-tunnus) |
-| `kirjapro_record_payment` | Record payment against an invoice |
-| `kirjapro_update_invoice_status` | Update invoice status with state machine validation |
-| `kirjapro_delete_invoice` | Delete draft invoices (audit-safe) |
-| `kirjapro_match_bank_transaction` | Match bank transaction to an invoice |
-| `kirjapro_create_from_template` | Create transaction from template with VAT splitting |
-| `kirjapro_create_from_template_batch` | Bulk create from templates (up to 50) |
-| `kirjapro_book_sale` | Book a sale with automatic VAT splitting (invoice/cash/prepaid) |
-| `kirjapro_book_purchase` | Book a purchase with VAT, reverse charge, or edustus |
-| `kirjapro_book_salary` | Book salary with 2026 Finnish social insurance rates |
-| `kirjapro_book_vat_settlement` | Book ALV-tilitys from journal entries |
-| `kirjapro_create_offer` | Create offer/contract with auto-generated number |
-| `kirjapro_update_offer_status` | Update offer status with state machine validation |
-| `kirjapro_delete_offer` | Delete draft offers/contracts |
-
-### Validation Tools
-
-| Tool | Description |
-|------|-------------|
-| `kirjapro_validate_business_id` | Validate Finnish Y-tunnus |
-| `kirjapro_validate_iban` | Validate Finnish IBAN |
-| `kirjapro_generate_reference` | Generate viitenumero with check digit |
-
-## Resources (4)
-
-| URI | Description |
-|-----|-------------|
-| `kirjapro://accounts/chart` | Finnish standard chart of accounts (YSE 2017) |
-| `kirjapro://vat-rates` | Finnish VAT rates (25.5%, 13.5%, 10%, 0%) |
-| `kirjapro://company/info` | Current company details |
-| `kirjapro://fiscal-years` | Fiscal years with open/closed status |
-
-## Development
-
-```bash
-cd mcp-server
-npm install
-npm run dev     # Run with tsx
-npm run build   # Build with esbuild
-npm test        # Run vitest
-npm run lint    # Type check
-```
+Ask your AI assistant: *"list my fiscal years"* — it should call `kirjapro_list_fiscal_years` and return your company's accounting periods.
+
+## What's included
 
-## Publishing
+**52 tools** across 13 domains:
 
-Releases are automated via GitHub Actions. To publish:
+| Domain | Tools | Examples |
+|--------|-------|---------|
+| Accounts | 1 | List chart of accounts with filtering |
+| Transactions | 5 | Create, search, get detail, batch import |
+| Templates | 3 | Auto-balanced entries with VAT splitting |
+| Invoices | 6 | Create, send, record payments, status management |
+| Customers | 5 | CRUD + PRH business lookup |
+| Banking | 3 | List accounts/transactions, match to invoices |
+| Reports | 6 | Dashboard, income statement, balance sheet, AR aging, general ledger, ALV summary |
+| Bookings | 4 | Purchase, sale, salary, VAT settlement — with automatic double-entry |
+| Offers | 7 | Offer/contract lifecycle, email send, convert to invoice |
+| Recurring | 6 | Recurring invoice templates |
+| Received | 2 | Received (purchase) invoices |
+| Fiscal Years | 1 | List fiscal years with status |
+| Validation | 3 | Y-tunnus, IBAN, viitenumero |
 
-1. Update version in `package.json`, `server.json`, and `src/index.ts`
-2. Update `CHANGELOG.md`
-3. Commit and tag: `git tag mcp-server/v0.3.0`
-4. Push: `git push origin mcp-server/v0.3.0`
+**9 resources** for reference data: chart of accounts, VAT rates, company info, fiscal years, and 5 Finnish compliance resources.
 
-The workflow validates version consistency, runs tests, publishes to npm, and creates a GitHub Release.
+See the [full tool reference](https://kirjapro.fi/docs/mcp/) for parameters, usage examples, and error handling.
 
 ## 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
-- All queries use the user's JWT with Row Level Security (RLS)
-- Automatic token refresh keeps long-running MCP sessions alive
-- Feature gate: requires `hasApiAccess` (Company/Custom tier)
+- All queries use Row Level Security (RLS) — users can only access their own company's data
+- Automatic token refresh keeps long-running sessions alive
 - Rate limiting: 10 auth requests per minute per key
+
+## License
+
+MIT