Fairplug (sandbox)

npx add-mcp 'https://fairplug-mcp.fairplughq.workers.dev/sandbox/mcp'

Fairplug MCP

Um servidor MCP que permite que assistentes de IA exibam ofertas patrocinadas com honestidade: dados de oferta tipados, um link rastreado e um texto de divulgação que o assistente deve mostrar. Desenvolvedores que exibem a oferta são pagos; os usuários sempre sabem que é patrocinado.

Piloto inicial. O Fairplug está em estágio inicial. As ofertas são dados de exemplo fictícios, ainda não há anunciantes reais e nenhum dinheiro real passa por este servidor. O sandbox serve para testar a integração, não para ganhar dinheiro.

Experimente agora (sem cadastro, sem chave)

Sandbox público, somente leitura, dados fictícios, nada é rastreado ou pago, limite de 60 requisições/min por IP:

https://fairplug-mcp.fairplughq.workers.dev/sandbox/mcp

Configuração do cliente (HTTP streamable):

{ "mcpServers": { "fairplug-sandbox": { "url": "https://fairplug-mcp.fairplughq.workers.dev/sandbox/mcp" } } }

Clientes somente stdio: npx mcp-remote https://fairplug-mcp.fairplughq.workers.dev/sandbox/mcp

Cartão do servidor: https://fairplug-mcp.fairplughq.workers.dev/.well-known/mcp/server-card.json

Início rápido (executar localmente)

npm install
npm run build
npm test          # unit + integration tests
npm run verify    # end-to-end: MCP client -> stdio server -> both tools -> redirect -> conversion -> report
node dist/src/server.js   # MCP over stdio

Requer Node >= 18 (Node >= 22 apenas para deploys wrangler). Verifique uma implantação remota: npm run remote-check -- <base-url> - (somente sandbox) ou <base-url> <mcp-token> <admin-token> (completo).

Ferramentas

• search_offers(query, category?, region?): busca por palavra-chave; category = travel | saas | retail ou uma subcategoria; region = código de país ISO (filtro rígido de elegibilidade). Cada resultado tem sponsored: true, um rótulo de divulgação e o nome do patrocinador.
• get_tracked_link(offer_id, agent_id, context?): retorna uma URL rastreada (assinada com HMAC, TTL de 15 minutos) e um disclosure_text obrigatório. No sandbox, a URL é um placeholder não funcional e nada é registrado.

Regras

Divulgação em primeiro lugar. Toda oferta é patrocinada e deve ser rotulada como tal, na mesma mensagem do link, usando o disclosure_text que retornamos. Mostre no máximo uma oferta patrocinada, junto com alternativas orgânicas. Sem divulgação, sem pagamento. A saída da ferramenta são dados tipados, nunca instruções para o modelo.

Taxas. O Fairplug cobra 10% de uma comissão validada, com mínimo de US$ 0,50, nunca mais que 15% da comissão (o teto vence em comissões pequenas: uma comissão de US$ 2,00 paga US$ 0,30). Taxas de rede são repassadas ao custo. Você vê todos os números no relatório de livros abertos. Apenas conversões validadas contam. Nenhuma taxa sobre itens pendentes ou revertidos.

Honestidade do piloto inicial. As ofertas iniciais são fictícias; as conversões aqui são simuladas; nenhum pagamento está sendo feito ainda. Diremos isso claramente até que mude.

Notas de segurança

• /mcp (privado) exige um token bearer; o sandbox em /sandbox/mcp é separado, não armazena nada e não expõe dados de relatório/administração.
• Nunca faça commit de segredos. Defina FAIRPLUG_SIGNING_SECRET, FAIRPLUG_MCP_TOKEN, FAIRPLUG_ADMIN_TOKEN como variáveis de ambiente ou wrangler secret put. O segredo de assinatura padrão é um valor público de desenvolvimento.

Licença

MIT, veja LICENSE.

---

Armazenamento

