mcp-wapromag

Serwer MCP (stdio) dla WAPRO Mag na SQL Server. Pozwala asystentowi AI (Claude Code, Claude Desktop i innym klientom MCP) czytać dane z WAPRO Mag. Na bazie testowej może też wywoływać endpointy API WAPRO (Api_<op>Pre, ok. 1400 operacji: faktury, dokumenty magazynowe, zamówienia, kontrahenci, kasa…).

Projekt niezależny, niezwiązany z producentem WAPRO. WAPRO jest znakiem towarowym jego właściciela. Repozytorium nie zawiera żadnych plików ani danych WAPRO: katalog endpointów generujesz z własnej, licencjonowanej instalacji (sekcja Katalog endpointów). Testowane na WAPRO Mag 9.20 i SQL Server 2022.

Dwa tryby

Tryb pełny działa tylko na kopii bazy. Część procedur WAPRO przy błędzie sama cofa transakcję, a to, co wykonają potem, zapisuje się nawet w dry-run (sekcja Dry-run bywa niepełny).

Related MCP server: SQL Server MCP

Narzędzia

wapro_sql:

• maxRows ≤ 5000;

• osobne połączenie zamykane po każdym wywołaniu, transakcja zawsze cofana;

• zapytanie musi zaczynać się od SELECT, WITH lub DECLARE;

• odrzuca EXEC, polecenia transakcji, WAITFOR, OPENQUERY/OPENROWSET i wskazówki blokad (TABLOCK, UPDLOCK, HOLDLOCK, SERIALIZABLE…), także gdy te słowa stoją wewnątrz tekstu.

Instalacja

Wymagania

• WAPRO Mag na SQL Server, uprawnienia sysadmina na czas zakładania loginów (raz).

• Maszyna z serwerem MCP: Node.js ≥ 24 (uruchamia .ts bezpośrednio, bez kompilacji), Python 3 (tylko do wygenerowania katalogu), git.

• Dostęp sieciowy z tej maszyny do SQL Server (TCP 1433), z logowaniem SQL (tryb mieszany).

• Klient MCP, np. Claude Code albo Claude Desktop.

1. Pobranie

git clone https://github.com/Zakwei/mcp-wapromag.git
cd mcp-wapromag
npm ci
npm test

npm test przed wygenerowaniem katalogu pomija testy, które go potrzebują. Pozostałe muszą przejść.

2. Login SQL tylko do odczytu

Na serwerze SQL (wiersz poleceń z uprawnieniami sysadmina), dla bazy WAPRO:

sqlcmd -S localhost -E -b -i scripts\setup-logins.sql -v DB=<nazwa_bazy_WAPRO> RO_PASS=<silne_hasło>

Skrypt jest idempotentny i tworzy login mcp_wapro_ro:

• db_datareader;

• DENY EXECUTE na schemacie dbo;

• DENY SELECT na kolumnach z hasłami i tokenami.

Login jest serwerowy, wspólny dla wszystkich baz. Ponowne uruchomienie ustawia hasło od nowa, więc podawaj za każdym razem to samo.

3. Katalog endpointów

Serwer potrzebuje pliku docs/wapro-api/catalog.json z opisem endpointów Twojej wersji WAPRO. Generujesz go z własnej bazy. Bez niego serwer nie wystartuje i poda komunikat z odesłaniem do tej sekcji.

1. Skopiuj tools/recon/dump_schema.ps1 i tools/recon/dump_dictionaries.ps1 na serwer SQL i uruchom w PowerShell (uwierzytelnianie Windows, konto z dostępem do bazy):

   .\dump_schema.ps1 -Database <nazwa_bazy_WAPRO>
   .\dump_dictionaries.ps1 -Database <nazwa_bazy_WAPRO>

   • Wynik trafia do C:\WaproMcpDump\ i C:\WaproMcpRef\.

   • Opcjonalnie -Server <instancja>, domyślnie localhost.

   • Moduły WITH ENCRYPTION zostają zaszyfrowane, serwer ich nie potrzebuje.

2. Przenieś oba katalogi na maszynę z repo, np. do /tmp/WaproMcpDump i /tmp/WaproMcpRef.

