@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, descoberta de categorias, tools Seller Central (listings, estoque, pedidos, auditoria, custos e lucratividade local, write e relatórios SP-API), Olist Tiny ERP REST v3 via Titanos OAuth e Titanos Tools — Cadastros para produtos, fornecedores, marcas, categorias, NCM/tributação.

Modo de descoberta (TITANOS_MCP_TOOLS, default)

O pacote expõe 282 tools. Anunciar todas no ListTools custa dezenas de milhares de tokens e piora a escolha do modelo, então o default é o modo search: o ListTools devolve só 4 meta-tools e o assistente descobre o que precisa sob demanda.

| Meta-tool | O que faz | |---|---| | titanos_search_tools | Busca por objetivo (query), com filtro opcional de domain e access (read/write). Devolve nome exato, domínio, leitura/escrita, scopes e resumo | | titanos_describe_tool | Descrição completa + JSON Schema de entrada de uma tool | | titanos_call_tool | Executa qualquer tool pelo nome — mesmo dispatch e mesma autorização do CallTool direto | | titanos_list_tool_domains | Domínios disponíveis com contagem de tools de leitura e escrita |

Nada fica inacessível: automação continua chamando qualquer uma das 282 tools, pelo nome direto ou por titanos_call_tool.

| TITANOS_MCP_TOOLS | ListTools | |---|---| | ausente (default) | 4 meta-tools (search) | | search / catalog | 4 meta-tools | | all / full | meta-tools + lista nominal (282, ou o subconjunto do perfil) | | valor inválido | search + warning no stderr |

Definir TITANOS_MCP_PROFILE sem TITANOS_MCP_TOOLS mantém o comportamento antigo (lista nominal do perfil), para não quebrar configs existentes.

Perfis MCP (TITANOS_MCP_PROFILE)

Quando você prefere tools nominais no contexto (TITANOS_MCP_TOOLS=all), a env TITANOS_MCP_PROFILE recorta a lista por um ou mais slugs. O filtro atua somente no ListTools.

Perfil é engenharia de contexto, NÃO controle de acesso. O filtro é client-side; o token OAuth continua autorizado em todos os endpoints MCP do backend conforme os escopos aprovados no consentimento (routeRegistry). Quem controla acesso são os escopos — não o perfil.

Comportamento

| TITANOS_MCP_PROFILE | ListTools (com TITANOS_MCP_TOOLS=all) | |---|---| | ausente / vazio | 282 tools | | slug válido | só as tools daquele perfil | | a,b (vírgula) | união dos perfis | | valor inválido | default 282 + warning no stderr | | só coming_soon (ex.: bling) | 0 tools + warning no stderr (não cai no default) |

CallTool não é filtrado: se o cliente chamar por nome uma tool fora do perfil, o dispatch segue; a autorização real continua sendo o scope da key.

Matriz de config (exemplo)

{
  "mcpServers": {
    "titanos-core": {
      "command": "npx",
      "args": ["-y", "@titanos/mcp-agents@1"],
      "env": {
        "TITANOS_MCP_PROFILE": "titanos-core"
      }
    },
    "titanos-miner": {
      "command": "npx",
      "args": ["-y", "@titanos/mcp-agents@1"],
      "env": {
        "TITANOS_MCP_PROFILE": "titanos-miner"
      }
    },
    "amazon-seller": {
      "command": "npx",
      "args": ["-y", "@titanos/mcp-agents@1"],
      "env": {
        "TITANOS_MCP_PROFILE": "amazon-seller"
      }
    },
    "amazon-ads": {
      "command": "npx",
      "args": ["-y", "@titanos/mcp-agents@1"],
      "env": {
        "TITANOS_MCP_PROFILE": "amazon-ads"
      }
    },
    "titanos-full": {
      "command": "npx",
      "args": ["-y", "@titanos/mcp-agents@1"]
    }
  }
}

Vários perfis na mesma sessão: "TITANOS_MCP_PROFILE": "titanos-core,titanos-miner".

Tabela de perfis

