Tools

Todas as tools do servidor MCP do uPubly — schemas de input, outputs e exemplos.

Chamadas via tools/call no endpoint POST /mcp. Todas aceitam workspace_id opcional (uuid) — omitido usa o workspace default do usuário.

Publicações

post_accounts_list

Lista as contas de rede social conectadas — descobre o account_id para agendar.

{ "workspace_id": "opcional" }

→ { "accounts": [{ "account_id", "platform", "username" }] }

post_list

Lista posts (templates) com seus agendamentos.

{ "workspace_id": "?", "page": 0, "size": 20, "search": "opcional" }

post_create

Cria um post e, se schedules vier, já agenda a publicação. Sem schedules vira rascunho.

{
  "description": "Texto principal do post",
  "caption": "Legenda (opcional)",
  "name": "Nome interno (opcional)",
  "media": ["file_id_1", "file_id_2"],
  "schedules": [
    {
      "account_id": "uuid da conta (post_accounts_list)",
      "scheduled_at": "2026-09-25T14:00:00-03:00",
      "post_type": "feed|reels|story|video (inferido se omitido)"
    }
  ]
}

media recebe file_ids do Storage (ver storage_request_upload).

post_delete

{ "post_id": 123 }

Storage

O upload é presignado em 2 passos:

storage_request_upload

{
  "file_name": "banner.png",
  "content_type": "image/png (inferido se omitido)",
  "file_size": 1024,
  "folder_id": "opcional"
}

→ { "upload_url", "file_id", "upload_id", ... }. Faça PUT do binário na upload_url e depois confirme:

storage_complete_upload

{ "file_id": "...", "upload_id": "...", "parts": [{ "part_number": 1, "etag": "..." }] }

storage_usage

→ bytes usados vs limite do plano.

media_upload_from_url

Atalho de uma chamada: baixa uma imagem de URL pública http(s) e sobe no storage — devolve file_id (o media_id usado em refs/avatares/cenários)

  • file_url. Máx 20MB; acima disso ou bytes locais → caminho presignado.
{ "url": "https://.../imagem.png", "file_name": "opcional" }

Marca (brain)

Sempre leia brand_get antes de propor mudanças — ele devolve o estado completo (identidade, identidade visual, memória).

Nicho, público e posicionamento não ficam na identidade: moram no Manifesto (brand_manifest_update_section). Os campos mainNiche, secondaryNiches, primaryGoal e workspaceType do brand_get voltam vazios.

brand_update_identity

{ "brand_name": "...", "language": "pt-BR", "region": "...", "website": "...", "active_platforms": ["instagram"] }

brand_manifest_get

O Manifesto é o documento que diz quem a marca é, e é o que a IA lê ao gerar conteúdo. Sete seções: identity (o que é, nicho), audience (público), positioning (diferencial), what_we_argue (teses), voice (tom), limits (o que não fazer) e subjects (assuntos).

{ "sections": ["identity", "positioning"] }

Omita sections para ler todas.

brand_manifest_update_section

Grava uma versão nova de uma seção. O texto substitui o conteúdo vigente e o histórico fica. A versão sai marcada como escrita pela IA.

{ "section": "identity", "content": "texto completo da seção" }

brand_briefing_get / brand_briefing_update_block

Briefing (Mapa do Negócio). Blocos: objetivo_do_negocio, como_ganha_dinheiro, cliente, mercado, comercial, marketing. A escrita define o estado do bloco e acrescenta respostas:

{
  "block": "cliente",
  "state": "confirmed|inferred|unknown",
  "answers": [{ "text": "...", "kind": "fact", "confidence": "high" }]
}

brand_vocabulary_list / brand_vocabulary_upsert / brand_vocabulary_delete

Termos approved, dont_use (com replacement) e use_carefully. O upsert é em lote: com id atualiza, sem id cria.

{ "terms": [{ "term": "cliente", "category": "dont_use", "replacement": "parceiro" }] }

brand_update_visual_identity

{
  "primary_color": "#FF5500", "secondary_color": "...", "accent_color": "...",
  "font_display": "...", "font_body": "...", "tagline": "...",
  "logo_file_id": "file_id do storage"
}

brand_update_memory

Memória do criador — o que a IA aprendeu do estilo:

{
  "preferred_angles": ["..."], "weak_angles": ["..."],
  "preferred_cta": ["..."], "avoid_cta": ["..."],
  "avg_retention": 42.5, "content_stats": { "...": "livre" }
}

brand_add_document

Documento na base de conhecimento (RAG) — guia de marca, estratégia, manifesto, pesquisa:

{
  "document_type": "brand_guide|brand_voice|strategy|manifesto|market_research|script|report|reference|high_performance|low_performance",
  "title": "...",
  "content": "texto puro",
  "file_url": "URL de arquivo (storage)",
  "source_url": "opcional", "metadata": {}
}

brand_documents_list / brand_document_delete

Lista os documentos da base (limit, offset) e remove um pelo document_id. Os trechos indexados saem junto.

Billing

plans_list

→ { "plans": [...], "topup": { ... } } — planos ativos com preço mensal/anual em BRL, créditos mensais, dias de trial e os ciclos aceitos (billing_cycles).

  • Créditos do plano: Pro 8.000 por mês (até 3.000 para imagem, vídeo e voz); Max 20.000 por mês (até 8.000 para mídia). O Basic não tem créditos mensais.
  • Teste: 500 créditos em todos os planos, Basic incluído.
  • topup — as regras dos créditos avulsos: { "by_value": true, "currency": "BRL", "methods": { "pix": { "min_brl", "bonus_percent" }, "card": { "min_brl", "bonus_percent" } } }. O avulso é comprado por valor em R$, no app, pelo dono do workspace: a partir de R$ 10 no Pix e R$ 20 no cartão, com +3% de créditos no Pix. A tela de compra mostra quantos créditos o valor rende. Créditos avulsos não vencem e não têm limite de mídia. Não há link de avulso pelo MCP.

Cria o checkout (link de pagamento) para o usuário assinar um plano:

{ "plan_id": "id do plano (plans_list)", "billing_cycle": "monthly|yearly" }

→ { "checkout_url", "session_id" } — envie checkout_url ao cliente para ele concluir a assinatura. Preços sempre vêm do catálogo server-side — o agente nunca injeta valores.

credits_balance

Saldo de créditos do usuário — consulte antes de operações que debitam (jobs UGC, geração de avatar/cenário):

→ { "monthly_balance", "topup_balance", "total_balance", "monthly_allowance", "cycle_started_at", "cycle_ends_at", "plan_name", "member_limit", "scope", "media_cap", "media_used" }

  • monthly_balance — os créditos do plano. Renovam a cada ciclo.
  • topup_balance — os créditos avulsos. Não vencem.
  • media_cap / media_used — quanto dos créditos do plano pode ir para imagem, vídeo e voz no ciclo, e quanto já foi. null = sem limite. No Pro o limite é 3.000 créditos; no Max, 8.000. Passou do limite, a mídia sai dos créditos avulsos, que não têm limite de mídia.
  • member_limit — { "limit", "used", "resets_at" } quando o usuário tem um limite próprio no workspace. Com scope: "member" os saldos são o que sobra desse limite.

Detalhes e códigos de erro: UGC — Geração.

UGC (avatares, cenários, geração)

O namespace ugc_* — modelos, estimativa, jobs async, avatares, cenários, templates e projetos — tem referência própria: UGC — Geração · Avatares · Geração de vídeo.