JSONL somente anexação em var/events.jsonl (substitua o diretório com FAIRPLUG_DATA_DIR). Registra cada chamada de ferramenta (ok ou erro), emissão de link, clique (incluindo rejeitado/duplicado) e conversão. Compartilhado com segurança pelos processos MCP, redirecionamento e CLI.

CLI

node dist/src/cli.js record_conversion --click-id clk_... [--order-value 189.00] [--status validated|pending|reversed] [--network-fee 0.25]
node dist/src/cli.js report

record_conversion é uma simulação (substituto para um postback de anunciante/rede). Requer que o clique tenha sido registrado (abra a URL rastreada primeiro, ex.: curl -i '<tracked_url>'). Ofertas cpa_percent exigem --order-value; fixas/CPL usam o valor de pagamento da oferta. Regravar para o mesmo clique substitui seu status (ex.: reversed).

Relatório por agente: chamadas, links, cliques únicos, conversões (validadas/pendentes/revertidas), comissão bruta, taxa Fairplug, taxas de rede, pagamento líquido. Apenas conversões validadas contam para dinheiro. Taxa = 10% da comissão validada, mínimo de US$ 0,50, limitada a 15% da comissão; taxas de rede repassadas ao custo. Líquido = bruto - taxa - taxas de rede.

Regra de comissão pequena: o teto de 15% supera o mínimo de US$ 0,50. O mínimo excederia o teto para qualquer comissão abaixo de ~US$ 3,33 (0,50 / 0,15), então aí a taxa é floor(15% x commission). Exemplos: comissão de US$ 2,00 -> taxa US$ 0,30 (não 0,50); US$ 1,00 -> 0,15; US$ 3,00 -> 0,45; US$ 4,00 -> 0,50 (o mínimo se aplica de ~US$ 3,34 até US$ 5,00, onde 10% assume). Implementado em src/fees.ts, coberto por test/core.test.ts. Interpretação assumida; confirme.

Limitações conhecidas / não implementado

• Caso extremo de taxa: veja "Regra de comissão pequena" acima (teto vence mínimo; assumido, confirme).
• Sem câmbio: pagamentos não-USD no seed (NZD) são tratados como equivalentes a USD no relatório.
• O segredo de assinatura padrão é um valor público de desenvolvimento; defina FAIRPLUG_SIGNING_SECRET para qualquer uso além do local.
• Não implementado: recibos de divulgação exibida (D5), pontuações de leilão/ranqueamento, limites de taxa, chaves de API, ledger/reservas, janelas de validação, integração real de rede/postback, ledger com dinheiro real; o endpoint de conversão hospedado é uma simulação registrada por administrador, não um postback real de rede, filtros de bot/IP. A busca é pontuação simples por palavra-chave, não BM25/embeddings.
• O servidor de redirecionamento da configuração stdio só vincula a 127.0.0.1; use o build HTTP/remoto abaixo para links que funcionem fora da máquina.

Remoto (HTTP streamable)

Um processo/Worker serve POST /mcp (MCP HTTP streamable, sem estado, respostas JSON), GET /r/clk_... (registrador de cliques), GET /health e GET /admin/report (somente se FAIRPLUG_ADMIN_TOKEN estiver definido). Código compartilhado: src/handler.ts (Web Request -> Response).

Env: FAIRPLUG_REDIRECT_BASE (URL base pública usada em links rastreados), FAIRPLUG_SIGNING_SECRET, opcional FAIRPLUG_MCP_TOKEN (Bearer obrigatório em /mcp), FAIRPLUG_ADMIN_TOKEN.

Node (qualquer host/VM/contêiner): FAIRPLUG_REDIRECT_BASE=http://127.0.0.1:8788 npm run start:http (PORT / FAIRPLUG_PORT, padrão 8788). Eventos vão para var/events.jsonl.

Cloudflare Workers (host gratuito recomendado): worker/index.ts + wrangler.jsonc. O estado é um Durable Object com SQLite (compatível com plano gratuito), tabela events. Teste local, sem necessidade de conta (wrangler requer Node >= 22):

