# 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:
```bash
cd webhooks-mcp
npm install
```
2. Compile o TypeScript:
```bash
npm run build
```
## Configuração no Claude Desktop
Adicione a seguinte configuração no arquivo `claude_desktop_config.json`:
```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
```json
{
"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
```json
{
"url": "https://api.exemplo.com/dados",
"method": "GET",
"parameters": {
"filtro": "ativo",
"limite": 10,
"pagina": 1
}
}
```
#### 3. PUT com headers personalizados
```json
{
"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
```json
{
"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:
```bash
# 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:
```bash
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:
```bash
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.
```bash
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.
```bash
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 <token>`
- `Content-Type`: deve ser `application/json`, `application/x-www-form-urlencoded` ou `application/xml`
**Exemplo de header válido:**
```json
{
"headers": {
"Authorization": "Bearer token123",
"Content-Type": "application/json"
}
}
```
**Exemplo de header inválido:**
```json
{
"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:
```bash
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:
```bash
npx ts-node src/cli.ts
```
Siga os prompts para informar URL, método, parâmetros e headers.
