Narzędzia i zakresy

Narzędzia to działania, które Twój agent AI może wykonywać za Ciebie w Zippendo, na przykład tworzenie przesyłki lub odczyt zamówienia. Serwer MCP udostępnia jedno narzędzie dla każdego działania w API, a Twój agent widzi tylko te narzędzia, na które pozwalają zatwierdzone przez Ciebie uprawnienia.

​

Jak narzędzia odpowiadają uprawnieniom

Każde narzędzie wymaga uprawnienia (zakresu, ang. scope), które pasuje do zasobu i działania:

• Odczyt danych wymaga zakresu read:. Na przykład wyświetlenie listy przesyłek wymaga read:shipments.
• Zmiana danych wymaga odpowiedniego zakresu write:. Na przykład utworzenie przesyłki wymaga write:shipments.

Zakresy się na siebie nakładają, więc możesz przyznawać uprawnienia szeroko lub wąsko:

• write:all obejmuje read:all oraz każdy zakres write: z poniższej tabeli.
• read:all obejmuje każdy zakres read: z poniższej tabeli.
• write:<resource> obejmuje read:<resource> (write:shipments obejmuje read:shipments).

Agent z samym read:shipments widzi narzędzia do odczytu przesyłek (lista, szczegóły, śledzenie przesyłek, dokumenty), ale żadnych narzędzi do tworzenia, wysyłania ani usuwania przesyłek.

​

Lista zakresów

Ekran zgody może też wymieniać inne uprawnienia, takie jak organizacje, członkowie zespołu (org_members), portale zwrotów i tokeny API. Obecnie nie odblokowują one żadnych narzędzi MCP.

​

Przykładowe polecenia

Po połączeniu rozmawiaj z agentem zwykłym językiem. Wybierze właściwe narzędzia i zapyta Zippendo:

• “Ile przesyłek nadal oczekuje i u jakich przewoźników?”
• “Utwórz przesyłkę dla zamówienia #10421 z PostNord i podaj mi numer przesyłki.”
• “Podziel przesyłkę dla zamówienia #10388 na dwie paczki i wyślij obie.”
• “Które zamówienia z ostatnich 24 godzin nie mają jeszcze przesyłki?”
• “Śledź przesyłkę shp_8f3kd9 i powiedz mi, czy jest opóźniona.”
• “Dodaj regułę wysyłki, która wysyła zamówienia powyżej 10 kg przez GLS.”

​

Narzędzia do dokumentacji i SDK

Oprócz narzędzi działań serwer MCP pozwala agentowi czytać dokumentację Zippendo, dzięki czemu może pomóc Ci zbudować integrację w Twoim języku programowania. Te narzędzia nie wymagają zakresu i ma je każdy połączony agent. Agent dostaje polecenie, by preferować SDK dla Twojego języka i używać surowej specyfikacji OpenAPI tylko wtedy, gdy dla danego języka nie ma SDK. Treść pochodzi na żywo z zippendo.com/docs i repozytoriów SDK, więc jest zawsze aktualna. Wypróbuj polecenia takie jak:

• “Użyj SDK Zippendo dla Pythona i napisz skrypt, który tworzy przesyłkę dla zamówienia i wypisuje numer przesyłki.”
• “Jak uwierzytelnić się w API Zippendo w Go? Pokaż mi konfigurację SDK.”
• “Używam PHP. Napisz obsługę webhooka, która weryfikuje podpis i reaguje na shipment.dispatched.”

​

Model bezpieczeństwa

Usuwanie przesyłek, zamówień, przewoźników, adresów, reguł wysyłki lub ról, wysyłanie przesyłki oraz tworzenie i unieważnianie tokenów kasy i kluczy podpisu wymagają wyraźnego potwierdzenia w wywołaniu narzędzia, więc agent powinien Cię wcześniej zapytać. Niektóre wrażliwe działania, takie jak rozliczenia i zarządzanie tokenami API, w ogóle nie są dostępne w narzędziach i żaden agent nie może z nich korzystać, niezależnie od uprawnień.

​

Te same narzędzia napędzają Zippy

Serwer MCP dzieli swoje narzędzia z Zippy, asystentem w aplikacji Zippendo. Różni się tylko miejsce: Zippy działa w aplikacji, a MCP pozwala Twojemu własnemu narzędziu AI korzystać z tych samych działań. Oba stosują te same uprawnienia, limity organizacji i walidację.