printf 'FAIRPLUG_SIGNING_SECRET=dev\nFAIRPLUG_MCP_TOKEN=test-token\nFAIRPLUG_ADMIN_TOKEN=admin-token\n' > .dev.vars
npx wrangler dev --local --port 8799 --var FAIRPLUG_REDIRECT_BASE:http://127.0.0.1:8799
npm run build && npm run remote-check -- http://127.0.0.1:8799 test-token admin-token

Configuração do cliente para desenvolvedores: { "mcpServers": { "fairplug": { "url": "https://<host>/mcp", "headers": { "Authorization": "Bearer <token>" } } } } (ou npx mcp-remote https://<host>/mcp --header "Authorization: Bearer <token>" para clientes somente stdio).

Endpoints de livros abertos (hospedado + build Node)

Todo dinheiro é em USD, 2 casas decimais. ADMIN = Authorization: Bearer <FAIRPLUG_ADMIN_TOKEN>. Endpoints de administração retornam 404 para qualquer outra pessoa (e se nenhum token de administrador estiver configurado).

• POST /admin/agent-token (ADMIN) corpo {"agent_id":"my_agent"} -> {agent_id, token}. É assim que um desenvolvedor obtém um token de relatório por agente: o Fairplug (admin) o emite e o entrega uma vez. Apenas um hash SHA-256 é armazenado (tabela do Durable Object agent_tokens; var/agent_tokens.json no Node), então um token perdido não pode ser recuperado, apenas reemitido; reemitir rotaciona (o token antigo para de funcionar). O token concede apenas GET /report para aquele agent_id.
• POST /admin/conversion (ADMIN) corpo {"click_id":"clk_...","status":"validated|pending|reversed","commission":20.00,"network_fee":0.25,"order_value":189.00} (status padrão é validated, network_fee/order_value opcionais). O click_id deve ter um link emitido e um clique registrado. Repostar para o mesmo click_id substitui seu status (ex.: validated -> reversed). Substituto de simulação para um postback de rede.
• GET /report?agent_id=my_agent com Authorization: Bearer <that agent's token> ou o token de administrador -> JSON: clicks (únicos), links_issued, conversions {validated, pending, reversed: contagem + comissão}, gross_commission_usd, fairplug_fee_usd, network_fees_usd, net_payout_usd, fee_policy e por conversão items para que cada número possa ser recalculado. Apenas conversões validadas contam para bruto/taxa/líquido; a taxa é calculada por conversão (10%, teto de 15%, mínimo de US$ 0,50, teto vence para comissões pequenas); taxas de rede ao custo.

curl -X POST $HOST/admin/agent-token -H "Authorization: Bearer $ADMIN" -H 'content-type: application/json' -d '{"agent_id":"my_agent"}'
curl -X POST $HOST/admin/conversion  -H "Authorization: Bearer $ADMIN" -H 'content-type: application/json' -d '{"click_id":"clk_...","commission":20,"network_fee":0.25}'
curl "$HOST/report?agent_id=my_agent" -H "Authorization: Bearer $AGENT_TOKEN"

Testes: test/http.test.ts (auth, validação, matemática de taxas, rotação, isolamento de token); npm run remote-check também os executa quando recebe um token de administrador.

Implantar (Cloudflare)

1. Conta gratuita do Cloudflare (somente e-mail, sem cartão). npx wrangler login (Node >= 22).
2. Edite FAIRPLUG_REDIRECT_BASE em wrangler.jsonc para https://fairplug-mcp.<your-subdomain>.workers.dev.
3. npx wrangler secret put FAIRPLUG_SIGNING_SECRET (aleatório longo), FAIRPLUG_MCP_TOKEN, FAIRPLUG_ADMIN_TOKEN.
4. npx wrangler deploy, depois npm run remote-check -- https://<host> <mcp-token> <admin-token>.
5. Não adicione método de pagamento / Workers Paid; no plano Free, exceder limites apenas falha requisições, nada é cobrado. Limites gratuitos: 100 mil requisições/dia, DO SQLite 100 mil gravações de linhas/dia (~cada chamada de ferramenta grava 1-3 linhas, cada clique 1), 5 GB; reinicia às 00:00 UTC.