mcp-fiskalizacija

MCP (Model Context Protocol) server za izradu i fiskalizaciju računa preko 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

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.

Spajanje na AI / agenta

Claude Code

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)

{
  "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:

{
  "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

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