@kirjapro/mcp-server 0.6.3 → 0.8.0

package/dist/tools/financialNotes.js

@@ -1,255 +0,0 @@
-import { z } from 'zod';
-import { getSupabase, getCompanyId } from '../auth.js';
-import { toErrorContent, toResult, sanitizeDbError, helsinkiDateString, formatFinnishDate, READ_ONLY_ANNOTATIONS, } from '../utils.js';
-/**
- * Liitetiedot (Notes to Financial Statements)
- *
- * Sister-tool of `kirjapro_get_income_statement` and `kirjapro_get_balance_sheet`
- * (skill `wave-sibling-rpc-doctrine-parity`):
- *   - Same input shape (company_id auto-derived from auth, fiscalYearId optional)
- *   - Same READ_ONLY_ANNOTATIONS (read-only, idempotent, closed-world)
- *   - Same toResult() / toErrorContent() envelope
- *
- * READ-ONLY by design (DT-045): the web form is the only write surface for
- * liitetiedot — finalization carries audit columns + 42501 lock semantics that
- * the UI is responsible for enforcing. AI agents read; humans finalize.
- *
- * Phase 1 (DT-045) added `finalized_at` and `finalized_by` to the row; this
- * tool surfaces them in `structuredContent` so the agent can render audit
- * status without separate calls.
- */
-/**
- * 11 user-facing liitetiedot fields, matching `FinancialNotes.tsx:FIELDS`
- * (10 narrative textarea + 1 numeric `henkilosto_lkm`). Used to compute
- * `filled_field_count` for the human-readable summary.
- */
-const NARRATIVE_FIELDS = [
-    'arvostusperiaatteet',
-    'poikkeukselliset_erat',
-    'tilikauden_jalkeiset',
-    'vakuudet_ja_vastuut',
-    'lainat_johdolle',
-    'henkiloston_maara',
-    'poistomenetelmat',
-    'pitkaikaiset_velat',
-    'oman_paoman_muutokset',
-    'olennaiset_tapahtumat',
-];
-const TOTAL_FIELD_COUNT = NARRATIVE_FIELDS.length + 1; // +1 for henkilosto_lkm
-const STATUS_ENUM = z.enum(['draft', 'final']);
-const FINANCIAL_NOTES_OUTPUT_SHAPE = {
-    fiscal_year_id: z.string().uuid(),
-    fiscal_year: z.object({
-        id: z.string().uuid(),
-        start_date: z.string(),
-        end_date: z.string(),
-        is_closed: z.boolean(),
-    }),
-    status: STATUS_ENUM,
-    finalized_at: z.string().nullable(),
-    finalized_by: z.string().nullable(),
-    arvostusperiaatteet: z.string(),
-    poikkeukselliset_erat: z.string(),
-    tilikauden_jalkeiset: z.string(),
-    vakuudet_ja_vastuut: z.string(),
-    lainat_johdolle: z.string(),
-    henkiloston_maara: z.string(),
-    poistomenetelmat: z.string(),
-    pitkaikaiset_velat: z.string(),
-    oman_paoman_muutokset: z.string(),
-    olennaiset_tapahtumat: z.string(),
-    henkilosto_lkm: z.number().nullable(),
-    filled_field_count: z.number(),
-    total_field_count: z.number(),
-    exists: z.boolean(),
-    note: z.string().optional(),
-};
-/**
- * Format finalized_at (ISO timestamp string) as "DD.MM.YYYY HH:MM" Finnish.
- * Returns null when input is null or unparseable so the caller can decide.
- */
-function formatFinnishTimestamp(iso) {
-    if (!iso)
-        return null;
-    const ms = Date.parse(iso);
-    if (Number.isNaN(ms))
-        return null;
-    // Render in Europe/Helsinki — the audit timestamp is for human review and
-    // should match the user's wall clock when they finalized.
-    const parts = new Intl.DateTimeFormat('fi-FI', {
-        timeZone: 'Europe/Helsinki',
-        year: 'numeric',
-        month: '2-digit',
-        day: '2-digit',
-        hour: '2-digit',
-        minute: '2-digit',
-        hour12: false,
-    }).formatToParts(new Date(ms));
-    const pick = (t) => parts.find((p) => p.type === t)?.value ?? '';
-    return `${pick('day')}.${pick('month')}.${pick('year')} ${pick('hour')}:${pick('minute')}`;
-}
-export function registerFinancialNotesTools(server) {
-    server.registerTool('kirjapro_get_financial_notes', {
-        description: 'Hae liitetiedot (notes to financial statements) yhdelle tilikaudelle. Palauttaa KPL 3:1 / PMA 3:2 mukaiset narratiivikentät (10), henkilöstön keskimääräinen lukumäärä, statuksen (draft/final) ja vahvistustiedot (finalized_at/by). READ-ONLY — luominen ja muokkaus tapahtuvat web-lomakkeella. If fiscalYearId is omitted, the fiscal year covering today (Europe/Helsinki) is auto-resolved.',
-        inputSchema: {
-            fiscalYearId: z
-                .string()
-                .uuid()
-                .optional()
-                .describe('Fiscal year UUID (auto-resolved to the FY covering today in Europe/Helsinki if omitted)'),
-        },
-        outputSchema: FINANCIAL_NOTES_OUTPUT_SHAPE,
-        annotations: READ_ONLY_ANNOTATIONS,
-    }, async (params) => {
-        const supabase = getSupabase();
-        const companyId = getCompanyId();
-        // Resolve fiscal year. Sister tool `kirjapro_get_balance_sheet` filters
-        // `is_closed=false` via `resolveOpenFiscalYear` — we mirror that posture
-        // here (skill `wave-sibling-rpc-doctrine-parity`). Auto-resolve picks the
-        // OPEN fiscal year covering today; if today falls inside a closed FY (a
-        // legitimate scenario when the new FY hasn't been provisioned yet), we
-        // surface a clear error instead of silently returning the closed row.
-        // An explicit `fiscalYearId` still works for closed FYs — read access is
-        // intentional for tilinpäätös history.
-        let fiscalYear;
-        if (params.fiscalYearId) {
-            const { data, error } = await supabase
-                .from('fiscal_years')
-                .select('id, start_date, end_date, is_closed')
-                .eq('company_id', companyId)
-                .eq('id', params.fiscalYearId)
-                .maybeSingle();
-            if (error) {
-                return toErrorContent(sanitizeDbError('Failed to load fiscal year', error));
-            }
-            if (!data) {
-                return toErrorContent(`Fiscal year ${params.fiscalYearId} not found. Use kirjapro_list_fiscal_years to find available fiscal years.`);
-            }
-            fiscalYear = data;
-        }
-        else {
-            const today = helsinkiDateString();
-            // Mirror resolveOpenFiscalYear posture (skill
-            // `wave-sibling-rpc-doctrine-parity`): error explicitly on 0 or >1
-            // matches rather than silently picking one. The date-range filter is
-            // intentional — liitetiedot is per-FY narrative, so we resolve to the
-            // open FY that covers TODAY rather than just any open FY (sister
-            // `kirjapro_get_balance_sheet` uses any-open semantics, which is fine
-            // for a balance sheet but wrong for a "this year's notes" surface).
-            // `.limit(2)` is the minimum needed to detect the >1 case.
-            const { data, error } = await supabase
-                .from('fiscal_years')
-                .select('id, start_date, end_date, is_closed')
-                .eq('company_id', companyId)
-                .eq('is_closed', false)
-                .lte('start_date', today)
-                .gte('end_date', today)
-                .order('end_date', { ascending: false })
-                .limit(2);
-            if (error) {
-                return toErrorContent(sanitizeDbError('Failed to resolve current fiscal year', error));
-            }
-            if (!data || data.length === 0) {
-                return toErrorContent(`No open fiscal year covers today (${today}). The fiscal year covering today may be closed, or no fiscal year has been created. Specify fiscalYearId explicitly (closed years are still readable) or list fiscal years with kirjapro_list_fiscal_years.`);
-            }
-            if (data.length > 1) {
-                return toErrorContent(`Multiple open fiscal years cover today (${data.length}). Specify fiscalYearId explicitly. Use kirjapro_list_fiscal_years to list them.`);
-            }
-            fiscalYear = data[0];
-        }
-        // Fetch the liitetiedot row. RLS enforces company_id isolation, but we
-        // still pass it explicitly so a misconfigured policy can't widen access
-        // (CLAUDE.md §12 cross-company isolation).
-        // Long select strings return PostgREST `GenericStringError | T` because
-        // supabase-js can't compile the column list at the type level — narrow
-        // back to the row type below after error-branching.
-        const { data: row, error: rowError } = await supabase
-            .from('liitetiedot')
-            .select('id, fiscal_year_id, status, finalized_at, finalized_by, ' +
-            'arvostusperiaatteet, poikkeukselliset_erat, tilikauden_jalkeiset, ' +
-            'vakuudet_ja_vastuut, lainat_johdolle, henkiloston_maara, ' +
-            'poistomenetelmat, pitkaikaiset_velat, oman_paoman_muutokset, ' +
-            'olennaiset_tapahtumat, henkilosto_lkm')
-            .eq('company_id', companyId)
-            .eq('fiscal_year_id', fiscalYear.id)
-            .maybeSingle();
-        if (rowError) {
-            return toErrorContent(sanitizeDbError('Failed to load financial notes', rowError));
-        }
-        const normalizedRow = row ?? null;
-        const status = normalizedRow?.status === 'final' ? 'final' : 'draft';
-        // Build the text payload. Empty placeholder when no row exists yet —
-        // matches the web hook's EMPTY_LIITETIEDOT shape so agents see consistent
-        // structure regardless of fill state.
-        const fields = {
-            arvostusperiaatteet: normalizedRow?.arvostusperiaatteet ?? '',
-            poikkeukselliset_erat: normalizedRow?.poikkeukselliset_erat ?? '',
-            tilikauden_jalkeiset: normalizedRow?.tilikauden_jalkeiset ?? '',
-            vakuudet_ja_vastuut: normalizedRow?.vakuudet_ja_vastuut ?? '',
-            lainat_johdolle: normalizedRow?.lainat_johdolle ?? '',
-            henkiloston_maara: normalizedRow?.henkiloston_maara ?? '',
-            poistomenetelmat: normalizedRow?.poistomenetelmat ?? '',
-            pitkaikaiset_velat: normalizedRow?.pitkaikaiset_velat ?? '',
-            oman_paoman_muutokset: normalizedRow?.oman_paoman_muutokset ?? '',
-            olennaiset_tapahtumat: normalizedRow?.olennaiset_tapahtumat ?? '',
-            henkilosto_lkm: typeof normalizedRow?.henkilosto_lkm === 'number'
-                ? normalizedRow.henkilosto_lkm
-                : null,
-        };
-        // Field-fill counter — narrative fields count when their trimmed length
-        // is > 0; henkilosto_lkm counts when it's a number (zero is a legitimate
-        // disclosure for "no employees").
-        let filledFieldCount = 0;
-        for (const key of NARRATIVE_FIELDS) {
-            const v = fields[key];
-            if (typeof v === 'string' && v.trim().length > 0)
-                filledFieldCount++;
-        }
-        if (typeof fields.henkilosto_lkm === 'number')
-            filledFieldCount++;
-        const exists = normalizedRow !== null;
-        const note = exists
-            ? undefined
-            : 'Liitetietoja ei vielä luotu tälle tilikaudelle.';
-        const payload = {
-            fiscal_year_id: fiscalYear.id,
-            fiscal_year: {
-                id: fiscalYear.id,
-                start_date: fiscalYear.start_date,
-                end_date: fiscalYear.end_date,
-                is_closed: fiscalYear.is_closed,
-            },
-            status,
-            finalized_at: normalizedRow?.finalized_at ?? null,
-            finalized_by: normalizedRow?.finalized_by ?? null,
-            ...fields,
-            filled_field_count: filledFieldCount,
-            total_field_count: TOTAL_FIELD_COUNT,
-            exists,
-            ...(note ? { note } : {}),
-        };
-        // Human-readable summary line in `content[0].text` — matches sister tools'
-        // toResult() shape but the JSON is fronted by a Finnish status sentence
-        // for agents that don't parse structuredContent. Plan §4 Wave 1C wording.
-        const yearLabel = fiscalYear.start_date.slice(0, 4);
-        const statusLabel = status === 'final' ? 'Valmis' : 'Luonnos';
-        const finalizedFi = formatFinnishTimestamp(payload.finalized_at);
-        const finalizedSentence = status === 'final' && finalizedFi
-            ? ` Vahvistettu ${finalizedFi}.`
-            : '';
-        const summary = `Liitetiedot tilikaudelle ${yearLabel} ` +
-            `(${formatFinnishDate(fiscalYear.start_date)} – ${formatFinnishDate(fiscalYear.end_date)}, ` +
-            `status: ${statusLabel}).${finalizedSentence} ` +
-            `Täytetyt kentät: ${filledFieldCount} / ${TOTAL_FIELD_COUNT}.`;
-        const result = toResult(payload);
-        // Prepend the summary line so MCP clients displaying only `content` see
-        // the human-readable status before the JSON blob.
-        return {
-            ...result,
-            content: [
-                { type: 'text', text: summary },
-                ...result.content,
-            ],
-        };
-    });
-}

