@titanos/mcp-agents

Model Context Protocol (MCP) server pra orquestrar ferramentas do Titanos em clientes externos como Claude Code, Cursor, Hermes, OpenClaw e qualquer outro cliente MCP.

Ele expõe geração de listing (Super Listing Power + Creative), lookup de produto Amazon, mineração de produtos Amazon multi-país, top vendidos, oportunidades de private label e descoberta de categorias já filtradas para a árvore visual do Titanos.

⚡ Quick Start

{
  "mcpServers": {
    "titanos-agents": {
      "command": "npx",
      "args": ["-y", "@titanos/mcp-agents@1"],
      "env": {
        "TITANOS_API_KEY": "tnk_live_xxxxxxxxxxxx",
        "TITANOS_API_URL": "https://www.titanos.com.br"
      }
    }
  }
}

Cole no arquivo de config do seu cliente MCP (Claude Desktop, Cursor, etc) e reinicie.

📋 Pré-requisitos

• Conta Titanos com plano Scale ou superior (hierarchy_level >= 30)
• API Key gerada em /conta/configuracoes → aba MCP / API
• Node.js 20+

🛠️ Tools expostas

invoke_listing_power

Dispara o agente Super Listing Power. Gera título, bullets, descrição, keywords backend, imagens de listing + A+. Retorna request_id em ~1s; use wait_for_result ou get_result pra resultado final (3-15 min).

Input:

{
  source: "manual" | "amazon_url",
  produto?: { nome: string, descricao: string },  // se source=manual
  amazon_url?: string,                             // se source=amazon_url
  imagens?: string[],                              // URLs HTTPS, máx 4
  gerar_imagens?: boolean,
  gerar_aplus?: boolean,
  gerar_mineracao?: boolean,
  gerar_mercado_livre?: boolean,
  modelo_texto?: TextModelPreset,
  modelo_imagem?: ImageModelPreset,
  aplus_quality?: "low" | "medium" | "high",
  aplus_resolution?: "2K" | "4K",
  aplus_num_imagens?: 1 | 2 | 3 | 4,
  pais?: "brasil" | "estados_unidos" | "espanha" | "reino_unido" | "alemanha" | "franca" | "japao" | "canada" | "italia" | "india" | "mexico" | "australia",
  idempotency_key?: string,                        // recomendado
}

Custo: 4-30 créditos (dinâmico por flags + modelo).

invoke_listing_creative

Análogo ao Power, mas com brief psicográfico + copy estruturada + plano de imagem cinematográfico. Admin only atualmente.

get_result

Polla resultado por request_id. Não-bloqueante. Retorna status processando | concluido | concluido_parcial | erro.

wait_for_result

Bloqueia até resultado pronto (default 300s, max 600s). Polling interno adaptativo (5s → 15s).

lookup_amazon_product

Lookup de dados de produto Amazon (título, preço, ranking, categorias, imagens, histórico). Cache hit grátis, cache miss cobra 1 crédito (mcp_amazon_lookup).

find_categories

Descobre IDs de categorias Amazon por termo e pais. Use antes das tools de mineração quando você souber o nicho, mas não souber o categoria_id.

O retorno já vem sem wrappers internos e inclui breadcrumb, categoria_final e usar_em_busca. Para o agente, a regra é: prefira categoria_final: true e repasse usar_em_busca para a próxima tool.

Input:

{
  "pais": "brasil",
  "termo": "pet",
  "limite": 10,
  "somente_visiveis": true,
  "incluir_arvore": true
}

Custo: gratuito.

search_products

Busca produtos para vender na Amazon usando presets ou filtros granulares. Suporta Brasil, Estados Unidos, Espanha e demais paises aceitos pelo campo pais. Cada produto retornado com incluir_detalhes: true inclui score_oportunidade, classificacao, motivos_recomendacao e alertas_risco para a IA explicar as recomendações.

Input:

