fynsight: MCP server for DATEV

Create a new budget plan. Version is auto-incremented for plans with the same name and year. FORECAST CONVENTION: a plan with type=forecast must contain the ACTUAL values of the already closed months PLUS the forecast for the remaining months of the year — otherwise year and YTD comparisons against actuals are wrong. Read the actuals of the closed months (e.g. get_periodic_summaries, category_totals) and load them together with the forecast via upload-budget-entries as category entries.

Budget (Soll) vs actual (Ist) with variance and YTD summary. Requires plan_id from list_budget_plans. detail=summary omits period_rows and row_count (use it for KPI-only questions). Besides the per-category rows (period_rows, ytd_summary) the response carries derived P&L metrics for plan AND actual: `metrics` (per period) and `metrics_ytd` (all periods of the response) with revenue, other_income, cogs, opex, depreciation, financial, tax, gross_margin, ebitda, ebit, ebt and net_income (= Jahresueberschuss), each with budget, actual, variance and variance_pct. They are computed from tenant_config.pnl_labels exactly like get_periodic_summaries.metrics — do NOT sum categories yourself. `unmapped_categories` lists categories with amounts but no subtotal_group (not part of any metric). With cost_center set, actuals of the metrics are tenant-wide (see metrics_note). Account level (granularity=account): one row per account/sub-account of the plan, key "8400" (the main account = sub-account 000, compared against the actuals of the main account only) or "8400/130" (a specific sub-account, compared against that sub-account only) — the two never overlap and are not summed.

List all budget plans for the tenant. Returns id, name, year, version, status, type. Call this first before get_budget_vs_actual to find the plan_id.

