MCP pre ERP: praktická príručka

Začnite od transakcie, nie od tabuľky

Prvým inštinktom pri exponovaní ERP je generovať nástroj pre každú tabuľku s operáciami vytvorenia, čítania, aktualizácie a odstránenia. Produkuje to veľký, jednotný zoznam, ktorý model spracováva zle, pretože obchodné pravidlo, že faktúra potrebuje daňovú sadzbu na každom riadku, alebo že zásoby nemôžu byť odoslané predtým, ako sú rezervované, sa nenachádza nikde, kde by to model videl. Namiesto toho exponujte akcie. Užitečným testom je, či by osoba mohla opísať nástroj ako niečo, čo urobila dnes: vystavila faktúru, zaznamenala platbu, presunula obchod, odložila sledovanie. Každá z týchto akcií nesie svoje pravidlá, overuje svoje vstupy a vracia čitateľný výsledok.

Popri akciách pridajte malé množstvo súhrnných nástrojov, ktoré odpovedajú na otázky, ktoré model kladie predtým, ako koná. Jedno volanie, ktoré vracia profil účtu, zdravie, otvorené položky a nedávnu históriu, ušetrí modelu štyri volania a niekoľko tisíc tokenov kontextu a robí ďalšiu akciu lepšie informovanou. Sois tieto nástroje nazýva nástrojmi na skúmanie; preskúmať kontakt a získať súhrn účtovníctva sú dva. Udržujte na pamäti aj celkový povrch: Claude Code obmedzuje výstup servera na volanie predvolene, a Claude aj OpenAI ponúkajú oneskorené načítanie alebo vyhľadávanie nástrojov pre veľké zoznamy, takže server s niekoľkými stovkami nástrojov by mal vracať ich v deterministickom poradí (špecifikácia to požaduje, aby si klienti mohli ukladať do cache) a mal by filtrovať podľa úlohy pred zoznamom.

Pomenovanie nástrojov, aby model vybral ten správny

Špecifikácia mierne obmedzuje názvy: jeden až 128 znakov, písmená, číslice, podčiarkovník, pomlčka a bodka, citlivé na veľké a malé písmená, jedinečné v rámci servera. Všetko ostatné je konvencia a konvencia, ktorá funguje, je sloveso nasledované obchodným podstatným menom v konzistentnom tvare, pričom rovnaké slovesá znamenajú to isté všade. Model, ktorý si vyberá medzi vyhľadávanieFaktúr, získať faktúru a vytvoriť faktúru si vyberá medzi zoznamom, jedným záznamom a zápisom, a tento vzor sa naučí raz pre celý server.

Popisy číta model pod tlakom konať, preto ich píšte ako pokyny. Uveďte, čo nástroj robí v prvej vete, potom podmienky. Ak je súrodenec nástroj správnou voľbou pre blízku požiadavku, povedzte to menom. Ak musí byť pole nastavené, aby bol výsledok správny, povedzte to VEĽKÝMI PÍSMENAMI, ak je to potrebné; fakturačný nástroj Sois hovorí modelu, že daňová sadzba musí byť nastavená na každom riadku a že presné sadzby pochádzajú z zoznam daňových typov, pretože faktúra bez DPH je horším zlyhaním ako odmietnutý hovor. Zahrňte jeden príklad hovoru. Všetko, čo model potrebuje na správne zavolanie nástroja, by malo byť v nástroji, pretože nikdy neotvorí vašu dokumentáciu.

Príklad definície nástroja

Toto je fakturačný nástroj Sois, ako ho klient dostáva od tools/list, upravené na polia, ktoré sú dôležité, s anotáciami a výstupným schémou pridanou v podobe, ktorú aktuálna špecifikácia definuje. Zobrazuje vzor: názov sloveso-podstatné meno, inštruktívny popis, schéma, ktorej popisy vlastností zabraňujú chybám modelu, a nápovedy, ktoré môže klient použiť na rozhodovanie, či potvrdiť.

