MCP / AI Connector — instrukcja dla asystentów AI

1. Opis aplikacji

Plan Budowy to aplikacja do zarządzania budową domu/działki: harmonogram (projekt → faza → zadanie), zdjęcia z postępów oraz uproszczona rachunkowość projektowa z podwójnym zapisem. Główny język interfejsu i danych to polski.

2. Autentykacja

Wszystkie żądania API (poza tą instrukcją) wymagają nagłówka:

X-API-Token: <token>

Token uzyskujesz przez stronę https://planbudowy.com.pl/mcp/device (sekcja 5): zaloguj się webowo, wpisz kod z klienta MCP i kliknij „Zezwól". Token przekazywany jest do klienta automatycznie. Tokeny zarządzasz w panelu „Moje tokeny API" po zalogowaniu (lista + unieważnianie).

3. Endpointy

Base URL: https://planbudowy.com.pl/api

• GET /api/accounts — lista kont księgowych.
• GET /api/accounts/search?q=... — wyszukiwanie kont.
• GET /api/accounts/{code} — szczegóły konta + saldo.
• GET /api/journal-entries — lista zapisów.
• POST /api/journal-entries — dodaj zapis księgowy.
• GET /api/journal-entries/{id} — szczegóły zapisu.
• POST /api/journal-entries/{id}/lines/{lineId}/allocate — przypisz linię do zadania.
• GET /api/projects — lista projektów.
• GET /api/projects/{id}/tasks — lista zadań w projekcie.

Pełna specyfikacja OpenAPI: https://planbudowy.com.pl/openapi.json

4. Jak dodać fakturę (przykład dla AI)

Gdy użytkownik powie: „Dodaj fakturę za 5000 zł na materiały, zapłacone z konta 100, i przypisz do zadania X”, AI powinno:

1. Wyszukać odpowiednie konta:

   GET /api/accounts?q=materiały
   GET /api/accounts?q=środki pieniężne

2. Utworzyć zbilansowany zapis:

   POST /api/journal-entries
   {
     "date": "2026-07-06",
     "description": "Faktura za materiały",
     "documentNo": "FV/2026/001",
     "lines": [
       {"accountCode": "500", "debit": "5000.00", "description": "Materiały budowlane"},
       {"accountCode": "100", "credit": "5000.00", "description": "Kasa"}
     ]
   }

3. (Opcjonalnie) przypisać linię WN do zadania:

   POST /api/journal-entries/{id}/lines/{lineId}/allocate
   {"taskId": 123, "amount": "5000.00"}

5. MCP server — HTTP connector (Grok / Claude / Cursor)

Jak uzyskać token MCP (ludzie)

1. Wejdź na stronę autoryzacji:

   https://planbudowy.com.pl/mcp/device

   i zaloguj się do Plan Budowy (zwykłe logowanie webowe).
2. Wpisz kod wyświetlony przez klienta MCP (lub pozostaw puste i nadaj nazwę tokenowi), a następnie kliknij Zezwól. Token zostanie przekazany do klienta automatycznie.
3. Alternatywnie token możesz wygenerować ręcznie w panelu „Moje tokeny API" po zalogowaniu i wkleić go do URL/headers poniżej.

HTTP 401 — instrukcja dla agenta AI (obowiązkowa)

Szablon wiadomości do usera (PL):

Aby podłączyć Plan Budowy (MCP), otwórz w przeglądarce ten link, zaloguj się i kliknij „Zezwól”.
Nie musisz nic pisać w czacie — sprawdzę autoryzację automatycznie.
{verification_uri_complete}

Transporty MCP

Dwa transporty wystawione w tym samym backendzie:

• Streamable HTTP (spec 2025-03-26+): https://planbudowy.com.pl/api/mcp — POST JSON-RPC, sesja przez nagłówek Mcp-Session-Id. Dla Claude Code, Claude Desktop, Cursor.
• Legacy SSE (spec 2024-11-05): https://planbudowy.com.pl/api/mcp/sse — strumień zdarzeń + POST na /api/mcp/messages. Dla klientów typu „Custom Connector" z samym URL (np. Grok).

Odświeżanie listy narzędzi (Mercure)

Odpowiedź initialize ogłasza tools.listChanged: true i zawiera:

• serverInfo.toolsHash — hash SHA-256 aktualnej listy narzędzi.
• serverInfo.mercureUrl oraz serverInfo.mercureTopic — URL Huba i topic mcp-tools-list-changed.
• serverInfo.mercureToken — JWT uprawniający do subskrypcji tego topicu.

Klient Streamable HTTP powinien otworzyć SSE do podanego Huba; gdy backend wyśle notifications/tools/list_changed, klient odświeża listę narzędzi (tools/list). Dzięki temu po deployu nowej wersji tooli nie trzeba ręcznie reconnectować. Połączenia SSE trzyma dedykowany Hub Mercure — php-fpm nie jest blokowany przez wiszące klientów.

Autoryzacja: ten sam token co w sekcji 2. Można go przekazać na trzy sposoby (header preferowany — nie trafia do logów proxy):

X-API-Token: <token>
Authorization: Bearer <token>
# lub w URL (dla klientów bez pola na header):
?token=<token>

Grok — Custom Connector

W polu Server URL wpisz URL z tokenem w query (Grok ma w UI tylko URL):

https://planbudowy.com.pl/api/mcp/sse?token=<TWÓJ_TOKEN>

Claude Code (.mcp.json)

W pliku .mcp.json dodaj serwer typu url z tokenem w nagłówku:

{
  "mcpServers": {
    "plan-budowy": {
      "type": "url",
      "url": "https://planbudowy.com.pl/api/mcp",
      "headers": { "X-API-Token": "<TWÓJ_TOKEN>" }
    }
  }
}

Dostępne narzędzia

• search_accounts, get_account, get_balance
• list_projects, list_tasks
• add_journal_entry, get_journal_entry, allocate_cost
• create_phase, create_task, update_task, attach_photo_to_task

Token uzyskasz przez stronę /mcp/device (sekcja powyżej) lub w panelu „Moje tokeny API" po zalogowaniu. Każde wywołanie narzędzia mutującego jest logowane (audyt AiActionLog) i wykonuje się w kontekście Twojego tenant-a.

6. Zasady modelu domenowego

• Każdy zapis księgowy musi być zbilansowany: suma WN = suma MA.
• Konta identyfikowane są po kodzie (np. 500, 520, 100).
• Alokacja kosztu do zadania dotyczy konkretnej linii zapisu.
• Daty zapisów: format YYYY-MM-DD.