✨ Notifications MCP Server ✨

概述

一个 Model Context Protocol 服务，允许 AI Agent 在任务完成时播放通知音效。这个基于 TypeScript 的 MCP 服务提供了简单、可配置的通知系统，并且内置音效，使用 npx 即可开箱即用！

✨ 功能特性

🔧 工具

• notify - 在任务完成时显示桌面弹出通知和/或播放音效（推荐用于摘要）
  • message（必填）：通知消息／已完成任务的摘要
  • title（可选）：弹出通知的标题（默认为 "Task Completed"）
  • mode（可选）："toast" | "sound" | "both"（默认为 "both"）
  • sound（可选）：要播放的音效名称，可覆盖默认设置
  • 开箱即支持 Windows、macOS 和 Linux！
• play_notification - 播放通知音效以提示任务完成
  • 可选传入 message 参数，用于与通知一起记录／显示
  • 支持跨平台播放音效（Windows、macOS 和 Linux）
  • 支持内置音效——无需手动下载！

🎵 内置音效库

软件包内置 5 种高品质通知音效：

• cosmic - 太空主题通知 🌌
• fairy - 梦幻奇妙的音调 🧚‍♀️
• gentle - 柔和悦耳的默认音效（默认）🔔
• pleasant - 均衡、专业的音调 📞
• retro - 怀旧复古风格通知 🕹️
• random - 随机播放 5 种音效之一 🎲

🚀 快速开始

选项 1：使用内置音效（推荐）⭐

直接使用 npx 运行，音效已包含在内！

{
  "mcpServers": {
    "notifications": {
      "command": "npx",
      "args": ["-y", "@pinkpixel/notification-mcp"]
    }
  }
}

选项 2：选择其他内置音效

{
  "mcpServers": {
    "notifications": {
      "command": "npx",
      "args": ["-y", "@pinkpixel/notification-mcp"],
      "env": {
        "MCP_NOTIFICATION_SOUND": "cosmic"
      }
    }
  }
}

选项 3：每次随机播放音效 🎲

{
  "mcpServers": {
    "notifications": {
      "command": "npx",
      "args": ["-y", "@pinkpixel/notification-mcp"],
      "env": {
        "MCP_NOTIFICATION_SOUND": "random"
      }
    }
  }
}

选项 4：使用自己的自定义音效

{
  "mcpServers": {
    "notifications": {
      "command": "npx",
      "args": ["-y", "@pinkpixel/notification-mcp"],
      "env": {
        "MCP_NOTIFICATION_SOUND_PATH": "C:\\path\\to\\your\\sound.mp3"
      }
    }
  }
}

⚙️ 配置

可以使用环境变量配置通知声音：

环境变量

变量	描述	默认值
MCP_NOTIFICATION_SOUND	从内置声音中选择：cosmic、fairy、gentle、pleasant、retro、random	gentle
MCP_NOTIFICATION_SOUND_PATH	自定义 MP3 文件的绝对路径（优先于内置声音）	null

优先级顺序

1. 自定义路径（MCP_NOTIFICATION_SOUND_PATH）- 最高优先级
2. 内置声音（MCP_NOTIFICATION_SOUND）- 从 5 种内置声音中选择
3. 默认值 - 未指定时使用轻柔的铃声

💻 使用方法

配置完成后，MCP 客户端可以调用统一的 notify 工具或仅播放音频的 play_notification 工具：

1. 统一的 Toast + 声音通知（推荐）

await client.request({
  method: "tools/call",
  params: {
    name: "notify",
    arguments: {
      title: "Build Succeeded",
      message: "Antigravity successfully tested the package version 0.2.0! 🚀",
      mode: "both", // "toast", "sound", or "both"
      sound: "cosmic" // optional override
    }
  }
});

2. 仅音频通知

await client.request({
  method: "tools/call",
  params: {
    name: "play_notification",
    arguments: {
      message: "Task completed successfully! 🎉"
    }
  }
});

🛠️ 开发

本地开发环境设置

# Clone the repository
git clone https://github.com/pinkpixel-dev/notification-mcp.git
cd notification-mcp

# Install dependencies
npm install

# Build the server
npm run build

# For development with auto-rebuild
npm run watch

本地开发配置

{
  "mcpServers": {
    "notifications": {
      "command": "node",
      "args": ["./build/index.js"],
      "env": {
        "MCP_NOTIFICATION_SOUND": "retro"
      }
    }
  }
}

调试

使用 MCP Inspector 进行交互式调试：

npm run inspector

Inspector 提供了一个 Web 界面，可在浏览器中测试你的 MCP 服务。

📦 安装方法

NPX（推荐）

无需安装——声音会自动打包：

npx @pinkpixel/notification-mcp

全局安装

npm install -g @pinkpixel/notification-mcp
notification-mcp

本地安装

npm install @pinkpixel/notification-mcp
npx notification-mcp

🎵 声音文件

所有声音文件都位于 sounds/ 目录中，安装软件包时会自动包含：

• Cosmic：sounds/cosmic_chime.mp3 - 🌌 太空主题
• Fairy：sounds/fairy_chime.mp3 - 🧚‍♀️ 魔法风格
• Gentle：sounds/gentle_chime.mp3 - 🔔 默认（轻柔）
• Pleasant：sounds/pleasant_chime.mp3 - 📞 专业风格
• Retro：sounds/retro_chime.mp3 - 🕹️ 复古风格
• Random：设置 MCP_NOTIFICATION_SOUND=random - 🎲 给我一个惊喜！

🤝 贡献

欢迎贡献！请参阅 CONTRIBUTING.md 了解相关指南。

📄 许可证

本项目采用 MIT 和 Apache 2.0 双重许可协议——详情请参阅 LICENSE 文件。

🌟 关于 Pink Pixel

• 网站： pinkpixel.dev
• GitHub： github.com/pinkpixel-dev
• Discord： @sizzlebop

---

由 Pink Pixel 倾心打造 ✨