Aller au contenu

Référence des outils et ressources

Outils d’écriture (mutables)

Désactivables globalement via le commutateur d’écriture.

Tool Route API sous-jacente Méthode
create_alarm mcp.create_alarm_route (défaut /internal/event) POST
ack_alarm /internal/alarms/{id}/ack PUT
comment_alarm /internal/alarms/{id}/comment PUT
snooze_alarm /internal/alarms/{id}/snooze PUT
associate_ticket_to_alarm /internal/alarms/{id}/assocticket PUT

Outils de lecture

Restent actifs même lorsque les tools d’écriture sont désactivés.

Tool Route API sous-jacente Méthode
get_alarm_by_id mcp.get_alarm_by_id_route (défaut /internal/alarms/{id}) GET
get_alarm_by_entity mcp.get_alarm_by_entity_route (défaut /internal/open-alarms?_id={id}) GET
search_alarms mcp.search_alarms_route (défaut /internal/alarms) GET

get_alarm_by_entity accepte directement un identifiant d’entité composite (par exemple resource/component) : l’encodage d’URL est géré par l’outil.

search_alarms reprend les mêmes sémantiques de filtrage que GET /internal/alarms :

  • resource et component : filtres de correspondance exacte, combinables entre eux.
  • search / search_by : recherche texte insensible à la casse ; search_by sélectionne les champs recherchés (par défaut v.connector, v.connector_name, v.component, v.resource), pas les champs retournés.
  • tstart / tstop / time_field : bornes temporelles inclusives, en secondes Unix ; time_field peut valoir t, v.creation_date, v.resolved, v.last_update_date ou v.last_event_date (par défaut t, ou v.resolved si opened est false).
  • alarm_pattern : pattern d’alarme structuré, encodé en JSON.
  • sort_by / sort / limit / page : tri et pagination (les métadonnées de pagination de l’API sont conservées dans la réponse) ; sans limit, la limite par défaut est 10.

Ressources (lecture seule)

Resource URI Description
Alarme par id canopsis://alarms/{id} Lit une alarme unique par son identifiant Canopsis
Alarme par entité canopsis://alarms/entity/{entity_id} Lit l’alarme courante d’une entité
Recherche d’alarmes canopsis://alarms/search{?...} Recherche paramétrée, mêmes paramètres que search_alarms

Format des réponses

Par choix de conception, les réponses des tools MCP Canopsis sont des objets JSON structurés et stables, sans texte libre explicatif. Ce choix reprend celui déjà fait pour la génération de patterns par l’assistant IA de l’interface : un client MCP a besoin d’un schéma prévisible pour enchaîner des appels et raisonner sur le résultat, plutôt que d’une réponse en langage naturel à réinterpréter.

Taxonomie d’erreurs

Code d’erreur Signification
unauthorized Authkey absente ou invalide
forbidden Permission refusée par l’API, ou tool d’écriture désactivé par le kill switch
validation_error Paramètres d’entrée invalides (schéma JSON non respecté)
not_found Ressource inexistante (par exemple, une alarme qui n’existe pas ou plus)
conflict Conflit de mutation concurrente, détecté et renvoyé par l’API
transient_error Erreur temporaire (route mal configurée, timeout, etc.)

Limitation connue : ressource introuvable et code JSON-RPC

Quand une resource MCP (par exemple canopsis://alarms/{id}) correspond à une alarme absente, l’API Canopsis renvoie normalement un 404 Not Found. C’est un résultat attendu, pas une anomalie. Avec le SDK MCP utilisé par le serveur (go-sdk), ce cas remonte cependant :

  • en HTTP 400,
  • avec un code JSON-RPC -32602 ("paramètres invalides"),

alors que la spécification MCP prévoit le code -32002 pour une ressource introuvable. Un client conforme peut donc, selon son interface, présenter ce résultat comme une requête malformée plutôt que comme une simple absence de résultat.

Il s’agit d’un comportement connu du serveur/SDK actuel, pas du mapping cible : une future évolution du serveur devra renvoyer un JSON-RPC valide avec le code -32002. En attendant, traitez un tel message comme équivalent à "ressource non trouvée" plutôt que comme une erreur de configuration côté client. Voir Dépannage.