# OSVčalc 2026

> A free, single-page calculator for Czech OSVČ (main or vedlejší activity) for tax year 2026. It estimates income tax, social and health insurance doplatky owed so far in 2026, and projects the year-end total based on expected future income. It is also available as a free JSON API (documented at `/api`, OpenAPI spec at `/api/openapi.json`) and as an MCP server, so scripts and AI assistants can run the same calculation programmatically or conversationally.

This is a static React/TypeScript single-page app. The web app itself has no backend: all calculations run client-side, in your browser, and the web app sends none of the calculator inputs anywhere. The separate JSON API and MCP server (see below) do receive and process inputs on the server, only to compute the result; osvcalc does not save them, though the hosting provider (Vercel) may keep short-lived technical logs such as IP addresses. It's ad-supported via Google AdSense, which sets its own cookies for ad personalization; see the in-app privacy policy (linked from the disclaimer, also at `/policy`) for details. It's also available as a separate MCP server (see below), which is a real backend, just not one the web app itself calls. Available in English and Czech, with light, dark and system color themes.

## Scope

- Applies to OSVČ with hlavní (main) or vedlejší (side) self-employment activity, including souběh se zaměstnáním (income alongside employment).
- Covers both regimes: skutečné výdaje (actual expenses) and výdajový paušál (flat-rate expense deduction of 30%, 40%, 60% or 80%), and compares both against paušální daň (pásmo 1-3).
- Computes income tax (15%, 23% above the threshold, minus the sleva na poplatníka and any credits/deductions), the daňový bonus, social and health insurance doplatek, VAT registration status, and a year-end projection: total to save, and monthly amount to set aside.
- Figures are for the 2026 tax year (rates, minimum bases, sleva na poplatníka, and paušál caps specific to 2026).
- Not tax advice; verify with an accountant before filing.

## MCP server

`https://osvcalc.cz/api/mcp` exposes the same calculator to AI assistants (Claude Desktop, Claude Code, Cursor and similar), with no accounts or API keys required. It reuses the same calculation code as the web app, so results always match. Two tools:

- `calculate_osvc_taxes`: runs the full calculation for a given situation and returns both structured data and a human-readable explanation, in English or Czech.
- `get_field_guide`: returns every input's label, explanation, type, options, default, bounds and when it applies (`appliesWhen`) without calculating anything. Call it before asking the user about options, so the assistant can explain an option before the user has decided on it.

## REST API

Free, keyless JSON API, no accounts, CORS open, rate-limited. Full documentation with every field explained and curl examples: `https://osvcalc.cz/api` (English and Czech). Machine-readable OpenAPI 3.1 spec: `https://osvcalc.cz/api/openapi.json` (add `?locale=cs` for Czech descriptions).

- `POST https://osvcalc.cz/api/calculate`: JSON body, send either `income` (paid to you so far this year, in CZK) or `invoices` (list of `{amount, paidDate}`), everything else is optional. Returns `{ summary, text }`: `summary` is the structured result, `text` a readable explanation. Errors: 400 invalid body, 422 both `income` and `invoices` sent, 429 rate-limited.
- `GET https://osvcalc.cz/api/field-guide?locale=en`: lists every input with its label, explanation, type, options, default, bounds and when it applies. `POST /api/calculate` rejects unknown fields with 400 and returns 200 with `summary.error` true if `currentMonth` is before `startMonth`.
- `GET https://osvcalc.cz/api/openapi.json`: the OpenAPI spec.

```bash
curl -X POST https://osvcalc.cz/api/calculate \
  -H "Content-Type: application/json" \
  -d '{"income": 500000, "currentMonth": 9}'
```

Same calculation code as the web app and the MCP server, so results always match. Results are an estimate, not tax advice.

## Key files

- index.html: app entry point
- src/calc.ts: pure calculation engine (income tax, social and health insurance liability, advance payments)
- src/present.ts: formats calculation results into localized display text
- src/filing.ts: where and how much to pay, shared by the web app and the MCP tool
- src/i18n/: English and Czech translation dictionaries
- src/mcp/: MCP tool schemas, field guide and calculation glue
- api/mcp.ts: the deployed MCP server endpoint
- api/calculate.ts, api/field-guide.ts, api/openapi.ts, src/rest/: the REST API and its OpenAPI generator
- src/components/ApiPage.tsx, ApiDocs.tsx: the /api documentation page (Scalar)
- README.md: project overview and local development instructions