3. W katalogu repo:

   mkdir -p /tmp/wapro-cat docs/wapro-api
   python3 -I tools/recon/extract_catalog.py /tmp/WaproMcpDump /tmp/wapro-cat
   python3 -I tools/recon/gen_docs.py /tmp/wapro-cat/catalog.json /tmp/WaproMcpRef docs/wapro-api

   gen_docs.py zapisuje docs/wapro-api/catalog.json i czytelną dokumentację docs/wapro-api/*.md.

4. Usuń katalogi tymczasowe z obu maszyn (C:\WaproMcpDump, C:\WaproMcpRef, /tmp/WaproMcp*, /tmp/wapro-cat). Zawierają pełne definicje procedur.

docs/wapro-api/, docs/czynnosci/ i docs/coverage.md są w .gitignore. Materiały WAPRO nie trafią przypadkiem do Twojego forka.

Po aktualizacji WAPRO powtórz kroki 1–4. Do tego czasu serwer w trybie pełnym widzi nowe endpointy przez katalog na żywo, ale bez opisu pól i bez klasyfikacji bezpieczeństwa: polityka traktuje je jak zwykły zapis, a wynik ma ostrzeżenie.

4. Konfiguracja

Zmienne środowiskowe (przekazuje je klient MCP, krok 5):

5. Rejestracja w kliencie MCP

Claude Code (tryb tylko do odczytu):

claude mcp add wapro-mag -s user \
  -e WAPRO_SQL_SERVER=<host> -e WAPRO_SQL_DATABASE=<baza> \
  -e WAPRO_SQL_RO_USER=mcp_wapro_ro -e WAPRO_SQL_RO_PASSWORD=<hasło> \
  -- node <pełna_ścieżka_do_repo>/src/index.ts

Claude Desktop: w claude_desktop_config.json (Ustawienia → Developer → Edit Config):

{
  "mcpServers": {
    "wapro-mag": {
      "command": "node",
      "args": ["<pełna_ścieżka_do_repo>/src/index.ts"],
      "env": {
        "WAPRO_SQL_SERVER": "<host>",
        "WAPRO_SQL_DATABASE": "<baza>",
        "WAPRO_SQL_RO_USER": "mcp_wapro_ro",
        "WAPRO_SQL_RO_PASSWORD": "<hasło>"
      }
    }
  }
}

Inny klient MCP: polecenie node <repo>/src/index.ts, transport stdio, zmienne z kroku 4.

Hasło trafia do konfiguracji klienta (u Claude Code ~/.claude.json). Chroń ten plik jak hasło.

6. Sprawdzenie

• Claude Code: nowa sesja, /mcp pokazuje wapro-mag z 4 narzędziami (tryb pełny: 6).

• Ręcznie, w katalogu repo, z ustawionymi zmiennymi: npm start. Na stderr powinno się pojawić catalog: <liczba> endpoints, potem serwer czeka na klienta (Ctrl+C kończy).

• Problemy:

  • Brak katalogu: wróć do kroku 3;

  • Login failed: sprawdź login, hasło i tryb mieszany SQL Server;

  • Missing required env vars: brakuje zmiennej z kroku 4.

Użycie

Piszesz do asystenta zwykłym językiem, a on sam dobiera narzędzia. Przykłady w trybie tylko do odczytu:

• „Pokaż magazyny firmy SolidnaFirma.” → wapro_sql na Api_V_Warehouse.

• „Ile faktur sprzedaży wystawiliśmy w październiku i na jaką kwotę brutto?” → wapro_describe_endpoint (pole views), potem wapro_sql.

• „Którzy kontrahenci mają przeterminowane należności powyżej 1000 zł?”

• „Jakie pola przyjmuje endpoint wystawienia faktury i co oznacza błąd INNER_ERROR?” → wapro_find_endpoints, wapro_describe_endpoint.

Słowniki ID (typy dokumentów, formy płatności, stawki VAT) są w widokach Api_V_DocumentTypeInvoice, Api_V_DocumentTypeWarehouse, Api_V_PaymentForm i Api_V_TaxRate. Serwer podpowiada je asystentowi w instrukcjach.

W trybie pełnym (baza testowa) zapis przebiega tak:

1. wapro_activity: kolejność endpointów danej czynności.

2. wapro_describe_endpoint: pola i ostrzeżenia.

3. wapro_write z dryRun: true.

4. wapro_write bez dryRun, czyli commit. Wymaga WAPRO_ALLOW_WRITE=1.

Przykład: „Wystaw fakturę dla kontrahenta X na 1 szt. towaru Y w cenie 500 zł netto i ją zatwierdź”. Po commicie 8 kluczowych endpointów (…Accept, inwentaryzacja) jest weryfikowanych odczytem. verified: false oznacza, że WAPRO zgłosiło sukces, ale dokument się nie zmienił.

Tryb pełny (tylko baza testowa)

1. Odtwórz kopię bazy produkcyjnej (np. backup COPY_ONLY) pod nazwą zawierającą TEST, np. WAPRO_MCP_TEST.

2. Uruchom setup-logins.sql dla tej kopii, a potem login zapisu:

   sqlcmd -S localhost -E -b -i scripts\setup-write-login.sql -v DB=WAPRO_MCP_TEST RW_PASS=<silne_hasło>

   • Skrypt przerywa, gdy nazwa bazy nie zawiera TEST.

   • Login mcp_wapro dostaje db_datareader, db_datawriter, EXECUTE i VIEW DEFINITION.

   • Celowo nie dostaje db_owner: bazy WAPRO mają TRUSTWORTHY ON i właściciela sa, więc db_owner pozwala przejąć sysadmina całego serwera.

   • Na koniec login jest wyłączony. Włączaj go tylko na czas pracy: sqlcmd -S localhost -E -Q "ALTER LOGIN [mcp_wapro] ENABLE", a potem … DISABLE. Działa na tym samym serwerze co produkcja.

3. Zarejestruj drugi serwer (np. wapro-mag-test) ze zmiennymi WAPRO_SQL_USER, WAPRO_SQL_PASSWORD, WAPRO_USER_ID i WAPRO_COMPANY_ID. Do zapisu dodaj WAPRO_ALLOW_WRITE=1.

4. WAPRO_USER_ID to użytkownik API WAPRO (WAPRO Anywhere), czyli wiersz w WAPROERP_MANDANT_USER. Znajdziesz go zapytaniem SELECT ID_UZYTKOWNIKA FROM WAPROERP_MANDANT_USER.

Nigdy nie dodawaj loginu zapisu do bazy produkcyjnej. Bez niego produkcja może działać tylko w trybie tylko do odczytu.

Bezpieczeństwo

• Tryb tylko do odczytu: w konfiguracji nie ma loginu zapisu, a w bazie produkcyjnej nie powinien istnieć. Żadna procedura WAPRO nie jest uruchamiana. Ograniczenia wapro_sql opisuje sekcja Narzędzia.

• Zapis (tryb pełny): bez WAPRO_ALLOW_WRITE=1 commit jest odrzucany („writes disabled”), a dryRun: true działa. Commit następuje tylko wtedy, gdy:

  • nie ma błędów;

  • errorData jest puste;

  • własna transakcja serwera jest nienaruszona (trancount 1, ten sam identyfikator transakcji).

• Efekty zewnętrzne: 58 endpointów woła HTTP lub e-mail (SMS, płatności online, kurierzy, KSeF, AI). ROLLBACK ich nie cofa.

  • Klasa realne (np. PackageSend, BlmtDocumentSend, odczyt PackageReceiveReportGet): zakaz dry-run i wapro_read. Commit wymaga WAPRO_ALLOW_WRITE=1 i WAPRO_ALLOW_EXTERNAL=1.

  • Klasa warunkowe (SMS, płatności online): dry-run tylko przy nieaktywnych strażnikach, liczonych przy starcie osobno dla każdej firmy.

  • Klasa lookup (NBP, VIES): jak zwykły zapis.

• Klasy broken i dangerous:

  • broken to wady producenta; serwer odmawia wywołania.

  • dangerous: commit wymaga WAPRO_ALLOW_DANGEROUS=1. Dotyczy DDL, usuwania firm i magazynów, UPDATE bez WHERE oraz zapisu kodu SQL wykonywanego później (atrybuty Genius, ReportAddOrModify, KsefFieldAddOrModify).

  • Endpointy z requireFields wymagają pól, bez których procedura robi coś innego, niż sugeruje nazwa.

• Walidacja wejścia: WAPRO skleja część pól do dynamicznego SQL, więc obowiązuje ona w każdym trybie, na każdym poziomie data i filter:

  • pola OrderBy, SortColumn, ColumnName, MenuName, TableName, FilterColumn, AtribiuteTable, TableKey, ValueColumn: tylko identyfikatory; Order: tylko ASC lub DESC;

  • pola z kodem SQL (JoinCondition, SqlFilter, SqlCode, SqlFunction) mogą być niepuste tylko z WAPRO_ALLOW_DANGEROUS=1;

  • Gdpr_AnonymizeData.EntityType: tylko Kontrahent, Kontakt, Pracownik, Osoba_powiazana;

  • AdditionalTableValueAddOrModify.Item: klucze tylko identyfikatory, teksty bez ' i &, tylko znaki strony kodowej 1250.

• Maskowanie: w wynikach wartości pod kluczami password, haslo, token, secret, apikey itp. są zastępowane "***".

Telemetria WAPRO (tryb pełny)

AP_ZapiszDoLogu dla użytkownika z UZYTKOWNIK.TELEMETRIA_ZGODA=1 czyta sys.dm_exec_connections. Bez uprawnienia serwerowego każde …Accept, także w dry-run, kończy się INNER_ERROR, a zapis jest cofany.

Na bazie testowej ustaw TELEMETRIA_ZGODA=0 dla użytkownika API. Skrypty celowo nie nadają VIEW SERVER PERFORMANCE STATE, bo to uprawnienie pokazuje treść zapytań innych sesji.

Dry-run bywa niepełny

Pokrycie zmierzone na bazie testowej WAPRO Mag 9.20 (npm run coverage:ops):

• 1404 przebiegi: 801 ok, 560 wapro_error (oczekiwana walidacja pustego wejścia), 16 sql_error, 27 pominiętych, 0 awarii;

• liczności tabel bez zmian.

W 382 endpointach procedura WAPRO przy błędzie cofa transakcję serwera, więc instrukcje wykonane po tym mogą się zapisać mimo dry-run. Wszystkie przypadki z pokrycia są na ścieżkach błędu. Serwer:

• dodaje wtedy ostrzeżenie („cofnęła transakcję serwera MCP”);

• takiej transakcji nie zatwierdza;

• cofa transakcję otwartą przez procedurę po jej ROLLBACK.

Dry-run to podgląd, nie gwarancja. Dlatego tryb pełny jest tylko dla bazy testowej, a produkcja działa w trybie tylko do odczytu.

Opisy czynności (opcjonalnie)

wapro_activity i opisy w wapro_find_endpoints korzystają z plików, których repo nie zawiera:

• docs/czynnosci/<obszar>.md: sekcje ## <czynność> z nazwami endpointów w backtickach, w kolejności wywołań;

• docs/czynnosci/opisy/<obszar>.json: { "<op>": "<jedno zdanie, co robi endpoint>" }.

Bez nich serwer działa, tylko wapro_activity nic nie zwraca. npm run docs:check sprawdza, czy opisy pokrywają cały katalog. Wymaga docs/wapro-api/uprawnienia.json, czyli kopii C:\WaproMcpRef\UPRAWNIENIE.json.

Testy i rozwój

• npm test: testy jednostkowe bez bazy. Testy zależne od katalogu i opisów są pomijane, dopóki ich nie wygenerujesz, i zakładają WAPRO Mag 9.20.

• npm run test:int: testy integracyjne, wyłącznie na bazie o nazwie WAPRO_MCP_TEST. Konfiguracja w .env.test (wzór: .env.example, plik poza gitem) i włączony login zapisu. Testy E2E zatwierdzają prawdziwe dokumenty w bazie testowej.

• npm run coverage:ops: przebieg po wszystkich endpointach na bazie testowej, raport docs/coverage.md.

• npm run typecheck.

Licencja

Wszelkie prawa zastrzeżone (plik LICENSE). Wolno pobrać i uruchamiać bez zmian na własny lub wewnętrzny użytek. Modyfikowanie, kopiowanie do innych projektów i rozpowszechnianie wymaga pisemnej zgody właściciela.