| Perfil | displayName | Tools | Status | |---|---|---:|---| | titanos-ai | TITANOS AI | 5 | available | | titanos-miner | TITANOS Miner | 25 | available | | titanos-core | TITANOS Core | 62 | available | | amazon-seller | Amazon Seller | 47 | available | | amazon-content | Amazon Content | 18 | available | | amazon-ads | Amazon Ads | 43 | available | | mercado-livre | Mercado Livre | 62 | available | | olist | Olist | 4 | available | | bling | Bling | 4 | available | | shopee | Shopee | 3 | available | | default (sem env) | — | 282 | — |

Use whoami para ver o perfil ativo e a contagem de tools da sessão; get_server_guide anexa a lista de tools visíveis ao markdown do backend.

Auto-filtro por scope da key (TITANOS_MCP_SCOPE_FILTER)

Além do perfil, o ListTools pode esconder tools cujos requiredBackendScopes (join tool→path→manifest no build) o token não tem. Objetivo: superfície anunciada ≈ superfície autorizada.

• Default: ligado. Opt-out: TITANOS_MCP_SCOPE_FILTER=0 (ou false/off).
• Fail-open: se GET /api/mcp/identity falhar, der timeout (1,5s) ou não trouxer scopes, o ListTools cai só no filtro de perfil e loga no stderr. Nunca quebra o handshake do cliente.
• Interseção: perfil ∩ escopos do token. Perfil = intenção; escopo = autorização anunciada.
• CallTool não filtra. 403 de scope continua vindo do backend — este filtro não é controle de acesso, é alinhamento de expectativa.
• whoami expõe mcp_scope_filter.toolsHiddenByMissingScope para explicar a diferença de contagem.

⚡ Quick Start

{
  "mcpServers": {
    "titanos-agents": {
      "command": "npx",
      "args": ["-y", "@titanos/mcp-agents@1"]
    }
  }
}

Cole no arquivo de config do seu cliente MCP (Claude Desktop, Cursor, etc) e reinicie. Não existe API key pra copiar: no primeiro start o pacote abre o navegador, você faz login no Titanos, escolhe a organização, revisa os escopos e aprova. O token fica salvo na sua máquina e renova sozinho.

Se preferir autorizar antes de configurar o cliente:

npx -y @titanos/mcp-agents login     # abre o navegador e salva a conexão
npx -y @titanos/mcp-agents status    # mostra organização, escopos e validade
npx -y @titanos/mcp-agents logout    # revoga a conexão e apaga o token local

🔑 Autenticação — OAuth 2.1

Desde a versão 1.44 o Titanos aceita apenas OAuth 2.1 no MCP público (Authorization Code + PKCE S256, RFC 8414/9728/7591). Keys tnk_* foram desativadas: o backend responde 401 MCP_LEGACY_KEY_DISABLED.

Como funciona:

1. o pacote descobre o resource (/.well-known/oauth-protected-resource) e o authorization server;
2. registra o cliente dinamicamente (RFC 7591) com redirect loopback http://127.0.0.1:33418/oauth/callback;
3. abre o navegador em /conta/mcp/autorizar — login, escolha da organização e revisão dos escopos;
4. troca o código por um access token curto (mcpat_*, 30 min) + refresh token rotativo;
5. renova sozinho; se o grant for revogado no painel, o acesso cai na hora.

A conexão fica em ~/.titanos/mcp-oauth.json (permissão 0600, uma entrada por TITANOS_API_URL). Para revogar, use logout ou Conta → MCP → Clientes conectados no Titanos.

Envs opcionais

