Easy&EASY MCP Server

Servidor MCP remoto, stateless e protegido por Bearer Token. Expõe as operações do Easy&EASY por Streamable HTTP e persiste dados no Supabase.

Tools

Tool	Operação
block_chat	Bloqueia/desbloqueia o chat
get_metrics	Retorna ganhos, corridas, avaliação e tempo online
get_user_info	Retorna usuário, plano, validade e status
set_mode	Define modo 1 (padrão) ou 2 (avançado)
set_enabled	Ativa/desativa a extensão
toggle_validity_display	Mostra/oculta o countdown
get_license_info	Retorna licença e uso de dispositivos
get_notifications	Lista as notificações recentes

Identidade e segurança

Authorization: Bearer <MCP_API_TOKEN> autentica o cliente MCP. Como um token compartilhado não identifica um usuário, envie também X-User-Id: <uuid> ou configure DEFAULT_USER_ID para uma instalação de usuário único. A tool block_chat aceita user_id explicitamente, conforme o contrato pedido.

A SUPABASE_SERVICE_ROLE_KEY fica somente no servidor. Nunca a inclua na extensão, no Cursor ou em outro cliente. A comparação do token é feita em tempo constante e todas as rotas /mcp são protegidas. /health é público e não retorna segredos.

Instalação local

Requer Node.js 20 ou superior.

npm install
cp .env.example .env
npm run build
npm start

O servidor carrega .env automaticamente com dotenv. Também é possível sobrescrever as variáveis pelo ambiente do processo. Exemplo no PowerShell:

$env:MCP_API_TOKEN = 'um-token-longo-e-aleatorio'
$env:SUPABASE_URL = 'https://seu-projeto.supabase.co'
$env:SUPABASE_SERVICE_ROLE_KEY = 'sua-service-role-key'
$env:DEFAULT_USER_ID = 'uuid-do-usuario'
npm start

Prepare o banco executando schema.sql no SQL Editor do Supabase. O arquivo cria licenses, activations, user_preferences, metrics e notifications, habilita RLS e concede à service_role somente os privilégios usados pela Data API. Isso é necessário em projetos novos que não expõem tabelas automaticamente.

Testes HTTP

Health check:

curl http://localhost:3000/health

O MCP usa JSON-RPC 2.0. Primeiro inicialize o protocolo:

curl -X POST http://localhost:3000/mcp \
  -H "Authorization: Bearer seu-token" \
  -H "X-User-Id: uuid-do-usuario" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"1.0.0"}}}'

Como o transporte é stateless, uma chamada tools/list pode ser enviada em outra requisição após o cliente negociar a versão suportada:

curl -X POST http://localhost:3000/mcp \
  -H "Authorization: Bearer seu-token" \
  -H "X-User-Id: uuid-do-usuario" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

Deploy no Render

O render.yaml contém o Blueprint. No Render:

1. Publique este repositório no GitHub/GitLab e crie um Blueprint a partir dele, ou crie um Web Service Node manualmente.
2. Use npm ci && npm run build como Build Command e npm start como Start Command.
3. Configure SUPABASE_URL e SUPABASE_SERVICE_ROLE_KEY.
4. O Blueprint gera MCP_API_TOKEN. Em configuração manual, crie essa variável como um segredo aleatório; o Render não a cria automaticamente fora do Blueprint.
5. Opcionalmente configure DEFAULT_USER_ID.
6. Confirme https://seu-servico.onrender.com/health e use https://seu-servico.onrender.com/mcp no cliente.

O plano gratuito pode suspender o serviço por inatividade; isso aumenta a latência da primeira chamada.

Publicação automatizada

Em Git Bash, execute ./deploy.sh. O script verifica a autenticação do GitHub, impede publicação acidental do .env, cria um repositório privado quando não há remoto e envia a branch main. Para verificar um serviço Render já criado, defina RENDER_URL e MCP_TOKEN no ambiente antes de executá-lo.

Para um serviço novo, use o fluxo de Blueprint no Dashboard. A CLI oficial atual usa render services create para criação e render deploys create <SERVICE_ID> para disparar deploys; o comando antigo render deploy --service não é válido.

Cursor / clientes HTTP MCP

{
  "mcpServers": {
    "easy-easy": {
      "url": "https://easy-easy-mcp.onrender.com/mcp",
      "headers": {
        "Authorization": "Bearer SEU_TOKEN",
        "X-User-Id": "UUID_DO_USUARIO"
      }
    }
  }
}

Claude Desktop

Claude Desktop normalmente inicia servidores locais por stdio; uma URL HTTP remota requer um conector/bridge que suporte Streamable HTTP. Quando a versão instalada aceitar servidores MCP remotos, use a mesma URL e os mesmos headers do exemplo acima. Não use npx @modelcontextprotocol/sdk connect: o SDK oficial é uma biblioteca e não fornece esse comando genérico.

Extensão

Crie um novo módulo tool-nome.ts, implemente um handler assíncrono que retorna CallToolResult e registre-o em mcp-server.ts. Cada requisição cria servidor e transporte novos; nenhum estado de usuário é mantido em memória.

Nota de estrutura: este checkout OneDrive recusou a criação de subdiretórios pelo sistema operacional. Por isso os módulos estão na raiz, com prefixos claros. Em um checkout normal, eles podem ser movidos sem mudança de lógica para src/tools, src/auth, src/supabase e src/types, ajustando os imports e rootDir.