Outils et ressources MCP de PrimeCal

Cette page documente la surface MCP canonique de PrimeCal exposée par le serveur.

Familles d'outils

Organisations, ressources et réservations

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

Champs de saisie courants :

organisationId uniquement pour le changement d'organisation active
resourceTypeId
resourceId optionnel
date pour la disponibilité au niveau du jour
startTime / endTime pour la création de réservation
status, startFrom et endTo optionnels pour la liste des réservations

Comportement important :

les outils de réservation et de ressource résolvent l'organisation active depuis le contexte de l'agent, pas depuis des charges utiles client arbitraires
les outils de facturation et de débogage des paiements utilisent aussi l'organisation active, mais nécessitent un périmètre d'organisation explicite et un contexte de propriété administrateur d'organisation
la disponibilité utilise la même logique de blocage que la réservation publique
MCP n'expose pas les clés Stripe, les sessions Checkout, les intentions de paiement, ni la gestion des webhooks
la création de réservation est limitée aux flux sans paiement, sauf si le contexte du propriétaire agit dans un rôle administratif d'organisation

Champs de saisie spécifiques à la facturation :

defaultCurrency pour les mises à jour sûres pour la facturation
reservationId / bookingId optionnels
paymentStatus optionnel
limit optionnel

Calendriers et événements

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_calendar_userGroups_list
primecal_calendar_userGroups_details
primecal_calendar_userGroups_createInvite
primecal_calendar_userGroups_acceptInvite
primecal_calendar_userGroups_attachCalendars
primecal_calendar_userGroups_detachCalendars

Champs de saisie courants :

calendarId optionnel (nombre)
calendarIds optionnel (tableau de nombres)
from / to (horodatages ISO 8601 UTC)
fields, limit, cursor, expandRecurrences, includeFullDescription, et userTimezone optionnels
eventId ou id pour les mises à jour/suppressions
objet event pour les charges utiles de création/mise à jour

Références recommandées :

Champs de saisie des outils de groupe de personnes :

groupId (nombre)
groupIds (tableau de nombres) pour le filtrage optionnel à la liste
calendarIds (tableau de nombres) pour les opérations d'attachement/détachement
permission (read, write, ou admin) pour les opérations d'attachement
email et message optionnel pour la création d'invitation
token pour l'acceptation d'invitation

Les outils de groupe de personnes sont soumis aux clés d'action calendar.userGroups.*. Les outils d'attachement et de détachement nécessitent à la fois un périmètre de groupe et un périmètre de calendrier.

Tâches et rappels

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_reminders_create
primecal_reminders_update

Les outils de rappel s'appuient sur les tâches et associent les champs de rappel (remindAt, note) aux champs de tâche (dueDate, body).

primecal_tasks_create/primecal_tasks_update acceptent aussi durationMinutes (1-1440, utilisé par la planification automatique), context (deep_work, errand, admin, kid_safe, low_energy), autoScheduled, et preferredWindowStartHour/preferredWindowEndHour (0-23) — par exemple « bloquer 30 minutes de travail concentré pour rédiger le rapport » correspond à primecal_tasks_create avec durationMinutes: 30, context: 'deep_work'.