package/dist/tools/fingerprints.d.ts

@@ -1,6 +0,0 @@
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-export interface ToolFingerprint {
-    name: string;
-    hash: string;
-}
-export declare function computeFingerprints(server: McpServer): ToolFingerprint[];

package/dist/tools/fingerprints.js

@@ -1,28 +0,0 @@
-import { createHash } from 'node:crypto';
-function canonicalize(value) {
-    if (value === null || value === undefined)
-        return 'null';
-    if (typeof value === 'function')
-        return 'fn';
-    if (typeof value !== 'object')
-        return JSON.stringify(value);
-    if (Array.isArray(value)) {
-        return `[${value.map(canonicalize).join(',')}]`;
-    }
-    const keys = Object.keys(value).sort();
-    const entries = keys.map((k) => `${JSON.stringify(k)}:${canonicalize(value[k])}`);
-    return `{${entries.join(',')}}`;
-}
-function hashTool(tool) {
-    const canonical = canonicalize({
-        description: tool.description ?? '',
-        annotations: tool.annotations ?? {},
-        inputSchema: tool.inputSchema ?? {},
-    });
-    return createHash('sha256').update(canonical).digest('hex').slice(0, 16);
-}
-export function computeFingerprints(server) {
-    const registered = server._registeredTools;
-    const names = Object.keys(registered).sort();
-    return names.map((name) => ({ name, hash: hashTool(registered[name]) }));
-}

