Skip to content
Back to search

openszamla

MarketplaceWorks with Claude CodeGitHub

OpenSzámla – nyílt forráskódú magyar számlázó MCP szerver és skill (NAV Online Számla v3)

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/openszamla--openszamla/badge.svg)](/listings/openszamla--openszamla)

HTML

<a href="/listings/openszamla--openszamla"><img src="/api/listings/openszamla--openszamla/badge.svg" alt="findsafeskills safety rating" /></a>

Install

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 14 lines
  1. {
  2. "name": "openszamla",
  3. "description": "OpenSzámla – nyílt forráskódú magyar számlázó MCP szerver és skill (NAV Online Számla v3)",
  4. "owner": { "name": "OpenSzámla közreműködők", "url": "https://github.com/openszamla/openszamla" },
  5. "plugins": [
  6. {
  7. "name": "openszamla",
  8. "source": "./plugins/openszamla",
  9. "description": "Magyar számlázás Claude-dal: számla, díjbekérő, sztornó, módosító számla, PDF, NAV Online Számla",
  10. "category": "productivity",
  11. "tags": ["szamlazas", "szamla", "nav", "invoice", "hungary"]
  12. }
  13. ]
  14. }
README.md · README · 445 lines
  1. # OpenSzámla
  2. **Nyílt forráskódú magyar számlázó program, amit AI-ügynökök kezelnek.**
  3. Claude (Claude Code, Claude Desktop, claude.ai), OpenAI Codex és bármely más MCP-kliens
  4. természetes nyelven állít ki számlát, díjbekérőt, sztornó és módosító számlát – a program
  5. pedig gondoskodik a sorszámozásról, az ÁFA-számításról, a kötelező tartalomról, a PDF-ről
  6. és a **NAV Online Számla** adatszolgáltatásról.
  7. > „Állíts ki számlát a Minta Kft.-nek 10 óra szoftverfejlesztésről, 15 000 Ft/óra + ÁFA,
  8. > 8 napos átutalással.” → az ügynök megkeresi a vevőt (NAV adószám-lekérdezéssel), piszkozatot
  9. > készít, megmutatja az előnézetet, a jóváhagyásod után kiállítja, PDF-et ad és jelenti a NAV-nak.
  10. - 🧾 Számla, előlegszámla, végszámla, díjbekérő, **sztornó** és **módosító** számla
  11. - 🏛️ NAV Online Számla v3.0: valós idejű adatszolgáltatás, adószám-lekérdezés, státuszkövetés
  12. - 🤖 MCP szerver 27 eszközzel, erőforrásokkal és promptokkal – stdio és Streamable HTTP, mindkét
  13. MCP protokoll-generáció (2025-ös és 2026-07-28)
  14. - 🔒 Megváltoztathatatlan kiállított számlák (SQLite triggerek), hézagmentes sorszámozás,
  15. hash-láncolt auditnapló, szerver által kiadott megerősítő kód minden visszafordíthatatlan művelethez
  16. - 💱 Devizás számla MNB árfolyammal, ÁFA forintban; készpénzes 0/5 Ft kerekítés
  17. - 📄 Magyar (és angol / kétnyelvű) PDF a kötelező szöveges megjelölésekkel
  18. - 📦 Egyetlen helyi fájl az adatbázis (`node:sqlite`, natív függőség nélkül), CSV/JSON/XML export,
  19. és a kötelező „adóhatósági ellenőrzési adatszolgáltatás” (a 23/2014. NGM rendelet 3. melléklete szerinti XML)
  20. > **Korai változat (0.1).** A program kiterjedt automatikus tesztekkel készült (a NAV-adatot a hivatalos
  21. > sémákkal ellenőrzi), de éles NAV-környezetben és sok felhasználónál még nem bizonyított. Mielőtt éles
  22. > számlát állítasz ki vele: próbáld ki a NAV **teszt**környezetével, egyeztess a könyvelőddel, ments
  23. > rendszeresen (`openszamla backup`), és az első éles számlákat ellenőrizd a NAV Online Számla felületén.
  24. > A program használata a saját felelősségedre történik (MIT licenc, garancia nélkül) – lásd
  25. > [Fontos jogi tudnivalók](#fontos-jogi-tudnivalók) és [Korlátok](docs/jogi-megfeleles.md#amit-a-01-es-verzió-nem-tud).
  26. ## Telepítés
  27. Három lépés – a harmadik végigvezet minden beállításon.
  28. **1. Node.js 22.13 vagy újabb** (ajánlott: az aktuális LTS-változat, pl. 24)
  29. | Rendszer | Telepítés |
  30. |---|---|
  31. | Windows 10/11 | PowerShellben vagy a Terminálban: `winget install OpenJS.NodeJS.LTS` – vagy a https://nodejs.org oldalról az LTS-telepítő (a „Tools for Native Modules” jelölő nem kell) |
  32. | macOS | a https://nodejs.org LTS-telepítője, vagy Homebrew-val: `brew install node` |
  33. | Linux | a disztribúció csomagkezelője, ha legalább 22.13-at telepít (`node --version`); különben a NodeSource-csomagok (https://github.com/nodesource/distributions) vagy az nvm |
  34. Utána **nyiss új terminálablakot** (a már nyitottak nem látják az új programot), és ellenőrizd:
  35. `node --version`.
  36. **Windowson** a további parancsokat a Terminálban (PowerShellben) `.cmd` végződéssel írd: `npm.cmd`,
  37. `openszamla.cmd`. A Windows alapbeállítása a PowerShellben letiltja az npm és az OpenSzámla `.ps1`
  38. indítóját („running scripts is disabled on this system”), a `.cmd` változat így is fut. A Parancssorban
  39. (`cmd`) a végződés nélküli parancs is működik. macOS-en és Linuxon a végződés nélküli parancsokat használd.
  40. **2. Az OpenSzámla telepítése**
  41. Windowson (Terminál, PowerShell):
  42. ```powershell
  43. npm.cmd install -g openszamla
  44. ```
  45. macOS-en és Linuxon:
  46. ```bash
  47. npm install -g openszamla
  48. ```
  49. Amíg a csomag nem érhető el az npm-en, csomagfájlból telepíthető: a kapott (vagy a forráskódból
  50. `npm install`, `npm run build`, `npm pack` paranccsal készített) `openszamla-<verzió>.tgz` fájl mappájában –
  51. Windowson:
  52. ```powershell
  53. npm.cmd install -g .\openszamla-0.1.1.tgz
  54. ```
  55. macOS-en és Linuxon:
  56. ```bash
  57. npm install -g ./openszamla-0.1.1.tgz
  58. ```
  59. Forráskódból, fejlesztéshez: a letöltött mappában `npm install`, `npm run build`, majd `npm link`
  60. (Windows PowerShellben `npm.cmd install` stb.). Ellenőrzés: `openszamla --version` (Windows PowerShellben
  61. `openszamla.cmd --version`).
  62. **3. Első beállítás**
  63. Windowson (Terminál, PowerShell):
  64. ```powershell
  65. openszamla.cmd setup
  66. ```
  67. macOS-en és Linuxon:
  68. ```bash
  69. openszamla setup
  70. ```
  71. Lépésenként végigvezet: ellenőrzi a Node.js-t, megmutatja (és létrehozza) az adatkönyvtárat, bekéri az
  72. eladó adatait, kérésre a NAV technikai felhasználóját (előbb a TESZT környezethez), és a kiválasztott
  73. AI-kliensek – Claude Desktop, Claude Code, Codex, Cursor, VS Code – saját beállításába beírja az
  74. OpenSzámlát (a meglévő beállításokat megtartja, előtte biztonsági másolatot készít). Végül megmondja,
  75. mit kérdezz először az AI-tól, és hogyan indul a webes felület (`openszamla serve`). Bármelyik lépés
  76. kihagyható, a parancs újra futtatható. Ellenőrzés bármikor: `openszamla doctor`. Windows PowerShellben a
  77. program által kiírt minden `openszamla …` parancsot `.cmd`-vel írj (pl. `openszamla.cmd doctor`).
  78. ### Claude Desktop egy kattintással (.mcpb)
  79. A kiadásokhoz mellékelt `openszamla-<verzió>.mcpb` bővítményt dupla kattintással (vagy Settings →
  80. Extensions → Advanced settings → Install Extension…) telepítheted; parancssor nem kell hozzá. A
  81. telepítő bekéri az adatkönyvtárat és – ha már megvannak – a NAV technikai felhasználó adatait; az
  82. eladó adatait utána az AI-nak mondhatod meg („Állítsd be a cégem adatait: …”). A bővítmény a Claude
  83. Desktop saját vagy a gépre telepített Node.js-ével fut; ha a naplójában a „Node.js 22.13.0 vagy újabb
  84. szükséges” hiba áll, telepítsd az 1. lépés szerint a Node.js-t, és a Claude Desktop Settings →
  85. Extensions → Advanced settings részén kapcsold ki a „Use Built-in Node.js for MCP” beállítást.
  86. Részletek: [docs/kliensek.md](docs/kliensek.md).
  87. ### Ha elakadsz
  88. - **PowerShell: „running scripts is disabled on this system” („a parancsfájlok futtatása le van tiltva”)** –
  89. a Windows alapbeállítása tiltja az npm `.ps1` indítóit. Írd ki a `.cmd` végződést:
  90. `npm.cmd install -g openszamla`, `openszamla.cmd setup`; vagy engedélyezd egyszer, a saját
  91. felhasználódnak: `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`.
  92. - **„'node' is not recognized…” / „A(z) node kifejezés nem ismerhető fel…” rögtön a telepítés után** –
  93. a már nyitott terminál nem látja az új programot: zárd be, és nyiss újat (ha ez sem segít, jelentkezz
  94. ki és be).
  95. - **„OpenSzámla: Node.js 22.13.0 vagy újabb szükséges …”** – a Node.js túl régi (`node --version`):
  96. telepítsd az LTS-változatot az 1. lépés szerint.
  97. - **EACCES a globális telepítésnél (macOS, Linux)** – ne `sudo`-val telepíts: Homebrew-val vagy nvm-mel
  98. telepített Node.js-nél ez nem fordul elő; vagy adj saját mappát: `npm config set prefix ~/.npm-global`
  99. (és tedd a `~/.npm-global/bin` mappát a PATH-ra).
  100. - **Proxy mögött** – az npm-nek:
  101. `npm config set proxy http://proxy.cegem.hu:8080` és
  102. `npm config set https-proxy http://proxy.cegem.hu:8080`;
  103. a forgalmat saját tanúsítvánnyal vizsgáló céges hálózatban: `npm config set cafile <tanúsítvány.pem>`.
  104. A program saját NAV- és MNB-kapcsolata a `HTTPS_PROXY` és a `NODE_OPTIONS=--use-env-proxy` környezeti
  105. változóval megy a proxyn át (Node.js 24; MCP-kliensnél a szerver `env` beállításában), a céges
  106. tanúsítványt a `NODE_EXTRA_CA_CERTS=<tanúsítvány.pem>` adja meg.
  107. - **Az AI nem látja az OpenSzámla eszközeit** – `openszamla doctor`: megmutatja, melyik kliens
  108. beállításában szerepel, létezik-e a beállított parancs, és mit kell javítani. A Claude Desktopból
  109. beállítás után teljesen ki kell lépni (Windowson a tálcán a Claude ikon → Quit), az ablak bezárása nem
  110. elég.
  111. ## Tartalom
  112. - [Telepítés](#telepítés)
  113. - [Fontos jogi tudnivalók](#fontos-jogi-tudnivalók)
  114. - [A csomagról](#a-csomagról)
  115. - [Első beállítás kézzel](#első-beállítás-kézzel)
  116. - [Csatlakoztatás AI-ügynökhöz](#csatlakoztatás-ai-ügynökhöz)
  117. - [Használat](#használat)
  118. - [MCP eszközök](#mcp-eszközök)
  119. - [Parancssor](#parancssor)
  120. - [Adatok, biztonság, mentés](#adatok-biztonság-mentés)
  121. - [Fejlesztés](#fejlesztés)
  122. - [English summary](#english-summary)
  123. ## Fontos jogi tudnivalók
  124. Az OpenSzámla a 2026. októberi jogszabályok (Áfa tv., 23/2014. (VI. 30.) NGM rendelet, NAV
  125. Online Számla v3.0 interfész-specifikáció) alapján készült, de **nem jogi vagy adótanácsadás**,
  126. és a szoftvert „ahogy van” alapon, garancia nélkül adjuk (lásd [LICENSE](LICENSE)). A számlázás
  127. helyességéért a számlát kiállító vállalkozás felel – bizonytalan esetben kérdezd a könyvelődet.
  128. A program használójaként neked kell:
  129. 1. **NAV Online Számla regisztráció és technikai felhasználó** – az onlineszamla.nav.gov.hu
  130. oldalon (előbb a teszt-, majd az éles környezetben) technikai felhasználót hozol létre
  131. aláíró- és cserekulccsal, és ezt megadod a programnak (`openszamla nav-setup`). NAV-kapcsolat
  132. nélkül a program kiállít számlát, de figyelmeztet: **minden számláról haladéktalanul adatot kell
  133. szolgáltatni**, a mulasztás számlánként akár 1 000 000 Ft bírság. A NAV **teszt** környezetébe
  134. (ez az alapértelmezés) küldött számla nem valódi adatszolgáltatás – a program minden ilyen
  135. eredményt „TESZT környezet” jelöléssel ad vissza; éles számlázáshoz `production` környezet kell.
  136. 2. **Árfolyam-választás bejelentése** – devizás számlánál a program alapból az MNB hivatalos
  137. árfolyamát használja. Ezt a választást előzetesen be kell jelentened a NAV-nak (Áfa tv. 80. §);
  138. ha nem tetted meg, állítsd az árfolyamforrást „manual”-ra, és add meg a bankod deviza eladási
  139. árfolyamát.
  140. 3. **Megőrzés** – a számlákat (elektronikus számlát elektronikusan) 8 évig meg kell őrizni:
  141. ments rendszeresen (`openszamla backup`), és őrizd meg a program dokumentációját is
  142. ([felhasználói dokumentáció](docs/felhasznaloi-dokumentacio.md)).
  143. 4. A „SZAMLAZO” bejelentés a számlázó program használatáról **2021. január 4. óta megszűnt**,
  144. ilyen teendőd nincs.
  145. Részletek és források: [docs/jogi-megfeleles.md](docs/jogi-megfeleles.md) és
  146. [docs/research/02-jogi-kovetelmenyek.md](docs/research/02-jogi-kovetelmenyek.md).
  147. ## A csomagról
  148. Szükséges: **Node.js 22.13.0 vagy újabb** (ajánlott: 24 LTS). Telepítés nélkül is futtatható:
  149. `npx -y openszamla <parancs>` (az első indítás lassabb, és az AI-kliensek beállításába így nem írható
  150. tartós útvonal, ezért ügynökökhöz a globális telepítést ajánljuk). A csomag parancssori program és MCP
  151. szerver; programkönyvtárként (`import`) nem használható.
  152. A program neve **OpenSzámla**, azonosítója (NAV `softwareId`) **OPENSZAMLA-0000001**; a telepített
  153. változat számát az `openszamla --version` írja ki. A változathoz tartozó felhasználói dokumentáció
  154. és a változásnapló a telepített csomag része (`docs/felhasznaloi-dokumentacio.md`, `CHANGELOG.md` –
  155. a csomag mappája: `npm root -g` → `openszamla`), a 0.1.1-es változaté online is:
  156. https://github.com/openszamla/openszamla/blob/v0.1.1/docs/felhasznaloi-dokumentacio.md
  157. ## Első beállítás kézzel
  158. Az `openszamla setup` ugyanezt teszi lépésenként; a lépések külön is futtathatók (Windows PowerShellben
  159. `openszamla.cmd init` stb.):
  160. ```bash
  161. openszamla init
  162. openszamla nav-setup
  163. openszamla status
  164. openszamla doctor
  165. ```
  166. - `openszamla init` – az eladó adatai: név, adószám, cím, bankszámla, ÁFA-státusz;
  167. - `openszamla nav-setup` – a NAV technikai felhasználója (alapból a TESZT környezethez);
  168. - `openszamla status` – állapot és teendők;
  169. - `openszamla doctor` – a telepítés és a beállítások ellenőrzése, javítási tippekkel.
  170. Az adatok alapértelmezett helye `~/.openszamla` (Windows: `C:\Users\<név>\.openszamla`); más
  171. mappa: `OPENSZAMLA_HOME` környezeti változó vagy `--data-dir`, abszolút útvonallal (a `~/…` alakot
  172. a program maga fejti ki). Ha az MCP-kliensnek más adatkönyvtárat adsz meg, a NAV-adatokat is oda
  173. mentsd: `openszamla nav-setup --data-dir <ugyanaz a mappa>` (a pontos parancsot az `openszamla
  174. status` teendői is kiírják). Éles NAV környezet: a `nav-setup` kérdésénél `production`, vagy
  175. `OPENSZAMLA_NAV_ENV=production` – a megadott (nem üres) `OPENSZAMLA_NAV_ENV` felülírja a `nav-setup`
  176. választását.
  177. Az eladói adatokat az ügynök is beállíthatja („Állítsd be a cégem adatait: …”).
  178. ## Csatlakoztatás AI-ügynökhöz
  179. A pontos, kliensenkénti leírás: **[docs/kliensek.md](docs/kliensek.md)**. A legegyszerűbb:
  180. ```bash
  181. openszamla config claude-desktop --write
  182. ```
  183. A `claude-desktop` helyén a kliens lehet `claude-code`, `codex`, `cursor` vagy `vscode` is (Windows
  184. PowerShellben: `openszamla.cmd config …`). Ez a kliens saját beállításába írja az OpenSzámlát (a többi
  185. beállítást megtartja, előtte biztonsági másolatot készít, és kiírja, mit változtatott és hogyan vonható
  186. vissza); meglévő, más `openszamla` bejegyzést csak `--force`-szal cserél le. A `--write` nélkül csak kiírja a bemásolható konfigurációt
  187. (`--data-dir <mappa>` megadásával a nem alapértelmezett adatkönyvtárral együtt). A beírt parancs a
  188. Node.js és az OpenSzámla abszolút útvonala, így a kliens parancsértelmező és PATH nélkül is elindítja
  189. (Windowson az `openszamla` és az `npx` parancsértelmezőt igénylő `.cmd` fájl, macOS-en az asztali
  190. alkalmazások nem látják a terminál PATH-ját). Az alábbi rövid forma (`"command": "openszamla"`) akkor
  191. működik, ha a kliens megtalálja az `openszamla` parancsot.
  192. **Claude Code**
  193. ```bash
  194. claude mcp add --transport stdio --scope user openszamla -- openszamla mcp
  195. ```
  196. **OpenAI Codex (CLI és IDE)**
  197. ```bash
  198. codex mcp add openszamla -- openszamla mcp
  199. ```
  200. vagy `~/.codex/config.toml`:
  201. ```toml
  202. [mcp_servers.openszamla]
  203. command = "openszamla"
  204. args = ["mcp"]
  205. startup_timeout_sec = 30
  206. tool_timeout_sec = 300
  207. ```
  208. **Claude Desktop** – `claude_desktop_config.json` (Windows: `%APPDATA%\Claude\`, a Microsoft Store-os
  209. változatnál `%LOCALAPPDATA%\Claude-Data\claude_…\`, régebbi kiadásainál
  210. `%LOCALAPPDATA%\Packages\Claude_…\LocalCache\Roaming\Claude\`; macOS:
  211. `~/Library/Application Support/Claude/`; Linux: `~/.config/Claude/`; az
  212. `openszamla config claude-desktop --write` a gépen használt fájlba írja):
  213. ```json
  214. {
  215. "mcpServers": {
  216. "openszamla": { "command": "openszamla", "args": ["mcp"] }
  217. }
  218. }
  219. ```
  220. **claude.ai, ChatGPT, távoli kliensek** – `openszamla serve` Streamable HTTP végpontot ad
  221. (`/mcp`, Bearer tokennel vagy `/mcp/<token>` alakban, alapból csak `127.0.0.1`-en). Nyilvános
  222. eléréshez HTTPS reverse proxy kell; lásd [docs/kliensek.md](docs/kliensek.md).
  223. Mellékeltünk egy **skillt** is ([skills/magyar-szamlazas/SKILL.md](skills/magyar-szamlazas/SKILL.md)),
  224. ami a magyar számlázási munkamenetre tanítja az ügynököt (Claude Code pluginként és Codex skillként is).
  225. ## Használat
  226. Példák, amiket az ügynöknek mondhatsz:
  227. - „Mi a helyzet a számlázóval?” – beállítások, függő NAV-jelentések, teendők
  228. - „Keresd ki a 12345676 adószámú céget a NAV-nál, és mentsd el vevőként.”
  229. - „Állíts ki számlát Kovács Annának (magánszemély, 1111 Budapest, Fő utca 1.) egy 12 990 Ft-os
  230. bruttó árú könyvről, készpénzes fizetéssel.”
  231. - „Készíts díjbekérőt az Alfa Kft.-nek 300 000 Ft + ÁFA tanácsadásról.” – majd fizetés után:
  232. „A díjbekérőből állíts ki számlát.”
  233. - „Ugyanazt számlázd ki, mint múlt hónapban a Béta Bt.-nek.”
  234. - „Sztornózd az SZ-2026-00042-es számlát, mert rossz vevőre állítottuk ki.”
  235. - „Az SZ-2026-00040-es számlán utólag adj 10% árengedményt.” (módosító számla)
  236. - „Mennyi volt az októberi forgalom és ÁFA? Melyik számlák lejártak?”
  237. - „Exportáld a harmadik negyedév számláit a könyvelőnek.”
  238. A kiállítás mindig két lépésben történik: az ügynök előbb **előnézetet** mutat, és csak a te
  239. jóváhagyásod után – a szerver által adott megerősítő kóddal – állítja ki a számlát.
  240. ### Webes felület
  241. Ügynök nélkül a böngészőből is számlázhatsz: az `openszamla serve` elindítja a webes felületet
  242. (alapból `http://127.0.0.1:8787`, csak a saját gépedről érhető el), és kiírja a belépési címet
  243. (`…/?token=…`) – azt megnyitva be is léptet. Első indításkor az Áttekintő **Első lépések** útmutatója
  244. végigvezet a beállításon: eladó adatai → NAV-kapcsolat (először a TESZT rendszerrel; a beállító parancsot
  245. egy kattintással kimásolhatod, a beépített adatkönyvtárnál egyszerűen `openszamla nav-setup`) → első vevő →
  246. első számla. A teendőket az Áttekintő a saját szavaival, a hozzájuk tartozó gombbal vagy hivatkozással
  247. mutatja. A számla tételsoraiban a mentett termékek közül is választhatsz (a sor magától kitöltődik), a
  248. díjbekérőből egy kattintással számlapiszkozat lesz (a rögzített befizetés átkerül rá), egy korábbi
  249. számlából pedig új a mintájára. Itt is két lépés a kiállítás: a mentés piszkozatot készít, a kiállítás
  250. külön, a következmények felsorolásával és megerősítéssel történik, és a gombok megmondják, mi következik
  251. (pl. „Számla kiállítása és beküldése a NAV-nak”, TESZT környezetben „… a NAV TESZT rendszerébe”). A
  252. felület telefonon, világos és sötét módban, billentyűzettel és JavaScript nélkül is használható.
  253. Részletek: [felhasználói dokumentáció, 8. fejezet](docs/felhasznaloi-dokumentacio.md#8-webes-felület).
  254. ## MCP eszközök
  255. | Eszköz | Mire való |
  256. |---|---|
  257. | `setup_status` | állapot, eladó, sorszámtartományok, NAV-kapcsolat, teendők |
  258. | `seller_update` | eladó adatai, számlázási alapértelmezések |
  259. | `series_manage` | sorszámtartományok (pl. `SZ-{YYYY}-{SEQ:5}`) |
  260. | `taxpayer_lookup` | adószám-lekérdezés a NAV-tól |
  261. | `customer_save`, `customer_find` | vevők |
  262. | `product_save`, `product_find` | termékek, szolgáltatások |
  263. | `invoice_draft` | piszkozat létrehozása / módosítása, előnézet + megerősítő kód |
  264. | `invoice_get`, `invoice_list` | számlák lekérdezése, keresése |
  265. | `invoice_issue` | **kiállítás** (visszafordíthatatlan) |
  266. | `invoice_cancel_preview`, `invoice_cancel` | **sztornó** előnézet és végrehajtás |
  267. | `invoice_correct` | módosító számla piszkozata |
  268. | `invoice_delete_draft` | piszkozat törlése |
  269. | `invoice_record_payment` | befizetés rögzítése (sztornón a vevőnek visszafizetett összegé) |
  270. | `invoice_pdf` | a kiállításkor megőrzött eredeti PDF (lenyomattal) / másolása helyi mappába |
  271. | `nav_sync` | NAV-jelentés és státusz-frissítés |
  272. | `nav_send_to_configured_environment` | a másik NAV-rendszerhez tartozó (pl. csak a TESZT rendszerbe jelentett) számla beküldése (visszafordíthatatlan) |
  273. | `exchange_rate` | MNB árfolyam |
  274. | `report_summary` | időszaki forgalom, ÁFA (pénzforgalmi elszámolásnál a befizetés dátuma szerint is), kintlévőség |
  275. | `export_invoices` | CSV / JSON / NAV XML export, befizetési napló |
  276. | `tax_audit_export` | **adóhatósági ellenőrzési adatszolgáltatás** (23/2014. NGM rendelet 11/A. §) |
  277. | `audit_log` | auditnapló |
  278. | `backup_create` | az adatbázis mentése az adatkönyvtár `backups` mappájába |
  279. | `verify_integrity` | annak ellenőrzése, hogy az adatbázist nem módosították a programon kívül |
  280. Részletes leírás minden eszközről és paraméterről:
  281. [docs/felhasznaloi-dokumentacio.md](docs/felhasznaloi-dokumentacio.md).
  282. ## Parancssor
  283. ```text
  284. openszamla setup első beállítás lépésenként (adatkönyvtár, eladó, NAV, AI-kliensek)
  285. openszamla doctor a telepítés és a beállítások ellenőrzése, javítási tippekkel
  286. openszamla mcp MCP szerver stdio-n
  287. openszamla serve MCP Streamable HTTP + webes felület (127.0.0.1:8787)
  288. openszamla init eladói adatok
  289. openszamla nav-setup NAV technikai felhasználó (a jelszó és a kulcsok gépeléskor rejtve)
  290. openszamla nav-send-to-configured-environment <sorszám> [--confirm]
  291. a csak a másik NAV-rendszerbe jelentett számla beküldése a beállítottba
  292. openszamla status állapot
  293. openszamla list | show | pdf számlák
  294. openszamla export export időszakra (csv, json, xml; kelte, teljesítés vagy befizetés szerint; --ledger: befizetési napló)
  295. openszamla adohatosagi-export adóhatósági ellenőrzési adatszolgáltatás (dátum- vagy sorszámtartomány)
  296. openszamla verify számla-hash-ek, auditlánc, sorszámfolytonosság ellenőrzése
  297. openszamla backup <fájl> adatbázis mentése
  298. openszamla restore <fájl> mentés visszaállítása (--confirm nélkül csak előnézet; a régi adatbázist félreteszi)
  299. openszamla config <kliens> MCP konfiguráció kiírása; --write: beírás a kliens beállításába
  300. openszamla install-skill <cél> a skill bemásolása (claude | codex)
  301. ```
  302. Minden parancs és kapcsoló leírása: [docs/felhasznaloi-dokumentacio.md](docs/felhasznaloi-dokumentacio.md#7-parancssor).
  303. ## Adatok, biztonság, mentés
  304. - Minden adat a gépeden marad: `~/.openszamla/openszamla.db` (SQLite), `pdf/`, `export/`. Az
  305. adatkönyvtárat ne tedd OneDrive-mappába vagy hálózati meghajtóra – ott az adatbázis megsérülhet; az
  306. `openszamla doctor` és az `openszamla setup` figyelmeztet is rá –, a mentéseket (`openszamla backup`)
  307. viszont nyugodtan. Mentést visszaállítani az `openszamla restore <fájl>` paranccsal kell, nem a fájl
  308. kézi másolásával: a parancs ellenőrzi a mentést, félreteszi (nem törli) a jelenlegi adatbázist, és a
  309. sorszámozást a már kiadott sorszámok után folytatja.
  310. - A NAV hitelesítő adatai környezeti változóból (`OPENSZAMLA_NAV_LOGIN`, `…_PASSWORD`,
  311. `…_SIGNING_KEY`, `…_EXCHANGE_KEY`) vagy a `nav-credentials.json` fájlból jönnek; soha nem kerülnek
  312. az adatbázisba, és egyetlen MCP eszköz sem adja vissza őket.
  313. - A kiállított számla adatait SQLite triggerek védik a módosítástól és törléstől; minden számla
  314. tartalmi hash-t kap, minden változás hash-láncolt auditnaplóba kerül. Az `openszamla verify` ezeket,
  315. a sorszámfolytonosságot és a védelmeket is ellenőrzi, és kiírja a napló utolsó bejegyzését – ezt
  316. őrizd meg a mentéssel együtt.
  317. - A kiállított bizonylat PDF-jét a program a kiállításkor bájtra pontosan megőrzi az adatbázisban
  318. (SHA-256 és SHA3-512 lenyomattal), és később – frissítés után is – ezt adja ki, újra nem állítja elő;
  319. a mentés ezeket is tartalmazza, a `verify` ezeket is ellenőrzi.
  320. - HTTP módban a szerver alapból csak `127.0.0.1`-en figyel, és a Host/Origin fejléceket ellenőrzi
  321. (DNS-rebinding védelem). Az MCP végponthoz és a webes felülethez token kell; token nélkül csak a
  322. `/healthz` állapotjelző válaszol (a program nevét és verzióját adja vissza, mást nem). A tokent a
  323. program generálja; saját token (`--token`, `OPENSZAMLA_HTTP_TOKEN`) legalább 20 karakteres kell
  324. legyen, és csak az angol ábécé betűiből, számjegyekből, `_` és `-` jelből állhat (`[A-Za-z0-9_-]`),
  325. különben a szerver nem indul el. A `/mcp` a token-próbálgatást korlátozza: egy címről percenként 10
  326. hibás token után – és ha az összes címről együtt percenként 100 érkezik, minden olyan címről, ahonnan
  327. az elmúlt 60 percben nem jött helyes tokenű kérés – a válasz 429 `Retry-After` fejléccel. Az
  328. `X-Forwarded-For` fejlécből csak `OPENSZAMLA_TRUST_PROXY=1` mellett veszi a kliens címét (lásd
  329. [docs/kliensek.md](docs/kliensek.md)).
  330. - A NAV-beküldés megismételhető: egy számla akkor sem kerül kétszer a NAV-hoz, ha a beküldés
  331. eredménye bizonytalan volt, vagy több szinkron fut egyszerre.
  332. - Számlákban, e-mailekben, fájlokban talált szöveg adat, nem utasítás – az ügynöknek szóló
  333. utasítások ezt kifejezetten rögzítik.
  334. ## Fejlesztés
  335. ```bash
  336. git clone https://github.com/openszamla/openszamla.git
  337. cd openszamla
  338. npm install
  339. npm test
  340. npm run typecheck
  341. npm run dev -- status
  342. ```
  343. Az `npm test` a vitest-teszteket futtatja – a NAV XML-t a hivatalos XSD-k ellen validálja –, az
  344. `npm run dev -- status` a forráskódból indítja a programot. Windows PowerShellben az npm parancsot
  345. `npm.cmd`-vel írd.
  346. Fejlesztéshez **Node.js 22.18 vagy újabb** kell: a `src/*.ts` fájlok build nélkül, a Node beépített
  347. TypeScript-típuseltávolításával futnak (`npm run dev`, a tesztek). A kiadott csomag (`dist/`)
  348. 22.13.0-tól fut; ezt a CI ezen a változaton is ellenőrzi (`node scripts/smoke.mjs`).
  349. Architektúra: [docs/architektura.md](docs/architektura.md). Közreműködés:
  350. [CONTRIBUTING.md](CONTRIBUTING.md). Kódolási ügynököknek: [AGENTS.md](AGENTS.md).
  351. A kutatási háttéranyagok (jog, NAV API, MCP, adatformátumok): [docs/research/](docs/research/).
  352. Licenc: MIT ([LICENSE](LICENSE)). A harmadik féltől származó összetevők – köztük a PDF-ekbe ágyazott
  353. Roboto betűkészlet (SIL Open Font License 1.1) – licencei: [THIRD-PARTY-NOTICES](THIRD-PARTY-NOTICES).
  354. ## English summary
  355. OpenSzámla is an open-source Hungarian invoicing program designed to be operated by AI agents
  356. through the **Model Context Protocol**. It issues invoices, advance/final invoices, pro-forma
  357. requests, cancellations (storno) and corrections, computes Hungarian VAT, renders PDFs, and reports
  358. every invoice in real time to the Hungarian tax authority (**NAV Online Számla v3.0**). Issued
  359. invoices are immutable (SQLite triggers), numbering is gap-free, every irreversible operation
  360. requires a server-issued confirmation code, and all changes go to a hash-chained audit log.
  361. It runs locally (Node.js ≥ 22.13.0, built-in `node:sqlite`) and works with Claude Code, Claude
  362. Desktop, claude.ai custom connectors, OpenAI Codex and any MCP client (stdio or Streamable HTTP).
  363. Licensed under MIT. Not legal or tax advice.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.