primecal_tasks_focus_list accepte une date optionnelle (YYYY-MM-DD, par défaut aujourd'hui en UTC) et renvoie la même liste ordonnée par planification et filtrée par dépendances que GET /api/tasks/focus.

primecal_tasks_auto_schedule, primecal_tasks_accept_assignment, et primecal_tasks_bounce_assignment acceptent chacun taskId ou id ; bounce accepte aussi un reason optionnel (max 500 caractères). primecal_tasks_dependencies_add/_remove prennent taskId et dependsOnTaskId.

primecal_tasks_checklist_list/_add/_update/_remove prennent tous taskId, plus title (add), ou itemId/id avec title/isDone/order optionnels (update), ou itemId/id (remove) — par exemple « ajoute 'réserver la salle' à la liste de contrôle de ma tâche d'organisation de fête » correspond à primecal_tasks_checklist_add. Les quatre renvoient la liste de contrôle complète et mise à jour de la tâche.

Routines et foyer

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

primecal_routine_templates_clone accepte templateId/id et un groupId optionnel pour cloner un modèle système dans un groupe de personnes plutôt que dans les modèles personnels de l'appelant. primecal_routine_templates_instantiate accepte templateId/id et démarre le modèle immédiatement — par exemple « démarre ma routine du soir » — exactement comme le bouton Démarrer maintenant, indépendamment de la planification de récurrence du modèle.

primecal_routine_templates_streak accepte templateId/id et renvoie { currentStreak, longestStreak, lastCompletedDate, totalInstantiations }. primecal_routine_templates_skip accepte templateId/id et ignore l'occurrence du jour sans créer de tâches — par exemple « saute le ménage cette semaine, on est en voyage » — sans perturber l'historique de rotation.

primecal_household_items_create accepte name, category, quantity, groupId, expiryDate (YYYY-MM-DD), shelfLifeDays (1-3650), et lowStockThreshold (>= 0, un déclencheur de réapprovisionnement indépendant basé sur la quantité). primecal_household_items_mark_used_up accepte un identifiant d'article et le signale afin que l'analyse horaire de réapprovisionnement crée une tâche pour lui. primecal_household_items_consume accepte itemId/id et un amount optionnel (par défaut 1) pour réduire la quantité — par exemple « utilisé 2 rouleaux d'essuie-tout ».

Voir l'API Routine Templates et l'API Household Items pour le contrat REST sous-jacent et le comportement de rotation/réapprovisionnement que ces outils appellent.

Automatisation

primecal_automation_rules_list
primecal_automation_rules_get
primecal_automation_rules_trigger
primecal_automation_rules_audit_list

Champs de saisie courants :

ruleId (nombre)
status, fromDate, toDate optionnels
pagination (page, limit)

Profil et contexte

primecal_profile_get
primecal_context_snapshot

Saisie de l'instantané de contexte :

days (1-30)
tasksLimit (1-200)
eventsLimit (1-200)
includeCompletedTasks (booléen)

Ressources

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})

Les deux ressources renvoient un contenu textuel application/json dans les réponses MCP resources/read.

Les ressources de groupe de personnes sont en lecture seule et n'incluent que les groupes et calendriers autorisés par le périmètre de l'agent.

Exemples JSON-RPC de réservation d'entreprise

Changer l'organisation active

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

Lire la disponibilité pour un service

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

Créer une réservation sans paiement

{
  "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"
    }
  }
}

Lire le statut de facturation de l'organisation active

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

Mettre à jour la devise de facturation par défaut

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

Préparer l'intégration Stripe

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

Inspecter l'état de débogage des paiements

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

Exemples JSON-RPC de groupe de personnes

Lister les groupes et calendriers scindés

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

Créer une invitation de groupe

{
  "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."
    }
  }
}

Le résultat est volontairement générique et ne divulgue pas si l'e-mail correspond à un utilisateur PrimeCal existant.

Attacher un calendrier à un groupe

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

Lire la ressource de résumé du groupe

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

Modèle de schéma et de résultat

Tous les outils sont listés via tools/list de MCP et publient des objets inputSchema compatibles JSON Schema.

La forme du résultat suit les conventions MCP, avec les distinctions importantes suivantes :

Outils renvoyant des tableaux

Les outils qui renvoient des collections (listOrganisations, listResources, listReservations, primecal_calendars_events_list, etc.) ne définissent pas structuredContent. Les appelants doivent analyser la chaîne JSON dans content[0].text pour obtenir le tableau.

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

Outils renvoyant des objets

Les outils qui renvoient un objet unique définissent structuredContent directement sur l'objet (sans l'envelopper dans un autre objet).

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

Enveloppe d'erreur

Toutes les erreurs définissent isError: true, incluent une description lisible dans content[0].text, et définissent toujours structuredContent sur l'objet d'erreur :

{
  "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
    }
  }
}

Valeurs de type d'erreur :