{
  "name": "createInvoice",
  "title": "Create invoice",
  "description": "Create a new invoice of any type and return the draft with its auto-generated number. TAX: set tax_rate on each line (for example 20 for 20% VAT); call listTaxTypes for this workspace's exact rates. If the user says 'plus VAT' you MUST set tax_rate or the invoice goes out with no VAT. To email the result use sendInvoice. Example: createInvoice({ type: \"sales_invoice\", contact_id: \"uuid\", currency: \"GBP\", lines: [{ description: \"Consulting\", quantity: 10, unit_price: 150 }] })",
  "inputSchema": {
    "type": "object",
    "properties": {
      "type": { "type": "string", "description": "sales_invoice, purchase_invoice, sales_credit_note or purchase_credit_note" },
      "contact_id": { "type": "string", "description": "Contact UUID (bill-to for sales, bill-from for purchases)" },
      "currency": { "type": "string", "description": "ISO code, for example GBP. Uses the workspace default if omitted" },
      "invoice_date": { "type": "string", "description": "ISO date. Defaults to today" },
      "reference": { "type": "string" },
      "lines": {
        "type": "array",
        "description": "Line items. Every line MUST carry the numeric unit_price the user asked for",
        "items": {
          "type": "object",
          "properties": {
            "description": { "type": "string" },
            "quantity": { "type": "number", "description": "Defaults to 1" },
            "unit_price": { "type": "number", "description": "NUMBER only: no currency symbols, no thousands separators. Use the exact amount stated; never guess or round" },
            "tax_rate": { "type": "number" },
            "discount_percent": { "type": "number" }
          },
          "required": ["description", "unit_price"]
        }
      }
    },
    "required": ["type"]
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "invoice_id": { "type": "string" },
      "number": { "type": "string" },
      "status": { "type": "string" },
      "total": { "type": "number" }
    },
    "required": ["invoice_id", "number", "status"]
  },
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": false,
    "idempotentHint": false,
    "openWorldHint": false
  }
}

Anotácie hovoria: toto zapisuje, iba pridáva (návrh), zavolanie dvakrát vytvorí dva návrhy a nič mimo systému sa nedotýka. Klienti musia považovať anotácie za nedôveryhodné, pokiaľ nie je server dôveryhodný, takže sú to nápovedy pre správanie pri potvrdení, nie náhrada za vlastné kontroly servera.

Tri voľby v tejto definícii sú zámerné. Výsledok vracia identifikátor, ktorý model musí preniesť do odoslať faktúru a zaznamenaťPlatbu, which is the specification's recommended way to relate calls now that servers hold no session state. The tool creates a draft, not a posted invoice, so the write is additive and a person or a separate approval tool finalises it. And the output schema means an integration can read the number and total as data while the model reads the same result as text.

Obmedzenie nástrojov na používateľa

Cez HTTP volajúci prichádza s OAuth prístupovým tokenom viazaným na váš server, a tento token identifikuje osobu. Špecifikácia umožňuje výsledok tools/list bude sa líšiť podľa poverení v žiadosti, takže prvé rozhodnutie o rozsahu je filtrovať zoznam podľa úlohy tejto osoby pred jeho vrátením: používateľ skladu nedostane schváliť faktúruZoznam sa nesmie líšiť podľa pripojenia alebo ako vedľajší účinok iných volaní, iba na základe autorizácie, čo ho robí cachovateľným.

Druhé rozhodnutie je skontrolovať znova pri vykonaní. Klient môže poslať akýkoľvek požiadavok, ktorý chce, a model môže byť manipulovaný textom v výsledku nástroja do pokusu o jeden. Určte používateľa z tokenu pri každom volaní, skontrolujte oprávnenie, ktoré nástroj vyžaduje, a odmietnite s chybou vykonania nástroja, ktorú model môže prečítať. Udržujte rozsahy OAuth hrubé (Sois vydáva rozsahy na čítanie, zápis a offline) a nechajte vlastné úlohy ERP byť jemne rozlíšenou hranicou, pretože tieto úlohy už existujú, sú už udržiavané a už niečo znamenajú pre podnikanie. Priraďte každé volanie osobe v protokole s jej argumentmi a výsledkom, aby bola práca agenta presne tak prehľadná ako práca osoby.