| Env | Efeito | |---|---| | TITANOS_API_URL | base URL (default https://www.titanos.com.br) | | TITANOS_MCP_TOOLS | search (default, meta-tools) ou all (lista nominal) | | TITANOS_MCP_PROFILE | perfis de tools; também reduz os escopos pedidos no consentimento | | TITANOS_MCP_OAUTH_SCOPES | lista explícita de escopos a pedir (separados por espaço/vírgula) | | TITANOS_MCP_OAUTH_OPEN_BROWSER=0 | não abre o navegador — a URL é impressa no stderr | | TITANOS_MCP_OAUTH_INTERACTIVE=0 | proíbe consentimento no start; exige login prévio | | TITANOS_MCP_CONFIG_DIR / TITANOS_MCP_AUTH_FILE | onde guardar a conexão | | TITANOS_API_KEY | bearer estático para ambientes sem navegador (CI). Aceita mcpat_*; tnk_* só funciona se o backend reabrir o legado |

📋 Pré-requisitos

• Conta Titanos com plano Scale ou superior (hierarchy_level >= 30)
• Node.js 20.18.1+ e um navegador na máquina que roda o cliente MCP (ou login feito antes, em máquina com navegador)

🛠️ Tools expostas

invoke_listing_power

Dispara o agente Super Listing Power. Gera até 5 pares título (máx. 75 chars) + destaque do produto (máx. 125 chars), 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.

list_seller_connections

Lista contas Seller Central conectadas via OAuth SP-API no Titanos. Use antes de get_listings para descobrir connection_id e marketplace.

Pré-requisito: conectar em /conta/configuracoes?tab=amazon e incluir scope seller:connections:read na API Key.

Custo: gratuito.

Custos e lucratividade Amazon

As tools get_amazon_costs, get_amazon_cost_history, get_amazon_cost_defaults, set_amazon_cost e set_amazon_cost_defaults consultam e alteram somente o ledger local de custos do Titanos. Elas não chamam a Amazon nem renovam LWA.

• Leituras usam seller:costs:read; mutações usam seller:costs:write.
• get_amazon_costs e get_amazon_cost_history exigem connection_id para preservar o recorte por conta.
• set_amazon_cost exige connection_id para uma conta ou apply_all_marketplaces: true para definir o padrão daquele SKU em todas as contas. Regras SKU+conta têm prioridade; para alterar uma conta que possui regra específica, envie connection_id e apply_all_marketplaces: false.
• COGS é sempre por SKU. set_amazon_cost_defaults grava somente imposto organizacional e mantém cost_components vazio.
• Todas são gratuitas e aceitam datas civis YYYY-MM-DD em as_of/effective_from; a moeda suportada é BRL.

Bling ERP

Use get_bling_guide, list_bling_connections, bling_get_catalog e bling_call_endpoint (padrão catalog-driven, paridade Olist). Scope base bling:connections:read; writes usam o scope exato do item do catálogo.

Shopee

Use list_shopee_connections, shopee_get_catalog e shopee_call_endpoint. Não há get_shopee_guide — o backend não expõe /api/mcp/shopee/guide. Scope base shopee:connections:read.

Olist Tiny ERP

Use get_olist_guide no início, depois list_olist_connections, olist_get_catalog e olist_call_endpoint.

Tools:

• get_olist_guide: guia operacional, scopes, custos, rate limits e idempotência. Scope olist:connections:read. Gratuito.
• list_olist_connections: lista contas Olist conectadas via OAuth no Titanos. Scope olist:connections:read. Gratuito.
• olist_get_catalog: lista endpoints REST v3 catalogados, com tool, method, path, resource, scope, write e path_params. Gratuito.
• olist_call_endpoint: executa uma tool catalogada. Não aceita URL livre. Requer o scope exato retornado pelo catálogo. Consome franquia Olist MCP ou 5 créditos após franquia.

Exemplo:

{
  "tool": "olist_pedidos_get",
  "connection_id": "323cde3a-6704-4ccf-8c2a-ba002973bd12",
  "path_params": { "idPedido": 123 },
  "query": { "incluir_itens": true }
}

Para POST/PUT/DELETE, envie idempotency_key estável e peça confirmação humana antes de operações fiscais, financeiras, estoque/preço em massa ou exclusões.

Titanos Tools — Cadastros

Tools CRUD para os cadastros operacionais do Titanos:

• Produtos: list_titanos_produtos, get_titanos_produto, create_titanos_produto, update_titanos_produto, delete_titanos_produto
• Fornecedores: list_titanos_fornecedores, get_titanos_fornecedor, create_titanos_fornecedor, update_titanos_fornecedor, delete_titanos_fornecedor
• Marcas: list_titanos_marcas, get_titanos_marca, create_titanos_marca, update_titanos_marca, delete_titanos_marca
• Categorias: list_titanos_categorias, get_titanos_categoria, create_titanos_categoria, update_titanos_categoria, delete_titanos_categoria
• NCM/tributação: list_titanos_ncm_tributacao, get_titanos_ncm_tributacao, get_titanos_ncm_tributacao_by_codigo, create_titanos_ncm_tributacao, update_titanos_ncm_tributacao, delete_titanos_ncm_tributacao

Scopes: titanos:cadastros:<entidade>:read para list/get e titanos:cadastros:<entidade>:write para create/update/delete.

get_listings

Consulta listings read-only da conta conectada (SKU, ASIN, título, status, fulfillment, issues).

Input:

{
  "connection_id": "323cde3a-6704-4ccf-8c2a-ba002973bd12",
  "marketplace_id": "A2Q3Y263D00KWC",
  "filters": {
    "page_size": 20,
    "status": "BUYABLE"
  }
}

Filtros: sku (item único), asin, status (BUYABLE | DISCOVERABLE), page_size, page_token.

Pré-requisito: scope seller:listings:read na API Key.

Custo: gratuito.

get_listing

Consulta um listing por SKU com payload completo (attributes, issues, offers, fulfillment).

Input: { "sku": "MEU-SKU-01", "connection_id": "...", "marketplace_id": "A2Q3Y263D00KWC" }

Scope: seller:listings:read · Custo: gratuito.

get_catalog_item

Catálogo Amazon por ASIN (título, brand, product types, identifiers, imagens, sales ranks).

Input: { "asin": "B0XXXXXXXXX", "marketplace_id": "A2Q3Y263D00KWC" }

Scope: seller:listings:read · Custo: gratuito.

search_product_types

Busca product types por keywords ou item_name (use antes do schema quando o tipo é desconhecido).

Scope: seller:listings:read · Custo: gratuito.

get_product_type_schema

Schema de atributos do product type (property_groups + JSON Schema). Obtenha product_type via listing, catálogo ou busca.

Input: { "product_type": "LUGGAGE", "locale": "pt_BR" }

Scope: seller:listings:read · Custo: gratuito.

get_browse_node_recommendations

Browse nodes (subcategorias) recomendados de um product type, extraídos do JSON Schema da Amazon. Retorna browse_nodes[] com { id, name }. Use o id no atributo recommended_browse_nodes do create_listing para fixar a subcategoria.

Na SP-API não há seletor de árvore de categorias: o product_type define a categoria de cadastro. Muitos tipos não expõem browse nodes (browse_nodes: []) — nesse caso a classificação fica a cargo do próprio product type.

Input: { "product_type": "LUGGAGE", "locale": "pt_BR" }

Fluxo de categoria (new_product): search_product_types → get_product_type_schema → get_browse_node_recommendations (opcional) → create_listing. Scope: seller:listings:read · Custo: gratuito.

list_financial_event_groups

Lista repasses (disbursements) via Finances v0. Retorna financial_event_groups[] com data, valor e status do repasse.

Input: { "financial_event_group_started_after": "2026-05-01T00:00:00Z" }

Scope: seller:finances:read · Custo: gratuito · Janela máx 180 dias.

list_financial_transactions

Taxas, vendas, refunds e ajustes via Finances 2024-06-19. Default aggregate: true (resumo). Drill-down de repasse: financial_event_group_id. Por pedido: order_id.

Input (resumo): { "posted_after": "2026-05-01T00:00:00Z", "aggregate": true }

Input (repasse): { "financial_event_group_id": "...", "aggregate": false, "transaction_status": "RELEASED" }

Scope: seller:finances:read · Custo: gratuito · Guia: get_seller_central_guide({ topic: "finances_reconciliation" }).

get_inventory

Estoque FBA (Inventory API, paginado) e FBM por SKU (fulfillment do listing).

Input: { "filters": { "channel": "ALL", "skus": ["SKU-1"] } }

Scope: seller:inventory:read · Custo: gratuito.

get_orders

Lista pedidos (default últimas 24h). Filtros: datas, status, AFN/MFN. Sem PII.

Scope: seller:orders:read · Custo: gratuito.

get_order

Detalhe do pedido + itens por order_id. Sem PII (sem email/endereço do comprador).

Scope: seller:orders:read · Custo: gratuito.

audit_listings

Audita qualidade de listings (issues Amazon, atributos obrigatórios, título, bullets, imagens, keywords, baseline Rufus). Retorna score 0–100 e findings por SKU.

Input:

{
  "skus": ["SKU-1"],
  "checks": ["amazon_issues", "title_length", "rufus_readiness"],
  "include_listing_data": false
}

Omita skus/asins para auditar a página atual de listings (filters.page_size).

Por quê: priorizar SKUs com maior impacto antes de editar. Scope: seller:listings:read · Custo: gratuito.

get_listing_restrictions

Consulta elegibilidade e gating (APPROVAL_REQUIRED) via Listings Restrictions API.

Input: { "asin": "B0TEST1234" } ou skus[] / asins[] (máx. 20).

Por quê: evitar tentar listar ASIN bloqueado ou que exige aprovação de marca/categoria. Scope: seller:listings:read · Custo: gratuito.

get_listing_change_history

Histórico operacional de snapshots SP-API — timeline por SKU ou scan de listings atualizados recentemente.

Modo SKU: { "sku": "SKU-1" } · Modo scan: omita sku e use filters.last_updated_after.

Por quê: detectar mudanças automáticas de status/preço/issues. Não substitui o View Change History do Seller Central. Scope: seller:listings:read · Custo: gratuito.

update_listing

Atualiza listing via patchListingsItem (SP-API write). Campos amigáveis (updates) ou JSON Patch raw (patches).

Input:

{
  "sku": "SKU-1",
  "updates": { "item_name": "Novo título", "price": 99.9 },
  "dry_run": true
}

Por quê: publicar correções após audit/schema. Sempre use dry_run: true antes de publicar. Scope: seller:listings:write · Custo: gratuito.

create_listing

Cria um listing via putListingsItem (SP-API write). Dois modos:

• offer_only — cria oferta sobre um ASIN existente no catálogo (rápido). Exige asin + price (e geralmente quantity + condition_type).
• new_product — cria produto novo no catálogo. Exige product_type (descubra com search_product_types / get_product_type_schema) + attributes brutos do schema do tipo, ou ao menos item_name + campos convenientes.

Campos convenientes (item_name, brand, bullet_points, product_description, generic_keyword, price, currency, quantity) são convertidos para atributos da Listings Items API; attributes brutos sobrescrevem os convenientes.

Input (offer_only):

{
  "sku": "SKU-1",
  "mode": "offer_only",
  "asin": "B0ABCDEFGH",
  "condition_type": "new_new",
  "price": 99.9,
  "quantity": 10,
  "dry_run": true
}

Input (new_product):

{
  "sku": "SKU-2",
  "mode": "new_product",
  "product_type": "LUGGAGE",
  "item_name": "Mala de viagem 360°",
  "brand": "Acme",
  "bullet_points": ["Resistente", "Rodas 360°"],
  "price": 299.9,
  "quantity": 5,
  "attributes": { "color": [{ "value": "Azul", "marketplace_id": "A2Q3Y263D00KWC" }] },
  "dry_run": true
}

Por quê: publicar novos produtos/ofertas pela IA. Sempre use dry_run: true antes. Para editar listing existente use update_listing. Scope: seller:listings:write · Custo: gratuito.

request_sp_report

Enfileira relatório assíncrono SP-API (Reports 2021-06-30). Allowlist: listings, FBA, restock, vendas/tráfego — sem PII de pedidos.

Input:

{
  "report_type": "GET_FLAT_FILE_OPEN_LISTINGS_DATA",
  "data_start_time": "2026-05-01T00:00:00Z",
  "data_end_time": "2026-05-27T00:00:00Z"
}

Retorna report_id + retry_after_seconds: 45. Leia resource titanos://seller/reports.

Scope: seller:reports:read · Custo: gratuito.

get_sp_report

Poll do relatório + preview TSV quando ready: true.

Input: { "report_id": "amzn1.spreport.xxx", "preview_rows": 25 }

Repita enquanto ready: false. Scope: seller:reports:read · Custo: gratuito.

get_report_metadata

Lista os datasets analíticos disponíveis para o report analyst (estoque FBA, vendas/tráfego por ASIN e por dia): colunas, tipos, descrições e freshness (last_ingested_at, row_count, marketplace). Chame antes de ask_selling_partner_report_analyst. Os datasets são alimentados por request_sp_report.

Input: { "connection_id": "uuid-opcional" }

Scope: seller:reports:read · Custo: gratuito.

ask_selling_partner_report_analyst

Responde perguntas em linguagem natural sobre os relatórios SP-API já ingeridos no warehouse. O planner gera uma consulta estruturada segura (sem SQL livre), restrita aos datasets do get_report_metadata. Não faz chamada SP-API ao vivo (só warehouse + 1 chamada LLM).

Input: { "question": "top 10 ASINs com menos estoque FBA" }

Retorna answer_summary, preview (25 linhas), total_rows, columns e um query_id para paginação/export.

Scope: seller:reports:read · Custo: gratuito (sem créditos Titanos; custo OpenRouter no backend).

paged_query_result

Pagina o resultado completo de uma consulta usando o query_id. Resultado em cache por 24h.

Input: { "query_id": "uuid", "page": 1, "page_size": 50 }

Scope: seller:reports:read · Custo: gratuito.

fetch_full_query_result

Exporta o resultado completo (query_id) em json ou csv. Limite síncrono de 10k linhas — acima disso, refine a pergunta.

Input: { "query_id": "uuid", "format": "csv" }

Scope: seller:reports:read · Custo: gratuito.

Docs detalhados (repo Titanos): docs/architecture/mcp-seller-catalog.md · mcp-seller-inventory.md · mcp-seller-orders.md · mcp-seller-reports.md · mcp-seller-p4-report-analyst-catalog.md

📚 Resources MCP

O servidor expõe resources de auto-documentação que o agente pode ler antes de chamar tools.

Mineraçã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.
• titanos://mining/sales — interpretar vendas reais vs estimativa BSR.

Seller Central

• titanos://seller/flows — fluxos operacionais: diagnosticar, auditar, corrigir, estoque, pedidos e relatórios.
• titanos://seller/reports — tipos de relatório permitidos, polling assíncrono e preview TSV.
• titanos://seller/scopes — matriz de scopes e quando recriar API Key.
• titanos://seller/tools — índice das 28 tools seller (o quê / quando usar).

Exemplo de fluxo mineração:

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 }).

