Vai al contenuto principale

Casi d'uso MCP

Questi workflow mostrano come un agente IA concatena i tool Copera MCP per fare lavoro reale. Poiché il server è stateless, ogni tool board/table/row richiede hex ObjectId espliciti — quindi la maggior parte dei flussi inizia con la discovery (list_boards → list_tables → get_table_schema) prima di leggere o scrivere.

Ogni esempio mostra le chiamate ai tool in ordine, con gli argomenti chiave. I risultati dei tool sono JSON; l'agente legge id e valori da un risultato per alimentare la chiamata successiva.

Trovare una board e leggere le sue righe​

Il pattern più comune: localizza una board per nome, trova una table, poi leggi le righe.

Trova la board
list_boards({ query: "Roadmap" })
// → [{ id: "66ab…b01", name: "Q3 Roadmap", … }]
Trova la table
list_tables({ boardId: "66ab…b01", query: "Features" })
// → [{ id: "66ab…t02", name: "Features", columns: [...] }]
Leggi lo schema, poi le righe
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
Filtra invece di scansionare

list_rows non è paginato e può essere grande. Restringilo con query, un filter strutturato ({ match, conditions: [{ column_id, operator, value }] }) e sort piuttosto che leggere ogni riga.

Aggiornare lo status di una riga​

Leggere prima lo schema è obbligatorio così usi il vero columnId e un option id valido.

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" }],
})

Per modificare la description di testo lungo di una riga o una cella di colonna RICH TEXT, usa set_row_markdown al suo posto — update_row non tocca il testo lungo. Le scritture markdown sono in coda (HTTP 202), quindi rileggi con get_row_markdown per confermare.

Cercare docs e riassumere​

Recupera il documento più rilevante per una keyword, prendi il corpo e lascia che il modello lo riassuma.

Cerca
search_docs({ query: "onboarding checklist", limit: 5 })
// → ranked hits with highlights showing what matched
Leggi il contenuto del top hit
get_doc_content({ docId: "66ab…d11" })
// → full markdown body (can be large — only fetch when you need it)
Riassumi

L'agente riassume il markdown restituito nella propria risposta. Per sfogliare anziché cercare, usa get_docs_tree per percorrere la gerarchia.

Catturare un riassunto in un nuovo doc​

Combina lettura e scrittura — ricerca nel workspace, poi persisti il risultato.

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

Pubblicare un messaggio di channel​

Notifica un channel, oppure invia un DM a una persona specifica. Fornisci esattamente uno tra channelId e userId.

Trova il channel (o l'utente)
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@…" }]
Invia
// 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?" })
Override del nome mittente

Il name opzionale (override del display-name) è solo channel — viene rifiutato quando si invia un messaggio diretto.

Triage delle notifiche​

Leggi l'inbox, segna gli elementi gestiti e rimuovi il rumore.

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

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

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

La paginazione usa gli ObjectId delle notifiche come cursor: passa l'id più vecchio restituito come after per scorrere indietro nella cronologia.

Commentare una riga per un cliente​

Aggiungi un commento visibile esternamente a una riga di board — usa external deliberatamente, solo quando persone fuori dal workspace devono vederlo.

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

Esportare una view e salvarla sul drive​

Renderizza una view di table in un file. Per PDF/ZIP o export grandi, preferisci saveToDrive: true così il file finisce nel drive invece che in un payload 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)

Consigli per esecuzioni affidabili degli agenti​

  • Scopri prima di scrivere. Chiama get_table_schema per ottenere columnId reali e option id prima di create_row / update_row / set_row_markdown — i tipi di colonna non supportati in create_row vengono ignorati silenziosamente.
  • Rileggi dopo le scritture async. set_row_markdown, set_doc_content e i messaggi diretti sono eventually consistent.
  • Tieni ragionevole il volume di richieste. L'API applica rate limit; i 429 vengono ritentati automaticamente con backoff, ma gli agenti che fanno fan-out possono comunque colpire i limiti. Restringi search e list con query/filter/limit.
  • Attento agli scope. Un 403 di solito significa che al token manca uno scope per quel tool — vedi Autenticazione.

Vedi anche​