NotifyMeMaybe

NotifyMeMaybe

Um poderoso servidor MCP (Model Context Protocol) para notificações multiplataforma e fluxos de trabalho interativos de IA

🚀 TLDR - Início Rápido

Comece em 2 minutos:

1. Crie um Bot do Telegram:

   • Envie mensagem para @BotFather no Telegram
   • Use /newbot para criar um bot e obter seu BOT_TOKEN
   • Inicie uma conversa com seu bot e obtenha seu CHAT_ID

2. Adicione à Configuração MCP:

   {
     "mcpServers": {
       "notify-me-maybe": {
         "command": "npx",
         "args": ["-y", "notify-me-maybe-mcp"],
         "env": {
           "TELEGRAM_BOT_TOKEN": "your_bot_token_here",
           "TELEGRAM_CHAT_ID": "your_chat_id_here",
           "TELEGRAM_PROMPT_ENABLED": "true",
           "TELEGRAM_INTERACTION_ENABLED": "true",
           "DEFAULT_NOTIFICATION_SERVICE": "telegram",
           "LANGUAGE": "en"
         }
       }
     }
   }
   

3. Reinicie Seu Assistente de IA:

   • Claude Desktop: Reinicie o aplicativo
   • Cursor: Reinicie e ative a configuração MCP

4. Teste: Peça ao seu assistente de IA para enviar uma notificação!

É isso! 🎉 Sem instalação, sem clonagem, sem compilação necessária.

---

🌐 Suporte a Idiomas

• Inglês (Atual) - Você está aqui
• 繁體中文 - Chinês Tradicional
• 简体中文 - Chinês Simplificado

🤖 Integração com Assistente de IA (Prompts de Agente)

Pronto para integrar com seu assistente de IA? Escolha a configuração de prompt certa para suas necessidades:

📋 Configurações de Prompt de Agente Disponíveis

Tipo de Prompt	Descrição	Melhor Para	Ferramentas Principais
Somente Notificação	Notificações simples de conclusão de tarefas	Necessidades básicas de notificação	send_notification, broadcast_notification
Interativo Básico	Interações do Telegram + notificações	Entrada do usuário e confirmações	request_interaction_sync, send_notification
Interativo Avançado	Fluxo de trabalho contínuo com prompts de acompanhamento	Tarefas complexas de múltiplas etapas	get_telegram_prompts, process_telegram_prompt, request_interaction_sync

🎯 Início Rápido para Assistentes de IA

1. Escolha um tipo de prompt abaixo
2. Copie a configuração completa do prompt
3. Adicione ao prompt de sistema do seu assistente de IA (Cursor, Claude, etc.)
4. Configure seus serviços NotifyMeMaybe
5. Comece a receber notificações e interações!

Recursos

🔔 Notificações Multicanal

• Integração com Telegram: Envie notificações diretamente para conversas do Telegram
• Suporte a Webhooks: Notificações via webhook HTTP para integrações personalizadas
• Níveis de Prioridade: Notificações de prioridade alta, normal e baixa
• Metadados Ricos: Anexe dados personalizados às notificações

🤖 Mecanismo de Prompt Interativo

O recurso principal do NotifyMeMaybe é seu sofisticado mecanismo de prompt que permite comunicação bidirecional entre sistemas de IA e usuários:

Tipos de Interação

• Solicitações de Confirmação: Decisões Sim/Não com interface de botões
• Prompts de Texto: Coleta de entrada de texto dos usuários
• Menus de Seleção: Opções de múltipla escolha com botões personalizados
• Síncrono e Assíncrono: Interações em tempo real e em fila

Integração com Fluxos de Trabalho de IA

• Compatível com MCP (Model Context Protocol): Integra-se perfeitamente com Claude e outros sistemas de IA
• Gerenciamento de Timeout: Timeouts configuráveis com tratamento de fallback
• Gerenciamento de Fila: Lida com múltiplas interações simultâneas de usuários
• Validação de Respostas: Garante a formatação adequada das respostas do usuário

Recursos Avançados

• Rejeição Automática: Lida automaticamente com interações expiradas
• Notificações de Broadcast: Envia para todos os canais ativos simultaneamente
• Monitoramento de Saúde do Serviço: Status em tempo real de todos os serviços de notificação
• Internacionalização: Suporte a múltiplos idiomas (Inglês, Chinês Tradicional, Chinês Simplificado)

