PrimeCal MCP eszközök és erőforrások

Ez az oldal dokumentálja a szerver által kiadott, hivatalos PrimeCal MCP felületet.

Eszközcsaládok

Szervezetek, erőforrások és foglalások

primecal_organisations_list
primecal_organisations_active_set
primecal_organisations_billing_status_get
primecal_organisations_billing_settings_update
primecal_organisations_stripe_onboardingLink_create
primecal_organisations_payments_debug_get
primecal_resourceTypes_list
primecal_resources_list
primecal_reservations_availability_list
primecal_reservations_list
primecal_reservations_get
primecal_reservations_create

Gyakori bemeneti mezők:

organisationId csak az aktív szervezet váltásához
resourceTypeId
opcionális resourceId
date a napi szintű elérhetőséghez
startTime / endTime foglalás létrehozásához
opcionális status, startFrom és endTo a foglalások listázásához

Fontos viselkedés:

a foglalási és erőforrás-eszközök az aktív szervezetet az ügynök kontextusából oldják fel, nem tetszőleges kliens-payloadból
a számlázási és fizetési-hibakeresési eszközök is az aktív szervezetet használják, de explicit szervezet-hatókört és szervezet-admin tulajdonosi kontextust igényelnek
az elérhetőség ugyanazt a blokkolási logikát használja, mint a nyilvános foglalás
a MCP nem adja ki a Stripe kulcsokat, Checkout session-öket, payment intenteket vagy a webhook-kezelést
a foglalás létrehozása nem-fizetős folyamatokra korlátozott, kivéve ha a tulajdonosi kontextus egy admin szervezeti szerepben jár el

Számlázásspecifikus bemeneti mezők:

defaultCurrency számlázás-biztos frissítésekhez
opcionális reservationId / bookingId
opcionális paymentStatus
opcionális limit

Naptárak és események

primecal_calendars_list
primecal_calendars_get
primecal_calendars_events_list
primecal_calendars_events_search_v2
primecal_calendars_events_get_v2
primecal_calendars_events_create
primecal_calendars_events_update
primecal_calendars_events_delete
primecal_calendars_events_move
primecal_calendars_events_conflicts
primecal_calendars_availability_find
primecal_calendar_userGroups_list
primecal_calendar_userGroups_details
primecal_calendar_userGroups_createInvite
primecal_calendar_userGroups_acceptInvite
primecal_calendar_userGroups_attachCalendars
primecal_calendar_userGroups_detachCalendars

Ütemezési eszközök

A primecal_calendars_events_move áthelyez egy eseményt, megtartva az időtartamát és (egész napos események esetén) a napterjedelmét. Ütemezés-áthelyezéshez részesítse előnyben a primecal_calendars_events_update helyett: a szerver az eredeti időtartamból számolja újra a végpontot, így a hívónak nem kell, és visszaadja azokat az eseményeket, amelyekkel a célidőpont ütközik. Adja meg a rejectOnConflict: true paramétert, hogy egy ütköző célidőpont hibával visszautasítódjon dupla foglalás helyett.

A primecal_calendars_events_conflicts arra válaszol, hogy „szabad-e ez az időpont?”, a primecal_calendars_availability_find arra, hogy „mikor szabad ez?”. Mindkettő félig-nyitott átfedést használ, így egy esemény, amely pontosan akkor ér véget, amikor egy ablak kezdődik, szomszédos, nem ütköző; az elérhetőség pedig összevonja az átfedő foglalt intervallumokat, mielőtt végigjárná a réseket, így egy időpontot sosem jelent szabadnak egy meglévő foglaláson belül.

A áthelyezéshez calendar.events.update szükséges; az ütközésekhez és elérhetőséghez calendar.events.read. Nem vezettek be új engedélykulcsot, így a meglévő ügynöki jogosultságok már lefedik ezeket az eszközöket.

Gyakori bemeneti mezők:

opcionális calendarId (szám)
opcionális calendarIds (szám tömb)
from / to (ISO 8601 UTC időbélyegek)
opcionális fields, limit, cursor, expandRecurrences, includeFullDescription és userTimezone
eventId vagy id frissítéshez/törléshez
event objektum a létrehozási/frissítési payloadokhoz

