Referência de ferramentas

list_scheduled_posts

Lista seus posts agendados (na fila para publicação, mas ainda não enviados).

Argumentos

Retorna

Um objeto com posts: [{id, platform, content, scheduledAt, status}]. Até limit resultados.

Exemplo

curl -X POST https://mcp.postnext.io/api \
  -H "Authorization: Bearer apikey_xxx" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","id":1,
       "params":{"name":"list_scheduled_posts",
                 "arguments":{"limit":5}}}'

list_drafts

Lista seus rascunhos (ainda não agendados).

Argumentos

Retorna

Um objeto com drafts: [{id, platform, content, updatedAt}]. Até limit resultados.

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":2,
 "params":{"name":"list_drafts","arguments":{"limit":10}}}

list_connected_accounts

Lista as contas sociais conectadas à sua equipe.

Argumentos

Sem argumentos.

Retorna

Um objeto com accounts: [{platform, handle, connected, lastSyncAt}].

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":3,
 "params":{"name":"list_connected_accounts","arguments":{}}}

get_account_healthPlano pago

Obtém um resumo de saúde em todas as plataformas conectadas.

Argumentos

Retorna

Um objeto com windowDays, postsScheduled, postsPublished, postsFailed, um detalhamento byPlatform e topErrors[].

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":4,
 "params":{"name":"get_account_health",
           "arguments":{"windowDays":30}}}

create_post_draft

Cria um novo rascunho. Rascunhos não são publicados automaticamente.

Argumentos

Retorna

Um objeto com o novo rascunho: {id, platform, content, status: "DRAFT", createdAt}.

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":5,
 "params":{"name":"create_post_draft",
           "arguments":{"platform":"twitter",
                        "content":"Hello from MCP"}}}

update_post_draft

Atualiza um rascunho existente. Pelo menos um dos campos content ou mediaUrls deve ser fornecido.

Argumentos

Retorna

Um objeto com o rascunho atualizado: {id, platform, content, mediaUrls, status, updatedAt}.

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":6,
 "params":{"name":"update_post_draft",
           "arguments":{"postId":"",
                        "content":"Updated copy"}}}

connect_channel

Gera uma URL de uso único que o usuário pode abrir para autorizar a conexão com uma nova plataforma.

Argumentos

Retorna

Um objeto com authUrl (link de uso único que o usuário abre para autorizar), expiresAt e platform.

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":7,
 "params":{"name":"connect_channel",
           "arguments":{"platform":"linkedin"}}}

schedule_post

Move um rascunho (status DRAFT) para a fila de publicação BullMQ em um timestamp futuro. Idempotente dentro de ±60s de drift; rejeita tentativas de reagendamento em outro horário sem cancelamento explícito.

Argumentos

Retorna

Um objeto com postId, scheduledAt (ISO), status: SCHEDULED.

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":8,
 "params":{"name":"schedule_post",
           "arguments":{"postId":"",
                        "scheduledAt":"2026-05-10T09:00:00Z"}}}

cancel_scheduled_post

Cancela uma publicação agendada e a remove da fila. O rascunho subjacente é preservado.

Argumentos

Retorna

Um objeto com postId e status: CANCELLED.

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":9,
 "params":{"name":"cancel_scheduled_post",
           "arguments":{"postId":""}}}

delete_draft

Exclui permanentemente um rascunho. Recusa publicações não-DRAFT (use cancel_scheduled_post para SCHEDULED).

Argumentos

Retorna

Um objeto com postId e deleted: true.

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":10,
 "params":{"name":"delete_draft",
           "arguments":{"postId":""}}}

get_post

Retorna o PostGroup completo para um postId com conteúdo por plataforma + status + timestamps.

Argumentos

Retorna

Um objeto com postId, status, scheduledAt, createdAt, updatedAt e providers (mapa plataforma → conteúdo).

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":11,
 "params":{"name":"get_post",
           "arguments":{"postId":""}}}

search_posts

Busca de substring (insensível a maiúsculas) no conteúdo de publicações da equipe ativa. Filtros: status, platform, limit (1-100, padrão 20).

Argumentos

Retorna

Um objeto com posts: [{postId, status, platforms, snippet, scheduledAt, updatedAt}]. O snippet contém o contexto correspondente com reticências em ambos os lados.

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":12,
 "params":{"name":"search_posts",
           "arguments":{"query":"launch","limit":10}}}

list_teams

Retorna as equipes que o usuário autenticado possui ou administra, com a equipe ativa marcada.

Argumentos

Sem argumentos.

Retorna

Um objeto com currentTeamId e teams: [{teamId, teamName, isCurrent}].

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":13,
 "params":{"name":"list_teams","arguments":{}}}

set_current_team

Troca a equipe ativa para este token Bearer. O usuário precisa ser membro. Persistido no documento do token OAuth; a mutação em sessão torna efetivo imediatamente para ferramentas seguintes na mesma conversa.

Argumentos

Retorna

Um objeto com teamId, teamName, persisted (true se OAuth, false se API key) e um note opcional.

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":14,
 "params":{"name":"set_current_team",
           "arguments":{"teamId":"team_xxxxx"}}}

get_plan_limits