{
  "pais": "espanha",
  "palavra_chave": "cafetera italiana acero",
  "categoria_id": 123456,
  "categoria_modo": "final",
  "preset": "hot_picks",
  "preco_min": 20,
  "preco_max": 90,
  "marcas": ["Bialetti"],
  "cadastrado_ultimos_dias": 45,
  "tem_a_plus": false,
  "produto_adulto": false,
  "produtos_genericos": true,
  "tem_avaliacoes": true,
  "avaliacoes_min": 10,
  "avaliacoes_max": 500,
  "rating_min": 3.8,
  "rating_max": 4.8,
  "buy_box_amazon": false,
  "buy_box_fba": true,
  "buy_box_desqualificado": false,
  "disponibilidade_amazon": "sem_oferta",
  "ordenar_por": "vendas_desc",
  "limite": 20,
  "incluir_detalhes": true,
  "idempotency_key": "busca-hot-picks-200-2026-05-11"
}

Presets disponíveis: hot_picks, low_competition, rising_stars, amazon_absent.

Filtros principais: palavra_chave, categoria_id, preco_min/preco_max, bsr_max, marcas, marca_exclui, vendas_mensais_min/max, tem_avaliacoes, avaliacoes_min/max, rating_min/max, buy_box_amazon, buy_box_fba, buy_box_desqualificado, disponibilidade_amazon, tem_a_plus, produto_adulto, produtos_genericos, cadastrado_ultimos_dias, peso_max_kg e ordenar_por.

Use produtos_genericos: true quando quiser procurar produtos sem marca forte. O Titanos aplica internamente as variações de marca generic, generico, genérico, genérica, genericos, genérico2 e genéric.

Custo: 1 crédito sem detalhes, 3 créditos com incluir_detalhes: true.

get_best_sellers

Retorna os produtos mais vendidos de uma categoria Amazon no marketplace escolhido. Use para perguntas de ranking, líderes de categoria e validação de demanda.

Input:

{
  "pais": "brasil",
  "categoria_id": 7841837011,
  "periodo": "atual",
  "limite": 30
}

Custo: 1 crédito sem detalhes, 3 créditos com incluir_detalhes: true.

find_private_label_opportunities

Encontra oportunidades de private label com demanda mínima, concorrência menor, limite de reviews e filtro de peso. Use para sugerir produtos de marca própria ou importação.

Input:

{
  "pais": "brasil",
  "categoria_id": 6740748011,
  "categoria_modo": "final",
  "produtos_genericos": true,
  "preco_min": 30,
  "preco_max": 200,
  "vendas_mensais_min": 100,
  "peso_max_kg": 1,
  "limite": 30
}

Custo: 3 créditos por busca.

📚 Resources MCP

O servidor também expõe resources de auto-documentação:

• titanos://mining/presets — quando usar cada preset.
• titanos://mining/filters — cheat sheet dos filtros públicos.
• titanos://mining/recipes — fluxos completos para produtos quentes, baixa concorrência, private label e top vendidos.
• titanos://mining/categories/br — orientação para escolher a ramificação final correta.

Exemplo de fluxo:

1. Leia titanos://mining/recipes.
2. Use find_categories({ "pais": "brasil", "termo": "cosmetico", "incluir_arvore": true, "somente_visiveis": true }).
3. Escolha uma categoria com categoria_final=true.
4. Use find_private_label_opportunities({ "pais": "brasil", "categoria_id": 123, "categoria_modo": "final", "produtos_genericos": true, "peso_max_kg": 1 }).

📦 Shape do resultado (Listing Power / Creative)

Quando status: "concluido" ou "concluido_parcial", o resultado é enxuto por design — só os campos necessários pra publicar/usar o listing. Internals do pipeline (competidores analisados, mineração de público, mercado livre interno, creative brief etc) ficam no DB e não vazam pelo wire MCP.

