Riferimento tool MCP
Questa pagina elenca 52 tool di Copera MCP Cloud in dieci domini. Ogni tool è un wrapper sottile su un endpoint della Copera Public API — la colonna Public API capability mostra l'endpoint sottostante che ciascun tool chiama.
| Domain | Tools |
|---|---|
| Workspace | 3 |
| Board | 11 |
| Search | 1 |
| Docs | 8 |
| Notifications | 3 |
| Chat | 2 |
| Comment | 3 |
| Drive | 5 |
| Export | 1 |
| Artefatti | 15 |
| Total | 52 |
Il server è stateless, quindi i tool board/table/row richiedono hex ObjectId espliciti. Il flusso di discovery è get_workspace_info → list_boards → list_tables → get_table_schema → list_rows. Chiama sempre get_table_schema prima di scrivere righe così usi columnId reali e option ID validi.
Workspace
Scope: a livello workspace (risultati filtrati dalle autorizzazioni del token).
| Tool | Description | Public API capability |
|---|---|---|
get_workspace_info | Metadati di base sul workspace a cui appartiene il token (name, slug, seat count, timestamp). | GET /workspace/info |
list_workspace_members | Elenca i membri per risolvere un user id da nome o email; paginazione offset, query opzionale. | GET /workspace/members |
list_workspace_teams | Elenca i team con i participant user id; paginazione offset, query opzionale. | GET /workspace/teams |
Board
Scope: access_boards. Il loop discovery → query → write su boards, tables e rows.
| Tool | Description | Public API capability |
|---|---|---|
list_boards | Elenca le board a cui il token può accedere, ricerca opzionale per nome. Parti da qui per trovare un boardId. | GET /board/list-boards |
get_board | Metadati di una singola board per boardId. | GET /board/{boardId} |
list_tables | Elenca le table di una board con le definizioni delle colonne, ricerca opzionale per nome. | GET /board/{boardId}/tables |
get_table_schema | Definizioni complete delle colonne di una table, inclusi gli option ID per le colonne STATUS/DROPDOWN/LABELS. | GET /board/{boardId}/table/{tableId} |
list_rows | Elenca le righe di una table con query, filter strutturato e sort opzionali. Non paginato. | GET /board/{boardId}/table/{tableId}/rows |
get_row | Ottiene una riga per hex rowId o per rowNumber visibile (fornisci esattamente uno). | GET …/row/{rowId} or GET …/row-number/{rowNumber} |
create_row | Crea una riga da celle { columnId, value }; description legacy opzionale. | POST /board/{boardId}/table/{tableId}/row |
update_row | Aggiorna i valori delle celle di una riga esistente per rowId (non modifica il testo lungo). | PATCH …/row/{rowId} |
delete_row | Elimina definitivamente una riga per rowId. Nessun undo. | DELETE …/row/{rowId} |
get_row_markdown | Legge il markdown di testo lungo: la description legacy della riga, oppure una cella di colonna RICH TEXT se è dato columnId. | GET …/row/{rowId}/md or …/column/{columnId}/md |
set_row_markdown | Scrive markdown (replace/append/prepend) sulla description legacy o su una cella di colonna RICH TEXT. Async (HTTP 202). | POST …/row/{rowId}/md or …/column/{columnId}/md |
Search
Scope: a livello workspace (risultati filtrati dalle autorizzazioni del token).
| Tool | Description | Public API capability |
|---|---|---|
search | Full-text search cross-entity su documenti, channels, messaggi, todo, file del drive, trascrizioni vocali e chat IA. Restringi con types. | GET /search/ |
Docs
Scope: access_docs (i documenti sono solo PAT).
| Tool | Description | Public API capability |
|---|---|---|
search_docs | Full-text search sui documenti con hit classificati e highlight. | GET /docs/search |
get_docs_tree | Sfoglia la gerarchia dei documenti; ometti parentId per la root, limita con depth. | GET /docs/tree |
get_doc | Metadati del documento (title, icon, cover, owner, parent, timestamp) per docId. | GET /docs/{docId} |
get_doc_content | Corpo markdown completo di un documento per docId (può essere grande). | GET /docs/{docId}/md |
create_doc | Crea un documento con un title, parentId e content seed opzionali. | POST /docs/ |
set_doc_content | Scrive markdown (replace/append/prepend) sul corpo di un documento. Async (HTTP 202). | POST /docs/{docId}/md |
update_doc_metadata | Aggiorna title, icon e/o cover di un documento (non il corpo). | PATCH /docs/{docId} |
delete_doc | Elimina un documento per docId (solo owner). Nessun undo. | DELETE /docs/{docId} |
Notifications
Scope: access_notifications (per l'utente del token).
| Tool | Description | Public API capability |
|---|---|---|
list_notifications | Elenca le notifiche dell'utente del token con unreadCount; paginazione id-cursor (after/before). | GET /notifications/ |
update_notification | Segna una notifica come read o unread per notificationId. | PATCH /notifications/{notificationId} |
delete_notification | Elimina una notifica per notificationId. Nessun undo. | DELETE /notifications/{notificationId} |
Chat
Scope: access_channels.
| Tool | Description | Public API capability |
|---|---|---|
list_channels | Elenca channels e conversazioni DM; filtra per query/type/kind/participantId; paginazione offset. | GET /chat/channels |
send_message | Invia un messaggio a un channel (channelId) o un DM a un utente (userId) — esattamente uno. | POST /chat/channel/{channelId}/send-message or POST /chat/direct-message/send-message |
Comment
Scope: access_boards. Commenti di riga e riferimenti agli allegati.
| Tool | Description | Public API capability |
|---|---|---|
list_row_comments | Elenca i commenti di una riga (più recenti prima) con autore e metadati degli allegati; paginazione cursor; filtro visibility. | GET …/row/{rowId}/comments |
add_row_comment | Aggiunge un commento a una riga; visibility è internal (predefinito) o external. | POST …/row/{rowId}/comment |
get_row_attachment_url | Risolve un downloadUrl autenticato per un allegato di colonna FILE o di commento (nessun byte restituito). | …/column/{columnId}/file/{fileId}/download or …/comment/{commentId}/file/{fileId}/download |
Drive
Scope: access_drive (il drive è solo PAT).
| Tool | Description | Public API capability |
|---|---|---|
get_drive_tree | Sfoglia il drive come albero annidato di file/cartelle; limitato da depth, con drill-down in caso di troncamento. | GET /drive/tree |
search_drive | Full-text search su file e cartelle del drive. | GET /drive/search |
get_drive_item | Metadati di un singolo file o cartella per fileId. | GET /drive/files/{fileId} |
get_drive_download_url | URL di download pre-firmato CloudFront a tempo limitato per un file (nessuna auth necessaria per il fetch). | GET /drive/files/{fileId}/download |
create_drive_folder | Crea una cartella alla root o sotto un parentId. | POST /drive/folders |
Export
Scope: access_boards.
| Tool | Description | Public API capability |
|---|---|---|
export_table | Renderizza una view di table in CSV/XLSX/JSON/MARKDOWN/HTML/PDF/ZIP/ICS; inline o in coda; saveToDrive per export grandi/binari. | POST /board/{boardId}/table/{tableId}/export |
Artefatti
Scope: access_drive, e nel tuo workspace devono essere disponibili gli Artefatti. Leggi e modifica le app, le dashboard e le pagine create in Copera — e affidale a un agente di programmazione.
| Tool | Description | Public API capability |
|---|---|---|
get_artifact_handoff | L'unica chiamata per costruire a partire da un artefatto. Restituisce il link dell'artefatto, la versione, la Spec, le note, il design condiviso (linee guida, token, componenti e asset con link di download a breve scadenza), ogni pagina (superficie, viewport, file di ingresso e i file che carica), i link tra le pagine e i file sorgente. versionId e maxInlineBytes opzionali. | GET /artifacts/{artifactId}/handoff |
list_artifacts | Elenca gli artefatti che puoi aprire; scope è mine o shared, search opzionale, paginazione a cursore (after, limit fino a 50). | GET /artifacts/ |
get_artifact | La versione corrente dell'artefatto: pagine, design condiviso, asset, l'elenco dei file con i digest SHA-256 e l'anteprima. Leggi il contenuto dei file con read_artifact_source. | GET /artifacts/{artifactId} |
list_artifact_versions | La cronologia delle versioni dell'artefatto; paginazione a cursore (after, limit fino a 50). | GET /artifacts/{artifactId}/versions |
get_artifact_version | Pagine, design condiviso ed elenco dei file di una versione (versionId). Una versione salvata non cambia mai. | GET …/versions/{versionId} |
read_artifact_source | Legge un file sorgente (path) di una versione a blocchi limitati. Prosegui con il nextCursor restituito finché eof è true. | GET …/versions/{versionId}/source |
get_artifact_page_preview | Anteprima di una pagina (pageId) di una versione. | GET …/versions/{versionId}/pages/{pageId}/preview |
get_artifact_design_snapshot | Una copia riutilizzabile del design condiviso di una versione (linee guida, token, componenti, asset) con il suo digest — passala a create_artifact come reuseDesign. | GET …/versions/{versionId}/design |
list_artifact_design_starters | I design starter selezionati (come shadcn-core-v1) e le loro dipendenze fissate. | GET /artifacts/starters |
list_artifact_assets | Loghi, font, immagini e riferimenti aggiunti al design dell'artefatto. | GET /artifacts/{artifactId}/design-assets |
import_artifact_asset | Aggiunge un file che hai caricato (fileId) al design dell'artefatto come logo, font, image o reference, con altText opzionale. Posizionalo in una pagina con patch_artifact_source. | POST /artifacts/{artifactId}/design-assets |
patch_artifact_source | Modifica i file sorgente a partire da baseVersionId con le operazioni replace_text, put_file e delete_file (fino a 32 file), ciascuna verificata rispetto allo SHA-256 attuale del file. In coda — interroga get_artifact_request. | POST /artifacts/{artifactId}/source-patches |
list_artifact_requests | Le richieste di modifica recenti sull'artefatto, con lo stato e la versione prodotta da ciascuna. | GET /artifacts/{artifactId}/requests |
get_artifact_request | Stato di una richiesta di modifica (requestId) e la versione esatta che ha prodotto. | GET /artifacts/{artifactId}/requests/{requestId} |
create_artifact | Crea un artefatto privato dal tuo progetto sorgente (static_web o vite_react), con un title, un request che ne descrive lo scopo e una idempotencyKey. Facoltativamente parti da un design starter (designStarterId) o riutilizza un design (reuseDesign) — l'uno o l'altro. | POST /artifacts/ |
get_artifact_handoff è tutto ciò che serve a un agente di programmazione. Segui il risultato nell'ordine: leggi la Spec, poi le note, poi imposta il design, poi costruisci ogni pagina dai suoi file e infine collega i link tra le pagine — seguendo i nextSteps restituiti. Ometti versionId per ottenere l'ultima versione costruita con successo. Il contenuto dei file è incluso fino a maxInlineBytes (32 KiB di default, fino a 1 MiB se il tuo client accetta risultati grandi); i file contrassegnati omitted: "over_budget" si leggono con read_artifact_source usando l'id di versione restituito. Vedi Costruisci con il tuo agente di programmazione per la configurazione.
Note di comportamento
set_row_markdown e set_doc_content sono messi in coda (HTTP 202) — rileggi con get_row_markdown / get_doc_content per confermare che la modifica sia applicata. Gli invii ai channel sono sincroni; i messaggi diretti sono in coda e potrebbero non comparire subito.
patch_artifact_source e create_artifact restituiscono una ricevuta, non una build completata. Dopo una patch, interroga get_artifact_request finché la richiesta è completata o fallita, poi leggi la versione prodotta; dopo una create, leggi l'artefatto restituito e la sua anteprima. Riusa una idempotencyKey solo per ripetere la stessa identica richiesta. Se un file è cambiato da quando l'hai letto, la modifica fallisce con un conflitto — rileggilo e riprova.
delete_row, delete_doc e delete_notification rimuovono i dati in modo permanente. Conferma l'id di destinazione prima di chiamarli.
Nessun tool restituisce mai i byte grezzi di un file. get_drive_download_url restituisce un URL pre-firmato che puoi scaricare senza auth; get_row_attachment_url restituisce un downloadUrl autenticato che recuperi tu con il bearer token.
Per lo schema request/response di ciascun endpoint sottostante, vedi l'API Reference.