affset

Execute o affset pelo chat: estatísticas de campanha, zonas, pagamentos, segmentação e gerenciamento de equipe.

Documentação

servidor MCP affset

Um servidor MCP que permite que um comprador de mídia execute o affset a partir de um cliente de chat — consulte estatísticas, gerencie campanhas/zonas/equipe, pagamentos, segmentação, sub-rótulos e corte zonas com baixo desempenho em linguagem simples, sem painel.

As ferramentas envolvem a API existente do tenant affset. Conecte-se pelo endpoint hospedado (OAuth, sem chave de API) ou execute este pacote localmente (token Bearer + X-Namespace). Uma conexão atende a um tenant.

Forma mais rápida de conectar — o endpoint hospedado. Adicione https://mcp.affset.com/mcp como um servidor MCP remoto no Claude (web ou desktop), Cursor, Claude Code ou qualquer cliente que suporte HTTP com streaming via OAuth: cole a URL, faça login com seu e-mail affset, mantenha Somente leitura (o padrão de consentimento) ou conceda acesso total. Cada conexão aparece na página Integrações do painel e pode ser revogada individualmente. Guia de configuração: affset.com/integrations.

O pacote npm abaixo é o caminho de auto-hospedagem: mesma lista de ferramentas, roda na sua máquina com uma chave de API que você gerencia. O stdio usa acesso total por padrão, a menos que você defina AFFSET_READ_ONLY=true.

Ferramentas