`type`	Statut HTTP	Signification
`validation_error`	400	Saisie malformée ou échec de validation DTO.
`unauthorized`	401	Clé d'agent manquante ou invalide.
`forbidden`	403	Clé valide mais périmètre de permission insuffisant.
`not_found`	404	La ressource demandée n'existe pas.
`conflict`	409	Conflit d'état (par ex. chevauchement de réservation).
`rate_limited`	429	Limite de débit dépassée ; réessayer après un délai.
`http_error`	5xx	Échec en amont ou côté serveur.
`internal_error`	—	Erreur interne inattendue.

retriable vaut true pour les erreurs transitoires (rate_limited, certaines variantes de http_error) et false pour les échecs permanents.

Note de migration : les documents précédents montraient "type": "permission_denied" dans l'enveloppe d'erreur. Ce type n'existe plus — utilisez "forbidden" (HTTP 403) à la place. Les appelants qui filtraient sur "permission_denied" doivent passer à "forbidden".

Attentes de richesse de la charge utile

Les outils PrimeCal doivent renvoyer des données riches afin que les hôtes IA puissent raisonner avec un minimum d'allers-retours supplémentaires.

Les objets événement incluent la chronologie, la récurrence, le statut, la couleur et les métadonnées.
Les objets groupe de personnes incluent le rôle, des résumés minimaux des membres, des métadonnées sûres pour l'invitation, et des références de calendrier simplifiées lorsqu'elles sont scindées.
Les objets tâche incluent les étiquettes et les métadonnées du miroir tâche-calendrier.
Les réponses d'automatisation incluent les définitions de règles, les compteurs et les journaux d'audit.
Les objets réservation incluent les ressources assignées, le type de ressource, l'instantané de devis, la charge utile client, le statut et l'état de paiement.

Test de fumée rapide du protocole

initialize contre /api/mcp
tools/list
resources/list
tools/call avec primecal_profile_get
resources/read pour primecal://current-context

Attente de la démo Alex Example :

primecal_calendars_list doit inclure Work, Personal, et Side projects.
primecal_calendar_userGroups_list doit renvoyer uniquement les groupes autorisés par le périmètre de groupe de personnes de l'agent.
primecal_organisations_list doit renvoyer uniquement les organisations autorisées par le profil de l'agent et l'accès du propriétaire sous-jacent.

Familles d'outils​

Organisations, ressources et réservations​

Calendriers et événements​

Tâches et rappels​

Routines et foyer​

Automatisation​

Profil et contexte​

Ressources​

Exemples JSON-RPC de réservation d'entreprise​

Changer l'organisation active​

Lire la disponibilité pour un service​

Créer une réservation sans paiement​

Lire le statut de facturation de l'organisation active​

Mettre à jour la devise de facturation par défaut​

Préparer l'intégration Stripe​

Inspecter l'état de débogage des paiements​

Exemples JSON-RPC de groupe de personnes​

Lister les groupes et calendriers scindés​

Créer une invitation de groupe​

Attacher un calendrier à un groupe​

Lire la ressource de résumé du groupe​

Modèle de schéma et de résultat​

Outils renvoyant des tableaux​

Outils renvoyant des objets​

Enveloppe d'erreur​

Attentes de richesse de la charge utile​

Test de fumée rapide du protocole​

Familles d'outils

Organisations, ressources et réservations

Calendriers et événements

Tâches et rappels

Routines et foyer

Automatisation

Profil et contexte

Ressources

Exemples JSON-RPC de réservation d'entreprise

Changer l'organisation active

Lire la disponibilité pour un service

Créer une réservation sans paiement

Lire le statut de facturation de l'organisation active

Mettre à jour la devise de facturation par défaut

Préparer l'intégration Stripe

Inspecter l'état de débogage des paiements

Exemples JSON-RPC de groupe de personnes

Lister les groupes et calendriers scindés

Créer une invitation de groupe

Attacher un calendrier à un groupe

Lire la ressource de résumé du groupe

Modèle de schéma et de résultat

Outils renvoyant des tableaux

Outils renvoyant des objets

Enveloppe d'erreur

Attentes de richesse de la charge utile

Test de fumée rapide du protocole