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 prawdziwym podwójnym zapisem (WN/MA). 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 lokalny serwer MCP (sekcja 5): przy pierwszym uruchomieniu skrypt otworzy przeglądarkę, poprosi o zalogowanie i potwierdzenie dostępu (ekran consent), a token zapisze lokalnie. 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 WN/MA.
• 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 (Claude Desktop / Cursor)

Dla narzędzi obsługujących protokół MCP dostarczamy samodzielny lokalny serwer MCP jako jeden plik Pythona. Ściągasz go na swój komputer, ustawiasz token i uruchamiasz. Nie potrzebujesz repo ani Dockera lokalnie.

Plik do pobrania:

https://planbudowy.com.pl/mcp_server.py

Krok po kroku

1. Zainstaluj bibliotekę requests (jeśli jej nie masz):

   pip install requests

2. Pobierz skrypt:

   curl -O https://planbudowy.com.pl/mcp_server.py

3. Uruchom serwer MCP (bez tokena — przy pierwszym uruchomieniu otworzy się przeglądarka):

   export PLAN_BUDOWY_BASE_URL="https://planbudowy.com.pl"
   python3 mcp_server.py

   Skrypt poprosi o zalogowanie w Plan Budowy i potwierdzenie dostępu (ekran consent), a otrzymany token zapisze w ~/.config/plan-budowy/mcp-token.json. Kolejne uruchomienia używają zapisanego tokenu; przy 401 — ponowna autoryzacja. Opcjonalnie: export PLAN_BUDOWY_MCP_LABEL="Claude Desktop" (nazwa tokenu sugerowana na ekranie consent; user może ją edytować).

Konfiguracja Claude Desktop

W pliku claude_desktop_config.json dodaj:

{
  "mcpServers": {
    "plan-budowy": {
      "command": "python3",
      "args": ["/ścieżka/do/mcp_server.py"],
      "env": {
        "PLAN_BUDOWY_BASE_URL": "https://planbudowy.com.pl",
        "PLAN_BUDOWY_MCP_LABEL": "Claude Desktop"
      }
    }
  }
}

Przy pierwszym uruchomieniu zostaniesz poproszony o jednorazową autoryzację w przeglądarce (zaloguj się + kliknij „Zezwól"). Token przechowywany jest lokalnie (chmod 600).

5a. Connector HTTP (Grok / dowolny klient MCP)

Dwa transporty MCP 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).

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 (12)

• 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 device flow (sekcja 5) 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.