Ferramenta	O que faz
`whoami`	Mostra o tenant ao qual este servidor está vinculado: namespace, base da API, URL do dashboard derivada e (quando legível) empresa / fuso horário / domínio de API personalizado. Somente leitura.
`get_stats`	Estatísticas de tráfego agrupadas por uma dimensão (data, campanha, zona, país, sub1–5, anunciante, publisher, …), opcionalmente restringidas com filtros `advertiser_email`/`publisher_email` (um usuário, qualquer group_by). Retorna cliques, conversões, CR, payout, custo de mídia e ROI como uma tabela. `paid_only` assume o valor verdadeiro por padrão (igual ao dashboard), então o CR exclui conversões informativas. Subcolunas usam os rótulos de sub do tenant quando configurados. Agrupamentos e filtros por usuário são owner/manager mais o papel de manager do lado correspondente.
`list_campaigns`	Lista campanhas (filtro por status / nome, paginação).
`get_campaign`	Registro completo de uma campanha — todos os campos (URL da oferta sem truncamento, agendamento exato, orçamentos/pacing, flag silencioso, tipo de meta de payout) além de suas regras de segmentação e regras de payout, em uma única chamada.
`list_zones`	Lista zonas de fonte de tráfego (filtro por status / nome, paginação, fonte vinculada).
`list_team`	Lista membros da equipe (email, papel, manager). Nunca retorna tokens de API.
`create_team_member`	Convida um membro da equipe (owner, manager, publisher, advertiser, publisher_manager, advertiser_manager). Uma chave de manager com escopo só pode criar seu próprio papel gerenciado, auto-atribuído. Retorna a nova chave de API uma vez — `list_team` nunca a mostra novamente. Dry-run por padrão; `confirm: true` para aplicar.
`create_campaign`	Cria uma campanha a partir de email do anunciante, URL da oferta, geo, payout e nome. Padrões: CPA / taxa 0, pausada, regra de payout global e link de rastreamento pronto (template de fonte vinculada quando configurado; caso contrário, `source_click_id={clickid}` + placeholders de sub). Dry-run por padrão; `confirm: true` para aplicar.
`set_campaign_status`	Executa ou pausa uma campanha (`action: "run" \| "pause"`). Dry-run por padrão; `confirm: true` para aplicar. Executar pode atingir o limite de campanhas ativas do plano.
`update_campaign`	Atualização parcial (nome, URL da oferta, status, taxa, orçamentos, datas, …). Dry-run por padrão; `confirm: true` para aplicar. Prefira `set_campaign_status` para executar/pausar.
`create_zone`	Cria uma zona de fonte de tráfego (nome + URLs opcionais de postback/site/tráfego de volta, link opcional `traffic_source_id`). Sempre criada `active`. Dry-run por padrão; `confirm: true` para aplicar.
`update_zone`	Atualização parcial (nome, status, URLs, `traffic_source_id`). Dry-run por padrão; `confirm: true` para aplicar. Passe `null` para limpar uma URL ou desvincular a fonte.
`list_traffic_sources`	Lista fontes de tráfego — as redes das quais se compra, cada uma com os templates de rastreamento/postback que suas zonas vinculadas usam. Token de API mostrado apenas como definido/nenhum.
`create_traffic_source`	Cria uma fonte de tráfego, opcionalmente a partir de um preset de rede (`exoclick`, `trafficstars`, `propellerads`, `adsterra`, `richads`) que copia templates verificados em uma linha editável. Dry-run por padrão; `confirm: true` para aplicar.
`update_traffic_source`	Atualização parcial (nome, templates, api_token, status). Zonas vinculadas adotam o novo template de rastreamento imediatamente. Dry-run por padrão; `confirm: true` para aplicar.
`list_source_bids`	As campanhas de rede de uma fonte de tráfego com seus lances atuais, lidas ao vivo da conta da rede (ExoClick, TrafficStars, RichAds — precisa do token de API da fonte): status, modelo de precificação, lance em USD, última mudança que entrou no estágio de mutação do Affset. Somente leitura.
`set_source_bid`	Define o lance de uma campanha de rede em USD usando seu modelo de precificação existente (para RichAds: CPM para pops, CPC para push/display). O dry run retorna `expected_current_bid`; passe esse valor de volta com `confirm: true` para vincular a escrita ao lance revisado, de modo que uma mudança concorrente seja recusada em vez de sobrescrita. Registra a tentativa no histórico de lances da fonte e reporta aplicado somente quando a rede ecoa o novo valor. Aumentar um lance acima de 5× precisa de `allow_large_increase: true`. Dry-run por padrão.
`get_zone_url`	A URL `/serve` para colar nas configurações de campanha de uma rede — rotaciona entre as campanhas ativas da zona. Uma zona vinculada a uma fonte de tráfego renderiza o template de rastreamento dessa fonte; caso contrário, convenção de sub pré-preenchida + macro opcional `cost`. Avisa quando nenhuma campanha ativa está visível.
`get_tracking_link`	O link `/track/click` para uma campanha + zona existentes — direto para uma campanha ativa, sem rotação ou verificações de segmentação. Renderiza o template de uma fonte vinculada como `get_zone_url`. Re-deriva o que `create_campaign` ecoou na criação.
`cut_zones`	Coloca na blacklist zonas com baixo desempenho em uma campanha por limite (CR / gasto / ROI). Dry-run por padrão; `confirm: true` para aplicar.
`list_payout_rules`	Lista as regras de payout globais e por zona de uma campanha e seu `payout_goal_type`.
`set_payout_rule`	Insere ou atualiza um payout global ou específico de zona. Dry-run por padrão; use `confirm: true` para aplicar.
`delete_payout_rule`	Exclui uma regra de payout global ou específica de zona. Dry-run por padrão; use `confirm: true` para aplicar.
`set_payout_goal`	Define ou limpa `payout_goal_type` (conversões baseadas em metas). Dry-run por padrão; use `confirm: true` para aplicar.
`list_targeting_types`	Catálogo de tipos de regras de segmentação, sinalizando as pré-configuradas que `/serve` nunca avalia.
`list_targeting_rules`	Lista as regras de segmentação de uma campanha, sinalizando qualquer uma que não tenha efeito.
`set_targeting_rule`	Insere ou atualiza uma regra de segmentação (mesclagem segura), normalizada para o que `/serve` corresponde. Dry-run por padrão; use `confirm: true` para aplicar.
`remove_targeting_rule`	Remove uma regra de segmentação por id ou tipo+método. Dry-run por padrão; use `confirm: true` para aplicar.
`list_sub_labels`	Lista os nomes de exibição do locatário para sub1–sub5.
`set_sub_labels`	Define ou limpa rótulos de sub (parcial; `null` limpa). Dry-run por padrão; use `confirm: true` para aplicar.
`list_conversions`	Lista registros de auditoria de conversão (payout, gasto, tipo de pixel, payload, postback). `paid_only` filtra no lado do servidor; outros filtros opcionais são no lado do cliente na página atual.