Ajánlott hivatkozások:

Csoport-eszközök bemeneti mezői:

groupId (szám)
groupIds (szám tömb) opcionális szűréshez listázáskor
calendarIds (szám tömb) csatolási/leválasztási műveletekhez
permission (read, write, vagy admin) csatolási műveletekhez
email és opcionális message meghívó létrehozásához
token meghívó elfogadásához

A csoport-eszközöket a calendar.userGroups.* művelet-kulcsok védik. A csatolás és leválasztás mindkét hatókört igényli: csoport- és naptár-hatókört is.

Feladatok és emlékeztetők

primecal_tasks_list
primecal_tasks_create
primecal_tasks_update
primecal_tasks_delete
primecal_tasks_labels_list
primecal_tasks_labels_create
primecal_tasks_labels_update
primecal_tasks_labels_delete
primecal_tasks_focus_list
primecal_tasks_auto_schedule
primecal_tasks_accept_assignment
primecal_tasks_bounce_assignment
primecal_tasks_dependencies_add
primecal_tasks_dependencies_remove
primecal_tasks_checklist_list
primecal_tasks_checklist_add
primecal_tasks_checklist_update
primecal_tasks_checklist_remove
primecal_tasks_reorder
primecal_tasks_archive
primecal_tasks_unarchive
primecal_tasks_archive_done
primecal_tasks_settings_get
primecal_tasks_settings_update
primecal_reminders_create
primecal_reminders_update

Az emlékeztető-eszközök feladat-alapúak, és az emlékeztető mezőket (remindAt, note) feladat mezőkre képezik le (dueDate, body).

A primecal_tasks_create/primecal_tasks_update elfogadja a durationMinutes (1-1440, az automatikus ütemezéshez), context (deep_work, errand, admin, kid_safe, low_energy), autoScheduled, és preferredWindowStartHour/preferredWindowEndHour (0-23) mezőket is — pl. „blokkolj 30 perc mélymunkát a jelentés megírásához” a primecal_tasks_create-re képeződik le durationMinutes: 30, context: 'deep_work' paraméterekkel.

A primecal_tasks_focus_list elfogad egy opcionális date paramétert (YYYY-MM-DD, alapértelmezés szerint a mai nap UTC-ben), és ugyanazt az ütemezés szerint rendezett, függőség-szűrt listát adja vissza, mint a GET /api/tasks/focus.

A primecal_tasks_auto_schedule, primecal_tasks_accept_assignment és primecal_tasks_bounce_assignment mindegyike elfogadja a taskId vagy id mezőt; a bounce egy opcionális reason mezőt is (max 500 karakter). A primecal_tasks_dependencies_add/_remove elfogadja a taskId és dependsOnTaskId mezőket.

A primecal_tasks_checklist_list/_add/_update/_remove mindegyike elfogadja a taskId mezőt, plusz title (hozzáadás), vagy itemId/id opcionális title/isDone/order mezőkkel (frissítés), vagy itemId/id (eltávolítás) — pl. „adj hozzá egy 'rendezvényhely lefoglalása' tételt a buliszervezés feladatom ellenőrzőlistájához” a primecal_tasks_checklist_add-re képeződik le. Mind a négy a feladat teljes, frissített ellenőrzőlistáját adja vissza.

A primecal_tasks_reorder elfogadja a status mezőt és a teljes, rendezett taskIds tömböt az adott oszlophoz — pl. „mozgasd az 'írj állapotjelentést' feladatomat a To Do oszlop tetejére” a jelenlegi To Do sorrend primecal_tasks_list-tel történő beolvasására, majd a primecal_tasks_reorder meghívására képeződik le úgy, hogy a feladat id-je előre kerül. A primecal_tasks_archive/primecal_tasks_unarchive elfogadja a taskId/id mezőt; a primecal_tasks_archive_done nem fogad el paramétert, és egyszerre archiválja az összes kész, még nem archivált feladatot. A primecal_tasks_settings_get nem fogad el paramétert; a primecal_tasks_settings_update elfogadja az autoArchiveCompletedTasksDays mezőt (1-3650 közötti egész szám, vagy null az automatikus archiválás kikapcsolásához).

