Specyfikacja Narzędzi MCP (Model Context Protocol) dla AMAGE AI

Wstęp

Niniejszy dokument zawiera szczegółową specyfikację narzędzi dostępnych w ramach serwera MCP w systemie AMAGE. Narzędzia te umożliwiają agentom AI interakcję z danymi i funkcjami systemu.

Każde narzędzie jest identyfikowane przez unikalną nazwę (toolName) i przyjmuje zestaw parametrów zdefiniowanych w schemacie JSON.

Obsługa parametrów

Większość narzędzi typu "List" lub "Search" obsługuje proste filtrowanie tekstowe. Narzędzia typu "Query" oferują zaawansowane filtrowanie strukturalne.

UWAGA: Znaki wieloznaczne (wildcards) takie jak * nie są obsługiwane w polach tekstowych. Aby uniknąć filtrowania po danym polu, należy pozostawić je puste.

Moduł: Zasoby (Assets)

Narzędzia do zarządzania bazą urządzeń i lokalizacji.

mcp_list_assets

Pobiera prostą listę zasobów pasujących do frazy wyszukiwania.

  • Opis: Listuje wszystkie urządzenia (limit 100).

  • Parametry:

    • search (string, opcjonalny): Fraza wyszukiwania (nazwa, numer seryjny, typ, grupa, kategoria itp.).

mcp_get_asset

Pobiera pełne szczegóły pojedynczego zasobu.

  • Opis: Zwraca kompletne dane zasobu, w tym pola wspólne, parametry specyficzne i powiązane obiekty.

  • Parametry:

    • id (string, wymagany): ID (numeryczne) lub UUID zasobu.

mcp_query_assets

Zaawansowane wyszukiwanie zasobów.

  • Opis: Pozwala na precyzyjne filtrowanie, sortowanie i stronicowanie wyników.

  • Parametry:

    • asset_type (string, opcjonalny): ID lub nazwa typu zasobu.

    • filters (array, opcjonalny): Tablica warunków filtrowania. Każdy filtr zawiera:

      • field (string): Nazwa pola.

      • op (string): Operator (eq, neq, gt, gte, lt, lte, like, in).

      • value (any): Wartość filtra.

    • fields (array, opcjonalny): Lista pól do zwrócenia.

    • limit (integer, opcjonalny): Maksymalna liczba wyników (domyślnie 50).

    • offset (integer, opcjonalny): Przesunięcie (stronicowanie).

    • order_by (array, opcjonalny): Sortowanie (field, dir: asc/desc).

mcp_count_assets

Zlicza zasoby spełniające kryteria.

  • Opis: Zwraca liczbę zasobów pasujących do zapytania.

  • Parametry: Analogiczne do mcp_query_assets (bez limit/offset).

mcp_get_asset_schema

Pobiera schemat danych dla typu zasobu.

  • Opis: Zwraca definicję pól i parametrów dla wskazanego typu zasobu.

  • Parametry:

    • asset_type (string, wymagany): ID lub nazwa typu zasobu.

mcp_list_asset_types

Listuje dostępne typy zasobów.

  • Opis: Zwraca listę zdefiniowanych w systemie typów zasobów.

Moduł: Zlecenia (Work Orders)

mcp_list_work_orders

Proste wyszukiwanie zleceń.

  • Opis: Listuje zlecenia pracy.

  • Parametry:

    • search (string, opcjonalny): Fraza wyszukiwania.

mcp_get_work_order

Pobiera szczegóły zlecenia.

  • Opis: Zwraca pełne dane zlecenia pracy.

  • Parametry:

    • id (string, wymagany): ID lub UUID zlecenia.

mcp_query_work_orders

Zaawansowane wyszukiwanie zleceń.

  • Opis: Analogiczne do mcp_query_assets, ale dla zleceń pracy.

  • Parametry:

    • filters, limit, offset, order_by.

mcp_list_work_order_types

Listuje typy zleceń.

  • Opis: Zwraca dostępne definicje typów zleceń.

Moduł: Klienci (Sales/Customers)

mcp_list_customers

Wyszukiwanie klientów.

  • Opis: Listuje klientów w systemie.

  • Parametry:

    • search (string, opcjonalny): Nazwa, NIP, itp.

mcp_get_customer_by_id / mcp_get_customer_by_uuid

Pobiera dane klienta.

  • Parametry:

    • id / uuid (string, wymagany): Identyfikator klienta.

Moduł: Serwis (Service)

mcp_query_service_events

Wyszukiwanie zdarzeń serwisowych.

  • Opis: Zaawansowane filtrowanie zdarzeń serwisowych.

  • Parametry: filters, limit, offset.

mcp_get_service_event

Pobiera szczegóły zdarzenia.

  • Parametry: id (string, wymagany).

mcp_add_service_event_comment

Dodaje komentarz do zdarzenia.

  • Parametry:

    • event_id (string, wymagany): ID zdarzenia.

    • comment (string, wymagany): Treść komentarza.

Moduł: Legislacja (Legislation)

mcp_list_legislation_documents

Przeglądanie dokumentów prawnych.

  • Parametry: search, context_id.

mcp_list_legislation_articles

Przeglądanie artykułów prawnych.

  • Parametry: document_id, search.

Moduł: Magazyn i Logistyka (Warehouse & Logistics)

mcp_list_warehouse_items

Przeglądanie stanów magazynowych.

  • Parametry: search, warehouse_id.

mcp_list_deliveries

Przeglądanie dostaw.

  • Parametry: search, status.

Akcje i Wykonywanie Operacji (Executors)

Narzędzia te powodują zmianę stanu systemu lub wywołują akcję w interfejsie użytkownika.

mcp_ai_tool_execute_show_assets_list

Pokazuje listę zasobów w UI.

  • Opis: Otwiera widok listy zasobów przefiltrowany do podanych ID.

  • Parametry:

    • ids (string, wymagany): Lista ID zasobów oddzielona przecinkami.

mcp_ai_tool_execute_show_asset_details

Pokazuje szczegóły zasobu w UI.

  • Opis: Przechodzi do widoku szczegółów konkretnego zasobu.

  • Parametry:

    • id (string, wymagany): ID zasobu.

mcp_ai_tool_execute_show_in_ifc_viewer

Otwiera model BIM.

  • Opis: Otwiera przeglądarkę 3D dla danego zasobu.

  • Parametry:

    • id (string, wymagany): ID zasobu.

mcp_ai_tool_execute_show_on_map_viewer

Pokazuje na mapie.

  • Opis: Lokalizuje zasób na mapie.

  • Parametry:

    • id (string, wymagany): ID zasobu.

mcp_ai_tool_execute_add_new_work_order

Tworzy nowe zlecenie.

  • Opis: Otwiera formularz lub tworzy zlecenie pracy.

  • Parametry:

    • asset_id (string, opcjonalny): ID zasobu, dla którego tworzone jest zlecenie.

    • type_id (string, opcjonalny): ID typu zlecenia.

    • description (string, opcjonalny): Opis zlecenia.

mcp_ai_tool_execute_add_new_service_event

Rejestruje zdarzenie serwisowe.

  • Opis: Tworzy nowe zgłoszenie serwisowe.

  • Parametry:

    • asset_id (string, wymagany): ID zasobu.

    • description (string, wymagany): Opis zdarzenia.