MCP — integracja z asystentami AI#

KSeFka obsługuje protokół MCP (Model Context Protocol) — standard pozwalający asystentom AI (Claude, Cursor i innym) bezpośrednio tworzyć faktury, zarządzać kontrahentami i pobierać dane bez opuszczania czatu.

Wymagania#

• Zainstalowana aplikacja KSeFka
• Skonfigurowana firma (Ustawienia → Firmy)
• Wybrane środowisko KSeF (test / demo / produkcja)
• Licencja PRO albo trwający 30-dniowy okres próbny, wspólny z aplikacją i CLI; szczegóły na stronie Licencja PRO

Serwer MCP sprawdza licencję przy każdym wywołaniu narzędzia, nie tylko przy starcie. Gdy okres próbny się skończy, a klient AI wciąż trzyma serwer uruchomiony, każde narzędzie odpowie błędem zaczynającym się od "Funkcja PRO:" z adresem strony zakupu i poleceniem aktywacji ksefka authorize <TOKEN>. Gdy pliku ustawień aplikacji nie da się odczytać, komunikat mówi zamiast tego, jak go naprawić. Po aktywacji licencji narzędzia działają od następnego wywołania, bez restartu klienta AI.

Uruchomienie serwera#

Serwer MCP uruchamia się przez CLI jako proces stdio — klient AI zarządza jego cyklem życia automatycznie:

ksefka mcp

Domyślnie serwer startuje w środowisku zapisanym w preferencjach aplikacji (ostatnio wybranym w sidebarze). Możesz nadpisać środowisko startowe flagą --env:

ksefka mcp --env test

Konfiguracja Claude Desktop#

Otwórz plik konfiguracyjny Claude Desktop (claude_desktop_config.json) i dodaj wpis:

{
  "mcpServers": {
    "ksefka": {
      "command": "ksefka",
      "args": ["mcp"]
    }
  }
}

Lokalizacja pliku konfiguracyjnego:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Konfiguracja Cursor#

W ustawieniach Cursor przejdź do MCP Servers i dodaj:

{
  "ksefka": {
    "command": "ksefka",
    "args": ["mcp"]
  }
}

Przełączanie środowiska#

Jedna sesja serwera MCP może swobodnie przełączać się między środowiskami KSeF (test / demo / produkcja) bez restartu klienta AI. Dwa narzędzia:

• get_environment — zwraca aktualnie aktywne środowisko, ID i nazwę aktywnej firmy. Wywołaj przed każdą mutacją, żeby mieć pewność gdzie pracujesz.
• switch_environment — zmienia aktywne środowisko na test, demo lub production. Zmiana jest sesyjna — po restarcie klienta serwer wraca do środowiska startowego: wartości flagi --env, a jeśli nie została podana, do środowiska zapisanego w preferencjach aplikacji desktopowej. Zmiany przez switch_environment nie są utrwalane.

⚠️ Gdy aktywne środowisko to production, asystent AI ma w instrukcjach zadanie potwierdzać z Tobą każdą operację mutującą (tworzenie faktur, wysyłanie do KSeF, zmiany kontrahentów). Dla zatwierdzenia faktury do wysyłki i pliku przelewów serwer dodatkowo wymusza zgodę w Ustawieniach i potwierdzenie tokenem, opisane w sekcji Zapis w środowisku produkcyjnym.

Uwaga: flaga --company-id w CLI dotyczy wyłącznie środowiska startowego. Po switch_environment serwer odczytuje aktywną firmę z preferencji nowego środowiska — ID firm są różne w każdej bazie.

Przełączanie firmy#

Jeśli w danym środowisku masz skonfigurowanych kilka firm, sesja MCP może przełączać się między nimi bez restartu klienta AI. Dwa narzędzia:

• list_companies — zwraca listę firm dostępnych w bazie danych aktualnie aktywnego środowiska. Każdy element ma id, company_name, nip oraz flagę is_session_active wskazującą firmę używaną przez bieżącą sesję MCP. Tylko aktywne środowisko — żeby zobaczyć firmy z innego, najpierw wywołaj switch_environment.
• switch_company — zmienia aktywną firmę w obrębie bieżącego środowiska. Parametr company_id (z list_companies). Zmiana jest sesyjna — nie modyfikuje preferencji aplikacji desktopowej i nie zmienia środowiska. Po restarcie klienta lub po switch_environment aktywna firma wraca do firmy zapisanej w preferencjach środowiska.

⚠️ Gdy aktywne środowisko to production, asystent AI powinien potwierdzić z Tobą zmianę firmy przed wywołaniem switch_company. Każda kolejna mutacja zapisze się dla nowo wybranej firmy.