Exemplo de fluxo seller:

1. Leia titanos://seller/flows e titanos://seller/scopes.
2. list_seller_connections() — obter connection_id.
3. audit_listings({ skus: ["SKU-1"] }) — score e findings.
4. update_listing({ sku: "SKU-1", updates: { item_name: "..." }, dry_run: true }).
5. update_listing({ ..., dry_run: false }) — publicar (scope write).

📦 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ó (máx. 75 chars Amazon BR)
  titulos_sugeridos: string[],        // até 5 opções de título
  destaque_produto: string,           // 1º destaque pareado (máx. 125 chars)
  destaques_sugeridos: string[],      // até 5 destaques pareados
  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,
}

Limites Amazon BR: título 75 caracteres; destaque do produto 125 caracteres (complementa título curto na PDP). update_listing valida item_name com o mesmo teto de 75 chars.

🔐 Segurança

• OAuth 2.1 obrigatório — Authorization Code + PKCE S256, redirect loopback, resource (audience) validado no authorize e no refresh
• Access token mcpat_* de 30 min, refresh rotativo com detecção de reuso; só hashes SHA-256 ficam no banco
• Um grant ativo por (usuário, cliente, organização) — o mesmo cliente pode ficar conectado em organizações diferentes
• Scopes granulares (aprovados no consentimento):
  • Agentes: agents:listing_power:invoke, agents:listing_creative:invoke, agents:read
  • Mineração: amazon:lookup, mining:search
  • Seller read: seller:connections:read, seller:listings:read, seller:inventory:read, seller:orders:read, seller:reports:read, seller:costs:read
  • Seller write: seller:listings:write, seller:costs:write
  • Olist read: olist:connections:read, olist:catalog:read, olist:orders:read, olist:finance:read, olist:documents:read, olist:crm:read
  • Olist write: olist:catalog:write, olist:orders:write, olist:finance:write, olist:documents:write, olist:crm:write
  • Matriz completa: resource titanos://seller/scopes
