Aller au contenu principal

Cas d'usage MCP

Ces workflows montrent comment un agent IA enchaîne les outils Copera MCP pour accomplir un vrai travail. Comme le serveur est sans état, chaque outil board/table/ligne a besoin d'ObjectIds hex explicites — la plupart des flux commencent donc par la découverte (list_boards → list_tables → get_table_schema) avant de lire ou d'écrire.

Chaque exemple montre les appels d'outils dans l'ordre, avec les arguments clés. Les résultats d'outils sont en JSON ; l'agent lit les ids et valeurs d'un résultat pour alimenter l'appel suivant.

Trouver un board et lire ses lignes​

Le motif le plus courant : localiser un board par nom, trouver une table, puis lire les lignes.

Trouver le board
list_boards({ query: "Roadmap" })
// → [{ id: "66ab…b01", name: "Q3 Roadmap", … }]
Trouver la table
list_tables({ boardId: "66ab…b01", query: "Features" })
// → [{ id: "66ab…t02", name: "Features", columns: [...] }]
Lire le schéma, puis les lignes
get_table_schema({ boardId: "66ab…b01", tableId: "66ab…t02" })
// → column ids + STATUS/DROPDOWN option ids

list_rows({ boardId: "66ab…b01", tableId: "66ab…t02", sort: "66ab…date:desc" })
// → rows with cell values keyed by columnId
Filtrez plutôt que de tout parcourir

list_rows n'est pas paginé et peut être volumineux. Affinez avec query, un filter structuré ({ match, conditions: [{ column_id, operator, value }] }), et sort plutôt que de lire chaque ligne.

Mettre à jour le statut d'une ligne​

Lire d'abord le schéma est requis pour utiliser le vrai columnId et un id d'option valide.

get_table_schema({ boardId, tableId })
// find the STATUS column id and the "Done" option id

update_row({
  boardId,
  tableId,
  rowId: "66ab…r07",
  columns: [{ columnId: "66ab…status", value: "66ab…doneOption" }],
})

Pour éditer la description de texte long d'une ligne ou une cellule de colonne RICH TEXT, utilisez set_row_markdown à la place — update_row ne touche pas au texte long. Les écritures markdown sont mises en file (HTTP 202), donc relisez avec get_row_markdown pour confirmer.

Rechercher des docs et résumer​

Récupérez le document le plus pertinent pour un mot-clé, chargez son corps, et laissez le modèle le résumer.

Rechercher
search_docs({ query: "onboarding checklist", limit: 5 })
// → ranked hits with highlights showing what matched
Lire le contenu du meilleur résultat
get_doc_content({ docId: "66ab…d11" })
// → full markdown body (can be large — only fetch when you need it)
Résumer

L'agent résume le markdown renvoyé dans sa propre réponse. Pour parcourir plutôt que rechercher, utilisez get_docs_tree pour marcher dans la hiérarchie.

Capturer un résumé dans un nouveau doc​

Combinez lecture et écriture — recherchez dans le workspace, puis persistez le résultat.

search({ query: "Q3 launch", types: ["document", "channelMessage"], limit: 20 })
// gather context across docs and chat

create_doc({ title: "Q3 Launch Summary", content: "# Summary\n\n…" })
// → { id: "66ab…d99" }

// append more later (async — re-read to confirm)
set_doc_content({ docId: "66ab…d99", content: "\n\n## Risks\n…", operation: "append" })

Publier un message de channel​

Notifiez un channel, ou envoyez un message direct à une personne précise. Fournissez exactement un de channelId ou userId.

Trouver le channel (ou l'utilisateur)
list_channels({ query: "engineering", type: "text" })
// → [{ id: "66ab…c01", name: "engineering" }]

// or resolve a DM target:
list_workspace_members({ query: "alex@" })
// → [{ id: "66ab…u22", name: "Alex", email: "alex@…" }]
Envoyer
// post to a channel (synchronous)
send_message({ channelId: "66ab…c01", message: "Deploy is green ✅" })

// or direct-message a user (queued, may not appear immediately)
send_message({ userId: "66ab…u22", message: "Can you review the PR?" })
Remplacement du nom d'expéditeur

Le name optionnel (remplacement du nom d'affichage) est channel uniquement — il est rejeté lors de l'envoi d'un message direct.

Trier les notifications​

Lisez la boîte de réception, marquez les éléments traités, et nettoyez le bruit.

list_notifications()
// → { notifications: [...], unreadCount, count }

update_notification({ notificationId: "66ab…n05", status: "read" })

delete_notification({ notificationId: "66ab…n06" }) // no undo

La pagination utilise les ObjectIds de notification comme curseurs : passez l'id le plus ancien renvoyé comme after pour parcourir l'historique en arrière.

Commenter une ligne pour un client​

Ajoutez un commentaire visible de l'extérieur à une ligne de board — utilisez external délibérément, uniquement lorsque des personnes hors du workspace doivent le voir.

list_row_comments({ boardId, tableId, rowId, visibility: "all" })
// review the thread (cursor-paginated via pageInfo.endCursor)

add_row_comment({
  boardId,
  tableId,
  rowId,
  content: "We shipped the fix in today's release.",
  visibility: "external",
})

Exporter une vue et l'enregistrer dans le drive​

Rendez une vue de table en fichier. Pour PDF/ZIP ou de gros exports, préférez saveToDrive: true pour que le fichier atterrisse dans le drive au lieu d'une charge utile inline.

// viewId comes from list_tables / get_table_schema
export_table({
  boardId,
  tableId,
  viewId: "66ab…v01",
  format: "PDF",
  saveToDrive: true,
})
// → async job snapshot + a drive reference

// later, fetch the file
get_drive_download_url({ fileId: "66ab…f44" })
// → presigned CloudFront url (fetch directly, no auth)

Conseils pour des exécutions d'agents fiables​

  • Découvrez avant d'écrire. Appelez get_table_schema pour obtenir de vrais columnIds et ids d'options avant create_row / update_row / set_row_markdown — les types de colonnes non pris en charge dans create_row sont silencieusement ignorés.
  • Relisez après les écritures async. set_row_markdown, set_doc_content et les messages directs sont éventuellement cohérents.
  • Gardez un volume de requêtes raisonnable. L'API applique des limites de débit ; les 429 sont automatiquement réessayés avec backoff, mais les agents qui fan-out peuvent tout de même les atteindre. Affinez les recherches et listes avec query/filter/limit.
  • Attention aux scopes. Un 403 signifie presque toujours que le token n'a pas un scope pour cet outil — voir Authentification.

Voir aussi​