@kirjapro/mcp-server 0.5.5 → 0.5.7

package/CHANGELOG.md

@@ -1,5 +1,156 @@
 # Changelog
 
+## [0.5.7] - 2026-05-09
+
+Pre-launch trim and supply-chain hardening. Two coordinated changes shape
+the launch posture: a curated default surface that keeps the agent under
+the empirical tool-selection accuracy cliff, and a fingerprint guard that
+defends against silent description / annotation / inputSchema tampering
+between releases.
+
+### Added — `KIRJAPRO_MCP_SURFACE` env var
+
+- **Default `core` surface (26 of 53 tools)** — daily-use shape per 2025-2026
+  SOTA research (Anthropic Opus 4 dropped to 49% accuracy at large MCP
+  catalogs, recovered to 79.5% with Tool Search). 27 tools deferred:
+  booking shortcuts (`book_*`), templates, recurring invoices, received
+  invoices, batch tools, deletes, financial notes, manual offer status,
+  search/get_transaction, general_ledger, list_bank_accounts,
+  update_customer. All kept in code; restored on flip of
+  `KIRJAPRO_MCP_SURFACE=full`.
+- **Surface-aware `INSTRUCTIONS`** — common preamble + core-mode addendum
+  ("redirect to web UI for these workflows") OR full-mode addendum
+  ("extended workflows for the deferred set"). The agent never reads
+  workflow hints for tools missing from its `tools/list`. Closes the
+  worst-class failure mode: agent reaches for closest-match tool and
+  ships a one-off invoice when the user wanted a recurring template.
+- **Capabilities NOT in this MCP** section in `INSTRUCTIONS_COMMON` —
+  always-missing tasks (file uploads, bank account configuration,
+  e-invoice sending, multi-company switching, year-end disclosure form)
+  redirected to the web UI in any surface mode.
+- **Boot log** announces `surface=core — registered 26 tools, deferred 27`
+  or `surface=full — registered all 53 tools`. Unknown values fall back
+  to `core` with a stderr warning.
+- **`kirjapro-aloita`** prompt computes the active tool count dynamically
+  from `_registeredTools` size — accurate for both surfaces, no copy
+  drift.
+
+### Added — Tool description fingerprint guard
+
+- **`tool-fingerprints.json`** ships with the package. Each tool's
+  `description + annotations + inputSchema` is hashed via SHA-256
+  truncated to 64 bits and persisted alphabetically by tool name.
+  Defends against the rug-pull vector documented by Pipelock and CyberArk
+  — silent description tampering or schema relaxation between releases.
+- **CI guard** (`tools-registry.test.ts`) asserts the running build's
+  fingerprint set matches the persisted file. Failure message tells the
+  operator: bump `package.json` version and run
+  `npm run fingerprints:update` if intentional, revert otherwise.
+- **`fingerprints:update` script** logs every `ADDED` / `REMOVED` /
+  `CHANGED <name> <oldhash> → <newhash>` entry before writing. Silent
+  laundering of a malicious description through "version-bump + regen"
+  must also falsify CI logs to slip past review.
+- **Schema coverage in v0.5.7** — `inputSchema` now part of the hash
+  payload. v0.5.6 had description+annotations only, leaving Zod-enum
+  relaxation as a coverage gap. Closed in this release per the
+  pre-launch code review (docs/reviews/2026-05-09-mcp-fingerprint-guard.md).
+
+### Tests
+
+- **187 passing** (was 172 in v0.5.6). Three new registry tests cover
+  surface=core (26-tool exact match), deferred tools NOT registered, and
+  CORE_TOOL_NAMES is a strict subset of the full registration set. One
+  new test asserts current build matches the persisted fingerprint file.
+
+### Fixed
+
+- **Stale `52 tools` claim** in `INSTRUCTIONS` and the `kirjapro-aloita`
+  Finnish prompt — was last updated before DT-045 added
+  `kirjapro_get_financial_notes`. Both now derive count dynamically.
+- **Supabase CLI version banner pollution** in `database.types.ts` — the
+  CLI emits its update-notification banner to STDOUT, which had been
+  concatenated to the bottom of the generated file by a prior
+  `gen types ... > database.types.ts` redirect. Broke `tsc --noEmit`
+  inside `mcp-server/` until removed. Skill
+  `supabase-gen-types-cli-banner-pollution` documents the failure mode
+  and the `grep -v` filter pipeline that prevents it.
+
+### Notes
+
+- The npm package now ships `tool-fingerprints.json` alongside
+  `dist/index.js`. Downstream operators who want Pipelock-style pinning
+  can read the JSON and reject mid-release tampering.
+- Part of the broader MCP SOTA enhancement track filed in
+  `docs/roadmap/features/planned/mcp-server-*` — Phase 1 (observability,
+  per-call telemetry, CI fingerprint enforcement at scale) is sequenced
+  for post-launch when real traffic exists to inform the eager-tool set.
+
+## [0.5.6] - 2026-04-20
+
+Pre-production adversarial audit hardening. Ten findings verified and patched
+across auth, idempotency, numbering, account scoping, and calendar validation.
+No tool-surface changes — all tool names, parameters, and return shapes are
+stable. One nullable DB column added (`mcp_idempotency_keys.body_sha256`);
+legacy rows continue to work without backfill.
+
+### Security & correctness
+
+- **`.or()` grammar injection blocked** — `escapeOrValue()` percent-encodes
+  `,`, `(`, `)` before interpolation into PostgREST `.or(...)` filters. Applied
+  at all four sites: `accounts.ts`, `customers.ts`, `received-invoices.ts`,
+  `banking.ts`. Five new test cases.
+- **Audit-log IP source trustworthiness** — `mcp-auth` edge function prefers
+  `x-real-ip`, then `cf-connecting-ip`, then leftmost of `x-forwarded-for`
+  before attributing a request to a caller IP. Requires `--no-verify-jwt`
+  redeploy.
+- **Idempotency burst fail-open** — `withIdempotency()` now polls a pending
+  claim in `CLAIM_WAIT_MS` slices until either the response lands or the claim
+  ages past `CLAIM_STALE_MS`; on exhaustion returns an explicit `retry_later`
+  error instead of racing into a duplicate write.
+- **Idempotency body-hash check** (T3-6, migration
+  `20260420185239_mcp_idempotency_body_hash.sql`) — each claim stores
+  `sha256(canonical JSON of params ∖ idempotencyKey)`. On cache hit the server
+  recomputes and compares; mismatch returns `IDEMPOTENCY_BODY_MISMATCH`
+  instead of silently replaying the wrong cached response. Nullable column,
+  legacy rows and tests without params skip the check.
+- **`initLegacyAuth` bypass closed** — `auth.ts` requires explicit
+  `ALLOW_LEGACY_AUTH=true` opt-in; otherwise throws with an actionable error.
+  Opt-in path logs a deprecation warning.
+
+### Validation & data integrity
+
+- **`accountOverrides` allowlist** — `validateAccountOverrides()` in
+  `templates.ts` rejects missing or inactive target accounts, enforces type
+  parity with the source account, and merges per-line overrides while
+  rejecting conflicts where a single source maps to multiple targets.
+- **Calendar-invalid dates rejected at parse** — new `isValidCalendarDate()`
+  + `ISO_DATE_SCHEMA` helpers validate via UTC round-trip (Feb 31 no longer
+  silently rolls over to Mar 3). Wired across nine tool files (27 call sites);
+  month-only patterns (e.g. `YYYY-MM` on ALV-kausi) are intentionally not
+  swapped. Six new unit tests.
+- **Invoice-numbering RPC audit** (T3-5) — verified all three monotonic
+  mints (`customers`, `invoices`, `offers`) plus `convert_offer_to_invoice`
+  use advisory-locked server-side RPCs. No in-tool `MAX(n)+1` anywhere.
+  Documented as clean; no code change required.
+
+### Tooling
+
+- **Tests:** 172 passing (up from 154 in v0.5.5). +6 ISO_DATE_SCHEMA,
+  +6 validateAccountOverrides, +6 body-hash (4 hash-helper + 2
+  mismatch/match scenarios).
+- **Typecheck:** `tsc --noEmit` clean.
+
+### Deploy prerequisites
+
+Published artefact requires:
+
+1. Apply migration `20260420185239_mcp_idempotency_body_hash.sql` to the
+   Supabase project (adds nullable `body_sha256`). Missing column will NOT
+   break the server — the INSERT still succeeds with PostgREST schema-cache
+   tolerance — but the mismatch check will be inert until migrated.
+2. Redeploy `mcp-auth` edge function with `--no-verify-jwt` so the IP-source
+   hardening (T2-3) takes effect.
+
 ## [0.5.5] - 2026-04-11
 
 Tool-annotation sweep: every remaining `server.tool()` call migrated to

