# ViralRecast

> Os olhos e ouvidos das redes sociais, orgânicas e pagas: lê qualquer post (transcrição, slides, comentários, métricas, Viral Score), descobre o que está em alta por tema, analisa anúncios de concorrentes e gera cortes de vídeo.

Documentação para humanos: https://viralrecast.com/docs

## Como chamar

- Endpoint único: POST https://viralrecast.com/mcp (JSON-RPC 2.0; é um servidor MCP, então clientes MCP conectam direto).
- Autenticação: header `Authorization: Bearer vr_...` (chave em https://viralrecast.com/connect) ou OAuth 2.1.
- Rodar uma tool: `{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"<tool>","arguments":{...}}}`.
- Resultado em `result.structuredContent` (JSON) e `result.content[0].text`. Falha da tool: `result.isError: true` com a mensagem em `result.content[0].text` (créditos estornados).
- Limite: 120 chamadas por minuto por conta (HTTP 429 acima disso). Use timeout de 120 s.
- Jobs de mídia devolvem `job_id`; consulte `get_job` até `status` = completed. Arquivos saem como links https://viralrecast.com/files/... (aceitam Range e `?download=1`).

## Problemas de conexão

- Cliente MCP mostra "InvalidHTTPResponse", "Failed" ou "Error POSTing to endpoint", mas a URL abre no navegador: quase sempre é antivírus com inspeção de HTTPS (Norton, Kaspersky, Avast, AVG, ESET, Bitdefender) ou proxy corporativo alterando a resposta no computador do usuário.
- Solução: adicionar viralrecast.com às exceções da verificação de SSL/TLS do antivírus (no Norton: Segurança → Proteção do agente de inteligência artificial → Configurações → desligar "Monitoramento da web", que inclui a "Varredura de servidores MCP") e reconectar o servidor MCP.
- Teste: `curl -i -X POST https://viralrecast.com/mcp` deve responder HTTP 401 com JSON. Certificado emitido pelo antivírus, e não por Let's Encrypt, confirma a inspeção.
- No claude.ai e no ChatGPT isso não acontece: a conexão sai da nuvem.
- Detalhes: https://viralrecast.com/docs#conexao

## Tools

### read_post

Lê qualquer post pelo link (TikTok, Instagram reel/carrossel/foto, YouTube, X, Threads, LinkedIn, Reddit) e devolve o conteúdo inteiro para você analisar: transcrição com tempos (da própria rede ou, se ela não legendou, transcrição automática do áudio), as imagens do carrossel (como imagens, para você ver) e o texto escrito em cada slide, comentários mais curtidos, métricas, resumo, pontos-chave, mapa mental e o Viral Score (quão fora da curva o post foi para o tamanho do autor). Use sempre que o usuário colar um link ou pedir para resumir, entender, estudar ou comparar um post. Grava no histórico do usuário.

Custo: Custa 20 créditos (2 se o post já foi lido nas últimas 6 horas).

Argumentos:
- `url` (string, obrigatório): Link do post
- `niche` (string): Tema/nicho de referência do usuário, para a nota de encaixe (fit)
- `include_images` (boolean): Devolver as imagens do carrossel (padrão true)

Exemplo: `{"url":"https://www.youtube.com/watch?v=KvLWuK2TU-w","include_images":false}`

### my_history

As consultas recentes do usuário no ViralRecast (painel, Claude, ChatGPT), com o Viral Score de cada post.

Custo: Grátis.

Argumentos:
- `limit` (integer): Quantas (padrão 15)

Exemplo: `{"limit":10}`

### similar_content

Conteúdos parecidos com um post já lido, na memória coletiva do ViralRecast (tudo o que já foi consultado na plataforma). Informe o content_id devolvido por read_post.

Custo: Custa 1 crédito.

Argumentos:
- `content_id` (integer, obrigatório): id do conteúdo (campo id de read_post)
- `limit` (integer)

Exemplo: `{"content_id":73,"limit":5}`

### search_viral_content

Busca posts em alta sobre um tema e ranqueia pelo trend_score (alcance + engajamento + viralidade relativa ao tamanho do criador). Redes: tiktok, instagram (Reels), youtube, x, threads, reddit e instagram_carousel (carrosséis e fotos do Instagram). Sem platforms busca em tiktok, instagram, youtube e x. Use instagram_carousel quando o usuário pedir carrossel/foto, reddit ou threads quando pedir discussão/texto.

Custo: Custa 4 créditos por rede; x custa 8 e instagram_carousel custa 100 (descobre autores pela hashtag e lê a grade deles).

Argumentos:
- `query` (string, obrigatório): Tema ou palavra-chave, ex.: "marketing para dentistas"
- `platforms` (string[]: tiktok | instagram | youtube | x | threads | reddit | instagram_carousel): Redes (padrão: tiktok, instagram, youtube, x)
- `period` (string: day | week | month | all): Janela de tempo (padrão week)
- `limit` (integer): Máximo de resultados (padrão 10)
- `region` (string): País, ISO-3166 (BR, US, PT...): filtra o TikTok por país e o X por idioma (BR = português). Omita para global. Use BR quando o usuário falar português e quiser o mercado brasileiro
- `min_followers` (integer): Só criadores com pelo menos N seguidores
- `max_followers` (integer): Só criadores com até N seguidores. Use quando o usuário pedir perfis pequenos, micro-criadores ou prospecção (ex.: 10000). Os resultados trazem author.followers verificado; não chame analyze_creator só para conferir seguidores.

Exemplo: `{"query":"receitas fit","platforms":["tiktok","instagram"],"region":"BR","limit":10}`

### search_mentions

Use para monitorar menções a uma marca, concorrente, produto ou tema: o que as pessoas estão dizendo, com o mais novo primeiro. Diferente de search_viral_content, que busca o que está em alta e ordena por alcance, aqui o termo é buscado como frase exata e só volta o que cita o termo no texto ou no título (comentários, reclamações, comparações, pedidos de indicação). Redes: reddit (posts e comentários; comentários são o principal sinal), x (posts e respostas) e youtube (vídeos; comentários do YouTube não são pesquisáveis por termo). linkedin ainda não tem busca confiável e volta em errors, sem custo. Cada resultado traz rede, tipo (post ou comment), link, texto, título do post (num comentário, o do post-pai), comunidade, data, pontuação e respostas; nunca traz o autor. Só planos pagos (no Free a tool responde com o link de upgrade).

Custo: Custa 5 créditos por página de resultados consultada no Reddit e no YouTube e 10 por página no X; cobra só as páginas que responderam (o padrão, Reddit com posts e comentários e limit 25, custa de 10 a 25).

Argumentos:
- `query` (string, obrigatório): Termo exato a monitorar, ex.: "SendGrid" ou "Acme Mail". Aspas internas são aceitas: cada trecho entre aspas e cada palavra solta precisam aparecer (ex.: "Acme Mail" suspensa)
- `platforms` (string[]: reddit | x | youtube | linkedin): Redes (padrão: reddit)
- `kind` (string: posts | comments | both): posts, comments (no X, respostas) ou both (padrão both)
- `period` (string: day | week | month | year): Janela de tempo (padrão week)
- `sort` (string: new | relevance): new = mais novo primeiro (padrão); relevance = ordem de relevância de cada rede
- `language` (string: pt | en | any): pt, en ou any (padrão any). Onde a rede não filtra, usa detecção simples do idioma do texto
- `limit` (integer): Máximo de resultados (padrão 25)

Exemplo: `{"query":"SendGrid","platforms":["reddit"],"kind":"comments","period":"week","sort":"new","language":"any","limit":25}`

### search_ads

Anúncios ativos sobre um tema nas bibliotecas públicas do Meta (Facebook e Instagram), TikTok e LinkedIn: texto, título, CTA, página de destino, formato, onde roda, há quantos dias está no ar e quantas variações tem. Ordena pelos sinais de anúncio vencedor (quem paga não mantém no ar o que não converte: 30+ dias ou 3+ variações = forte). Use para 'o que está em alta nos anúncios de X', pesquisa de criativos e ofertas.

Custo: Custa 4 créditos por rede.

Argumentos:
- `query` (string, obrigatório): Tema, produto ou palavra-chave, ex.: "curso de inglês", "skincare"
- `platforms` (string[]: meta | tiktok | linkedin): Padrão: meta
- `country` (string): País ISO-3166 (BR, US...) ou ALL. Padrão BR (vale para Meta e LinkedIn)
- `media` (string: ALL | VIDEO | IMAGE): Só Meta. Padrão ALL
- `limit` (integer)

Exemplo: `{"query":"curso de inglês","platforms":["meta"],"country":"BR","limit":10}`

### advertiser_ads

Todos os anúncios ativos de uma marca ou concorrente no Meta, Google (Pesquisa, YouTube, Display), LinkedIn e TikTok, com o resumo por rede: quantos anúncios, formatos e o mais antigo no ar. Aceita o nome da empresa, o site (ex.: reportei.com, o mais preciso) ou o id de uma página do Meta ou de um anunciante do Google. Cada rede devolve matched (a empresa consultada e como foi achada) e alternatives (outras com nome parecido): se não for a empresa certa, avise o usuário e chame de novo com o id da alternativa.

Custo: Custa 8 créditos no Meta, 8 no Google pelo site ou id (12 pelo nome) e 4 no LinkedIn e no TikTok.

Argumentos:
- `advertiser` (string, obrigatório): Site (ex.: opus.pro), nome da empresa/página ou id de uma alternativa devolvida antes
- `platforms` (string[]: meta | google | linkedin | tiktok): Padrão: meta e google
- `country` (string): País ISO-3166 ou ALL. Padrão BR
- `limit` (integer)

Exemplo: `{"advertiser":"reportei.com","platforms":["meta","google"]}`

### read_ad

Criativo completo de um anúncio pelo link da biblioteca (Meta: facebook.com/ads/library?id=...; Google: adstransparency.google.com; LinkedIn: linkedin.com/ad-library; TikTok: library.tiktok.com): textos de todas as versões, CTA, destino, dias no ar e a transcrição do vídeo (Meta). Use para destrinchar gancho, roteiro e oferta.

Custo: Custa 10 créditos.

Argumentos:
- `url` (string, obrigatório): Link do anúncio na biblioteca (ou o ID do anúncio do Meta)

Exemplo: `{"url":"https://www.facebook.com/ads/library?id=688654197622766"}`

### trending_now

Vídeos em alta agora, sem tema: feed de tendências do TikTok ou Shorts em alta do YouTube.

Custo: Custa 4 créditos.

Argumentos:
- `platform` (string: tiktok | youtube): Padrão tiktok
- `region` (string): País (ISO-3166 alpha-2) para o TikTok, ex.: BR, US. Padrão BR
- `limit` (integer)

Exemplo: `{"platform":"tiktok","region":"BR","limit":15}`

### analyze_creator

Perfil de um criador com médias e os posts que mais furaram a bolha em relação à própria média.

Custo: Custa 8 créditos.

Argumentos:
- `platform` (string: tiktok | instagram | youtube | twitter, obrigatório)
- `handle` (string, obrigatório): @ do criador, com ou sem @
- `limit` (integer): Quantos posts devolver (padrão 12)

Exemplo: `{"platform":"instagram","handle":"@nasa","limit":12}`

### find_similar_posts

Busca por similaridade na base de posts virais já indexados. Útil para validar uma ideia de post.

Custo: Custa 1 crédito.

Argumentos:
- `text` (string, obrigatório): Ideia, roteiro ou legenda
- `platform` (string)
- `limit` (integer)

Exemplo: `{"text":"3 erros que todo iniciante comete na academia","limit":5}`

### download_video

Baixa o vídeo de um link (YouTube, TikTok sem marca d'água, Instagram, X, Facebook) e devolve um link de download. Use só para conteúdo próprio, licenciado ou para referência interna.

Custo: Custa 10 créditos (estornados se falhar).

Argumentos:
- `url` (string, obrigatório): Link do vídeo

Exemplo: `{"url":"https://www.youtube.com/watch?v=KvLWuK2TU-w"}`

### transcribe_video

Transcrição completa de um vídeo por link, com links de SRT/VTT.

Custo: Custa 8 créditos + 4 por minuto de vídeo (estornados se falhar).

Argumentos:
- `url` (string, obrigatório): Link do vídeo
- `language` (string): ISO-639-1; vazio = automático

Exemplo: `{"url":"https://www.youtube.com/watch?v=KvLWuK2TU-w","language":"en"}`

### create_clips

Transforma um vídeo longo em cortes verticais prontos para postar, com legenda, título, gancho e hashtags. Informe url OU job_id de um download já feito. Leva de 1 a 5 minutos: a tool devolve um job_id; consulte com get_job. Use em conteúdo próprio ou licenciado.

Custo: Custa 100 créditos + 4 por minuto de vídeo, limite de 180 min (estornados se falhar).

Argumentos:
- `url` (string): Link do vídeo
- `job_id` (string): ID de um job de download concluído
- `clip_count` (integer): Quantos cortes (padrão 5)
- `min_seconds` (integer): Duração mínima de cada corte (padrão 20)
- `max_seconds` (integer): Duração máxima de cada corte (padrão 60)
- `orientation` (string: vertical | horizontal | square | original): Formato de saída (padrão vertical 9:16)
- `captions` (boolean): Queimar legendas palavra por palavra (padrão true)
- `language` (string): Idioma do áudio, ISO-639-1 (pt, en, es). Vazio = automático

Exemplo: `{"url":"https://www.youtube.com/watch?v=KvLWuK2TU-w","clip_count":3,"orientation":"vertical"}`

### get_job

Status e resultado de um job de download, transcrição ou cortes.

Custo: Grátis.

Argumentos:
- `job_id` (string, obrigatório): ID do job

Exemplo: `{"job_id":"e8ab6df8-8456-4661-a285-fdd73f5ed504"}`

### list_jobs

Últimos jobs de mídia do usuário.

Custo: Grátis.

Argumentos:
- `limit` (integer)

Exemplo: `{"limit":10}`

### get_account

Plano, créditos restantes e a tabela de preço de cada tool.

Custo: Grátis.

Exemplo: `{}`