Reset przy zmianie środowiska: wywołanie switch_environment z innym środowiskiem zawsze resetuje aktywną firmę do firmy z preferencji tego środowiska. Jeśli wcześniej zmieniłeś firmę przez switch_company, ta zmiana nie propaguje się do innego środowiska i nie jest zachowywana po powrocie do poprzedniego — każde wejście do innego środowiska zaczyna się od jego domyślnej firmy. Wyjątek: wywołanie switch_environment ze środowiskiem, w którym już jesteś, jest no-op'em i nie resetuje firmy (zachowuje aktualny switch_company).

Zapis w środowisku produkcyjnym#

Dwa narzędzia mają skutki poza KSeFką: finalize_invoice kieruje fakturę do kolejki wysyłki do KSeF, a generate_payment_file tworzy plik, który trafia do banku. W środowisku production oba działają dopiero po spełnieniu dwóch warunków, które sprawdza serwer KSeFki, nie model.

Zgoda w aplikacji. W KSeFce otwórz Ustawienia → CLI → Integracja AI i włącz "Pozwól asystentowi AI zatwierdzać dokumenty w produkcji". Opcja jest domyślnie wyłączona, dotyczy tylko środowiska produkcyjnego i nie da się jej włączyć z czatu ani z wiersza poleceń. Dopóki jest wyłączona, oba narzędzia w produkcji odpowiadają błędem z kodem PRODUCTION_WRITES_DISABLED i nie zmieniają niczego; asystent dostaje w komunikacie ścieżkę do tej opcji.

Potwierdzenie każdej operacji. Pierwsze wywołanie bez tokenu nic nie zapisuje. Zwraca status: "confirmation_required", podgląd skutków (numer faktury, kontrahent, kwota brutto albo liczba przelewów i nazwa pliku) oraz confirmation_token. Asystent ma pokazać Ci podgląd i zapytać o zgodę, a dopiero po Twoim "tak" wywołać narzędzie ponownie z tym tokenem; wtedy faktura trafia do kolejki albo plik powstaje na dysku. Token działa raz, wygasa po 5 minutach i przestaje działać, gdy dokument zmienił się od chwili podglądu (inne pozycje, inny kontrahent, inny rachunek odbiorcy lub firmy, faktura opłacona w międzyczasie). Każdy z tych przypadków kończy się kodem CONFIRMATION_INVALID; asystent wywołuje narzędzie jeszcze raz bez tokenu i pokazuje nowy podgląd. Gdy nie ma czego zapisać (żadna z faktur nie kwalifikuje się do przelewu, dokument nie jest szkicem wystawionym), narzędzie odpowiada od razu, bez tokenu.

Token wraca do tego samego asystenta, więc nie dowodzi, że zgoda przyszła od Ciebie: wymusza krok z podglądem, blokuje zapis jednym wywołaniem i wykrywa zmianę dokumentu między podglądem a wykonaniem. Twarda granica jest jedna: zgoda w Ustawieniach. Dopóki jej nie włączysz, żaden asystent nie zatwierdzi faktury przez finalize_invoice ani nie utworzy pliku przelewów w produkcji; o drodze przez harmonogramy cykliczne, która tej bramki nie ma, mowa niżej.

W środowiskach test i demo nic się nie zmienia: oba narzędzia działają od razu, bez zgody i bez tokenu.

send_now, które wysyła fakturę do KSeF od razu, w produkcji też wymaga zgody w Ustawieniach. Tokenu nie ma, bo wysyła tylko faktury już zatwierdzone: przez finalize_invoice z tokenem albo w aplikacji. Szkic odrzuca z prośbą o zatwierdzenie.

Narzędzia tylko do odczytu#

Każde narzędzie deklaruje adnotacje MCP (readOnlyHint, destructiveHint, idempotentHint), z których klient AI buduje własne pytania o zgodę. Tylko odczytują dane: get_environment, list_companies, list_invoices, get_invoice, list_proformas, get_proforma, list_contractors, get_contractor, lookup_company_by_nip, list_products, get_product, list_templates, get_attachments, list_recurring, get_recurring, monthly_summary, dashboard_stats, fetch_nbp_rate i get_daemon_status. Jako destrukcyjne (mogą nadpisać lub usunąć dane albo skierować dokument do KSeF) oznaczone są finalize_invoice, send_now, generate_payment_file, convert_proforma, cancel_proforma, update_contractor, delete_contractor, remove_attachment, delete_recurring, generate_recurring, process_recurring i ksef_authorize. Pozostałe dodają nowe rekordy albo zmieniają stan, który da się przestawić z powrotem.

