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 :
resourceetcomponent: filtres de correspondance exacte, combinables entre eux.search/search_by: recherche texte insensible à la casse ;search_bysélectionne les champs recherchés (par défautv.connector,v.connector_name,v.component,v.resource), pas les champs retournés.tstart/tstop/time_field: bornes temporelles inclusives, en secondes Unix ;time_fieldpeut valoirt,v.creation_date,v.resolved,v.last_update_dateouv.last_event_date(par défautt, ouv.resolvedsiopenedestfalse).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) ; sanslimit, 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.