Webhooks MCP

Um servidor MCP (Model Context Protocol) para enviar requisições HTTP para webhooks com parâmetros dinâmicos.

Funcionalidades

• ✅ Suporte a todos os métodos HTTP: GET, POST, PUT, PATCH, DELETE
• ✅ Parâmetros dinâmicos de qualquer tipo (nome, email, telefone, etc.)
• ✅ Headers HTTP personalizados
• ✅ Timeout configurável
• ✅ Validação de entrada com Zod
• ✅ Tratamento de erros detalhado
• ✅ Logs de requisição e resposta

Instalação

1. As dependências já estão instaladas. Para reinstalar se necessário:

cd webhooks-mcp
npm install

2. Compile o TypeScript:

npm run build

Configuração no Claude Desktop

Adicione a seguinte configuração no arquivo `claude_desktop_config.json`:

{
  "mcpServers": {
    "webhooks": {
      "command": "node",
      "args": ["/Users/rafabarbosa/Desktop/scripts/webhooks-mcp/dist/index.js"]
    }
  }
}

Localização do arquivo de configuração:

• macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`

Uso

Ferramenta Disponível

`send_webhook`

Envia uma requisição HTTP para um webhook com parâmetros personalizados.

Parâmetros:

• `url` (obrigatório): URL do webhook (ex: https://meuwebhook.com.br)
• `method` (obrigatório): Método HTTP (GET, POST, PUT, PATCH, DELETE)
• `parameters` (opcional): Objeto com parâmetros de qualquer tipo
• `headers` (opcional): Headers HTTP adicionais
• `timeout` (opcional): Timeout em milissegundos (padrão: 30000)

Exemplos de Uso

1. POST com dados de usuário

{
  "url": "https://meuwebhook.com.br/usuarios",
  "method": "POST",
  "parameters": {
    "nome": "João Silva",
    "email": "joao@email.com",
    "telefone": "11999999999",
    "idade": 30,
    "ativo": true
  }
}

2. GET com query parameters

{
  "url": "https://api.exemplo.com/dados",
  "method": "GET",
  "parameters": {
    "filtro": "ativo",
    "limite": 10,
    "pagina": 1
  }
}

3. PUT com headers personalizados

{
  "url": "https://api.exemplo.com/atualizar/123",
  "method": "PUT",
  "parameters": {
    "nome": "João Santos",
    "status": "atualizado"
  },
  "headers": {
    "Authorization": "Bearer token123",
    "X-Custom-Header": "valor"
  }
}

4. DELETE simples

{
  "url": "https://api.exemplo.com/deletar/123",
  "method": "DELETE"
}

Comportamento por Método HTTP

• GET/DELETE: Parâmetros são enviados como query parameters na URL
• POST/PUT/PATCH: Parâmetros são enviados no body da requisição como JSON

Tratamento de Erros

O MCP trata diferentes tipos de erro:

• Erros de validação: Quando os parâmetros não estão no formato correto
• Erros HTTP: Quando o webhook retorna status de erro (4xx, 5xx)
• Erros de rede: Timeout, conexão recusada, etc.

Desenvolvimento

Scripts disponíveis

• `npm run build`: Compila o TypeScript
• `npm run dev`: Compila em modo watch
• `npm start`: Executa o servidor compilado

Estrutura do projeto

webhooks-mcp/
├── src/
│   └── index.ts          # Servidor MCP principal
├── dist/                 # Arquivos compilados
├── examples.json         # Exemplos de uso
├── claude_desktop_config.json  # Configuração de exemplo
├── package.json
├── tsconfig.json
└── README.md

Testando o Servidor

Para testar se o servidor está funcionando:

# Compilar
npm run build

# Testar execução (pressione Ctrl+C para sair)
node dist/index.js

# Rodar testes automatizados
npm test

# Os exemplos do arquivo examples.json são validados automaticamente por testes automatizados.

Logs

O servidor gera logs detalhados:

• Requisições enviadas (método, URL, parâmetros)
• Respostas recebidas (status, tempo de resposta)
• Erros detalhados com contexto

Segurança

• Validação rigorosa de entrada com Zod
• Headers de User-Agent identificando o MCP
• Timeout configurável para evitar requisições infinitas
• Tratamento seguro de erros sem exposição de dados sensíveis
• Whitelist de URLs/domínios: configure a variável de ambiente `WHITELIST_URLS` (separada por vírgula) para restringir os destinos permitidos. Exemplo:

export WHITELIST_URLS="api.exemplo.com,https://hooks.slack.com"

Se não configurada, qualquer URL será permitida.

• Níveis de log configuráveis: defina a variável de ambiente `LOG_LEVEL` para controlar a verbosidade dos logs (`debug`, `info`, `warn`, `error`). Exemplo:

export LOG_LEVEL="debug"

• Retentativas automáticas: defina as variáveis de ambiente `RETRY_ATTEMPTS` (número de tentativas, padrão 1) e `RETRY_BASE_DELAY_MS` (delay inicial em ms, padrão 500) para habilitar retentativas automáticas com backoff exponencial em falhas temporárias.

export RETRY_ATTEMPTS=3
export RETRY_BASE_DELAY_MS=1000

• Internacionalização (i18n): defina a variável de ambiente `LANG` como `pt` (padrão) ou `en` para receber mensagens em português ou inglês.

export LANG=en

Exemplos de Respostas de Erro

• Erro de validação de parâmetros:

{
  "content": [
    {
      "type": "text",
      "text": "❌ Erro ao enviar webhook!\n\n**Erro:** Erro de validação dos parâmetros\n\n**Detalhes:**\n{...}"
    }
  ],
  "isError": true
}

• Erro HTTP (exemplo 500):

{
  "content": [
    {
      "type": "text",
      "text": "❌ Erro ao enviar webhook!\n\n**Erro:** Erro HTTP: Request failed with status code 500\n\n**Detalhes:**\n{...}"
    }
  ],
  "isError": true
}

• URL não permitida (whitelist):

{
  "content": [
    {
      "type": "text",
      "text": "❌ URL não permitida pelo servidor (whitelist).\n\nConsulte o administrador para liberar o domínio ou URL desejada."
    }
  ],
  "isError": true
}

Validação de Headers HTTP

Alguns headers são validados automaticamente:

• `Authorization`: deve ser no formato `Bearer `
• `Content-Type`: deve ser `application/json`, `application/x-www-form-urlencoded` ou `application/xml`

Exemplo de header válido:

{
  "headers": {
    "Authorization": "Bearer token123",
    "Content-Type": "application/json"
  }
}

Exemplo de header inválido:

{
  "headers": {
    "Authorization": "Token 123",
    "Content-Type": "text/plain"
  }
}

FAQ

Como configuro domínios permitidos?

Defina a variável de ambiente `WHITELIST_URLS` com uma lista separada por vírgula dos domínios ou URLs permitidos.

Como habilito logs mais detalhados?

Defina `LOG_LEVEL=debug` para ver logs detalhados.

Como habilito retentativas automáticas?

Defina `RETRY_ATTEMPTS` e `RETRY_BASE_DELAY_MS` conforme desejado.

Como executo os testes automatizados?

Basta rodar `npm test` na raiz do projeto.

Como reportar um bug ou sugerir melhoria?

Abra uma issue no repositório do GitHub.

Próximos Passos

1. Configure o Claude Desktop: Adicione a configuração no arquivo `claude_desktop_config.json`

2. Reinicie o Claude Desktop: Para carregar a nova configuração

3. Teste o MCP: Use o Claude para enviar webhooks com diferentes parâmetros

Exemplos Práticos

Veja o arquivo `examples.json` para exemplos detalhados de como usar o MCP em diferentes cenários:

• Cadastro de usuários
• Integrações com CRM
• Notificações Slack
• Processamento de pagamentos
• E muito mais!

Deploy com Docker

Você pode rodar o MCP facilmente usando Docker:

docker build -t webhook-mcp .
docker run --rm -p 3000:3000 \
  -e WHITELIST_URLS="api.exemplo.com" \
  -e LOG_LEVEL=info \
  -e RETRY_ATTEMPTS=3 \
  webhook-mcp

Adapte as variáveis de ambiente conforme necessário.

CLI Interativa

Você pode testar webhooks manualmente pelo terminal:

npx ts-node src/cli.ts

Siga os prompts para informar URL, método, parâmetros e headers.