Ai Notify MCP

Ai Notify MCP

🎯 Servidor de notificações inteligente projetado para editores de código com IA que suportam o protocolo MCP. Envia notificações do sistema automaticamente quando a IA conclui uma resposta, melhorando a experiência de programação.

📑 Índice

• Recursos
• Instalação e Configuração
• Instruções de Uso
• Guia de Desenvolvimento
• Solução de Problemas
• Guia de Contribuição

✨ Recursos

🔔 Suporte a Notificações Multiplataforma

🎨 Altamente Personalizável

• Título Inteligente: Exibe automaticamente o nome do projeto atual
• Conteúdo Flexível: Suporta mensagens de notificação personalizadas
• Personalização de Ícones: Suporta ícones de notificação personalizados
• Controle de Som: Permite ativar/desativar sons de alerta

🤖 Disparo Inteligente

• Notificação Automática: Disparada automaticamente quando a IA conclui a resposta
• Controle Manual: Suporta chamadas programáticas de notificação

📦 Instalação e Configuração

Requisitos do Sistema

Instalação do libnotify para usuários Linux

# Ubuntu/Debian
sudo apt-get install libnotify-bin

# CentOS/RHEL/Fedora
sudo dnf install libnotify  # 或 yum install libnotify

# Arch Linux
sudo pacman -S libnotify

# openSUSE
sudo zypper install libnotify-tools

Etapas Detalhadas de Instalação

1️⃣ Clonar o Projeto

git clone https://github.com/zhiyingzzhou/ai-notify-mcp.git
cd ai-notify-mcp

2️⃣ Instalar Dependências e Compilar

npm install
npm run build

3️⃣ Configurar o Editor

Edite o arquivo de configuração MCP e adicione a seguinte configuração:

{
  "mcpServers": {
    "ai-notify": {
      "command": "node",
      "args": ["/绝对路径/ai-notify-mcp/dist/index.js"],
      "autoRun": true
    }
  }
}

💡 Dica: Substitua o caminho pelo seu caminho real de instalação

4️⃣ Configurar as Regras do Assistente de IA

Em Cursor Settings → Rules → User Rules, adicione:

When responding to user requests, use the ai-notify MCP tool (auto_notify_completion) only as the final step after you have fully completed your answer. Never call this tool during thinking phases, tool calls, or before your answer is complete. The notification should only be triggered when the entire response is ready for the user.

5️⃣ Ativar o Modo Auto-Run

Etapas de Configuração:

1. Abra Cursor Settings → Features → Chat
2. Marque Enable auto-run mode
3. Reinicie o Cursor

🛠 Instruções de Uso

📋 Ferramentas Disponíveis

Este serviço MCP fornece as duas ferramentas a seguir para uso pela IA:

🔧 show_completion_notification

Função: Dispara notificações manualmente, com suporte a parâmetros personalizados

🤖 auto_notify_completion

Função: Ferramenta de notificação automática, chamada automaticamente após a conclusão da resposta da IA

⚙️ Configuração de Notificações

Você pode personalizar o comportamento das notificações através do arquivo de configuração:

{
  "notification": {
    "sound": true,
    "icon": "./assets/icon.png",
    "defaultTitle": "Cursor AI",
    "defaultMessage": "回答完成"
  }
}

Descrição das Opções de Configuração:

🎨 Recomendações de Especificação de Ícones

🔧 Guia de Desenvolvimento

Ambiente de Desenvolvimento

# 开发模式（热重载）
npm run dev

# 构建项目
npm run build

# 启动服务
npm start

# 类型检查
npm run type-check

Estrutura do Projeto

ai-notify-mcp/
├── 📁 src/
│   └── 📄 index.ts          # 主入口文件
├── 📁 dist/                 # 构建输出
├── 📁 assets/               # 资源文件
│   ├── 🖼️ icon.png          # 默认图标
│   └── 🖼️ cursor-auto-run.jpg # 配置截图
├── 📄 package.json          # 项目配置
├── 📄 tsconfig.json         # TypeScript 配置
└── 📄 README.md            # 项目文档