Qual URL eu forneço para a rede?

	`get_zone_url` (`/serve/{zone}`)	`get_tracking_link` (`/track/click/{campaign}/{zone}`)
Escolhe a campanha	affset, a partir da rotação da zona	você, uma campanha fixa
Precisa de uma campanha ativa	sim — caso contrário, tráfego de volta / não vendido	sim — caso contrário, 404
Precisa de uma zona ativa	sim	sim
Regras de geo e segmentação	aplicadas	não aplicadas
`cost=` cai em	a linha de impressão	a linha de clique

Use um ou outro para um determinado fluxo de tráfego — nunca ambos com cost=, ou o custo de mídia é contado duas vezes.

Ambos usam o domínio de API personalizado do locatário quando definido, já que a URL é colada na rede literalmente. Macros ({clickid}, [CLICK_ID], ${SUBID}) são inseridas sem codificação percentual — a fonte as expande antes que a solicitação chegue ao affset.

cut_zones apenas adiciona zonas à lista negra de uma campanha, e faz uma leitura-mesclagem-gravação para que as regras de segmentação existentes nunca sejam alteradas.

create_campaign precisa de uma zona de fonte de tráfego para o link de rastreamento: passe zone_id, ou deixe-o escolher automaticamente quando o namespace tiver exatamente uma zona ativa. As campanhas são criadas paused; ative-as antes de enviar tráfego por qualquer uma das URLs. Ambos os tipos de URL também exigem uma zona ativa. A lista de permissões geográficas é aplicada em /serve apenas — o link de rastreamento direto não é restrito por geo, mas ainda requer uma campanha ativa e atualmente atendível.

Recursos de documentação

Além das ferramentas, o servidor expõe a referência da API do affset como recursos do MCP, para que um assistente possa responder "como funciona o rastreamento de conversões?" ou "o que /serve aceita?" a partir dos próprios documentos — não apenas dos esquemas das ferramentas.

URI do recurso	Tipo	Conteúdo
`affset://docs/api-reference`	`text/markdown`	A referência completa da API — endpoints, autenticação, funções, exemplos.
`affset://docs/api-reference.json`	`application/json`	A mesma referência como dados estruturados, para uso programático.

Eles são exatamente o conteúdo publicado em affset.com/docs, gerado a partir de uma única fonte, e buscados no momento da leitura de AFFSET_DOCS_URL ({origin}/api-reference.md e {origin}/api-reference.json) — então eles sempre refletem os documentos atualmente publicados, não uma cópia fixada neste pacote. A busca envia nenhuma credencial (os documentos são públicos e vivem em uma origem diferente da API do locatário). Fallbacks de SPA HTML, redirecionamentos, JSON inválido e corpos superdimensionados são rejeitados. Ambos os recursos estão sempre disponíveis, inclusive sob AFFSET_READ_ONLY.

Configuração

Somente auto-hospedado (stdio) — conexões hospedadas não usam essas variáveis. Toda a configuração vem do ambiente (nunca codificada):

Variável	Descrição
`AFFSET_BASE_URL`	Origem da API do affset, ex.: `https://api.affset.com` (sem caminho/consulta/credenciais). Deve ser `https` a menos que o host seja `localhost`/`127.0.0.1`/`::1` — http simples enviaria a chave da API em texto claro.
`AFFSET_API_KEY`	Chave da API do locatário. Seu namespace deve corresponder a `AFFSET_NAMESPACE`.
`AFFSET_NAMESPACE`	Namespace do locatário (letras minúsculas, números, hífens; 3–63 caracteres — mesmas regras do cadastro).
`AFFSET_READ_ONLY`	Opcional, padrão `false`. Defina como `true`/`1` para registrar apenas as ferramentas somente leitura (`whoami`, `get_stats`, `get_campaign`, cada `list_*`, `get_zone_url`, `get_tracking_link`) — toda ferramenta de criar/atualizar/excluir/cortar fica indisponível, não apenas atrás de confirmação. Veja Segurança para saber por que isso importa.
`AFFSET_REQUEST_TIMEOUT_MS`	Opcional, padrão `30000`. Tempo limite de HTTP por solicitação em milissegundos (`1000`–`300000`).
`AFFSET_DOCS_URL`	Opcional, padrão `https://affset.com`. Origem da qual os recursos de documentação da referência da API são buscados (somente origem, sem caminho). Buscado anonimamente — nenhuma chave da API é enviada aqui.

