@kirjapro/mcp-server 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+## [0.2.0] - 2026-02-19
+
+### Added
+
+- **npm publish infrastructure** — version validation, GitHub Releases on tag push
+- `kirjapro_get_invoice` — get single invoice with lines, payments, and VAT breakdown
+- `kirjapro_get_transaction` — get single transaction with journal entries and account details
+- `kirjapro_list_bank_accounts` — list active bank accounts with balances
+- `kirjapro_list_bank_transactions` — list/filter bank transactions (unreconciled, date range, search)
+- `kirjapro_list_fiscal_years` — list fiscal years as a tool (complements the resource)
+- `kirjapro_get_general_ledger` — general ledger for one account with running balance
+- `kirjapro_update_invoice_status` — update invoice status with state machine validation
+- `kirjapro_update_customer` — partial update customer fields with Y-tunnus re-validation
+- `kirjapro_get_customer` — get single customer with invoice stats
+- `kirjapro_delete_invoice` — delete draft invoices (audit-safe: sent/paid must be cancelled first)
+
+### Changed
+
+- Version bumped to 0.2.0 across package.json, server.json, and index.ts
+- Fixed `server.json` repository URL
+- Added `publishConfig`, `repository`, `bugs`, `homepage`, and `peerDependencies` to package.json
+- Fixed `InvoiceStatus` type to include `partial` status
+- Fixed `BankTransaction` type: `counterpart_name` → `counterparty_name` to match DB schema
+
+## [0.1.0] - 2026-02-16
+
+### Added
+
+- Initial release with 17 tools, 4 resources
+- Authentication via API key or legacy JWT
+- Chart of accounts, transactions, invoices, customers, reports
+- Finnish reference number generation and Y-tunnus validation
+- Bank transaction matching
+- Income statement, balance sheet, AR aging reports

package/README.md

@@ -0,0 +1,160 @@
+# @kirjapro/mcp-server
+
+MCP server for Finnish accounting. Exposes Kirjapro bookkeeping, invoicing, and reporting tools to Claude Code, Claude Desktop, and any MCP client.
+
+## Requirements
+
+- Node.js 20+
+- Kirjapro account with **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
+2. Click **"Luo uusi avain"**
+3. Copy the key (shown only once)
+
+### 2. Configure your MCP client
+
+#### Claude Code
+
+Add to `.claude/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "kirjapro": {
+      "command": "npx",
+      "args": ["-y", "@kirjapro/mcp-server"],
+      "env": {
+        "KIRJAPRO_API_KEY": "kp_your_key_here"
+      }
+    }
+  }
+}
+```
+
+#### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "kirjapro": {
+      "command": "npx",
+      "args": ["-y", "@kirjapro/mcp-server"],
+      "env": {
+        "KIRJAPRO_API_KEY": "kp_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### 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 (28)
+
+### 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 |
+
+### 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 |
+
+### 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
+```
+
+## Publishing
+
+Releases are automated via GitHub Actions. To publish:
+
+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.2.0`
+4. Push: `git push origin mcp-server/v0.2.0`
+
+The workflow validates version consistency, runs tests, publishes to npm, and creates a GitHub Release.
+
+## 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)
+- Rate limiting: 10 auth requests per minute per key