Jedna droga do KSeF nie przechodzi przez bramkę: harmonogram faktury cyklicznej utworzony z trybem "gotowa do wysłania" sam kieruje kolejne faktury do kolejki, także gdy utworzy go asystent przez create_recurring_from_invoice. Przy tych narzędziach w produkcji asystent ma jedynie prośbę o potwierdzenie z opisu narzędzia; sprawdzaj tryb harmonogramu, który proponuje.

Treść faktur a asystent AI#

Faktury otrzymane pisze ktoś inny. Nazwa pozycji, opis albo uwagi na fakturze zakupowej mogą zawierać zdanie skierowane do asystenta, na przykład polecenie zatwierdzenia dokumentu albo zmiany rachunku kontrahenta. Gdy asystent czyta taką fakturę przez get_invoice, to zdanie trafia do jego kontekstu razem z danymi i model może je potraktować jak Twoje polecenie. Dlatego zgoda w Ustawieniach jest po stronie serwera: asystent, który dał się namówić, nie zatwierdzi faktury przez finalize_invoice ani nie utworzy pliku przelewów, dopóki jej nie włączysz. Po włączeniu chroni Cię to, że asystent musi przejść przez podgląd, i Twoja uwaga przy tym podglądzie. Przy zmianach kontrahentów, rachunków i harmonogramów cyklicznych, które nie przechodzą przez tę bramkę, czytaj to, co asystent proponuje, zanim się zgodzisz.

Dane, które asystent pobiera z KSeFki, trafiają do dostawcy modelu, z którym rozmawiasz (Anthropic dla Claude, OpenAI dla ChatGPT, operator modelu w Cursorze). KSeFka niczego sama nie wysyła: wynik każdego narzędzia odbiera klient AI na Twoim komputerze i to on przekazuje go do modelu. Numery faktur, nazwy i NIP-y kontrahentów, kwoty i numery rachunków, o które zapytasz, są więc przetwarzane na warunkach tego dostawcy. Jeśli nie chcesz, żeby dane produkcyjne opuszczały komputer, pracuj z asystentem w środowisku demo albo pytaj o konkretne faktury zamiast o całe listy.

Synchronizacja i wysyłka do KSeF#

Serwer MCP sam nie łączy się z KSeF. Synchronizację i wysyłkę zleca procesowi pracy w tle (demonowi), który uruchamia otwarta aplikacja KSeFka albo komenda ksefka daemon start (opis w dokumentacji CLI). Gdy demon nie działa, nic nie jest pobierane z KSeF ani do niego wysyłane, a sync_now i send_now odpowiadają błędem z kodem DAEMON_NOT_RUNNING i podpowiedzią, jak go uruchomić. Ten sam kod dostaniesz, gdy demon działa na innym środowisku niż sesja MCP.

• sync_now synchronizuje firmę aktywną w sesji (albo podaną w company_id) i czeka na wynik do 2 minut. Gdy części faktur nie pobrała, odpowiedź ma status: "partial" i listę problemów w result.failures. Dłuższa synchronizacja trwa dalej w demonie, a odpowiedź ma status: "in_progress".
• send_now z invoice_id wysyła zatwierdzoną fakturę i czeka na status z KSeF do 2 minut. Bez invoice_id zleca wysyłkę wszystkich zatwierdzonych faktur firmy i odpowiada od razu.
• finalize_invoice z send_now: true zatwierdza fakturę i od razu ją wysyła. Status z KSeF jest w polu send odpowiedzi. Gdy wysyłka nie ruszy (brak demona, odmowa demona), faktura zostaje zatwierdzona i wyjdzie z kolejką; fakturę odrzuconą przez KSeF trzeba poprawić i wysłać ponownie.
• get_daemon_status mówi, czy demon działa, kiedy ostatnio zsynchronizował każdą firmę i do kiedy trwa blokada po limicie zapytań KSeF.

Dostępne narzędzia#

Przykład#

Wpisujesz do czatu:

AI kolejno wywołuje:

1. list_contractors — szuka "Acme" w bazie kontrahentów
2. create_invoice — tworzy fakturę: kierunek issued, 1 pozycja (10 h × 200 zł, VAT 23%), kontrahent z poprzedniego kroku, termin płatności +14 dni
3. open_invoice — otwiera fakturę w aplikacji do podglądu i ewentualnej korekty

Efekt: w KSeFce pojawia się gotowy szkic faktury na kwotę 2460 zł brutto (2000 zł netto + 460 zł VAT). Możesz go przejrzeć, poprawić i wysłać do KSeF — bez ręcznego wypełniania formularza.

Serwer MCP zawiera wbudowane instrukcje dla AI dotyczące faktur korygujących, zaliczkowych, rozliczeniowych oraz faktur w walutach obcych z automatycznym kursem NBP.