# 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
```

✦

**Szybsza konfiguracja:** Wklej do czatu z AI: `https://ksefka.com/llms.txt` — asystent sam się skonfiguruje i wyjaśni jak zacząć.

## 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

| Narzędzie | Opis |
| --- | --- |
| Sesja |  |
| `get_environment` | Zwraca aktywne środowisko KSeF, ID i nazwę aktywnej firmy |
| `switch_environment` | Przełącza aktywne środowisko (test / demo / production) bez restartu — sesyjnie. Resetuje aktywną firmę do firmy z preferencji nowego środowiska |
| `list_companies` | Lista firm dostępnych w bazie aktywnego środowiska, z oznaczeniem aktywnej |
| `switch_company` | Przełącza aktywną firmę w obrębie bieżącego środowiska — sesyjnie, bez zmiany środowiska |
| Faktury |  |
| `list_invoices` | Lista faktur z filtrowaniem po kierunku, miesiącu, statusie, kontrahencie i wartości |
| `get_invoice` | Szczegóły faktury wraz z pozycjami |
| `create_invoice` | Utwórz fakturę (VAT, korygującą, zaliczkową, rozliczeniową) — dane jako obiekt JSON |
| `finalize_invoice` | Przenieś szkic do stanu "gotowa do wysłania do KSeF" |
| `unfinalize_invoice` | Cofnij finalizację faktury z powrotem do szkicu |
| `copy_invoice` | Skopiuj fakturę jako nowy szkic z dzisiejszą datą |
| `mark_invoice_paid` | Oznacz fakturę jako opłaconą lub nieopłaconą (lokalna adnotacja użytkownika, nie pole KSeF/XML) |
| `export_invoice` | Eksportuj fakturę do PDF i/lub XML (PRO). PDF zawiera kod QR, gdy faktura ma numer KSeF lub certyfikat offline |
| `generate_payment_file` | Wygeneruj plik przelewów (Elixir-0) dla faktur otrzymanych do zapłaty (PRO, 1 darmowy eksport) |
| `open_invoice` | Otwórz fakturę w aplikacji desktopowej do podglądu lub edycji |
| Załączniki |  |
| `attach_file` | Dodaj załącznik do faktury (pdf, png, jpg, jpeg, webp, gif, bmp, tiff). Pierwszy załącznik faktury otrzymanej jest darmowy; każdy kolejny załącznik faktury otrzymanej oraz dowolny załącznik faktury wystawionej wymagają licencji PRO |
| `get_attachments` | Lista załączników faktury |
| `remove_attachment` | Usuń załącznik faktury |
| Faktury cykliczne |  |
| `list_recurring` | Lista harmonogramów faktur cyklicznych aktywnej firmy |
| `get_recurring` | Szczegóły harmonogramu faktury cyklicznej |
| `create_recurring_from_invoice` | Utwórz harmonogram faktury cyklicznej na podstawie istniejącej faktury — kopiuje pozycje, kontrahenta i ustawienia płatności |
| `pause_recurring` | Wstrzymaj harmonogram faktury cyklicznej |
| `resume_recurring` | Wznów wstrzymany harmonogram faktury cyklicznej |
| `generate_recurring` | Wygeneruj kolejne wystąpienie faktury cyklicznej teraz, niezależnie od daty |
| `process_recurring` | Przetwórz wszystkie zaległe harmonogramy — generuje faktury dla wszystkich, których data następnego wystąpienia już minęła |
| `delete_recurring` | Usuń harmonogram faktury cyklicznej |
| Kontrahenci |  |
| `list_contractors` | Lista kontrahentów z wyszukiwaniem po nazwie lub NIP |
| `get_contractor` | Pełne dane kontrahenta |
| `create_contractor` | Dodaj nowego kontrahenta |
| `update_contractor` | Zaktualizuj dane kontrahenta |
| `delete_contractor` | Usuń (dezaktywuj) kontrahenta |
| `lookup_company_by_nip` | Pobierz dane firmy z rejestru GUS BIR1 na podstawie NIP |
| Produkty |  |
| `list_products` | Lista produktów/usług z katalogu |
| `get_product` | Szczegóły produktu |
| `create_product` | Dodaj produkt do katalogu |
| Raporty i kursy walut |  |
| `monthly_summary` | Podsumowanie miesięczne: suma przychodów i kosztów |
| `dashboard_stats` | Statystyki bieżącego miesiąca |
| `fetch_nbp_rate` | Kurs średni NBP dla waluty na dany dzień |
| Szablony i KSeF |  |
| `list_templates` | Lista szablonów faktur |
| `ksef_authorize` | Zapisz token autoryzacyjny KSeF |

## Przykład

Wpisujesz do czatu:

"Stwórz fakturę dla Acme Sp. z o.o. za 10 godzin programowania po 200 zł netto, VAT 23%, termin płatności 14 dni."

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.