Veja .env.example.

Instalação

Hospedado (mais rápido — sem instalação)

Adicione o servidor remoto no seu cliente MCP e aprove o acesso no navegador. O OAuth é descoberto a partir do endpoint — não cole uma chave da API e não adicione um cabeçalho Authorization.

Claude (web ou desktop) — Personalizar → Conectores → + → Adicionar conector personalizado → https://mcp.affset.com/mcp.
Cursor — Configurações → MCP → Adicionar servidor, transporte "streamable HTTP", mesma URL.
Claude Code — claude mcp add --transport http affset https://mcp.affset.com/mcp e então autentique com /mcp.

Você entra com seu e-mail do affset (link mágico). Somente leitura é selecionado na tela de consentimento, a menos que você alterne para Acesso total. A conexão recebe sua própria credencial com escopo — sua chave da API nunca é envolvida — e aparece na página de Integrações do painel, onde pode ser revogada a qualquer momento. Guia completo: affset.com/integrations.

Os caminhos de auto-hospedagem abaixo executam o mesmo conjunto de ferramentas via stdio e exigem Node.js 22.13 ou mais recente.

Do npm (recomendado para auto-hospedagem)

Sem clone, sem build — seu cliente MCP o executa com npx. Para Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "affset": {
      "command": "npx",
      "args": ["-y", "@affset/mcp"],
      "env": {
        "AFFSET_BASE_URL": "https://api.affset.com",
        "AFFSET_API_KEY": "sk_live_...",
        "AFFSET_NAMESPACE": "your-namespace"
      }
    }
  }
}

Para Claude Code:

claude mcp add affset \
  -e AFFSET_BASE_URL=https://api.affset.com \
  -e AFFSET_API_KEY=sk_live_... \
  -e AFFSET_NAMESPACE=your-namespace \
  -- npx -y @affset/mcp

Mesmas flags de ambiente com -- npx -y github:affset/mcp se você instalar do GitHub em vez do registro npm (veja abaixo).

Adicione -e AFFSET_READ_ONLY=true para uma instância somente de estatísticas/relatórios (veja Segurança).

Do GitHub diretamente (sem publicação no npm necessária)

npx pode instalar direto do repositório git em vez do registro npm — útil se você preferir não publicar, ou apenas quiser rastrear main sem uma etapa de lançamento:

{
  "mcpServers": {
    "affset": {
      "command": "npx",
      "args": ["-y", "github:affset/mcp"],
      "env": {
        "AFFSET_BASE_URL": "https://api.affset.com",
        "AFFSET_API_KEY": "sk_live_...",
        "AFFSET_NAMESPACE": "your-namespace"
      }
    }
  }
}

Um push para main torna esse commit disponível para este caminho de instalação não fixado — nenhuma publicação no npm é necessária. Na resolução, o npm busca o repositório e executa o script prepare para construir dist/ antes de iniciar o binário. O npm pode reutilizar seu cache em inicializações posteriores; um processo MCP já em execução não é atualizado até que seja reiniciado e npx resolva a dependência novamente.

Para implantações reproduzíveis, fixe uma revisão revisada em vez de flutuar em main: github:affset/mcp#<commit-sha> ou github:affset/mcp#<tag>. Reinicie o processo MCP deliberadamente quando quiser que ele resolva e execute uma revisão mais recente.

Da fonte

git clone https://github.com/affset/mcp.git affset-mcp
cd affset-mcp
npm install        # builds via the prepare script

Em seguida, aponte seu cliente MCP para o arquivo de entrada compilado — troque o comando npx acima por "command": "node", "args": ["/absolute/path/to/affset-mcp/dist/index.js"].

Exemplos de uso

listar campanhas pausadas → list_campaigns(status: "paused")

mostre-me tudo sobre a campanha 42 → get_campaign(campaign_id: 42)

mostrar zonas → list_zones()

quem está na equipe? → list_team()

adicionar sarah@offer.com como editora → create_team_member(email: "sarah@offer.com", role: "publisher") (simulação) → confirmar

estatísticas de hoje por sub1 → get_stats(group_by: "sub1")