Rutinok és háztartás

primecal_routine_templates_list
primecal_routine_templates_clone
primecal_routine_templates_instantiate
primecal_routine_templates_streak
primecal_routine_templates_skip
primecal_household_items_list
primecal_household_items_create
primecal_household_items_mark_used_up
primecal_household_items_consume

A primecal_routine_templates_clone elfogadja a templateId/id mezőt és egy opcionális groupId-t, hogy egy rendszersablont egy csoportba klónozzon a hívó személyes sablonjai helyett. A primecal_routine_templates_instantiate elfogadja a templateId/id mezőt, és azonnal elindítja a sablont — pl. „indítsd el az esti rutinomat” — ugyanúgy, mint a Start now gomb, a sablon ismétlődési ütemezésétől függetlenül.

A primecal_routine_templates_streak elfogadja a templateId/id mezőt, és visszaadja a { currentStreak, longestStreak, lastCompletedDate, totalInstantiations } objektumot. A primecal_routine_templates_skip elfogadja a templateId/id mezőt, és kihagyja a mai előfordulást feladatok létrehozása nélkül — pl. „hagyd ki a takarítást ezen a héten, utazunk” — a rotáció-előzmény megzavarása nélkül.

A primecal_household_items_create elfogadja a name, category, quantity, groupId, expiryDate (YYYY-MM-DD), shelfLifeDays (1-3650) és lowStockThreshold (>= 0, egy önálló, darabszám-alapú újrarendelési trigger) mezőket. A primecal_household_items_mark_used_up elfogad egy tétel-id-t, és megjelöli, hogy az óránkénti utánpótlás-ellenőrzés feladatot hozzon létre rá. A primecal_household_items_consume elfogadja az itemId/id mezőt és egy opcionális amount mezőt (alapértelmezés 1) a mennyiség csökkentéséhez — pl. „elhasználtunk 2 tekercs papírtörlőt”.

Lásd a Rutinsablonok API és a Háztartási tételek API oldalakat az alapul szolgáló REST szerződésért és a rotáció/utánpótlás viselkedésért, amelybe ezek az eszközök hívnak.

Automatizálás

primecal_automation_rules_list
primecal_automation_rules_get
primecal_automation_rules_trigger
primecal_automation_rules_audit_list

Gyakori bemeneti mezők:

ruleId (szám)
opcionális status, fromDate, toDate
lapozás (page, limit)

Profil és kontextus

primecal_profile_get
primecal_context_snapshot
primecal_context_snapshot_v2
primecal_summary_today_week

Kontextus-pillanatkép bemenet:

days (1-30)
tasksLimit (1-200)
eventsLimit (1-200)
includeCompletedTasks (boolean)

A primecal_summary_today_week egy egy-hívásos mai+heti összefoglaló (ma esedékes és a mától induló, görgő 7 napos ablakban esedékes események és feladatok) — használja ezt két külön kontextus-pillanatkép/esemény hívás helyett, amikor a cél egy napi vagy heti összefoglaló. Bemenet: userTimezone, eventsLimit (1-100), tasksLimit (1-200), includeCompletedTasks (boolean).

Értesítések

primecal_notifications_list
primecal_notifications_mark_read
primecal_notifications_act
primecal_notifications_preferences_get
primecal_notifications_preferences_update

Gyakori bemeneti mezők:

opcionális unreadOnly, archived (boolean) és threadId (szám) a listaszűréshez
opcionális afterCursor (átlátszatlan ISO-időbélyeg kurzor) a lista lapozásához
ids (szám tömb, 1-100) értesítések olvasottként jelöléséhez
notificationId (szám) és actionType (confirm | snooze | delegate | claim | done | undo | ack), plusz egy opcionális payload objektum (pl. { snoozeUntil } vagy { snoozeMinutes } egy szundi-művelethez) a primecal_notifications_act-hez
preferences (tömb, { eventType, channels, digest?, fallbackOrder?, quietHours? } elemekkel) preferencia-frissítésekhez