Lê o nível de assinatura atual do usuário e as cotas por nível (canais, armazenamento, créditos de IA, publicação). Disponível em todos os planos. Útil antes de ferramentas mutadoras para prever se a chamada será bloqueada.

Argumentos

Sem argumentos.

Retorna

Um objeto com tier, tierDisplayName, isPaid, isTrial, upgradeUrl, limits (channels/storage/aiCalls/posts cada um como {limit, current, exceeded} ou {limit, allowed}) e creditsAvailable ({total, subscriptionRemaining, purchasedBalance} ou null).

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":15,
 "params":{"name":"get_plan_limits","arguments":{}}}

get_post_metrics

Busca métricas de engajamento de uma publicação publicada em cada plataforma para a qual foi enviada. Twitter e Instagram retornam métricas populadas (curtidas, retweets/compartilhamentos, comentários/respostas, impressões); LinkedIn, Threads e TikTok retornam apenas status de publicação e URL (a coleta de engajamento foi adiada para uma versão posterior). Um resumo normalizado totals soma curtidas/comentários/compartilhamentos/impressões das plataformas que reportaram.

Argumentos

postId ID do post no PostNext obtido em uma chamada de listagem.

Retorna

Um objeto com postId, status, providers: [{platform, publishedPostId, publishedUrl, publishedAt, status, metrics}] e totals: {likes, comments, shares, impressions}. metrics é um objeto de contadores numéricos por plataforma, ou null quando a plataforma ainda não coleta engajamento.

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":16,
 "params":{"name":"get_post_metrics",
           "arguments":{"postId":""}}}

get_publish_status

Diagnostica uma publicação agendada: status da fila, sucesso/erro por plataforma, tempo de processamento e jobId do worker. Retorna isScheduled=false para publicações que existem como rascunho mas não foram movidas para a fila, com um hint apontando para schedule_post.

Argumentos

postId ID do post no PostNext obtido em uma chamada de listagem.

Retorna

Um objeto com postId, isScheduled, status, scheduledAt, publishedAt, platforms, processingTimeMs, jobId, topLevelError e results: [{platform, success, publishedPostId, publishedAt, error}]. Inclui hint quando isScheduled é false.

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":17,
 "params":{"name":"get_publish_status",
           "arguments":{"postId":""}}}

update_brand_profile

Atualiza o perfil de marca ativo do usuário. Campos permitidos: bio, brandVoice, personalityTraits, mainThemes, expertiseAreas, preferredHashtags, audienceSize. Qualquer outro campo é descartado silenciosamente. Resolve "ativo" primeiro como default da equipe, depois o primeiro perfil ativo próprio do usuário.

Argumentos

brandVoice Array de descritores de voz de marca (ex. ["profissional", "conciso"]).

Other patchable fields: bio, personalityTraits, mainThemes, expertiseAreas, preferredHashtags, audienceSize.

Retorna

Um objeto com profileId, name, updated: [nomes dos campos patchados] e os valores atuais de bio, brandVoice, personalityTraits, mainThemes, expertiseAreas, preferredHashtags, audienceSize após o patch.

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":18,
 "params":{"name":"update_brand_profile",
           "arguments":{"brandVoice":["professional","concise"]}}}

get_best_time_to_post Plano pago

Recomenda os melhores N slots (diaDaSemana, hora) para a próxima publicação em uma plataforma, ordenados por engajamento por publicação dos últimos 90 dias. Twitter e Instagram retornam scores ponderados por engajamento; LinkedIn, Threads, TikTok ordenam apenas por frequência. Horários no fuso IANA informado (UTC por padrão). Plano pago obrigatório.

Argumentos

platform Plataforma social: twitter, instagram, linkedin, threads ou tiktok.

timezone Nome do fuso horário IANA (ex. America/Sao_Paulo, Europe/London). Padrão UTC.

topN Número de recomendações de slots a retornar (1-24, padrão 5).

Retorna

Um objeto com platform, timezone, sampleWindowDays, sampleSize, metricsAvailable e recommendations: [{dayOfWeek (1-7, Seg=1), dayLabel, hour (0-23), score, basedOn: {posts, avgEngagement}}]. Inclui hint para casos cold-start ou sem métricas disponíveis.

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":19,
 "params":{"name":"get_best_time_to_post",
           "arguments":{"platform":"twitter","timezone":"Europe/Berlin","topN":5}}}

search_tools

Pesquisa o catálogo de ferramentas MCP por texto livre, categoria ou intenção. Retorna categorias, requiresScope, descrições de uma linha e os tags de caso de uso que corresponderam. Disponível em qualquer plano (superfície de descoberta).

Argumentos

All optional. Call with no arguments to list every available tool.

query Busca de texto livre em nomes, descrições e tags de uso das ferramentas.

category Filtra para uma categoria: posts, accounts, analytics, brand, teams, discovery, other.

Retorna

Um objeto com totalTools, matchCount, categories: [string[]] e tools: [{name, category, requiresScope, description, useCases, matchedOn: [name|category|description|use_case]}]. Inclui hint quando não há correspondência ou não há filtro.

Exemplo

{"jsonrpc":"2.0","method":"tools/call","id":20,
 "params":{"name":"search_tools",
           "arguments":{"query":"why did my post fail"}}}