{
  schema_version: "1.0",
  titulo: string,                     // 1 só, mesmo se pipeline gerou 5 opções
  bullet_points: string[],
  descricao: string,
  keywords_backend: string[],         // pra Amazon Seller Central
  marketplace_fields: Record<string, unknown>,  // sanitizado, sem chaves internas do pipeline
  imagens_listing: string[],          // URLs HTTPS
  imagens_aplus: string[],            // URLs HTTPS
  parcial: boolean,                   // true se concluido_parcial
  alertas: string[],                  // avisos do pipeline
  custo_creditos_real: number,
  duracao_segundos: number,
}

🔐 Segurança

• API Keys formato tnk_live_* (32 chars prefix + 32 chars secret)
• Hash SHA-256 do plaintext no DB; plaintext mostrado uma única vez na criação
• Scopes granulares: agents:listing_power:invoke, agents:listing_creative:invoke, agents:read, amazon:lookup, mining:search
• Plan gating runtime: cada request valida Scale+ via requireMcpApiKey
• Idempotência atômica nos invokes assíncronos via INSERT ... ON CONFLICT; tools síncronas também enviam Idempotency-Key para retries
• Auto-suspend de keys em downgrade de plano (reativável em upgrade)
• Rate limit: 5 invokes/min/key + concurrency max 2 jobs/key, 3/user, 5/org
• SSRF guard em download de imagens (HTTPS only, IP allowlist, redirect manual, streaming cap)

🧪 Códigos de erro estáveis

INVALID_API_KEY       — key não encontrada ou prefix errado (401)
API_KEY_REVOKED       — revogada ou suspensa (401)
SCOPE_MISSING         — key não tem o scope necessário (403)
PLAN_ACCESS_REQUIRED  — plano < Scale (403)
ADMIN_REQUIRED        — Creative invoke sem isAdmin (403)
INSUFFICIENT_CREDITS  — saldo zerado (402)
VALIDATION_ERROR      — body fora do schema Zod (400)
IMAGE_FETCH_FAILED    — falha download/MIME/tamanho (400)
IMAGE_BLOCKED_PRIVATE_IP — SSRF guard tripou (400)
AMAZON_URL_INVALID    — URL fora do regex (400)
INVALID_FILTERS       — filtros de mineração ausentes ou incoerentes (400)
INVALID_CATEGORY      — categoria_id inexistente para o marketplace escolhido (400)
RESULT_NOT_READY      — request_id não existe ou ainda processando (404)
CONCURRENCY_LIMIT     — limite key/user/org atingido (429)
RATE_LIMITED          — rate limit atingido (429)
IDEMPOTENCY_CONFLICT  — mesma key + body diferente (409)
AGENT_FAILED          — pipeline crashou (500)
INTERNAL_ERROR        — outros erros (500)

Mensagens humanas mudam; códigos são contrato estável.

📦 Versionamento

Pin no major pra patches/minors automáticos:

"args": ["-y", "@titanos/mcp-agents@1"]

Pra produção que precisa de reprodutibilidade total:

"args": ["-y", "@titanos/[email protected]"]

🐛 Troubleshooting

• 401 sem auth: verifique se TITANOS_API_KEY está exportada no env do cliente MCP
• 403 PLAN_ACCESS_REQUIRED: faça upgrade pra Scale em https://www.titanos.com.br/conta/configuracoes?tab=billing
• npx trava: cliente não interativo precisa do flag -y — confirme args: ["-y", "@titanos/mcp-agents@1"]
• Timeout no wait_for_result: jobs do Power+Imagens+A+ podem levar até 15min. Use timeout máximo de 600s ou faça polling com get_result

🤝 Contribuindo

Issues e PRs: https://github.com/gavasques/titanos-mcp

Runbook de publish npm: https://github.com/gavasques/titanos-mcp/blob/main/docs/npm-publish-runbook.md

📄 License

MIT © Guilherme Vasques / Titanos