• Plan gating runtime: cada request valida Scale+ via requireMcpApiKey
• Auto-suspend/revogação: revogar em Conta → MCP → Clientes conectados corta o acesso imediatamente
• Idempotência atômica nos invokes assíncronos via INSERT ... ON CONFLICT; tools síncronas também enviam Idempotency-Key para retries
• Rate limit: 5 invokes/min/credencial + concurrency max 2 jobs/credencial, 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       — credencial não encontrada ou prefix errado (401)
API_KEY_REVOKED       — revogada ou suspensa (401)
MCP_LEGACY_KEY_DISABLED — key tnk_* enviada; o MCP exige OAuth 2.1 (401)
SCOPE_MISSING         — o consentimento não inclui o escopo 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)
OLIST_CONNECTION_NOT_FOUND — conta Olist não conectada ou fora do tenant (404)
OLIST_CONNECTION_EXPIRED — refresh token Olist expirou; reautorizar OAuth (403)
OLIST_RATE_LIMITED    — limite Olist atingido; respeitar Retry-After (429)
AGENT_FAILED          — pipeline crashou (500)
INTERNAL_ERROR        — outros erros (500)

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

📊 Catálogo completo (282 tools)

O pacote expõe 282 tools MCP: agentes listing, mineração, Seller Central, Amazon Ads (SP/SB/SD/DSP), custos e lucratividade local, diagnósticos Ads locais, A+/Brand Analytics, Mercado Livre, Olist, cadastros Titanos, experiments, brands/integrations e suporte. No default (search) elas são descobertas por titanos_search_tools; com TITANOS_MCP_TOOLS=all entram nominalmente no ListTools (filtradas pelo perfil, se houver).

