FakturaXL MCP Server

Zdalny serwer MCP dla API FakturaXL, wystawiany pod URL przez Streamable HTTP. Obsługuje legacy Bearer z kluczem FakturaXL oraz opcjonalny OAuth 2.1 dla Cursor Desktop, ChatGPT i Claude.

Domyślnie serwer jest read-only. Wystawianie faktur włącza flaga ALLOW_WRITE=true (patrz „Zapis: wystawianie faktur”).

Stack

• Node.js (>=20) + TypeScript (ESM)

• @modelcontextprotocol/sdk v1.x (McpServer + StreamableHTTPServerTransport)

• Express (endpoint HTTP)

• fast-xml-parser (API FakturaXL komunikuje się XML-em)

Related MCP server: InvoiceNinja MCP Server

Instalacja

npm install
cp .env.example .env   # Windows: copy .env.example .env

Uruchomienie

npm run dev     # tryb deweloperski (tsx watch)
npm run build   # kompilacja do dist/
npm start       # uruchomienie z dist/

Serwer nasłuchuje na http://localhost:<PORT>/mcp (domyślnie port 3000). Health check: GET /health.

Konfiguracja (.env)

Warstwa praktyczna (agent-friendly)

Serwer nie jest cienkim wrapperem — ukrywa uciążliwości API przed agentem:

• Auto-paginacja — pobiera wszystkie strony pod spodem; agent nie widzi strona/na_stronie.

• Chunking dat — dowolny zakres jest wewnętrznie dzielony na okna ≤31 dni (limit API) i scalany. Powyżej MAX_RANGE_MONTHS zakres jest przycinany z ostrzeżeniem.

• Kursor czasowy — szeroki zakres nie zmieści się w jednym wywołaniu (patrz „Limity API” poniżej), więc narzędzie pracuje do TOOL_BUDGET_MS i zwraca dane częściowe z kursor_nastepny, ukonczono i postep. Agent kontynuuje kolejnym wywołaniem z tym kursorem. Zawsze przetwarzane jest co najmniej jedno okno, więc kursor nie może się zapętlić.

• Natywny throttling — rate limiter respektuje odstępy z dokumentacji (dokumenty 5 s; produkty/klienci/stany 10 s; reszta 1 s) + retry z backoff na kod 2. Kolejka jest per token API, bo limit obowiązuje per konto — agenci różnych kont nie blokują się wzajemnie.

• Filtrowanie po kliencie (którego API nie ma) — po nazwie (fuzzy) lub NIP, realizowane po stronie serwera.

• Compact + summary + has_more — listy zwracają skrócone rekordy, zawsze z agregatami (liczba, sumy per waluta, rozkład statusów/rodzajów) i informacją o obcięciu, żeby nie zalewać kontekstu agenta.

• Cache TTL — listy słownikowe (klienci/produkty/magazyny/działy) są cache'owane. Dokumenty nie są cache'owane, bo mogą być edytowane.

Limity API FakturaXL (zweryfikowane empirycznie)

Te ograniczenia determinują architekturę narzędzi dokumentów, dlatego zostały sprawdzone zapytaniami do produkcyjnego API, nie tylko odczytane z dokumentacji:

Konsekwencja: 2 lata dokumentów to ~24 okna × 5 s ≈ 120 s i nie ma sposobu, by to skrócić. Dlatego narzędzia dokumentów zwracają kursor zamiast wisieć do timeoutu klienta (zwykle 60 s).

Autoryzacja

Serwer obsługuje dwie zgodne wstecznie metody.

Legacy Bearer

Klient wysyła klucz FakturaXL bezpośrednio w każdym żądaniu:

Authorization: Bearer <TWOJ_KLUCZ_API_FAKTURAXL>

Ta metoda działa zawsze, również po włączeniu OAuth. Klucz nie jest wtedy zapisywany przez serwer. Nieprawidłowy klucz daje błąd auth z API FakturaXL.

OAuth 2.1 dla Cursor Desktop, ChatGPT i Claude

OAuth jest domyślnie wyłączony. Po włączeniu klient MCP wykonuje discovery, Dynamic Client Registration i PKCE S256, po czym otwiera formularz w przeglądarce. Użytkownik podaje klucz FakturaXL, serwer sprawdza go odczytowym dokument_lista_dzialow.php, szyfruje i zapisuje grant. Klient otrzymuje opaque access token; ten token nigdy nie jest przekazywany do FakturaXL.