1. Token prichádzaOverte podpis a to, že publikum je tento server, ako vyžaduje RFC 8707; odmietnite všetko ostatné s 401.
2. Rozpoznať osobuPriraďte token k používateľovi v pracovnom priestore a načítajte jeho rolu a nainštalované aplikácie.
3. Filtrovať zoznamVráťte iba nástroje, ktoré môže táto rola používať, v stabilnom poradí, z nástroje/zoznam.
4. Skontrolujte volanieNa nástrojoch/volanie skontrolujte povolenie znova a odmietnite s isError, ak chýba; nič sa nespustí.
5. Spustiť a zaznamenaťVykonajte transakciu, zmerajte ju, ak váš vlastný agent vykonal uvažovanie, a zapíšte volanie do audítorského denníka pod týmto používateľom.

Spracovanie zápisov

Model, ktorý dostane nejasný výsledok, zavolá znova, a ten, ktorý dostane chybu, sa pokúsi o opravený vstup. Navrhnite to tak. Zápisy, ktoré vytvárajú, by mali vracať identifikátor a, ak je to možné, akceptovať kľúč idempotencie alebo prirodzený kľúč, aby sa detegovalo opakovanie. Zápisy, ktoré menia stav, by mali byť explicitné ohľadom prechodu, ktorý vykonávajú, a odmietnuť nemožné prechody s čitateľným dôvodom: zaznamenanie platby voči zrušenej faktúre je jeChyba výsledok, ktorý to hovorí, nie tichý no-op a nie zásobník chýb. Nikdy nenechávajte čiastočný zápis; ak nástroj s viacerými krokmi nemôže dokončiť, vráťte sa späť a hláste to.

• Preferujte návrhy a schválenia. Urobte vytváranie aditívne (návrh) a dajte finalizácii vlastný nástroj s vlastným povolením, takže deštruktívny krok je ten, ktorý potvrdzuje klient a kontroluje rola.
• Označte deštruktívne nástroje. Nastaviť destructiveHint o zrušeniach a vymazaniach a povedz to v popise; Claude a ChatGPT používajú takéto signály pri rozhodovaní, či sa opýtať pred volaním.
• Pýtaj sa, namiesto aby si hádal. Keď hovor potrebuje rozhodnutie, ktoré nástroj nemôže urobiť, vráť výsledok vyžadujúci vstup s požiadavkou na vyžiadanie; klient položí otázku osobe a znova sa pokúsi o hovor s odpoveďou.
• Obmedz rozsah výbuchu. Obmedz rýchlosť na pripojenie, nastav limit výdavkov na integráciu, kde tvoj vlastný agent vykonáva uvažovanie, a over každé vstupné údaje na serveri bez ohľadu na schému, pretože schéma je rada pre model, nie vynucovanie.

Testovanie rozhrania s reálnym klientom

Inšpektor MCP vykoná tools/list a nástroje/vola a prejde OAuth tokom. Skutočná skúška je model. Pripoj Claude ako vlastný konektor, alebo ChatGPT v režime vývojára, prihlás sa ako používateľ s úzkou rolou a požiadaj o jeden rutinný výsledok, ktorý potrebuje tri alebo štyri nástroje. Sleduj, ktoré nástroje si vyberie a prečo; nesprávny výber je takmer vždy problém s popisom. Potom sa prihlás ako používateľ bez jednej z oprávnení a potvrď, že beh sa zastaví na správnom hovore s dôvodom, ktorý model opakuje.

Takto je postavený a kontrolovaný server pracovného priestoru Sois: transakcie ako nástroje, inštruktážne popisy, zoznam filtrovaný podľa rolí, druhá kontrola pri každom hovore, návrhy pred schválením a záznam, ktorý si môže osoba prečítať. Vývojári, ktorí vytvárajú aplikácie pre trh, publikujú nástroje do rovnakého zoznamu podľa rovnakých pravidiel, takže aplikácia je použiteľná akýmkoľvek agentom v momente, keď je nainštalovaná. Tento vzor nie je špecifický pre jeden produkt; akýkoľvek ERP, ktorý ho prijme, sa stáva niečím, čo agent môže spustiť.

Otázky, ktoré sa ľudia pýtajú.

Tento článok sa prehodnocuje, keď sa zmenia produkty, ktoré popisuje. Ďalšie naplánované prehodnotenie: 4. decembra 2026.