Configurações de Prompt de Agente

1. 📢 Modo Somente Notificação

Copie esta configuração de prompt para seu assistente de IA:

## NotifyMeMaybe Notification-Only Mode Configuration

### When to use NotifyMeMaybe tools:
- **ALWAYS** notify when tasks are completed
- Send progress updates for long-running operations
- Notify on errors or important status changes

### Required MCP Tools Usage:

#### Task Completion Notifications:
Use `send_notification` or `broadcast_notification` when:
- Any task is completed successfully
- An error occurs during task execution
- Important milestones are reached

Parameters:
- service: "telegram" (or use broadcast_notification for all services)
- title: Clear, concise summary of what was accomplished
- message: Detailed results, file paths, URLs, or error details
- priority: "high" (errors), "normal" (completions), "low" (progress updates)
- metadata: Include relevant context like file paths, timestamps, etc.

#### Example Usage:
send_notification(
  service="telegram",
  title="Task Completed: Code Analysis",
  message="Successfully analyzed 15 files and found 3 potential issues. Results saved to /reports/analysis.json",
  priority="normal",
  metadata={"files_analyzed": 15, "issues_found": 3, "report_path": "/reports/analysis.json"}
)

### Service Health Check:
Use `test_services` periodically to ensure services are available.

2. 🔄 Modo Interativo

Copie esta configuração de prompt para seu assistente de IA:

## NotifyMeMaybe Interactive Mode Configuration

### When to use NotifyMeMaybe tools:
- Request user input when clarification is needed
- Ask for confirmations before major operations
- Provide selection menus for user choices
- Send completion notifications

### Required MCP Tools Usage:

#### User Interaction Requests:
Use `request_interaction_sync` when:
- You need user confirmation before proceeding
- You require text input from the user
- You want to offer multiple choice options

Parameters:
- type: "confirmation" (Yes/No), "prompt" (text input), "selection" (multiple choice)
- message: Clear question or request for user
- options: Array of choices (only for type="selection")
- timeout: 60000 (60 seconds) or appropriate timeout

#### Examples:

Confirmation Request:
request_interaction_sync(
  type="confirmation",
  message="Do you want to proceed with deleting 5 files from the project directory?"
)

Text Input Request:
request_interaction_sync(
  type="prompt",
  message="Please provide the target deployment environment (staging/production):"
)

Selection Menu:
request_interaction_sync(
  type="selection",
  message="Choose the deployment strategy:",
  options=["Blue-Green Deployment", "Rolling Update", "Canary Release"]
)

#### Completion Notifications:
Always send completion notifications using `send_notification` after tasks finish.

#### Error Handling:
- Handle interaction timeouts gracefully
- Provide fallback responses if user doesn't respond
- Use high priority notifications for critical errors

3. 🚀 Modo Interativo Avançado

Copie esta configuração completa de prompt para seu assistente de IA:

## NotifyMeMaybe Advanced Interactive Mode Configuration

### Core Agent Behavior Rules:
- **ALWAYS** check for new Telegram prompts at session start
- **NEVER** end a session without asking for additional requests
- **ALWAYS** process pending prompts before starting new tasks
- **ALWAYS** send progress notifications for long operations

### Required MCP Tools Usage Protocol:

#### 1. Session Start Protocol:
ALWAYS execute at the beginning of each session:

1. Check for pending prompts:
   get_telegram_prompts()

2. If prompts exist, process each one:
   process_telegram_prompt(
     promptId="<prompt_id>",
     response="Received your request. Processing now..."
   )

3. Send status notification:
   send_notification(
     service="telegram",
     title="AI Session Started",
     message="Processing your Telegram requests. Session active.",
     priority="normal"
   )

#### 2. Task Execution Protocol:
During task execution:

1. Send progress updates for long operations:
   send_notification(
     service="telegram",
     title="Progress Update",
     message="Step 2/5 completed: Database backup finished",
     priority="normal",
     metadata={"step": 2, "total_steps": 5}
   )

2. Use interactions when user input needed:
   request_interaction_sync(
     type="confirmation",
     message="Ready to proceed with database migration. Continue?"
   )