package/dist/tools/fiscal-years.d.ts

@@ -1,2 +0,0 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-export declare function registerFiscalYearTools(server: McpServer): void;

package/dist/tools/fiscal-years.js

@@ -1,35 +0,0 @@
-import { getSupabase, getCompanyId } from '../auth.js';
-import { z } from 'zod';
-import { toResult, toErrorContent, sanitizeDbError, READ_ONLY_ANNOTATIONS } from '../utils.js';
-export function registerFiscalYearTools(server) {
-    server.registerTool('kirjapro_list_fiscal_years', {
-        description: 'List fiscal years (tilikaudet) for the company. Shows start/end dates and open/closed status. Many tools require a fiscal year ID — use this to find the right one.',
-        inputSchema: {},
-        outputSchema: {
-            fiscal_years: z.array(z.object({
-                id: z.string().uuid(),
-                start_date: z.string(),
-                end_date: z.string(),
-                is_closed: z.boolean(),
-                created_at: z.string(),
-            }).passthrough()),
-            count: z.number(),
-        },
-        annotations: READ_ONLY_ANNOTATIONS,
-    }, async () => {
-        const supabase = getSupabase();
-        const companyId = getCompanyId();
-        const { data, error } = await supabase
-            .from('fiscal_years')
-            .select('id, start_date, end_date, is_closed, created_at')
-            .eq('company_id', companyId)
-            .order('start_date', { ascending: false });
-        if (error) {
-            return toErrorContent(sanitizeDbError("Failed to list fiscal years", error));
-        }
-        return toResult({
-            fiscal_years: data || [],
-            count: (data || []).length,
-        });
-    });
-}