estatísticas por anunciante → get_stats(group_by: "advertiser_email")

estatísticas para um editor, agrupadas por zona → get_stats(group_by: "zone_id", publisher_email: "publisher@example.com")

estatísticas incluindo conversões informativas → get_stats(paid_only: false)

configurar RichAds de ponta a ponta → create_traffic_source(name: "RichAds", preset: "richads") (simulação) → confirmar → create_zone(name: "RichAds push", traffic_source_id: "…") (simulação) → confirmar → get_zone_url()

criar uma campanha para a oferta X, anunciante buyer@example.com, geo BR, pagamento $2 → create_campaign(user_email: "buyer@example.com", offer_url: "https://offer.example/lp?s={click_id}", geo: ["BR"], payout: 2) (simulação) → confirmar

qual URL eu colo no RichAds? → get_zone_url() — uma zona vinculada a uma fonte de tráfego recebe o modelo da fonte preenchido

me dê o link para a campanha 42 novamente → get_tracking_link(campaign_id: 42)

executar campanha 42 → set_campaign_status(campaign_id: 42, action: "run") (simulação) → confirmar

pausar campanha 42 → set_campaign_status(campaign_id: 42, action: "pause") (simulação) → confirmar

definir postback da zona → update_zone(zone_id, postback_url: "…") (simulação) → confirmar

cortar zonas com CR < 0.2% and spend > $5 → cut_zones(campaign_id, cr_max: 0.002, spend_min: 5) (simulação) → confirmar

mostrar pagamentos para a campanha 42 → list_payout_rules(campaign_id: 42)

definir pagamento da zona para $3 → set_payout_rule(campaign_id: 42, payout: 3, zone_id: "…") (simulação) → confirmar

pagar apenas em conversões de depósito → set_payout_goal(campaign_id: 42, goal_type: "deposit") (simulação) → confirmar

quais tipos de segmentação existem? → list_targeting_types()

lista de permissões BR+MX na campanha 42 → set_targeting_rule(campaign_id: 42, type: "geo", method: "whitelist", rule: "BR,MX") (simulação) → confirmar

nomear sub1 Zona, sub2 Criativo → set_sub_labels(sub1: "Zone", sub2: "Creative") (simulação) → confirmar

mostrar conversões recentes → list_conversions()

ocultar conversões informativas (erros de tipo de meta) → list_conversions(paid_only: true)

encontrar pagamentos de $0 (sem regra / ainda nesta página) → list_conversions(zero_payout: true)

consulta por id de clique da fonte → list_conversions(source_click_id: "abc123")

Notas e limites