Provider akceptuje dokładne callbacki skonfigurowane w OAUTH_ALLOWED_REDIRECT_URIS oraz oficjalne callbacki zdalnych konektorów:

• ChatGPT: https://chatgpt.com/connector/oauth/{callback_id} z jednym niepustym segmentem identyfikatora oraz starszy https://chatgpt.com/connector_platform_oauth_redirect;

• Claude: https://claude.ai/api/mcp/auth_callback i https://claude.com/api/mcp/auth_callback.

Przykładowa konfiguracja Cursor nie zawiera sekretu:

{
  "mcpServers": {
    "fakturaxl": {
      "url": "https://mcp.example.pl/mcp"
    }
  }
}

Endpointy discovery i protokołu:

• /.well-known/oauth-authorization-server

• /.well-known/oauth-protected-resource/mcp

• /register, /authorize, /token, /revoke

• /oauth/authorize/complete — obsługa formularza, nie endpoint publicznego API

Uruchomienie OAuth

Wygeneruj jeden trwały klucz szyfrujący. Jego zmiana uniemożliwi odszyfrowanie istniejącego magazynu:

node -e "console.log(require('node:crypto').randomBytes(32).toString('base64'))"

Ustaw:

OAUTH_ENABLED=true
PUBLIC_BASE_URL=https://mcp.example.pl
OAUTH_STORE_KEY=<WYNIK_POLECENIA>

PUBLIC_BASE_URL musi być originem bez ścieżki. Produkcja wymaga HTTPS; HTTP jest akceptowane wyłącznie dla localhost. Access i refresh token są domyślnie bezterminowe; refresh token nadal jest rotowany przy każdym odświeżeniu. Skradziony token pozostaje ważny do wywołania /revoke albo usunięcia grantu, dlatego krótsze TTL są bezpieczniejszą opcją dla publicznych wdrożeń.

Magazyn oauth-store.json jest w całości szyfrowany AES-256-GCM. Kody i tokeny są dodatkowo zapisywane tylko jako SHA-256. Zapis używa pliku tymczasowego, fsync i atomowego rename; zły klucz szyfrujący lub uszkodzony plik zatrzymuje start.

Implementacja plikowa obsługuje wielu użytkowników, ale zakłada jeden kontener. Nie skaluj tej wersji poziomo — wiele replik wymaga wspólnego magazynu transakcyjnego.

Dostępne narzędzia (odczyt)

Przykład (agent): „faktury od K8 z ostatniego kwartału” → lista_dokumentow z data_od/data_do i klient: "K8". Chunking, paginacja, throttling i mapowanie nazwy klienta na klient_id dzieją się wewnętrznie.

Przy dłuższym zakresie odpowiedź zawiera ukonczono: false i kursor_nastepny. Agent musi wtedy wywołać narzędzie ponownie z tym samym zakresem i kursor równym tej wartości, aż ukonczono: true, a wyniki scalić (sumy dodać). Przy TOOL_BUDGET_MS=40000 jedno wywołanie obejmuje ~7 okien, czyli 2 lata to ~4 wywołania.

Świadomie pominięte: korekty, faktury zaliczkowe/końcowe, wysyłka e-mail, KSeF, relacje, tagi, zmiana statusu, usuwanie dokumentów.

Zapis: wystawianie faktur

Włączane flagą ALLOW_WRITE=true. Bez niej narzędzia zapisu nie są rejestrowane, więc agent ich nie widzi — domyślne wdrożenie pozostaje read-only. GET /health raportuje tryb (read-only / read-write).

Zakres: Faktura VAT (typ_faktury=0), przychodowa.

Dlaczego dwa kroki: wystawienie faktury jest nieodwracalne (zużywa numer z ciągłej numeracji), a MCP nie ma UI z przyciskiem potwierdzenia. Bariera siedzi więc w protokole — agent musi najpierw pokazać użytkownikowi podgląd z kwotami.

Token daje przy okazji idempotencję, której API FakturaXL nie ma: klient MCP potrafi powtórzyć wywołanie po timeoucie, a zużyty draft zwraca pierwotny dokument zamiast wystawiać drugi. Drafty żyją w pamięci procesu (TTL DRAFT_TTL_MS), więc restart unieważnia te niepotwierdzone.