package/dist/tools/index.d.ts

@@ -1,9 +0,0 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-export type Surface = 'core' | 'full';
-export declare const CORE_TOOL_NAMES: ReadonlySet<string>;
-interface RegisterToolsOptions {
-    surface?: Surface;
-}
-export declare function resolveSurface(explicit?: Surface): Surface;
-export declare function registerTools(server: McpServer, options?: RegisterToolsOptions): void;
-export {};

package/dist/tools/index.js

@@ -1,105 +0,0 @@
-import { registerAccountTools } from './accounts.js';
-import { registerTransactionTools } from './transactions.js';
-import { registerInvoiceTools } from './invoices.js';
-import { registerCustomerTools } from './customers.js';
-import { registerReportTools } from './reports.js';
-import { registerBankingTools } from './banking.js';
-import { registerValidationTools } from './validation.js';
-import { registerFiscalYearTools } from './fiscal-years.js';
-import { registerTemplateTools } from './templates.js';
-import { registerBookingTools } from './bookings.js';
-import { registerOfferTools } from './offers.js';
-import { registerRecurringInvoiceTools } from './recurring-invoices.js';
-import { registerReceivedInvoiceTools } from './received-invoices.js';
-import { registerFinancialNotesTools } from './financialNotes.js';
-// 26 tools that ship in the default `core` surface — the daily-use shape that
-// keeps the agent under the empirical degradation cliff (~25-50 tools per
-// 2025-2026 SOTA research) while preserving the headline workflows (read books,
-// invoice flow, transactions + banking, contract create→send→convert).
-//
-// Adjust this list based on Phase 1 observability data post-launch (see
-// roadmap: mcp-server-progressive-disclosure). Adding a tool here — and only
-// here — promotes it from deferred to eager.
-export const CORE_TOOL_NAMES = new Set([
-    // Read everything
-    'kirjapro_list_fiscal_years',
-    'kirjapro_list_accounts',
-    'kirjapro_get_dashboard',
-    'kirjapro_get_income_statement',
-    'kirjapro_get_balance_sheet',
-    'kirjapro_get_alv_summary',
-    'kirjapro_get_ar_aging',
-    // Customers
-    'kirjapro_list_customers',
-    'kirjapro_get_customer',
-    'kirjapro_create_customer',
-    'kirjapro_lookup_business',
-    // Invoice lifecycle
-    'kirjapro_list_invoices',
-    'kirjapro_get_invoice',
-    'kirjapro_create_invoice',
-    'kirjapro_record_payment',
-    'kirjapro_update_invoice_status',
-    // Transactions + banking
-    'kirjapro_list_transactions',
-    'kirjapro_create_transaction',
-    'kirjapro_list_bank_transactions',
-    'kirjapro_match_bank_transaction',
-    // Contracts (create → send → convert)
-    'kirjapro_create_offer',
-    'kirjapro_send_offer',
-    'kirjapro_convert_offer_to_invoice',
-    // Pure validators (zero database cost, useful for any agent flow)
-    'kirjapro_validate_business_id',
-    'kirjapro_validate_iban',
-    'kirjapro_generate_reference',
-]);
-export function resolveSurface(explicit) {
-    if (explicit)
-        return explicit;
-    const env = process.env.KIRJAPRO_MCP_SURFACE?.toLowerCase();
-    if (env === 'full')
-        return 'full';
-    if (env === 'core')
-        return 'core';
-    if (env && env !== 'core') {
-        console.error(`[kirjapro-mcp] Unknown KIRJAPRO_MCP_SURFACE="${env}" — falling back to "core". ` +
-            `Valid values: "core" (default, 26 tools), "full" (52 tools).`);
-    }
-    return 'core';
-}
-export function registerTools(server, options = {}) {
-    const surface = resolveSurface(options.surface);
-    registerAccountTools(server);
-    registerTransactionTools(server);
-    registerTemplateTools(server);
-    registerBookingTools(server);
-    registerInvoiceTools(server);
-    registerCustomerTools(server);
-    registerReportTools(server);
-    registerBankingTools(server);
-    registerValidationTools(server);
-    registerFiscalYearTools(server);
-    registerOfferTools(server);
-    registerRecurringInvoiceTools(server);
-    registerReceivedInvoiceTools(server);
-    registerFinancialNotesTools(server);
-    if (surface === 'core') {
-        // Strip deferred tools from the registered map. Each register*Tools()
-        // function keeps its own local logic intact (no scattered surface-flag
-        // gates); we centralize the trim here so the deferred set is one list.
-        const internals = server;
-        let removed = 0;
-        for (const name of Object.keys(internals._registeredTools)) {
-            if (!CORE_TOOL_NAMES.has(name)) {
-                delete internals._registeredTools[name];
-                removed++;
-            }
-        }
-        console.error(`[kirjapro-mcp] surface=core — registered ${CORE_TOOL_NAMES.size} tools, deferred ${removed}. ` +
-            `Set KIRJAPRO_MCP_SURFACE=full to access the complete tool catalog.`);
-    }
-    else {
-        console.error(`[kirjapro-mcp] surface=full — registered all 52 tools (CORE_TOOL_NAMES bypass active).`);
-    }
-}

package/dist/tools/invoices.d.ts

@@ -1,2 +0,0 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-export declare function registerInvoiceTools(server: McpServer): void;