3. Handle errors with high priority:
   send_notification(
     service="telegram",
     title="Error Occurred",
     message="Database connection failed. Retrying in 30 seconds...",
     priority="high"
   )

#### 3. Session End Protocol:
**MANDATORY**: Never end without this sequence:

1. Send completion notification:
   send_notification(
     service="telegram",
     title="Task Completed Successfully",
     message="All requested operations completed. Summary: [detailed results]",
     priority="normal"
   )

2. ALWAYS ask for additional requests:
   request_interaction_sync(
     type="prompt",
     message="Task completed successfully. Do you have any additional instructions or follow-up requests?",
     timeout=60000
   )

3. Continue interaction loop until user indicates completion
4. Only stop when user explicitly says "finished", "done", "no more tasks", or similar

#### 4. Telegram Prompt Monitoring:
Regularly check for new prompts:
- Use get_telegram_prompts() to check queue
- Process immediately with process_telegram_prompt()
- Prioritize user prompts over automated tasks

#### 5. Service Health Monitoring:
Periodically verify services:
test_services()
get_service_status(service="telegram")

### Advanced Mode Benefits:
- Users can send tasks anytime via Telegram
- AI automatically processes queued requests
- Continuous workflow without manual intervention
- Comprehensive progress tracking
- Error recovery with user guidance

📦 Instalação e Configuração

🌟 Método 1: NPX (Recomendado)

Adicione ao seu arquivo de configuração MCP:

Locais dos Arquivos de Configuração:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "notify-me-maybe": {
      "command": "npx",
      "args": ["-y", "notify-me-maybe-mcp"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "your_bot_token_here",
        "TELEGRAM_CHAT_ID": "your_chat_id_here",
        "TELEGRAM_PROMPT_ENABLED": "true",
        "TELEGRAM_INTERACTION_ENABLED": "true",
        "DEFAULT_NOTIFICATION_SERVICE": "telegram",
        "LANGUAGE": "en"
      }
    }
  }
}

⚠️ Importante: Após a configuração, reinicie completamente seu assistente de IA.

🛠️ Método 2: Desenvolvimento Local

Para desenvolvedores que desejam modificar o código:

git clone https://github.com/keoy7am/NotifyMeMaybe.git
cd NotifyMeMaybe
npm install
npm run build

📱 Obtendo Credenciais do Telegram

1. Crie um Bot: Envie mensagem para @BotFather → /newbot
2. Obtenha o ID da Conversa: Envie uma mensagem para seu bot, visite https://api.telegram.org/bot<TOKEN>/getUpdates

🔧 Configuração

Variáveis Obrigatórias

TELEGRAM_BOT_TOKEN=your_bot_token_here
TELEGRAM_CHAT_ID=your_chat_id_here

Variáveis Opcionais

TELEGRAM_PROMPT_ENABLED=true
TELEGRAM_INTERACTION_ENABLED=true
DEFAULT_NOTIFICATION_SERVICE=telegram
LANGUAGE=en

🛠️ Ferramentas MCP

• send_notification: Enviar para serviço específico
• broadcast_notification: Enviar para todos os serviços
• request_interaction_sync: Interação síncrona com o usuário
• test_services: Verificação de saúde de todos os serviços
• get_telegram_prompts: Recuperar prompts pendentes
• process_telegram_prompt: Processar prompts do Telegram

🤝 Contribuindo

Contribuições são bem-vindas! Por favor:

1. Faça um fork do repositório
2. Crie um branch de funcionalidade
3. Envie um pull request

📄 Licença

Licença MIT - consulte o arquivo LICENSE para detalhes.

🎯 Pronto para Começar?

Início Rápido (Recomendado)

1. Obtenha o token do bot do Telegram
2. Adicione a configuração MCP
3. Reinicie seu assistente de IA
4. Teste com uma notificação!

Configuração Avançada

1. Escolha uma Configuração de Prompt de Agente
2. Copie para o prompt de sistema do seu assistente de IA
3. Configure recursos avançados
4. Crie fluxos de trabalho interativos!

📦 Pacote NPM

npm view notify-me-maybe-mcp
npx notify-me-maybe-mcp  # Use directly

NotifyMeMaybe - Tornando a interação IA-humano perfeita! 🚀

💡 Dica Profissional: Não se esqueça de reiniciar seu assistente de IA após a configuração!