ksefnik
KSeF SDK for TypeScript/Node.js — invoice reconciliation with bank statements (MT940, mBank, ING, PKO, Santander), production KSeF 2.0 HTTP client, MCP server for Claude and Cursor. Open-source, MIT.
Install / Use
claude mcp add CodeFormers-it -- npx -y github:CodeFormers-it/ksefnikIf the server publishes to npm under a different name, use that package instead — check the repo README.
MCP Server
Model Context Protocol server
Quality Score
Category
Finance & AccountingSupported Platforms
Skill content
View source on GitHubO projekcie
Ksefnik to kompletne, otwarte SDK do Krajowego Systemu e-Faktur (KSeF 2.0) — obowiązkowego od 2026-02-01 systemu Ministerstwa Finansów do wystawiania i pobierania faktur elektronicznych w Polsce. Projekt rozwijany przez CodeFormers.it adresuje dwa problemy, które każdy deweloper integrujący się z KSeF musi rozwiązać: produkcyjny klient HTTP do api.ksef.mf.gov.pl (auth flow z challenge + RSA-OAEP, parsowanie FA(2)/FA(3), refresh tokenów, rate limiting) oraz reconcyliacja faktur z wyciągami bankowymi (6-stopniowy pipeline dopasowujący KSeF ↔ MT940/mBank/ING/PKO BP/Santander).
Jako jeden z pierwszych SDK-ów do polskiej e-faktury Ksefnik wystawia również Model Context Protocol server — dzięki czemu możesz rozmawiać z KSeF-em z poziomu Claude Desktop, Cursora, Continue albo dowolnego innego klienta MCP. Pobranie faktur kosztowych za marzec, import wyciągu z ING i uruchomienie reconcyliacji sprowadza się do jednego zdania w czacie z AI.
Projekt jest na wczesnym etapie rozwoju — API może się zmieniać między wersjami 0.x. Od 1.0 obowiązuje semver.
Funkcje
Reconciliation Engine
Automatyczne dopasowywanie faktur KSeF do przelewow bankowych w 6 krokach: numer KSeF, dokladne dopasowanie NIP + kwota, numer faktury w tytule przelewu, przyblizone dopasowanie nazwy (fuzzy matching), platnosci czesciowe, dopasowanie bliskosci. Dokumentacja →
Bank Parsers
Import wyciagow z polskich bankow: MT940 (standard), CSV z mBank, ING, PKO BP, Santander. Automatyczna detekcja formatu pliku. Ekstrakcja NIP z tytulow przelewow. Dokumentacja →
HTTP Adapter (@ksefnik/http)
Produkcyjny klient HTTP do KSeF 2.0 (api.ksef.mf.gov.pl). Pelny flow uwierzytelnienia (challenge + RSA-OAEP), pobieranie metadanych faktur, parsowanie FA(2)/FA(3) XML, ekstrakcja kwot brutto. Gotowy do podpiecia pod createKsefnik() przez createHttpAdapter({ nip, token, environment, publicKeyPem }). Szczegoly: packages/http/README.md. Dokumentacja →
KSeF Simulator
Lokalny mock serwer KSeF do testow offline. Deterministyczny, bez polaczenia z Ministerstwem Finansow. Gotowe scenariusze: happy-path, timeout, odrzucenie faktury, wygasniecie sesji. Dokumentacja →
MCP Server
Model Context Protocol server (9 narzedzi) do integracji z Claude i innymi asystentami AI. Reconcyliacja, import wyciagow i zapytania o faktury bezposrednio z poziomu AI. Dokumentacja →
Walidacja faktur
Walidacja faktur przed wyslaniem do KSeF. Reguly biznesowe Ministerstwa Finansow z czytelnymi komunikatami bledow po polsku. Dokumentacja →
Type-Safe SDK
Pelne typy TypeScript wygenerowane z oficjalnych schematow XSD KSeF. Bledy wychwytywane na etapie kompilacji, a nie w runtime.
Instalacja
Wymagania: Node.js 22+, pnpm 9+
npm install @ksefnik/core @ksefnik/http
# lub
pnpm add @ksefnik/core @ksefnik/http
@ksefnik/core— reconcyliacja, parsery bankow, walidacja (baza)@ksefnik/http— produkcyjny klient HTTP do KSeF 2.0 (wymagane do produkcji)@ksefnik/simulator— mock KSeF do testow offline (devDep)
npm install --save-dev @ksefnik/simulator
Konfiguracja HTTP adaptera
import { createKsefnik } from '@ksefnik/core'
import { createHttpAdapter } from '@ksefnik/http'
import { readFileSync } from 'node:fs'
const adapter = createHttpAdapter({
nip: '7010002137',
token: process.env.KSEF_TOKEN!,
environment: 'production',
publicKeyPem: readFileSync('./ksef-public-key.pem', 'utf8'),
})
const ksef = createKsefnik({
config: { nip: '7010002137', environment: 'production', token: process.env.KSEF_TOKEN! },
adapter,
})
await adapter.initSession?.()
const invoices = await ksef.invoices.fetch({ from: '2026-03-01', to: '2026-03-31' })
await adapter.closeSession?.()
Szybki start
Pelny przewodnik krok po kroku: docs.ksefnik.pl/wprowadzenie/szybki-start
import { createKsefnik } from '@ksefnik/core'
const ksef = createKsefnik({
nip: '1234567890',
environment: 'test',
token: process.env.KSEF_TOKEN
})
// Pobierz faktury z KSeF
const invoices = await ksef.invoices.fetch({
dateFrom: '2026-03-01',
dateTo: '2026-03-31'
})
// Zaimportuj wyciag bankowy
const transactions = await ksef.bank.import('./wyciag.mt940')
// Uruchom reconcyliacje
const report = await ksef.reconciliation.run({ invoices, transactions })
console.log(`Dopasowane: ${report.matched.length}`)
console.log(`Niedopasowane faktury: ${report.unmatchedInvoices.length}`)
console.log(`Niedopasowane przelewy: ${report.unmatchedTransactions.length}`)
Architektura
Szczegolowy opis architektury monorepo: docs.ksefnik.pl/zaawansowane/architektura-monorepo
Ksefnik stosuje podejscie SDK-first -- cala logika biznesowa znajduje sie w pakiecie core, a pozostale pakiety (CLI, MCP server) sa cienkimi wrapperami, ktore z niego korzystaja.
ksefnik/
packages/
shared/ @ksefnik/shared Typy Zod, interfejsy, plugin system
core/ @ksefnik/core Reconciliation engine, bank parsers, KSeF adapter
http/ @ksefnik/http Produkcyjny klient HTTP do KSeF API v2
simulator/ @ksefnik/simulator Offline KSeF test harness
mcp/ @ksefnik/mcp MCP server (wrapper na core)
cli/ @ksefnik/cli CLI (Commander.js), standalone binary via bun compile
| Pakiet | Opis |
|--------|------|
| @ksefnik/shared | Wspoldzielone typy Zod, interfejsy i plugin system |
| @ksefnik/core | Glowna logika: reconciliation engine, bank parsers, adapter KSeF |
| @ksefnik/http | Produkcyjny klient HTTP do KSeF 2.0 (auth RSA-OAEP, sesje, pobieranie faktur) |
| @ksefnik/simulator | Lokalny mock serwer KSeF do testow offline |
| @ksefnik/mcp | Model Context Protocol server -- integracja z AI |
| @ksefnik/cli | Interfejs wiersza polecen, kompilacja do standalone binary |
MCP Server
MCP server udostępnia 9 narzędzi (reconcyliacja, import wyciągów, zapytania o faktury, walidacja, wysyłka, UPO) bezpośrednio z poziomu Claude Desktop, Cursor, Claude Code i innych klientów MCP.
Claude Desktop
Dodaj do claude_desktop_config.json (~/Library/Application Support/Claude/claude_desktop_config.json na macOS):
{
"mcpServers": {
"ksefnik": {
"command": "npx",
"args": ["-y", "@ksefnik/mcp"],
"env": {
"KSEF_NIP": "7010002137",
"KSEF_TOKEN": "twoj-token-ksef",
"KSEF_ENV": "test"
}
}
}
}
Cursor
Dodaj do .cursor/mcp.json w katalogu projektu:
{
"mcpServers": {
"ksefnik": {
"command": "npx",
"args": ["-y", "@ksefnik/mcp"],
"env": {
"KSEF_NIP": "7010002137",
"KSEF_TOKEN": "twoj-token-ksef",
"KSEF_ENV": "test"
}
}
}
}
Claude Code
claude mcp add ksefnik -- npx -y @ksefnik/mcp
Uruchomienie ręczne
npx @ksefnik/mcp
Dostępne narzędzia
| Narzędzie | Opis |
|-----------|------|
| sync-invoices | Pobierz faktury z KSeF |
| query-invoices | Wyszukaj faktury |
| import-bank | Importuj wyciąg bankowy |
| reconcile | Uruchom reconcyliację |
| get-unmatched | Pokaż niedopasowane pozycje |
| send-invoice | Wyślij fakturę do KSeF |
| validate-invoice | Waliduj fakturę |
| confirm-match | Potwierdź dopasowanie |
| get-upo | Sprawdź status UPO (potwierdzenie odbioru) |
Stack technologiczny
| Technologia | Zastosowanie | |-------------|-------------| | TypeScript (strict) | Jezyk programowania | | Node.js 22 | Srodowisko uruchomieniowe | | pnpm | Menedzer pakietow, workspace monorepo | | Zod | Walidacja danych i definicja schematow | | Vitest | Framework testowy | | Commander.js | CLI framework | | @clack/prompts | Interaktywne prompty CLI | | @modelcontextprotocol/sdk | Implementacja MCP server | | fuzzball | Fuzzy string matching | | mt940js | Parser formatu MT940 | | bun | Kompilacja CLI do standalone binary |
Rozwoj
Uruchomienie lokalne
git clone https://github.com/CodeFormers-it/ksefnik.git
cd ksefnik
pnpm install
pnpm build
Testy
pnpm test # uruchom wszystkie testy
pnpm test:watch # tryb watch
Wytyczne dla Pull Requestow
Pelny przewodnik dla kontrybutorów: docs.ksefnik.pl/zaawansowane/contributing
- Stworz branch z opisowa nazwa (
feat/partial-payments,fix/mt940-parser). - Upewnij sie, ze wszystkie testy przechodza (
pnpm test). - Dodaj testy dla nowej funkcjonalnosci.
- Opisz zmiany w PR -- co, dlaczego i jak przetestowac.
Zapraszamy do zglaszania Issues i Pull Requestow. Projekt jest na wczesnym etapie, wiec kazdego rodzaju wklad jest mile widziany.
Często zadawane pytania
Jak pobrać faktury z KSeF w Node.js albo TypeScript?
Zainstaluj @ksefnik/core i @ksefnik/http, skonfiguruj createHttpAdapter z tokenem KSeF i kluczem publicznym MF, i woła ksef.invoices.fetch({ from, to }). Pełen przykład w sekcji Szybki start. Ksefnik jest w tej chwili jedynym produkcyjnym KSeF SDK dla TypeScript / Node.js z pełnym pokryciem flow uwierzytelnienia KSeF 2.0.
Czy Ksefnik wspiera KSeF 2.0 (obowiązkowe API od 2026-02-01)?
Tak. Pakiet @ksefnik/http rozmawia bezpośrednio z api.ksef.mf.gov.pl/v2, implementuje pełen flow uwierzytelnienia (challenge + RSA-OAEP SHA-256, redeem, refresh) i parsuje faktury w formacie FA(2)/FA(3). Typy są generowane z oficjalnego OpenAPI MF, więc przy każdej zmianie kontraktu w MF masz breaking change na etapie kompilacji TypeScript.
Jak zintegrować KSeF z Claude Desktop, Cursorem albo innym agentem AI?
Ksefnik wystawia pełny serwer Model Context Protocol (@ksefnik/mcp) z 8 narzędziami: pobieranie faktur z KSeF,
Truncated for display — read the full file on GitHub.
Related Skills
Agent-Reach
84.4kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
headroom
73.4kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
ruflo
73.0k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
CowAgent
47.1kOpen-source super AI assistant & Agent Harness. Plans tasks, runs tools and skills, self-evolves with memory and knowledge. Multi-agent, multi-model, multi-channel. Lightweight, extensible, one-line install.