package/README.md

@@ -80,26 +80,51 @@ See [full setup guide](https://kirjapro.fi/docs/mcp/) for Cursor, VS Code / Copi
 
 Ask your AI assistant: *"list my fiscal years"* — it should call `kirjapro_list_fiscal_years` and return your company's accounting periods.
 
+### 4. Try these prompts
+
+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
+- *"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
+- *"Show overdue invoices"* — AR aging report
+- *"Match this bank deposit to invoice #42"* — bank reconciliation in one call
+
 ## What's included
 
-**49 tools** across 10 domains:
-
-| Domain | Tools | Examples |
-|--------|-------|---------|
-| Accounts | 1 | List chart of accounts with filtering |
-| Transactions | 4 | Create, search, batch import |
-| Templates | 3 | Auto-balanced entries with VAT splitting |
-| Invoices | 5 | Create, send, record payments, status management |
-| Customers | 4 | 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 | 5 | Offer/contract lifecycle management |
-| Recurring | 6 | Recurring invoice templates |
-| Received | 2 | Received (purchase) invoices |
-| Validation | 3 | Y-tunnus, IBAN, viitenumero |
-
-**9 resources** for reference data: chart of accounts, VAT rates, company info, fiscal years, and 5 Finnish compliance resources.
+**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 53-tool catalog (booking shortcuts, recurring invoices, templates, batch tools, etc.) is available via opt-in:
+
+```jsonc
+{
+  "mcpServers": {
+    "kirjapro": {
+      "command": "npx",
+      "args": ["-y", "@kirjapro/mcp-server"],
+      "env": {
+        "KIRJAPRO_API_KEY": "kp_your_key_here",
+        "KIRJAPRO_MCP_SURFACE": "full"   // 53 tools instead of 26
+      }
+    }
+  }
+}
+```
+
+**Why default to 26 instead of 53:** 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.
+
+| Domain (core) | Tools |
+|---|---|
+| 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` |
+| 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` |
+
+**Deferred in core, available with `KIRJAPRO_MCP_SURFACE=full`:** booking shortcuts (`book_*`), templates, recurring invoices, received invoices, batch tools, `delete_*`, `update_*` (besides invoice status), `search_transactions`, `get_transaction`, `get_general_ledger`, `list_bank_accounts`, `get_financial_notes`, manual offer status / list / get / delete.
+
+**11 resources** for reference data: chart of accounts, VAT rates, company info, fiscal years, 5 Finnish compliance resources, compliance freshness index, and security data-handling.
 
 See the [full tool reference](https://kirjapro.fi/docs/mcp/) for parameters, usage examples, and error handling.
 
@@ -110,6 +135,7 @@ See the [full tool reference](https://kirjapro.fi/docs/mcp/) for parameters, usa
 - 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
+- **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.
 
 ## License