Kwoty w podglądzie liczymy lokalnie w groszach (float gubi grosze na sumach pozycji), wyłącznie po to, żeby użytkownik zobaczył wartość przed wystawieniem. Ostateczne kwoty nalicza FakturaXL — w teście E2E obie liczby były identyczne (230.00 / 52.90 / 282.90).

Pułapki API przy zapisie (zweryfikowane sondą)

Logowanie

Logi są w formacie JSON (jedna linia = jedno zdarzenie). Token API jest zawsze maskowany (widoczne tylko ostatnie 4 znaki). Trafiają na konsolę oraz — gdy LOG_TO_FILE=true — do katalogu logs/.

Rejestrowane zdarzenia:

Body request/response jest obcinane do LOG_BODY_MAX_CHARS (odpowiedzi API sięgają setek KB). Pełne body jest logowane tylko przy błędach. Kontenery mają ustawioną rotację logów Dockera (max-size: 10m, max-file: 3).

Struktura

src/
  index.ts                 # inicjalizacja OAuth i start procesu HTTP
  app.ts                   # Express + Streamable HTTP + dual auth + logi żądań/rozłączeń
  server.ts                # buildServer(apiToken) - instancja McpServer per request
  config.ts                # konfiguracja z .env
  logger.ts                # logger JSON + maskowanie sekretów + obcinanie body
  callContext.ts           # kontekst wywołania narzędzia (licznik zapytań do API, czas)
  auth/
    runtime.ts             # router OAuth SDK, metadata i trwały runtime
    provider.ts            # DCR, authorize, token, refresh, revoke i formularz
    store.ts               # szyfrowany, atomowy magazyn JSON
    resolveCredential.ts   # OAuth access token lub legacy klucz FakturaXL
    validateApiToken.ts    # odczytowa walidacja klucza przed wydaniem grantu
    ui.ts                  # responsywny formularz autoryzacji
  tools/runner.ts          # wspólny wrapper narzędzia (kontekst pomiarowy + logi)
  tools/register.ts        # rejestracja narzędzi odczytu
  tools/registerWrite.ts   # rejestracja narzędzi zapisu (tylko przy ALLOW_WRITE)
  fakturaxl/invoice.ts     # schema faktury VAT, wyliczenia podglądu, mapowanie na XML
  fakturaxl/drafts.ts      # drafty faktur (dwa kroki + idempotencja)
  fakturaxl/client.ts      # XML->POST->JSON, mapowanie błędów, rate limiter + retry
  fakturaxl/rateLimiter.ts # throttling per (token + endpoint) wg odstępów z dokumentacji
  fakturaxl/pagination.ts  # auto-paginacja (fetchAllPages)
  fakturaxl/dates.ts       # chunking zakresu dat na okna <=31 dni + cap 24 mies.
  fakturaxl/cache.ts       # cache TTL w pamięci (tylko listy słownikowe)
  fakturaxl/service.ts     # getDocuments z budżetem czasu i kursorem, findClients/Products
  fakturaxl/compact.ts     # compact mappery + agregacja (summary)
  fakturaxl/codes.ts       # mapa kodów zwracanych przez API
docs/
  api-fakturaxl.md         # dokumentacja API FakturaXL
  diagram.md               # architektura dual auth i przepływ sekretów
  etap 1/backlog.md        # wykonanie wystawiania faktur
  etap 2/backlog.md        # wykonanie OAuth 2.1
.github/workflows/
  ci-cd.yml                # build + push obrazu do GHCR i deploy przez SSH
Dockerfile                 # multi-stage: build / runtime (prod) / dev
docker-compose.dev.yml     # lokalny dev (hot-reload, bez Traefika)
docker-compose.example.yml # szablon compose produkcyjnego (Traefik) do skopiowania

Docker

Legacy Bearer pozostaje bezstanowy. Po włączeniu OAuth stan trafia do ./data/oauth-store.json, montowanego jako /app/data/oauth-store.json. Katalog nie trafia do obrazu ani repozytorium.

Pliki:

• Dockerfile — multi-stage (build → runtime produkcyjny, oraz dev z hot-reload). Obraz produkcyjny na node:22-alpine, uruchamiany jako user node, z healthcheckiem /health.

• docker-compose.dev.yml — lokalny development, port 3000:3000 i bind mount ./data.

• docker-compose.example.yml — produkcja za Traefikiem z TLS i bind mount ./data.

Dev (lokalnie)

