Työkalut ja oikeudet

Työkalut ovat toimintoja, joita tekoälyagenttisi voi tehdä Zippendo-palvelussa puolestasi, kuten lähetyksen luominen tai tilauksen lukeminen. MCP-palvelin tarjoaa yhden työkalun jokaista rajapinnan toimintoa kohden, ja agenttisi näkee vain ne työkalut, jotka hyväksymäsi oikeudet sallivat.

​

Miten työkalut liittyvät oikeuksiin

Jokainen työkalu vaatii oikeuden (scope), joka vastaa resurssia ja toimintoa:

• Tietojen lukeminen vaatii read:-oikeuden. Lähetysten listaaminen vaatii esimerkiksi oikeuden read:shipments.
• Tietojen muuttaminen vaatii vastaavan write:-oikeuden. Lähetyksen luominen vaatii esimerkiksi oikeuden write:shipments.

Oikeudet rakentuvat toistensa päälle, joten voit antaa laajan tai suppean pääsyn:

• write:all sisältää oikeuden read:all ja kaikki alla olevan taulukon write:-oikeudet.
• read:all sisältää kaikki alla olevan taulukon read:-oikeudet.
• write:<resource> sisältää oikeuden read:<resource> (write:shipments sisältää oikeuden read:shipments).

Agentti, jolle on annettu vain read:shipments, näkee lähetysten lukutyökalut (lista, tiedot, seuranta, asiakirjat) mutta ei yhtään työkalua, jolla lähetyksiä luodaan, lähetetään tai poistetaan.

​

Oikeuksien viite

Suostumusnäkymä voi näyttää myös muita oikeuksia, kuten organisaatiot, tiimin jäsenet (org_members), palautusportaalit ja API-tokenit. Ne eivät avaa tällä hetkellä yhtään MCP-työkalua.

​

Esimerkkikehotteet

Kun yhteys on tehty, puhu agentillesi tavallisella kielellä. Se valitsee oikeat työkalut ja kysyy Zippendo-palvelulta:

• “Kuinka monta lähetystä on vielä odottamassa ja millä kuljetusyhtiöillä ne ovat?”
• “Luo lähetys tilaukselle #10421 kuljetusyhtiöllä PostNord ja anna minulle seurantakoodi.”
• “Jaa tilauksen #10388 lähetys kahteen pakettiin ja lähetä molemmat.”
• “Millä viimeisen 24 tunnin tilauksilla ei ole vielä lähetystä?”
• “Seuraa lähetystä shp_8f3kd9 ja kerro, onko se myöhässä.”
• “Lisää toimitussääntö, joka lähettää yli 10 kg:n tilaukset kuljetusyhtiöllä GLS.”

​

Dokumentaatio- ja SDK-työkalut

Toimintotyökalujen lisäksi MCP-palvelin antaa agentin lukea Zippendo-palvelun dokumentaatiota, jotta se voi auttaa sinua rakentamaan integraation omalla ohjelmointikielelläsi. Nämä työkalut eivät vaadi mitään oikeutta, ja jokaisella yhdistetyllä agentilla ne ovat käytössä. Agentille kerrotaan, että se suosii kielesi SDK:ta ja käyttää raakaa OpenAPI-määrittelyä vain, kun sille ei ole SDK:ta. Sisältö tulee suoraan osoitteesta zippendo.com/docs ja SDK-repositorioista, joten se on aina ajan tasalla. Kokeile esimerkiksi näitä kehotteita:

• “Kirjoita Zippendo Python SDK:ta käyttäen skripti, joka luo lähetyksen tilaukselle ja tulostaa seurantakoodin.”
• “Miten todennan itseni Zippendo-rajapintaan Go-kielellä? Näytä SDK:n käyttöönotto.”
• “Käytän PHP:tä. Kirjoita webhook-käsittelijä, joka varmentaa allekirjoituksen ja reagoi tapahtumaan shipment.dispatched.”

​

Turvallisuusmalli

Lähetysten, tilausten, kuljetusyhtiöiden, osoitteiden, toimitussääntöjen tai roolien poistaminen, lähetyksen lähettäminen sekä kassa-tokenien ja allekirjoitussalaisuuksien luominen tai peruuttaminen vaativat kaikki erillisen vahvistuksen työkalukutsussa, joten agentin pitäisi kysyä sinulta ensin. Jotkin arkaluonteiset toiminnot, kuten laskutus ja API-tokenien hallinta, on jätetty kokonaan pois työkaluista, eikä mikään agentti voi käyttää niitä oikeuksistaan riippumatta.

​

Samat työkalut toimivat avustajassa Zippy

MCP-palvelin jakaa työkalunsa avustajan Zippy kanssa, joka on Zippendo-sovelluksen avustaja. Vain paikka on eri: Zippy toimii sovelluksen sisällä, kun taas MCP antaa oman tekoälytyökalusi käyttää samoja toimintoja. Molemmat käyttävät samoja oikeuksia, organisaation rajoja ja validointia.