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)

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).

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).

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.