Writes Ads relevantes (#310):

• update_resources / create_resources / delete_resources — SP, SB, SD via resource_type
• update_dsp_resources / create_dsp_resources / delete_dsp_resources — DSP (incl. associações creative↔ad group)

Validação Hermes: ver runbook Titanos.

📦 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 MCP_LEGACY_KEY_DISABLED: você ainda está passando TITANOS_API_KEY=tnk_.... Remova a env e rode npx -y @titanos/mcp-agents login
• 401 sem auth / sessão sumiu: rode npx -y @titanos/mcp-agents status; se não houver conexão, login de novo (o grant pode ter sido revogado no painel)
• O navegador não abriu: a URL de autorização é sempre impressa no stderr (URL de autorização: ...) — copie e abra manualmente. Abra no mesmo navegador/perfil onde você já usa o Titanos, senão vai pedir login de novo
• Caiu na tela de login: normal quando o perfil aberto não tem sessão do Titanos. Faça o login ali mesmo — o Titanos volta sozinho para a tela de autorização (o pedido é preservado na URL). Não abra a URL de autorização de novo em outra janela: cada login gera um pedido novo
• login esperou e expirou (10 min): o pedido de autorização vence; rode login outra vez e conclua login + Autorizar na mesma janela
• Node antigo: o pacote recusa a subir abaixo de 20.18.1 com a mensagem do que atualizar (nvm install 20.18.1)
• Cliente MCP mata o processo antes de você aprovar: autorize fora dele com npx -y @titanos/mcp-agents login e depois reinicie o cliente
• Faltou escopo depois de conectar: refaça o consentimento (logout + login) marcando os escopos necessários
• 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/guilherme-vasques-ltda/titanos-mcp

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

📄 License

MIT © Guilherme Vasques / Titanos