Get list of all cost centers with their IDs and names. Use this to answer questions about what cost centers exist. Rows carry `hidden: true` when the tenant has hidden that cost center in the app (Issue #89) — it still holds bookings and still counts towards company-wide figures, but nobody selects it any more. List hidden cost centers last and say that they are hidden; answer questions about a specific one normally.

Search individual transactions. Returns period, cost_center, account, amount, description, transaction_date (day-exact booking date), contra_account, sub_account, contra_sub_account (sub-account of the account/contra account, null if none), plus `id` (use this as transaction_id for propose-transaction-correction) and `source` ("upload" or "manual"). Each row also reports `correction_status` ("none" | "pending" | "corrected") and `correction_role` (null | "reversal" | "rebooking") so you can see whether a booking already has an open or approved correction, or is itself the reversal/re-booking line of one — check this before calling propose-transaction-correction to avoid duplicate proposals. With truncated=true not all matches were loaded — FIRST call the tool again with a higher limit_count (default 200, maximum 1000); only if limit_count=1000 still returns truncated=true, narrow down via periods/cost_centers/accounts/text_query/date_from/date_to. Never claim 'no further data'. Use available_range. text_query searches the term literally as a case-insensitive substring in description OR reference; % and _ are NOT wildcards but are searched as characters ("25%" only finds "25%", not "2500"). With group_by the tool returns bookings grouped by period and/or cost center instead of the flat row list. Take counts only from total_count (returned bookings), group_count (groups) or transaction_count per group — never count yourself and never state limit_count as a count. This tool returns individual bookings; for sums (per month, cost center or account) call compute_aggregates instead of adding up the rows yourself. If the user names a cost center (e.g. "Betriebsrat"), call get_cost_center_list FIRST to resolve its number; never guess the number.

List manual correction bookings (proposals and approved) for the tenant. Filter by status (pending, approved, rejected) and/or period.

Edit a PENDING manual correction proposal (amount, account, cost center, description, note, period). Approved bookings cannot be edited — delete them in the app instead.

Propose a manual correction booking (Korrekturbuchung) for a month — e.g. an unbooked invoice or an anomaly correction. This does NOT post to the ledger: it creates a PENDING proposal that a human must approve in the web app. Use when the user wants to add a missing cost/revenue on a specific account and cost center.

Propose a correction to an EXISTING ledger booking — wrong cost center, wrong account, wrong amount, or wrong month. This does NOT change the original booking and does NOT post to the ledger: it creates a PENDING proposal that a human approves in the web app. On approval a reversal of the original booking plus a corrected re-booking are written. Find the transaction id with `search_cost_center_transactions` first. Use `propose-manual-adjustment` instead when adding a booking that does not exist yet.

P&L metrics per cost center and period across the full history, paginated. `revenue` is the sum of ALL labels in the tenant's revenue group — sales deductions and penalties booked on revenue-group labels are already netted in; with include_categories=true you see the split per label (category_totals, result effect: revenue +, expense −), and revenue is then the sum of the revenue-group categories. Pages losslessly over cost_center via after_cost_center/next_cursor (with categories each row counts several times against the page budget; the response states the weight). Use available_range to state the overall time range; never claim 'no data' when available_range says otherwise. For yearly/quarterly figures (e.g. 'EBIT per year per cost center') set granularity — the tool then returns the finished yearly figure instead of you adding up monthly values. Hidden cost centers stay included and are marked as hidden on each row. If the user names a cost center (e.g. "Betriebsrat"), call get_cost_center_list FIRST to resolve its number; never guess the number.

Get all accounts with their labels and categories for this tenant. Filter by the 'category' field, NOT account numbers. Use the system prompt's tenant-specific category lists to identify revenue vs. cost accounts. Ignore: 'Bank', 'Cash', 'VAT'. Optional filters: exact category, account number range (account_from/account_to), and is_pnl (P&L vs. balance sheet accounts). Omit 'limit' to get every matching account (paginated internally, no row cap); pass it only to cap the number of rows returned — the response then reports whether the result was truncated.

Answer an open clarification question raised for an anomaly case. Records the answer only; it does NOT approve any correction (corrections are approved by the user in the app).

For a Monatsreporting run, list every P&L position and whether it is commented, has an AI draft, or is still open. Covers P&L lines, summary metrics, cost centers and the total, each with a shareable deeplink and the published/draft comment text (body). Optional filters target_type and state. READ ONLY.

Main calculation tool for sums, MoM, YoY, shares. Supports cost_centers, accounts, text_query filters. Use for ALL aggregations. Pages losslessly over groups via after_group/next_cursor; use available_range and never claim 'no data' when it shows data. For yearly/quarterly/overall figures set granularity instead of summing months yourself; totals.sum is the total over all periods in scope regardless of granularity. mom/yoy compare with the previous bucket inside the requested window; for the calendar previous month use get_periodic_summaries with include_previous. With group_by=account every sub-account is its own group: the group key carries account, sub_account (null = none) and account_ref ("8400/130" or "8400"). If the user names a cost center (e.g. "Betriebsrat"), call get_cost_center_list FIRST to resolve its number; never guess the number. `scope` says what the result covers. scope.pnl_reconciled=true means each month was cross-checked against the P&L; a warning then means bookings are missing — pass it on with period, both amounts and the difference. With text_query, cost_centers or categories the result is a subset by design and is not reconciled against the P&L, so never call it provisional or incomplete for that reason. With text_query, scope.text_match gives matched_sum (the result), unfiltered_sum (all bookings of the same accounts, cost centers and months without the search term) and matched_share_pct: name the result together with unfiltered_sum and the share, e.g. 'X € of Y € on these accounts (Z %)'.

Create an AI DRAFT explanation (status ai_draft) for a position of the month report. The draft has a short form (`summary`: one sentence saying why the number deviates, no figures) and an optional `detail` (may name single amounts from the material). The material is the position's figures plus the notes and clarification answers of the decided cases of the run that belong to it. Drafts are only created on request (here or by a click in the app), never automatically: check list-comment-status first and draft only for positions that are still open. It is NEVER published automatically — the user reviews and publishes it in the app. The response returns `summary` and `detail`. Existing explanations are never overwritten silently (see replace_published).

Generate a structured financial report as JSON. Supports P&L statement, KPI dashboard, and category breakdown report types.

Create the first report draft of a run whose figures a person has already approved in the app (run status approved). Any other status is rejected with the status named; regenerating an existing report is not possible here (it can mark edited texts for review or drop them) and stays in the app. Fynsight's own AI writes the driver sentences of the headlines and the three summary sentences from the computed figures and the published explanations, so the figures and explanation texts of this period are sent to Fynsight's AI provider (see data flows in the documentation). The result is a DRAFT: it is reviewed, published and signed off in the app. If building the report fails, the run goes to failed (a new run and a new approval are then needed). Returns the deeplink to the report.

Calculate KPI values for a given period. Returns each KPI with value, previous-period value, and month-over-month change. Use for KPI-specific questions.

Time series for a SINGLE named metric across periods, with month-over-month AND year-over-year change already computed (value, change, change_percentage, yoy_change, yoy_change_percentage, compared_period per point). Use this for 'how does X develop over time' questions about one bucket (revenue, other_income, cogs, opex, depreciation, financial, tax), one derived P&L aggregate (gross_margin, ebitda, ebit, ebt, net_income), or one P&L category from tenant_config.pnl_labels. Prefer get_periodic_summaries instead when you need ALL metrics for a period at once (no single-metric filter, but it does have sort_order/include_previous); prefer compute_aggregates instead for account/cost-center/category SUMS with grouping, share, or cumulative — compute_aggregates cannot compute the derived P&L aggregates (ebitda etc.) this tool knows about. Time range: `periods` (a COUNT of the most recent periods, default 12) or `date_from`/`date_to` — not a period list like other tools.

Get the status of a Monatsreporting run (month-end close): its phase plus the number of open anomaly cases, open clarification questions and open follow_up checks (follow_ups_open). Pass period (YYYY-MM) to get the active run of that month (not superseded or failed); without a run for it the answer says so. run_id takes precedence over period; with neither, the most recent run is returned. READ ONLY. Starting a run is also possible with start-month-run; approving, publishing and closing happen only in the app.

Write the reporting note (Reporting-Vermerk) of an open anomaly case: e.g. "one-off consulting invoice". The month report shows explanations, not case notes: once the case is decided in the app, the note becomes material from which the explanation draft of the position is written. It changes ONLY this note, never the case status — deciding a case (resolved/dismissed) happens in the app. A case that already has a note is rejected (CASE_NOTE_EXISTS, existing_note returned) unless replace is true; only pass replace after the user asked to overwrite. Only possible before the figures are approved (run status up to awaiting_approval); from approved on, and for decided cases, the call is rejected. The internal processing note is never touched.

Summarize anomaly cases of a Monatsreporting run by default (counts, sums, top cases); view cases lists single cases, filtered and paginated. status: open (default), decided (resolved/dismissed) or all. Filters for both views: kind, severity, category (label name; ambiguous names are rejected, then pass pnl_label_id), pnl_label_id, cost_center, min_abs_delta. by_cost_center entries carry hidden (cost center hidden in the app); they are marked, never dropped. Amounts (actual, reference, delta = actual - reference, delta_pct) are taken unchanged from the detection rules and follow their sign convention; only budget_deviation and mom_outlier carry delta (sign_flip fills actual from current, duplicate_suspicion from amount, missing_account has no amount). Sums (sum_abs_delta) are given per kind only, never mixed across kinds; kinds without delta report sum_abs_delta null and cases_without_delta. commentary is the case note (Reporting-Vermerk): while the case is open it is material for the comment of the position; once a person accepts the comment in the app it holds the short form of that comment. The report shows the comments (see list-comment-status), not case notes. commentary_source says who wrote the note (ai = AI review, user = a person, null = older case). follow_up is a check of an earlier watch item (the case carries watch with the original statement and the result of the check: recurred true/false/null from the detection, position_missing true when the position could not be assessed in this month - then it is never "did not recur"). Each case carries clarification (the one open or answered question with its context, suggestions and answer) or null; the summary counts open_clarifications and follow_ups. updated_at is the last change of the case (not the decision time). READ ONLY.

List every organisation the authenticated user is a member of. Each entry reports the user's role, whether the org is a holding (is_holding, derived from its holding entitlement), and which org is currently active for this MCP session (is_active=true). parent_organization_id holds the parent organisation's ID for a child organisation, and null otherwise; parent_relation says what kind of child it is: 'client' (client tenant of a service provider) or 'subsidiary' (subsidiary of a holding), null for an organisation without a parent.

P&L summaries per period: metrics (EBIT, EBITDA, margins) and category_totals. For a yearly or quarterly figure set granularity — the tool then sums the months and re-derives the metrics itself. Each summary's metrics.category_totals_sort_order gives the GuV-Explorer display order per category (lower sorts first). Per-account balances are NOT returned by default (keeps the answer small): set include_account_totals=true to get `totals` per summary, but for account questions prefer compute_aggregates. Set include_previous for a ready-made deviation report against the CALENDAR predecessor (previous month/quarter/year; loaded automatically if not requested, granularity total has none): each summary gets previous_period, previous_comparison (per headline figure: current, previous, delta_absolute, delta_percentage) and delta_category_totals (same keys as category_totals, i.e. the current label name, with label_ids, current, previous and the deltas; the current value equals the category_totals value of the same key). A category without bookings in a period that has computed metrics counts as 0, not null; delta_percentage is null when the previous value is 0. All deltas are null (never 0) when a side has no computed metrics. For quarter/year, if the current bucket or its predecessor covers fewer months than the bucket length (3/12; see months_covered and previous_months_covered), all deltas are null and a warning names the period. There is no previous_metrics and no top-level delta_absolute/delta_percentage.

Start the Monatsreporting run (month-end close) for a month. It only starts when that month has NO run yet (any status except failed/superseded counts, including signed-off months): otherwise nothing is written and the existing run is returned with already_exists true, its status and a deeplink, so calling it twice is safe. It NEVER replaces a run — restarting happens only in the app, with confirmation. The month must have booking data, otherwise NO_DATA_FOR_PERIOD is returned and no run is created. Starting normalizes the figures, collects anomaly cases and checks due watch items against them (no approval). Nothing runs in the background afterwards: AI reviews and comment drafts are created only when a person asks for them in the app. Ask the user before starting. Next steps: get-month-run-status, list-open-anomaly-cases.

Switch the active organisation for subsequent MCP tool calls (e.g. get_periodic_summaries, query_kpis). The user must be a member and the target org must have an active subscription.

Insert or update budget entries (monthly values) for a plan. Exactly one of category, account, or knw_row_number must be set per entry. An account entry may name one sub-account as part of the account, e.g. "8400/130" (slash, as shown in the app) — there is no separate sub_account parameter. The main account is sub-account 000: "8400" and "8400/000" mean the same and are compared against the actuals of the main account ONLY (not the sum of the sub-accounts; main-account and sub-account entries never overlap). If the account has no main account but exactly ONE sub-account, that one is used; if it has SEVERAL, the entry is rejected (BUDGET_ACCOUNT_AMBIGUOUS, the sub-accounts are listed) — name one ("8500/130"). A sub-account that does not exist for the tenant is rejected (BUDGET_ACCOUNT_UNKNOWN). An account unknown to the tenant is still accepted. Amounts are signed (expenses negative); plans created from a file upload that store expenses as positive magnitudes are rejected. For a forecast plan (type=forecast) the entries must cover the ACTUAL values of the closed months plus the forecast of the remaining months — read the closed months e.g. via get_periodic_summaries (category_totals) and include them as category entries; a forecast without the closed months makes the year/YTD comparison wrong. A category name that matches no P&L label is rejected with the list of valid category names and nothing is written.

Result bridge for a month: EBITDA, EBIT and net income from a comparison value to actual, step by step per P&L category. READ ONLY. compare_to: previous_month, previous_quarter_month, previous_year or budget (plan_id optional, only with budget; default is the active plan of the year of the period, without one the call fails with NO_ACTIVE_BUDGET_PLAN). All amounts are result impact (revenue +, expense -, positive = improves the result; deltas = actual - comparison). start/end come from the computed metrics, the steps from category deltas, check.reconciles proves they add up (on unrounded values). unassigned = result change no category of this metric explains (labels without id or subtotal group, accounts without label); excluded lists what is left out (unlabeled_accounts, labels_without_group) and a warning appears when either is non-empty. rounding_difference = end - (start + steps + other + unassigned) on the rounded figures, draw it as a last tiny bar or absorb it. Steps carry sort_order (P&L order) and auffaellig; the list is sorted by absolute delta. Small steps (below other_threshold, share of the absolute total change, default 0.05) are collapsed into other with their list. Use this instead of subtracting category totals yourself.

Withdraw (delete) a PENDING manual correction proposal that has not been approved yet. Approved bookings must be deleted in the app.