get_stats agrupa por uma dimensão por chamada. Drill-down é uma sequência de chamadas, cada uma estreitando com filtros campaign_ids / zone_ids / sub1..sub5 / conversion_type / advertiser_email / publisher_email / paid_only. Os dois filtros de e-mail selecionam as campanhas ou zonas de um usuário sem alterar group_by; o acesso é limitado ao proprietário/gerente ou ao papel de gerente com escopo correspondente. Filtrar por conversion_type retorna apenas linhas de conversão (impressões, cliques e custo de mídia são zero). paid_only tem como padrão true (o padrão da API é false; isso corresponde ao painel) para que a contagem de conversões e a taxa de conversão removam linhas informativas registradas com postback_skipped=non_goal_type — o tipo de pixel não correspondeu ao payout_goal_type da campanha. Conversões silenciosas ainda contam; este não é um filtro de payout>0. Defina false para a contagem bruta. Apenas eventos recentes (não consolidados) são filtrados; conversões já nos arquivos diários permanecem incluídas.
spend significa media_cost (seu custo de tráfego). Limites de ROI/gasto precisam de dados de custo importados para o recorte.
Os endpoints de listagem não têm busca de nome no servidor — name_contains filtra a página atual no lado do cliente.
Predefinições de intervalo de datas, limites de YYYY-MM-DD e timestamps renderizados são todos resolvidos no fuso horário do locatário (lido uma vez de /api/tenant), então uma janela se alinha com os buckets de data que group_by=date retorna em vez de cruzar dois deles. Timestamps explícitos devem incluir Z ou um offset UTC.
Todas as mutações (criações, atualizações, cortes, exclusões) permanecem em dry-run → confirm: true. Criações são aditivas uma vez confirmadas e ecoam o que foi escrito.
Ativar uma campanha ou criar uma zona pode retornar 402 limite do plano — o erro expõe dimensão / atual / limite.
Resolução de payout na conversão: específico da zona → global → $0. O tipo de meta limita gasto/payout pela correspondência de type= do pixel; eventos não correspondentes ainda registram a $0. Payouts vão até $0.00001, então valores de payout são impressos com até cinco casas decimais.
Alterar um payout é excluir + criar — a API não tem atualização e o par (campanha, zona) é único. set_payout_rule restaura o payout anterior se a criação falhar, e diz isso em voz alta no único caso em que não pode.
Segmentação é aplicada apenas em /serve — não em links de rastreamento direto. set_targeting_rule / remove_targeting_rule mesclam com segurança; outras regras são mantidas.
Valores de segmentação são correspondidos exatamente e com distinção de maiúsculas/minúsculas no momento da exibição (geo de CF-IPCountry, os/browser do user agent, tipo de dispositivo de um conjunto fixo). set_targeting_rule normaliza o que pode (br,mx → BR,MX, android → Android) e rejeita o que nunca poderia corresponder — uma whitelist sem correspondência interrompe silenciosamente a entrega.
capping, weekdays e hours são semeados mas nunca avaliados por /serve. set_targeting_rule se recusa a escrevê-los (eles seriam lidos como segmentação funcional enquanto a campanha continuasse comprando); list_targeting_types os sinaliza. Use unique_users (visits/hours) para limite de frequência.
list_conversions é a trilha de auditoria de conversão (não estatísticas agregadas). A API não tem filtros de campanha/zona/data; paid_only é o único filtro no servidor (true remove linhas registradas com postback_skipped=non_goal_type — o tipo de pixel não correspondeu ao payout_goal_type da campanha; conversões silenciosas e outros motivos de pulo ainda voltam — este não é um filtro de payout>0). Os outros filtros opcionais se aplicam apenas à página atual. Linhas não incluem campaign_id/zone_id. Papéis do lado do editor não veem spend e papéis do lado do anunciante não veem payout, então zero_payout precisa de um papel que possa; paid_only não (ele se baseia em postback_skipped, não em payout).
create_team_member cria a chave de API diretamente (como o "Adicionar Membro da Equipe" do painel) — ele não envia um e-mail de convite. Entregue a chave retornada à pessoa você mesmo. Revogar/remover um membro da equipe ainda não é uma ferramenta; use a página de Equipe do painel.
Fora do escopo: excluir campanhas/zonas/conversões, cobrança, gerenciamento de criativos.
O cadastro de locatário deliberadamente não é uma ferramenta. POST /api/public/create-instance é limitado por Origin e falha fechado, que é o que mantém o cadastro apenas no navegador; um chamador no lado do servidor teria que falsificar um Origin na lista de permitidos para passar. O endpoint também retém a chave de API quando a entrega de e-mail está configurada (ele envia um magic link em vez disso), e este servidor vincula um namespace do ambiente na inicialização — então ele não poderia usar um locatário que acabou de criar. Cadastre-se no painel, depois aponte uma instância do servidor para o novo namespace.

Usando como biblioteca

Desde 0.2.0 o pacote também funciona como uma biblioteca agnóstica de runtime: tudo que o servidor stdio registra (ferramentas, recursos de documentação, remoção de somente leitura) é exposto como um único helper que roda em qualquer runtime com fetch — Node ≥22.13 ou Cloudflare Workers. O gateway MCP affset hospedado (mcp.affset.com) consome exatamente essa superfície, então o roster remoto nunca pode divergir do stdio.

import { registerAffsetTools, type Config } from "@affset/mcp/core";

const config: Config = {
  baseUrl: "https://api.affset.com",
  docsBaseUrl: "https://affset.com",
  apiKey: perRequestKey, // e.g. an OAuth grant's backing credential
  namespace: tenantNamespace,
  requestTimeoutMs: 30_000,
  readOnly: scope === "read", // never registers tools without readOnlyHint: true
};

registerAffsetTools(server, config); // server: your own McpServer instance