Desenvolvimento de Extensões

// 自定义通知处理器示例
import { NotificationHandler } from './types';

const customHandler: NotificationHandler = {
  async show(options) {
    // 你的自定义逻辑
    console.log(`显示通知: ${options.title}`);
  }
};

🔍 Solução de Problemas

🔧 Problemas Comuns

# 检查进程是否运行
ps aux | grep "ai-notify"

# 手动测试通知
node dist/index.js test

# 查看 MCP 服务状态
curl -X POST http://localhost:3000/test

# 1. 安装必要依赖
sudo apt-get install libnotify-bin

# 2. 测试系统通知
notify-send "测试" "通知功能正常"

# 3. 检查 D-Bus 服务
systemctl --user status dbus

# 4. 检查通知守护进程
ps aux | grep notification

📊 Modo de Depuração

Ative logs detalhados para visualizar o status de execução:

# 启用所有调试信息
DEBUG=* npm start

# 仅查看通知相关日志
DEBUG=mcp:notification npm start

# 保存日志到文件
DEBUG=mcp:notification npm start 2>&1 | tee debug.log

🆘 Obter Ajuda

Se nenhum dos métodos acima resolver o problema, por favor:

1. Colete informações do sistema

   echo "OS: $(uname -a)"
   echo "Node: $(node --version)"
   echo "npm: $(npm --version)"
   

2. Crie um Issue detalhado, incluindo:

   • Informações do sistema
   • Logs de erro
   • Arquivo de configuração
   • Etapas para reproduzir o problema

🤝 Guia de Contribuição

Aceitamos contribuições de todos os tipos! Vamos tornar este projeto melhor juntos 🚀

🎯 Formas de Contribuir

🔄 Fluxo de Desenvolvimento

1️⃣ Preparar o Ambiente

# Fork 并克隆项目
git clone https://github.com/your-username/ai-notify-mcp.git
cd ai-notify-mcp

# 安装依赖
npm install

2️⃣ Criar um Branch de Funcionalidade

git checkout -b feature/amazing-feature
# 或者修复分支
git checkout -b fix/issue-123

3️⃣ Desenvolver e Testar

npm run dev      # 开发模式（热重载）
npm run test     # 运行测试
npm run lint     # 代码检查
npm run build    # 构建验证

4️⃣ Enviar as Alterações

# 使用约定式提交
git commit -m "feat: add amazing feature"
git commit -m "fix: resolve notification issue"
git commit -m "docs: update installation guide"

git push origin feature/amazing-feature

5️⃣ Criar um Pull Request

📋 Padrões de Código

💡 Recomendações de Desenvolvimento

• 🔍 Antes de enviar: Garanta que todos os testes passem
• 📚 Documentação: Adicione explicações para funcionalidades complexas
• 🧪 Testes: Escreva testes unitários e de integração
• 🎨 Código: Mantenha o código limpo e legível
• 💬 Comunicação: Discuta dúvidas prontamente nos Issues

📄 Licença

Este projeto é licenciado sob a Licença MIT.

🙏 Agradecimentos

Agradecemos a todas as pessoas e organizações que tornaram este projeto possível:

• 🏛️ Equipe do Protocolo MCP - Por fornecer um excelente padrão de protocolo
• 🌍 Comunidade Open Source - Por fornecer feedback e contribuições valiosas
• 👥 Todos os Contribuidores - Por tornar este projeto melhor
• 💻 Equipes de Desenvolvimento de Editores - Por suportar a implementação do protocolo MCP

📞 Suporte e Feedback

Encontrou problemas ou tem sugestões? Adoraríamos ouvir sua opinião!

💌 Fale Conosco

• Tem dúvidas sobre o projeto? Consulte primeiro a Solução de Problemas
• Encontrou um bug? Crie um Issue detalhado