Mind az öt eszköz a hitelesített felhasználó saját értesítéseire és preferenciáira korlátozott; nincs felhasználók közötti hozzáférés. A primecal_notifications_list legfeljebb 50 értesítést ad vissza, a legújabbtól kezdve. A primecal_notifications_act rögzíti az „acted” életciklus-fázist ugyanazon a NotificationsService.recordAction útvonalon, mint a REST /notifications/:id/act végpont, és mellékhatásokat is kezel (olvasottként jelölés, archiválás done/confirm esetén, szundi-újraütemezés, archiváltsági állapot törlése undo esetén). A primecal_notifications_preferences_update lecseréli a tárolt preferenciát minden beküldött eventType-hoz — a tömbből kihagyott eseménytípusok eltávolításra kerülnek, megfelelve a PUT /api/notifications/preferences viselkedésének.

Képernyők és eszközök

primecal_screens_list
primecal_screens_get
primecal_screen_templates_list
primecal_screen_templates_apply
primecal_devices_list

Gyakori bemeneti mezők:

screenId vagy id (szám) a primecal_screens_get-hez
templateId vagy id (szám), opcionális screenId (szám), és opcionális newScreenName (string, ≤120) a primecal_screen_templates_apply-hoz

Mind az öt eszköz túlnyomórészt olvasó jellegű, és a hitelesített felhasználó saját Képernyőire, Sablonjaira és Eszközeire korlátozott — a primecal_screen_templates_apply az egyetlen író művelet, és csak egy, a hívó tulajdonában lévő Képernyőt érinthet. A párosítási kód beváltása, az Eszköztoken kiadása/visszavonása és az org-szintű Képernyő RBAC admin műveletek szándékosan nincsenek MCP eszközként kiadva — egyszerűen ki vannak hagyva az eszközregisztrációból, nem egy külön engedélymechanizmus zárja le őket. A primecal_devices_list sosem adja vissza egy Eszköz hitelesítő adatát — csak a nevét, állapotát, hozzárendelt Képernyőjét és az utolsó látott időbélyeget.

Erőforrások

