Narzędzia MCP Firmowida: pełna lista
Aktualizacja:
Serwer MCP Firmowida udostępnia 42 narzędzia: 21 czyta dane, 21 je zapisuje. Dwa z czytających otwierają widżet, w którym potwierdzasz fakturę albo korektę. Poniżej każde narzędzie z opisem i najniższą rolą, która może go użyć.
Podstawowe dane serwera
| Cecha | Wartość |
|---|---|
| Adres | https://firmowid.pl/mcp |
| Transport | Streamable HTTP |
| Logowanie | OAuth 2.1, kod autoryzacyjny z PKCE (S256), zakres mcp |
| Rejestracja klienta | Client ID Metadata Document albo Dynamic Client Registration (POST /oauth/register) |
| Typ klienta | publiczny, bez client_secret |
| Token dostępu | ważny 1 godzinę |
| Token odświeżania | ważny 30 dni, wymieniany przy każdym użyciu |
| Zakres danych | jedna firma, wybrana na ekranie zgody |
| Karta serwera | /.well-known/mcp/server-card.json |
| Opis dla agentów | /.well-known/agent-skills/firmowid-mcp/SKILL.md |
Adres zwrotny klienta musi być w HTTPS. Wyjątkiem jest adres lokalny (localhost, 127.0.0.1), więc Cursor i inne narzędzia uruchamiane na komputerze łączą się bez dodatkowej konfiguracji.
Jak czytać tabele
- Odczyt niczego nie zmienia w firmie.
- Zapis wykonuje się od razu po wywołaniu. Serwer nie pokazuje przy nim własnego okna potwierdzenia. Czy przed wywołaniem zobaczysz pytanie o zgodę, zależy od Twojego klienta (Claude, ChatGPT, Cursor) i jego ustawień, więc zapis może się wykonać bez dodatkowego potwierdzenia.
- Odczyt + widżet otwiera podgląd dokumentu. Fakturę albo korektę wystawia dopiero kliknięcie w tym podglądzie.
- Rola to najniższa rola w Firmowidzie, która może użyć narzędzia. Kolejność ról: pracownik, fakturowanie, księgowość, admin.
Czas pracy, urlopy, profil (11)
| Narzędzie | Typ | Co robi | Rola |
|---|---|---|---|
list_sessions |
odczyt | pokazuje Twoje sesje pracy od najnowszych; zawsze tylko własne, także na koncie admina | pracownik |
get_current_session |
odczyt | zwraca trwającą sesję, jeśli jakaś jest | pracownik |
start_session |
zapis | zaczyna sesję teraz, z opisem i projektem; trwająca sesja zostaje zatrzymana | pracownik |
stop_current_session |
zapis | kończy trwającą sesję | pracownik |
edit_session |
zapis | zmienia Twoją sesję: opis, czas, projekt, pracę zdalną; sesji z miesiąca ze złożoną ewidencją nie da się zmienić | pracownik |
add_sessions |
zapis | dodaje zakończone sesje z przeszłości, wszystkie naraz albo żadną; jedna sesja ma najwyżej 24 godziny i nie może nachodzić na inną | pracownik |
list_leave_requests |
odczyt | pokazuje Twoje wnioski o nieobecność | pracownik |
create_leave_request |
zapis | składa wniosek o nieobecność z powodem: niedyspozycja, wypoczynek albo inne; data początku nie może być przeszła | pracownik |
list_projects |
odczyt | pokazuje projekty, do których jesteś przypisany, aktywne albo zarchiwizowane | pracownik |
update_profile |
zapis | zmienia Twój profil: imię i nazwisko, telefon, adresy, numer konta do wypłaty, widoczność daty urodzin | pracownik |
get_shared_birthday |
odczyt | zwraca Twoją datę urodzin, jeśli ją udostępniasz | pracownik |
Przez MCP nie ma narzędzi do akceptowania wniosków ani do przeglądania godzin innych osób.
Faktury i kontrahenci (18)
| Narzędzie | Typ | Co robi | Rola |
|---|---|---|---|
list_sales_invoices |
odczyt | wyszukuje faktury sprzedażowe po datach, kwocie, walucie, rodzaju, stanie rozliczenia i terminie; kwota uwzględnia korekty | fakturowanie |
list_cost_invoices |
odczyt | wyszukuje faktury kosztowe, także po źródle: z KSeF albo wgrane ręcznie | fakturowanie |
get_sales_invoice |
odczyt | otwiera jedną fakturę: pozycje, stan po korektach, status w KSeF, lista korekt | fakturowanie |
list_counterparties |
odczyt | wyszukuje kontrahentów, aktywnych albo zarchiwizowanych | fakturowanie |
suggest_sales_invoice_transactions |
odczyt | układa ranking przelewów, które mogły opłacić fakturę sprzedażową | fakturowanie |
suggest_cost_invoice_transactions |
odczyt | to samo dla faktury kosztowej | fakturowanie |
preview_sales_invoice |
odczyt + widżet | sprawdza dane faktury i otwiera podgląd z potwierdzeniem; służy też do wystawienia zapisanego szkicu | księgowość |
preview_sales_invoice_correction |
odczyt + widżet | pokazuje korektę z wartościami przed i po, wymaga potwierdzenia | księgowość |
get_next_sales_invoice_number |
odczyt | podaje następny wolny numer dla daty, w formacie miesięcznym albo rocznym, z opcjonalną serią | księgowość |
create_sales_invoice_draft |
zapis | zapisuje kompletny szkic bez numeru; działa także bez połączenia z KSeF | księgowość |
update_sales_invoice_draft |
zapis | zmienia zapisany szkic | księgowość |
update_sales_invoice_internal_note |
zapis | podmienia notatkę wewnętrzną faktury sprzedażowej; notatka nie trafia do KSeF ani do nabywcy | księgowość |
update_cost_invoice_internal_note |
zapis | podmienia notatkę wewnętrzną faktury kosztowej | księgowość |
link_sales_invoice_counterparty |
zapis | podpina wystawioną fakturę bez kontrahenta do kontrahenta z bazy; dane nabywcy na fakturze zostają | księgowość |
connect_sales_invoice_transactions |
zapis | oznacza fakturę sprzedażową jako opłaconą przez powiązanie z przelewami; można łączyć kilka przelewów i kilka faktur | księgowość |
connect_cost_invoice_transactions |
zapis | to samo dla faktury kosztowej | księgowość |
disconnect_sales_invoice_transactions |
zapis | usuwa błędne powiązanie; faktura i przelew zostają | księgowość |
disconnect_cost_invoice_transactions |
zapis | to samo dla faktury kosztowej | księgowość |
Najważniejsze zasady przy fakturach:
- Nabywcą musi być firma z NIP albo jego zagranicznym odpowiednikiem. Faktury dla osób prywatnych wystawia się w aplikacji, a istniejące można przez MCP czytać.
- Numer PESEL nie występuje w danych wejściowych ani w wynikach.
- Do podglądu potrzebne są: nabywca z adresem, data sprzedaży, termin płatności i pozycje z nazwą, ilością, jednostką, ceną netto i stawką VAT. Sprzedawca, data wystawienia, PLN i przelew na domyślne konto uzupełniają się same.
- Rodzaje faktur dostępne w danych: zwykła i zaliczkowa, krajowa i zagraniczna.
- Faktura odrzucona przez KSeF wraca do szkicu bez numeru. Odrzucona korekta jest usuwana.
Bank i wynagrodzenia (8)
| Narzędzie | Typ | Co robi | Rola |
|---|---|---|---|
list_transactions |
odczyt | wyszukuje przelewy z podłączonych kont po dacie, kwocie, walucie, tekście i stanie: oczekujące, dopasowane, pominięte | fakturowanie |
suggest_transaction_invoices |
odczyt | układa ranking nierozliczonych faktur, które może opłacać oczekujący przelew | fakturowanie |
update_transaction_internal_note |
zapis | podmienia notatkę wewnętrzną przelewu; danych bankowych nie zmienia | księgowość |
restore_transaction_for_matching |
zapis | przywraca pominięty przelew do oczekujących | księgowość |
list_monthly_salaries |
odczyt | pokazuje wynagrodzenia miesiąca dla całego zespołu; kwota oczekiwana to stawka razy godziny zaokrąglone w górę | admin |
suggest_transaction_salaries |
odczyt | wskazuje, czyje wynagrodzenie opłaca wychodzący przelew w PLN; sprawdza do 6 miesięcy wstecz | admin |
connect_transaction_salary |
zapis | rozlicza wynagrodzenie danej osoby za dany miesiąc przelewem | admin |
disconnect_transaction_salary |
zapis | zdejmuje przypisanie przelewu do wynagrodzenia | admin |
Pewne dopasowania Firmowid robi sam po każdej synchronizacji banku. „Oczekujące” to więc pozycje, które wymagają decyzji człowieka. Przelew przypięty do wynagrodzenia nie może jednocześnie opłacać faktury.
KSeF i Analiza (5)
| Narzędzie | Typ | Co robi | Rola |
|---|---|---|---|
get_ksef_connection_status |
odczyt | podaje stan połączenia firmy z KSeF: rozłączone, w trakcie łączenia, połączone, wygasłe, oraz metodę: token, certyfikat, certyfikat wygenerowany przez Firmowid; nigdy nie zwraca danych logowania | fakturowanie |
list_analysis_entries |
odczyt | zwraca wpisy, z których liczona jest Analiza, za pełne miesiące, najwyżej 12: kontrahent, kwota w PLN, kategoria i przypisania | fakturowanie |
list_analysis_tags |
odczyt | pokazuje projekty i własne kategorie dostępne do przypisań | pracownik |
set_analysis_entry_category |
zapis | przypisuje wpis do jednej z kategorii: Firma, Podatki albo pominięte w Analizie; zastępuje wcześniejsze przypisania | księgowość |
set_analysis_entry_project_tags |
zapis | przypisuje wpis do wybranych projektów i dzieli kwotę po równo; pusta lista usuwa przypisania | księgowość |
KSeF łączy administrator w aplikacji. Serwer nie ma narzędzia do łączenia i nie przyjmuje tokenów, certyfikatów ani haseł. Stan „połączone” nie mówi, kiedy ostatnio pobrano faktury.
Widżety potwierdzenia
| Widżet | Otwiera go | Co pokazuje |
|---|---|---|
| potwierdzenie faktury | preview_sales_invoice |
podgląd faktury, wybór numeru lub serii, uwagi, notatka wewnętrzna, potem postęp wysyłki do KSeF |
| potwierdzenie korekty | preview_sales_invoice_correction |
wartości przed korektą i po niej, wybór numeru, obowiązkowe potwierdzenie |
Widżet jest ważny 15 minut albo krócej, jeśli wcześniej wygaśnie token. Przy każdym kliknięciu Firmowid sprawdza ponownie, czy połączenie nie zostało unieważnione i czy nadal należysz do firmy. Po każdej zmianie widżet przekazuje do rozmowy stan dokumentu, numer faktury i numer KSeF.
Co może która rola
| Rola | Zakres |
|---|---|
| pracownik | 11 narzędzi czasu pracy, urlopów i profilu oraz lista projektów i kategorii dostępnych w Analizie (list_analysis_tags) |
| fakturowanie | dodatkowo odczyt faktur, kontrahentów, przelewów, stanu KSeF, wpisów Analizy i propozycji dopasowań |
| księgowość | dodatkowo podglądy i szkice faktur, notatki, łączenie i rozłączanie płatności, przywracanie przelewów, przypisania w Analizie |
| admin | dodatkowo cztery narzędzia wynagrodzeń |
Narzędzia, których Twoja rola nie może użyć, zwracają odmowę. Uprawnienia sprawdzane są przy każdym wywołaniu.
Czego na liście nie ma
- Wystawiania faktur dla osób prywatnych.
- Tworzenia i edycji kontrahentów oraz projektów.
- Akceptowania wniosków o nieobecność i ewidencji godzin.
- Delegacji, umów i dokumentów pracowniczych.
- Łączenia banku i KSeF oraz uruchamiania synchronizacji.
- Zatwierdzania kategorii kosztów kontrahenta i tworzenia nowych kategorii w Analizie.
Te rzeczy robi się w aplikacji.