mkdir data
docker compose -f docker-compose.dev.yml up --build
# MCP: http://localhost:3000/mcp   health: http://localhost:3000/health

Na Windowsie uprawnienia bind mountu obsługuje Docker Desktop. Na natywnym Linuksie katalog musi należeć do UID/GID 1000, bo proces działa jako user node.

Serwer (produkcja, Traefik)

Wymaga istniejącej zewnętrznej sieci traefik-net. Na serwerze, w katalogu aplikacji (u nas /home/user/myapps/fakturaxl-mcp-server/), tworzymy docker-compose.yml na bazie szablonu, przygotowujemy katalog danych i ustawiamy .env:

cp docker-compose.example.yml docker-compose.yml
mkdir -p data
sudo chown 1000:1000 data
chmod 700 data
# .env: MCP_DOMAIN, TRAEFIK_CERTRESOLVER, OAUTH_ENABLED i OAUTH_STORE_KEY
docker compose up -d

Plik jest tworzony z trybem 600. Backupuj data/oauth-store.json razem z bezpiecznie przechowywanym OAUTH_STORE_KEY; sam plik bez klucza jest nieczytelny. Nie używaj docker compose down -v jako procedury sprzątania danych i nie uruchamiaj drugiej repliki.

Router nasłuchuje na wskazanej domenie (entrypoint websecure, TLS przez certresolver Traefika), kierując ruch na port 3000 kontenera. W mcp.json użyj samego URL dla OAuth albo dodaj nagłówek Authorization: Bearer <klucz> dla trybu legacy.

Test lokalny (MCP Inspector)

npx @modelcontextprotocol/inspector

W Inspectorze: transport Streamable HTTP, URL http://localhost:3000/mcp, nagłówek Authorization: Bearer <klucz>.

Test OAuth w Cursor Desktop: włącz OAuth z PUBLIC_BASE_URL=http://localhost:3000, zostaw w konfiguracji MCP wyłącznie url, uruchom ponownie Cursor i wybierz połączenie. Przeglądarka powinna otworzyć formularz, a callback wrócić na http://localhost:8787/callback. W ChatGPT i Claude dodaj zdalny konektor wskazujący na publiczny URL /mcp; ich callbacki są rozpoznawane automatycznie.

Wdrożenie produkcyjne (CI/CD)

Wdrożenie jest automatyczne: każdy push do main uruchamia .github/workflows/ci-cd.yml, który buduje obraz, wypycha go do GHCR i wchodzi na serwer przez SSH, żeby zrobić docker compose pull && up -d. Ręcznie można go odpalić przez workflow_dispatch (gh workflow run "Build & Deploy").

Jak to działa:

1. Build i push — obraz ghcr.io/socialbuzzstudio/fakturaxl-mcp-server w tagach latest i wersji z package.json. Build używa target: runtime — to obowiązkowe, bo ostatnim etapem Dockerfile jest dev z hot-reloadem. Kompilacja TypeScript dzieje się w etapie build, więc błąd typów zatrzymuje CI. Publikacja idzie wbudowanym GITHUB_TOKEN (job ma packages: write) — żadnych własnych PAT-ów.

2. Deploy — appleboy/ssh-action loguje się na serwer kluczem z sekretu, robi docker login ghcr.io tokenem ważnym tylko na czas tego przebiegu, pobiera obraz, restartuje kontener i się wylogowuje. Serwer nie przechowuje żadnych poświadczeń do rejestru.

Paczka w GHCR jest prywatna, mimo że repozytorium jest publiczne — w GHCR widoczność paczki jest niezależna od widoczności repo i domyślnie ustawiona na prywatną. Paczka dziedziczy uprawnienia dostępu z repo, dzięki czemu job deployu ma do niej dostęp bez dodatkowej konfiguracji. Uwaga: zmiana paczki na publiczną jest nieodwracalna.

Wymagane sekrety w repozytorium (ustawiane przez gh secret set, nie klikane w przeglądarce):

Klucz prywatny podaje się przez potok (Get-Content -Raw ... | gh secret set ...), a nie przez --body — musi wejść w całości, z liniami BEGIN/END, inaczej deploy padnie na „invalid format".

Bez Dockera (wdrożenie ręczne): npm ci && npm run build && npm start za reverse proxy (nginx/Caddy/Traefik) z TLS, kierującym /mcp na port aplikacji.