primecal.current-context (primecal://current-context)
primecal.automation-summary (primecal://automation-summary)
primecal.calendar.user-groups (primecal://calendar/user-groups)
primecal.calendar.user-group-detail (primecal://calendar/user-groups/{id})

Mindkét erőforrás application/json szöveges tartalmat ad vissza a MCP resources/read válaszokban.

A csoport-erőforrások csak olvashatók, és csak az ügynök hatóköre által engedélyezett csoportokat és naptárakat tartalmazzák.

Enterprise foglalási JSON-RPC példák

Aktív szervezet váltása

{
  "jsonrpc": "2.0",
  "id": 30,
  "method": "tools/call",
  "params": {
    "name": "primecal_organisations_active_set",
    "arguments": {
      "organisationId": 12
    }
  }
}

Egy szolgáltatás elérhetőségének beolvasása

{
  "jsonrpc": "2.0",
  "id": 31,
  "method": "tools/call",
  "params": {
    "name": "primecal_reservations_availability_list",
    "arguments": {
      "date": "2026-05-20",
      "resourceTypeId": 8
    }
  }
}

Nem-fizetős foglalás létrehozása

{
  "jsonrpc": "2.0",
  "id": 32,
  "method": "tools/call",
  "params": {
    "name": "primecal_reservations_create",
    "arguments": {
      "resourceTypeId": 8,
      "resourceIds": [41, 42],
      "startTime": "2026-05-20T10:00:00Z",
      "endTime": "2026-05-20T11:00:00Z",
      "notes": "Agent-assisted booking"
    }
  }
}

Az aktív szervezet számlázási állapotának beolvasása

{
  "jsonrpc": "2.0",
  "id": 33,
  "method": "tools/call",
  "params": {
    "name": "primecal_organisations_billing_status_get",
    "arguments": {}
  }
}

Az alapértelmezett számlázási pénznem frissítése

{
  "jsonrpc": "2.0",
  "id": 34,
  "method": "tools/call",
  "params": {
    "name": "primecal_organisations_billing_settings_update",
    "arguments": {
      "defaultCurrency": "eur"
    }
  }
}

Stripe onboarding előkészítése

{
  "jsonrpc": "2.0",
  "id": 35,
  "method": "tools/call",
  "params": {
    "name": "primecal_organisations_stripe_onboardingLink_create",
    "arguments": {}
  }
}

Fizetési hibakeresési állapot megtekintése

{
  "jsonrpc": "2.0",
  "id": 36,
  "method": "tools/call",
  "params": {
    "name": "primecal_organisations_payments_debug_get",
    "arguments": {
      "paymentStatus": "pending",
      "limit": 10
    }
  }
}

Csoport JSON-RPC példák

Hatókörbe eső csoportok és naptárak listázása

{
  "jsonrpc": "2.0",
  "id": 20,
  "method": "tools/call",
  "params": {
    "name": "primecal_calendar_userGroups_list",
    "arguments": {
      "includeCalendars": true
    }
  }
}

Csoportmeghívó létrehozása

{
  "jsonrpc": "2.0",
  "id": 21,
  "method": "tools/call",
  "params": {
    "name": "primecal_calendar_userGroups_createInvite",
    "arguments": {
      "groupId": 9,
      "email": "teammate@example.com",
      "message": "Join the shared planning calendars."
    }
  }
}

Az eredmény szándékosan általános, és nem fedi fel, hogy az e-mail cím egy létező PrimeCal felhasználóhoz tartozik-e.

Naptár csatolása egy csoporthoz

{
  "jsonrpc": "2.0",
  "id": 22,
  "method": "tools/call",
  "params": {
    "name": "primecal_calendar_userGroups_attachCalendars",
    "arguments": {
      "groupId": 9,
      "calendarIds": [5],
      "permission": "write"
    }
  }
}

A csoport-összefoglaló erőforrás beolvasása

{
  "jsonrpc": "2.0",
  "id": 23,
  "method": "resources/read",
  "params": {
    "uri": "primecal://calendar/user-groups"
  }
}

Séma és eredménymodell

Minden eszköz fel van sorolva a MCP tools/list-en, és JSON Schema-kompatibilis inputSchema objektumokat publikál.

Az eredmény alakja a MCP konvencióit követi, a következő fontos eltérésekkel:

Tömböt visszaadó eszközök

A gyűjteményeket visszaadó eszközök (listOrganisations, listResources, listReservations, primecal_calendars_events_list, stb.) nem állítják be a structuredContent-et. A hívóknak a content[0].text-ben lévő JSON stringet kell feldolgozniuk a tömb megszerzéséhez.

{
  "content": [
    {
      "type": "text",
      "text": "[{\"id\":41,\"name\":\"Pool lane A\"},{\"id\":42,\"name\":\"Pool lane B\"}]"
    }
  ]
}

Objektumot visszaadó eszközök

A egyetlen objektumot visszaadó eszközök a structuredContent-et közvetlenül az objektumra állítják (nem egy másik objektumba csomagolva).

{
  "content": [
    {
      "type": "text",
      "text": "{\"id\":42,\"title\":\"Project review\"}"
    }
  ],
  "structuredContent": {
    "id": 42,
    "title": "Project review"
  }
}

Hibaboríték

Minden hiba beállítja az isError: true-t, tartalmaz egy ember által olvasható leírást a content[0].text-ben, és mindig beállítja a structuredContent-et a hibaobjektumra:

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "Agent does not have access to this tool or scope."
    }
  ],
  "structuredContent": {
    "error": {
      "type": "forbidden",
      "message": "Agent does not have access to this tool or scope.",
      "statusCode": 403,
      "retriable": false
    }
  }
}

type hibaértékek:

`type`	HTTP státusz	Jelentés
`validation_error`	400	Hibás bemenet vagy DTO-validációs hiba.
`unauthorized`	401	Hiányzó vagy érvénytelen ügynökkulcs.
`forbidden`	403	Érvényes kulcs, de nem elegendő jogosultság.
`not_found`	404	A kért erőforrás nem létezik.
`conflict`	409	Állapotütközés (pl. foglalási átfedés).
`rate_limited`	429	A sebességkorlát túllépve; próbálja újra visszavárakozás után.
`http_error`	5xx	Upstream vagy szerveroldali hiba.
`internal_error`	—	Nem várt belső hiba.

A retriable true tranziens hibáknál (rate_limited, néhány http_error variáns), és false tartós hibáknál.

Migrációs megjegyzés: a korábbi dokumentáció "type": "permission_denied"-ot mutatott a hibaborítékban. Ez a típus már nem létezik — használja a "forbidden"-t (HTTP 403) helyette. A "permission_denied"-ra illesztő hívóknak frissíteniük kell a "forbidden"-ra.

Payload-gazdagsági elvárások

A PrimeCal eszközöknek gazdag adatot kell visszaadniuk, hogy az AI-hosztok minimális további körutakkal tudjanak következtetni.

Az esemény-objektumok tartalmazzák az idővonalat, az ismétlődést, az állapotot, a színt és a metaadatokat.
A csoport-objektumok tartalmazzák a szerepet, minimális tagsági összefoglalókat, meghívó-biztos metaadatokat, és egyszerűsített naptár-hivatkozásokat, ha hatókörbe esnek.
A feladat-objektumok tartalmazzák a címkéket és a feladat-naptár tükör-metaadatokat.
Az automatizálási válaszok tartalmazzák a szabálydefiníciókat, számlálókat és audit-rekordokat.
A foglalás-objektumok tartalmazzák a hozzárendelt erőforrásokat, erőforrástípust, árajánlat-pillanatképet, ügyfél-payloadot, állapotot és fizetési állapotot.

Gyors protokoll-füstpróba

initialize a /api/mcp ellen
tools/list
resources/list
tools/call a primecal_profile_get-tel
resources/read a primecal://current-context-hez

Alex Example demó elvárás:

a primecal_calendars_list-nek tartalmaznia kell a Work, Personal és Side projects naptárakat.
a primecal_calendar_userGroups_list-nek csak az ügynök csoport-hatóköre által engedélyezett csoportokat kell visszaadnia.
a primecal_organisations_list-nek csak az ügynökprofil és az alapul szolgáló tulajdonosi hozzáférés által engedélyezett szervezeteket kell visszaadnia.

Eszközcsaládok​

Szervezetek, erőforrások és foglalások​

Naptárak és események​

Ütemezési eszközök​

Feladatok és emlékeztetők​

Rutinok és háztartás​

Automatizálás​

Profil és kontextus​

Értesítések​

Képernyők és eszközök​

Erőforrások​

Enterprise foglalási JSON-RPC példák​

Aktív szervezet váltása​

Egy szolgáltatás elérhetőségének beolvasása​

Nem-fizetős foglalás létrehozása​

Az aktív szervezet számlázási állapotának beolvasása​

Az alapértelmezett számlázási pénznem frissítése​

Stripe onboarding előkészítése​

Fizetési hibakeresési állapot megtekintése​

Csoport JSON-RPC példák​

Hatókörbe eső csoportok és naptárak listázása​

Csoportmeghívó létrehozása​

Naptár csatolása egy csoporthoz​

A csoport-összefoglaló erőforrás beolvasása​

Séma és eredménymodell​

Tömböt visszaadó eszközök​

Objektumot visszaadó eszközök​

Hibaboríték​

Payload-gazdagsági elvárások​

Gyors protokoll-füstpróba​

Eszközcsaládok

Szervezetek, erőforrások és foglalások

Naptárak és események

Ütemezési eszközök

Feladatok és emlékeztetők

Rutinok és háztartás

Automatizálás

Profil és kontextus

Értesítések

Képernyők és eszközök

Erőforrások

Enterprise foglalási JSON-RPC példák

Aktív szervezet váltása

Egy szolgáltatás elérhetőségének beolvasása

Nem-fizetős foglalás létrehozása

Az aktív szervezet számlázási állapotának beolvasása

Az alapértelmezett számlázási pénznem frissítése

Stripe onboarding előkészítése

Fizetési hibakeresési állapot megtekintése

Csoport JSON-RPC példák

Hatókörbe eső csoportok és naptárak listázása

Csoportmeghívó létrehozása

Naptár csatolása egy csoporthoz

A csoport-összefoglaló erőforrás beolvasása

Séma és eredménymodell

Tömböt visszaadó eszközök

Objektumot visszaadó eszközök

Hibaboríték

Payload-gazdagsági elvárások

Gyors protokoll-füstpróba