registerAffsetTools aceita seu McpServer estruturalmente, então sua própria instalação de @modelcontextprotocol/sdk funciona — sem necessidade de corresponder à cópia deste pacote. O carregamento de variáveis de ambiente (AFFSET_*) deliberadamente não faz parte da superfície da biblioteca; ele pertence apenas ao entrypoint stdio. Um terceiro argumento opcional { onToolCall } relata apenas nome da ferramenta, duração e status de sucesso/erro para auditoria de log de propriedade do transporte; argumentos e saída nunca são incluídos.

A biblioteca valida e normaliza config antes de registrar qualquer coisa. Origens de API remota devem usar HTTPS (HTTP simples é aceito apenas em loopback), origens não podem conter credenciais ou caminhos, e namespaces inválidos, timeouts, chaves de API ou configurações de somente leitura não booleanas falham fechado na inicialização. As declarações públicas não exigem tipos ambientais do Node, então a mesma importação verifica tipos em Workers e outros runtimes com padrões web.

Desenvolvimento

npm run type-check   # tsc --noEmit
npm run lint         # eslint src
npm run format       # prettier --write .
npm run build        # compile to dist/
npm test             # build + node --test over dist/**/*.test.js
npm run check-all    # lint + format:check + type-check + test — CI runs this
npm run dev          # watch mode

Segurança

Hospedado (https://mcp.affset.com/mcp): OAuth via magic link. Somente leitura é o padrão de consentimento (ferramentas de mutação nunca são registradas). Acesso total ainda executa mutações em dry-run até confirm: true. Revogue na página de Integrações do painel. Nada em mcp.affset.com / oauth.affset.com pede uma chave de API.
Auto-hospedado (stdio): sem segredos no repositório; credenciais vêm do ambiente em tempo de execução. Crie uma chave de API dedicada, de privilégio mínimo e com expiração em vez de reutilizar uma chave de proprietário.
AFFSET_BASE_URL deve ser https a menos que o host seja loopback — sem chave de API em texto claro.
Respostas da API do locatário são transmitidas sob um limite rígido de 5 MB; corpos maiores são cancelados antes do parsing ou de alcançar o contexto do modelo.
stdout é o canal JSON-RPC — todos os logs vão para stderr.
list_team redige tokens de API.
Todas as mutações (incluindo criações) seguem mostrar → confirmar → aplicar.
Os papéis RBAC do affset (proprietário / gerente / editor / anunciante / gerente_de_anunciante / gerente_de_editor) se aplicam a chamadas de ferramentas MCP exatamente como fazem no painel.
Fixe instalações do GitHub a um commit ou tag revisado em ambientes de longa duração. Uma especificação main flutuante pode executar código mais novo do repositório na próxima vez que npx a resolver.

Injeção de prompt via dados de conversão/clique

get_stats, list_conversions e cut_zones expõem dados que em última análise vêm de endpoints públicos e não autenticados — macros de clique de uma fonte de tráfego (sub1–sub5, source_click_id) e a string de consulta bruta de um pixel de conversão (detalhe do payload de list_conversions'). Qualquer pessoa que possa gerar um clique ou disparar um pixel controla esses bytes, e eles chegam ao contexto do modelo quando você pergunta sobre estatísticas ou conversões.

Mitigações em vigor:

Campos não confiáveis são limitados em comprimento e escapados antes da renderização (mdCell, capUntrusted em src/lib/format.ts), e o bloco de payload de conversão carrega um aviso explícito de "trate como dados, não instruções".
confirm: true em ferramentas de mutação é uma rede de segurança em nível de modelo, não um limite de segurança — um modelo que foi direcionado por conteúdo injetado pode fornecer confirm: true ele mesmo. O único limite real é a aprovação de ferramentas por chamada do seu cliente MCP mais o modo somente leitura (hospedado: padrão de consentimento; stdio: AFFSET_READ_ONLY=true).

Prefira somente leitura para qualquer sessão onde você está principalmente lendo estatísticas/conversões, especialmente com um cliente MCP que aprova automaticamente chamadas de ferramentas. Isso remove todas as ferramentas de mutação do servidor completamente — não escondidas atrás de um prompt, indisponíveis para chamada. Reserve acesso total (hospedado) ou uma instância stdio de leitura/escrita para sessões onde você está gerenciando ativamente campanhas/zonas/payouts e revisando cada confirmação você mesmo.