# mcp-fiskalizacija

MCP (Model Context Protocol) server za **izradu i fiskalizaciju računa** preko [solo.com.hr](https://solo.com.hr) API-ja.

Daj ovaj MCP bilo kojem AI-ju ili agentu (Claude, Cursor, ChatGPT s MCP podrškom, custom agenti...) i reci mu npr.:

> *"Napravi mi račun za tvrtku Acme d.o.o., OIB 12345678901, za konzultantske usluge, 10 sati po 80 EUR, PDV 25%, plaćanje na transakcijski račun."*

AI će pozvati `solo_create_invoice`, Solo će dodijeliti sljedeći broj računa, fiskalizirati ga (ZKI/JIR) i vratiti PDF link.

## Alati

| Alat | Opis |
|------|------|
| `solo_create_invoice` | Izrađuje i fiskalizira novi račun. Vraća broj računa, iznose, ZKI/JIR i PDF link. |
| `solo_get_invoice` | Dohvaća jedan račun po ID-u sa svim detaljima. |
| `solo_list_invoices` | Popis računa (najnoviji prvi, do 1000 po stranici). |
| `solo_next_invoice_number` | Čita zadnji izdani račun i izračunava sljedeći broj (`redni-prostor-uređaj`, npr. `13-1-1`). Solo broj dodjeljuje automatski pri izradi — alat služi za najavu i provjeru. |

## Instalacija

```bash
git clone <ovaj-repo>
cd mcp-fiskalizacija
npm install
npm run build
```

Trebаš **Solo API token** — pronađi ga u *Postavkama* nakon prijave na [solo.com.hr](https://solo.com.hr).

## Spajanje na AI / agenta

### Claude Code

```bash
claude mcp add fiskalizacija \
  --env SOLO_API_TOKEN=tvoj-token \
  -- node /putanja/do/mcp-fiskalizacija/dist/index.js
```

### Claude Desktop / bilo koji MCP klijent (JSON config)

```json
{
  "mcpServers": {
    "fiskalizacija": {
      "command": "node",
      "args": ["/putanja/do/mcp-fiskalizacija/dist/index.js"],
      "env": {
        "SOLO_API_TOKEN": "tvoj-token"
      }
    }
  }
}
```

### Cursor

Isti JSON u `.cursor/mcp.json` u projektu ili globalno u `~/.cursor/mcp.json`.

## Primjer: kako AI izrađuje račun

Korisnik kaže:

> "Napravi račun: kupac Marko Horvat (fizička osoba), usluga 'Izrada web stranice', 1 kom, 500 EUR, PDV 25%, plaćanje karticom."

AI pozove alat ovako:

```json
{
  "tool": "solo_create_invoice",
  "arguments": {
    "tip_kupca": 1,
    "kupac_naziv": "Marko Horvat",
    "usluge": [
      {
        "opis_usluge": "Izrada web stranice",
        "cijena": 500,
        "kolicina": 1,
        "porez_stopa": 25,
        "jed_mjera": "kom"
      }
    ],
    "nacin_placanja": 3
  }
}
```

Odgovor sadrži:

```
Račun uspješno kreiran.

Broj računa: 13-1-1
Kupac: Marko Horvat
Neto: 500,00 | Bruto: 625,00 EUR
Način plaćanja: Kartice
ZKI: e4d909c290d0fb1ca068ffaddf22cbd0
JIR (fiskaliziran): 2cf55235-9470-4b5c-a539-463f52b109d2
PDF: https://solo.com.hr/download/...
```

### Obavezne informacije za račun

Minimalno: **tip kupca**, **stavke** (opis, cijena, PDV stopa) i **način plaćanja**.

Za B2B/B2G kupce (tvrtke, javna nabava) dodatno su obavezni **naziv kupca**, **OIB** i **KPD oznaka** po stavci — server to validira prije slanja i vraća jasnu grešku ako nedostaje.

## Šifrarnici (Solo API)

| Parametar | Vrijednosti |
|-----------|-------------|
| `tip_kupca` | 1=B2C fizička osoba, 2=B2B poslovni subjekt, 3=B2G država/javna nabava, 4=EU, 5=INT |
| `tip_racuna` | 1=R1, 2=R2, 3=bez oznake, 4=avansni |
| `nacin_placanja` | 1=transakcijski račun, 2=gotovina, 3=kartice, 4=ček, 5=ostalo |
| `porez_stopa` | 0, 5, 13, 25 |
| `jezik_racuna` | 1=hrvatski, 2=engleski, 3=njemački, 4=francuski, 5=talijanski, 6=španjolski |
| `valuta_racuna` | 14=EUR (zadano), 12=USD, 11=GBP, 10=CHF, 6=HUF, 13=BAM, ... |
| `status` | 1=otvoren, 2=poslan, 3=opomenut, 5=plaćen |

## Kako funkcionira

```
AI / agent ──(MCP, stdio)──► mcp-fiskalizacija ──(HTTPS)──► api.solo.com.hr ──► Porezna uprava (fiskalizacija)
```

1. AI dobije zahtjev korisnika i prikupi obavezne podatke.
2. Pozove `solo_create_invoice` (po želji prvo `solo_next_invoice_number` da najavi broj).
3. Server validira ulaz (B2B pravila, PDV stope, popusti), pretvori brojeve u Solo format (decimalni zarez) i pošalje form-encoded POST na `https://api.solo.com.hr/racun`.
4. Solo dodijeli broj računa, fiskalizira račun (ZKI/JIR) i vrati PDF.
5. AI korisniku vrati broj računa, iznose i PDF link.

**Numeracija:** hrvatski broj računa ima oblik `redni-poslovniProstor-naplatniUređaj` (npr. `13-1-1`), a redni broj se resetira svake kalendarske godine — `solo_next_invoice_number` to uzima u obzir.

## Ograničenja Solo API-ja

- Plaćeni paket: do **300 računa mjesečno**; besplatni: **3 mjesečno**.
- Fiskalizacija (ZKI/JIR) mora biti uključena u Solo postavkama (certifikat Porezne uprave).
- `solo_get_invoice` koristi Solo **ID** računa (hex string), ne broj računa.

## Razvoj

```bash
npm run dev            # pokreni server iz src/ (tsx)
npm test               # testovi (vitest)
npm run test:coverage  # testovi s pokrivenošću
npm run build          # TypeScript build u dist/
```

Struktura:

```
src/
  index.ts                  # entry point (stdio transport)
  server.ts                 # MCP server + registracija alata
  solo/
    client.ts               # HTTP klijent za api.solo.com.hr
    serialize.ts            # validacija + form-encoding (decimalni zarez, indeksirane stavke)
    invoice-number.ts       # parsiranje i predviđanje broja računa
    types.ts                # tipovi i šifrarnici
  tools/                    # MCP alati (jedan po datoteci)
```

## Roadmap (2.0)

- [ ] Više providera fiskalizacije (apsolutna apstrakcija providera iza zajedničkog sučelja)
- [ ] Storno i brisanje računa (Solo API to podržava)
- [ ] Ponude (Solo API `/ponuda`)
- [ ] Fiskalizacija 2.0 (eRačun B2B obveza od 1.1.2026.)

## Licenca

MIT