Referência de Ferramentas MCP
Esta página lista 52 ferramentas do Copera MCP Cloud em dez domínios. Cada ferramenta é um wrapper fino sobre um endpoint da Copera Public API — a coluna capacidade da Public API mostra o endpoint subjacente que cada ferramenta chama.
| Domínio | Ferramentas |
|---|---|
| Workspace | 3 |
| Board | 11 |
| Busca | 1 |
| Docs | 8 |
| Notificações | 3 |
| Chat | 2 |
| Comentário | 3 |
| Drive | 5 |
| Exportação | 1 |
| Artefatos | 15 |
| Total | 52 |
O servidor é sem estado, então as ferramentas de board/tabela/linha precisam de ObjectIds hex explícitos. O fluxo de descoberta é get_workspace_info → list_boards → list_tables → get_table_schema → list_rows. Sempre chame get_table_schema antes de escrever linhas para usar columnIds reais e IDs de opções válidos.
Workspace
Escopo: nível de workspace (resultados filtrados pelas permissões do token).
| Ferramenta | Descrição | Capacidade da Public API |
|---|---|---|
get_workspace_info | Metadados básicos sobre o workspace ao qual o token pertence (nome, slug, contagem de assentos, timestamps). | GET /workspace/info |
list_workspace_members | Lista membros para resolver um id de usuário a partir de um nome ou e-mail; paginado por offset, query opcional. | GET /workspace/members |
list_workspace_teams | Lista times com os ids de usuário de seus participantes; paginado por offset, query opcional. | GET /workspace/teams |
Board
Escopo: access_boards. O loop de descoberta → consulta → escrita sobre boards, tabelas e linhas.
| Ferramenta | Descrição | Capacidade da Public API |
|---|---|---|
list_boards | Lista boards que o token pode acessar, busca opcional por nome. Comece aqui para encontrar um boardId. | GET /board/list-boards |
get_board | Metadados de um único board por boardId. | GET /board/{boardId} |
list_tables | Lista as tabelas de um board com definições de colunas, busca opcional por nome. | GET /board/{boardId}/tables |
get_table_schema | Definições completas das colunas de uma tabela, incluindo IDs de opções para colunas STATUS/DROPDOWN/LABELS. | GET /board/{boardId}/table/{tableId} |
list_rows | Lista linhas em uma tabela com query opcional, filter estruturado e sort. Não paginado. | GET /board/{boardId}/table/{tableId}/rows |
get_row | Obtém uma linha pelo rowId hex ou pelo rowNumber visível (forneça exatamente um). | GET …/row/{rowId} ou GET …/row-number/{rowNumber} |
create_row | Cria uma linha a partir de células { columnId, value }; description legada opcional. | POST /board/{boardId}/table/{tableId}/row |
update_row | Atualiza valores de células de uma linha existente por rowId (não edita texto longo). | PATCH …/row/{rowId} |
delete_row | Exclui permanentemente uma linha por rowId. Sem desfazer. | DELETE …/row/{rowId} |
get_row_markdown | Lê markdown de texto longo: a descrição legada da linha, ou uma célula de coluna RICH TEXT se columnId for fornecido. | GET …/row/{rowId}/md ou …/column/{columnId}/md |
set_row_markdown | Escreve markdown (replace/append/prepend) na descrição legada ou em uma célula de coluna RICH TEXT. Assíncrono (HTTP 202). | POST …/row/{rowId}/md ou …/column/{columnId}/md |
Busca
Escopo: nível de workspace (resultados filtrados pelas permissões do token).
| Ferramenta | Descrição | Capacidade da Public API |
|---|---|---|
search | Busca full-text entre entidades em documentos, channels, mensagens, todos, arquivos do drive, transcrições de voz e chats de IA. Restrinja com types. | GET /search/ |
Docs
Escopo: access_docs (documentos são exclusivos de PAT).
| Ferramenta | Descrição | Capacidade da Public API |
|---|---|---|
search_docs | Busca full-text em documentos com hits ranqueados e destaques. | GET /docs/search |
get_docs_tree | Navega na hierarquia de documentos; omita parentId para a raiz, limite com depth. | GET /docs/tree |
get_doc | Metadados do documento (título, ícone, capa, dono, pai, timestamps) por docId. | GET /docs/{docId} |
get_doc_content | Corpo markdown completo de um documento por docId (pode ser grande). | GET /docs/{docId}/md |
create_doc | Cria um documento com um title, parentId opcional e content inicial. | POST /docs/ |
set_doc_content | Escreve markdown (replace/append/prepend) no corpo de um documento. Exige acesso de edição (admin/member, incluindo compartilhamentos via time); 403 se o chamador consegue ver o doc mas não pode editá-lo. Assíncrono (HTTP 202). | POST /docs/{docId}/md |
update_doc_metadata | Atualiza o title, icon e/ou cover de um documento (não o corpo). | PATCH /docs/{docId} |
delete_doc | Exclui um documento por docId (apenas o dono). Sem desfazer. | DELETE /docs/{docId} |
Notificações
Escopo: access_notifications (para o próprio usuário do token).
| Ferramenta | Descrição | Capacidade da Public API |
|---|---|---|
list_notifications | Lista as notificações do usuário do token com unreadCount; paginado por cursor de id (after/before). | GET /notifications/ |
update_notification | Marca uma notificação como read ou unread por notificationId. | PATCH /notifications/{notificationId} |
delete_notification | Exclui uma notificação por notificationId. Sem desfazer. | DELETE /notifications/{notificationId} |
Chat
Escopo: access_channels.
| Ferramenta | Descrição | Capacidade da Public API |
|---|---|---|
list_channels | Lista channels e conversas de DM; filtra por query/type/kind/participantId; paginado por offset. | GET /chat/channels |
send_message | Envia uma mensagem para um channel (channelId) ou manda mensagem direta a um usuário (userId) — exatamente um. | POST /chat/channel/{channelId}/send-message ou POST /chat/direct-message/send-message |
Comentário
Escopo: access_boards. Comentários de linha e referências de anexos.
| Ferramenta | Descrição | Capacidade da Public API |
|---|---|---|
list_row_comments | Lista os comentários de uma linha (mais recentes primeiro) com metadados de autor e anexos; paginado por cursor; filtro de visibility. | GET …/row/{rowId}/comments |
add_row_comment | Adiciona um comentário a uma linha; visibility é internal (padrão) ou external. | POST …/row/{rowId}/comment |
get_row_attachment_url | Resolve uma downloadUrl autenticada para um anexo de coluna FILE ou de comentário (sem retornar bytes). | …/column/{columnId}/file/{fileId}/download ou …/comment/{commentId}/file/{fileId}/download |
Drive
Escopo: access_drive (o drive é exclusivo de PAT).
| Ferramenta | Descrição | Capacidade da Public API |
|---|---|---|
get_drive_tree | Navega no drive como uma árvore aninhada de arquivos/pastas; limitada por depth, com aprofundamento em caso de truncamento. | GET /drive/tree |
search_drive | Busca full-text em arquivos e pastas do drive. | GET /drive/search |
get_drive_item | Metadados de um único arquivo ou pasta por fileId. | GET /drive/files/{fileId} |
get_drive_download_url | URL de download CloudFront pré-assinada e com tempo limitado para um arquivo (sem necessidade de autenticação para baixar). | GET /drive/files/{fileId}/download |
create_drive_folder | Cria uma pasta na raiz ou sob um parentId. | POST /drive/folders |
Exportação
Escopo: access_boards.
| Ferramenta | Descrição | Capacidade da Public API |
|---|---|---|
export_table | Renderiza uma view de tabela para CSV/XLSX/JSON/MARKDOWN/HTML/PDF/ZIP/ICS; inline ou enfileirado; saveToDrive para exportações grandes/binárias. | POST /board/{boardId}/table/{tableId}/export |
Artefatos
Escopo: access_drive, e seu workspace precisa ter Artefatos disponíveis. Leia e edite os apps, dashboards e páginas que as pessoas criam na Copera — e entregue-os a um agente de código.
| Ferramenta | Descrição | Capacidade da Public API |
|---|---|---|
get_artifact_handoff | A única chamada para construir a partir de um artefato. Retorna o link do artefato, a versão, a Spec, as notas, o design compartilhado (diretrizes, tokens, componentes e assets com links de download de curta duração), cada página (superfície, viewport, arquivo de entrada e os arquivos que ela carrega), os links entre páginas e os arquivos de código. versionId e maxInlineBytes opcionais. | GET /artifacts/{artifactId}/handoff |
list_artifacts | Lista os artefatos que você pode abrir; scope é mine ou shared, search opcional, paginado por cursor (after, limit até 50). | GET /artifacts/ |
get_artifact | A versão atual do artefato: páginas, design compartilhado, assets, a lista de arquivos com digests SHA-256 e o preview. Leia o conteúdo dos arquivos com read_artifact_source. | GET /artifacts/{artifactId} |
list_artifact_versions | O histórico de versões do artefato; paginado por cursor (after, limit até 50). | GET /artifacts/{artifactId}/versions |
get_artifact_version | Páginas, design compartilhado e lista de arquivos de uma versão (versionId). Uma versão nunca muda depois de salva. | GET …/versions/{versionId} |
read_artifact_source | Lê um arquivo de código (path) de uma versão em blocos limitados. Continue com o nextCursor retornado até eof ser true. | GET …/versions/{versionId}/source |
get_artifact_page_preview | Preview de uma página (pageId) de uma versão. | GET …/versions/{versionId}/pages/{pageId}/preview |
get_artifact_design_snapshot | Uma cópia reutilizável do design compartilhado de uma versão (diretrizes, tokens, componentes, assets) com seu digest — passe-a para create_artifact como reuseDesign. | GET …/versions/{versionId}/design |
list_artifact_design_starters | Os design starters curados (como shadcn-core-v1) e suas dependências fixadas. | GET /artifacts/starters |
list_artifact_assets | Logos, fontes, imagens e referências adicionados ao design do artefato. | GET /artifacts/{artifactId}/design-assets |
import_artifact_asset | Adiciona um arquivo que você enviou (fileId) ao design do artefato como logo, font, image ou reference, com altText opcional. Coloque-o em uma página com patch_artifact_source. | POST /artifacts/{artifactId}/design-assets |
patch_artifact_source | Edita arquivos de código sobre baseVersionId com operações replace_text, put_file e delete_file (até 32 arquivos), cada uma conferida contra o SHA-256 atual do arquivo. Enfileirado — consulte get_artifact_request. | POST /artifacts/{artifactId}/source-patches |
list_artifact_requests | Pedidos de edição recentes no artefato, com o status e a versão que cada um gerou. | GET /artifacts/{artifactId}/requests |
get_artifact_request | Status de um pedido de edição (requestId) e a versão exata que ele gerou. | GET /artifacts/{artifactId}/requests/{requestId} |
create_artifact | Cria um artefato privado a partir do seu próprio projeto de código (static_web ou vite_react), com um title, um request descrevendo para que ele serve e uma idempotencyKey. Opcionalmente comece de um design starter (designStarterId) ou reutilize um design (reuseDesign) — um ou outro. | POST /artifacts/ |
get_artifact_handoff é tudo de que um agente de código precisa. Percorra o resultado em ordem: leia a Spec, depois as notas, depois configure o design, depois construa cada página a partir dos seus arquivos e, por fim, conecte os links entre as páginas — e siga os nextSteps retornados. Omita versionId para obter a versão mais recente que foi construída com sucesso. O conteúdo dos arquivos vem embutido até maxInlineBytes (32 KiB por padrão, até 1 MiB se o seu cliente aceitar resultados grandes); arquivos marcados com omitted: "over_budget" são lidos com read_artifact_source usando o id de versão retornado. Veja Construa com seu agente de código para a configuração.
Notas de comportamento
set_row_markdown e set_doc_content são enfileiradas (HTTP 202) — releia com get_row_markdown / get_doc_content para confirmar que a mudança foi aplicada. Envios para channels são síncronos; mensagens diretas são enfileiradas e podem não aparecer imediatamente.
patch_artifact_source e create_artifact retornam um recibo, não um build concluído. Depois de um patch, consulte get_artifact_request até o pedido ser concluído ou falhar e então leia a versão gerada; depois de um create, leia o artefato retornado e seu preview. Reutilize uma idempotencyKey apenas para repetir o pedido idêntico. Se um arquivo mudou desde que você o leu, a edição falha com um conflito — leia de novo e tente outra vez.
delete_row, delete_doc e delete_notification removem dados permanentemente. Confirme o id de destino antes de chamá-las.
Nenhuma ferramenta jamais retorna bytes brutos de arquivo. get_drive_download_url retorna uma URL pré-assinada que você pode baixar sem autenticação; get_row_attachment_url retorna uma downloadUrl autenticada que você mesmo baixa com seu token bearer.
Para o schema de requisição/resposta de cada endpoint subjacente, veja a Referência da API.