Notifications MCP Server

# ✨ Notification MCP Server - Project Overview ✨ *Dream it, Pixel it. Made with ❤️ by Pink Pixel* **Last Updated:** May 31, 2025 --- ## 📋 Project Identity - **Name:** `@pinkpixel/notification-mcp` - **Version:** 0.1.0 - **Author:** Pink Pixel ([pinkpixel.dev](https://pinkpixel.dev)) - **License:** MIT - **Repository:** [github.com/pinkpixel-dev/notification-mcp](https://github.com/pinkpixel-dev/notification-mcp) - **Package Manager:** npm - **Language:** TypeScript (ES2022, Node16) --- ## 🎯 Project Purpose A Model Context Protocol (MCP) server that enables AI agents and LLM applications to play notification sounds when tasks are completed. This tool bridges the gap between silent AI workflows and user awareness by providing audible feedback when important operations finish. **Now with bundled sounds that work out of the box with npx!** --- ## 🏗️ Architecture & Technology Stack ### **Core Framework** - **MCP SDK:** `@modelcontextprotocol/sdk v1.12.1` (Latest stable) - **Runtime:** Node.js with TypeScript ES Modules - **Protocol:** JSON-RPC 2.0 over stdio transport - **Build System:** TypeScript compiler with automated chmod for executable - **Asset Bundling:** MP3 files packaged with npm distribution ### **Project Structure** ``` notification-mcp/ ├── src/ │ └── index.ts # Main MCP server implementation ├── sounds/ # Bundled notification audio files │ ├── cosmic_chime.mp3 # Space-themed notification │ ├── fairy_chime.mp3 # Magical, whimsical tone │ ├── gentle_chime.mp3 # Soft, pleasant default sound │ ├── pleasant_chime.mp3 # Balanced, professional tone │ └── retro_chime.mp3 # Nostalgic, vintage-style notification ├── build/ # Compiled output directory ├── package.json # npm configuration & dependencies ├── tsconfig.json # TypeScript compiler settings ├── README.md # User documentation ├── OVERVIEW.md # This comprehensive project overview ├── CHANGELOG.md # Version history and changes ├── CONTRIBUTING.md # Contribution guidelines └── LICENSE # MIT license ``` ### **MCP Compliance** - Follows MCP Specification 2025-03-26 (Latest) - Implements server-side capabilities only - Uses stdio transport for host communication - Provides capability negotiation and tool exposure --- ## ⚙️ Core Functionality ### **Primary Tool: `play_notification`** - **Type:** MCP Tool - **Purpose:** Play audio notification sounds with bundled asset support - **Parameters:** - `message` (optional string): Custom notification message - **Cross-Platform Support:** - **Windows:** Uses `start` command - **macOS:** Uses `afplay` command - **Asset Resolution:** Uses `import.meta.url` for reliable npx compatibility - **Error Handling:** Graceful failure with detailed error messages ### **Enhanced Configuration System** - **Environment Variables:** - `MCP_NOTIFICATION_SOUND`: Choose from bundled sounds (`cosmic`, `fairy`, `gentle`, `pleasant`, `retro`, `random`) - `MCP_NOTIFICATION_SOUND_PATH`: Custom absolute path to MP3 file (overrides bundled) - **Priority Order:** 1. Custom path (highest priority) 2. Bundled sound selection (including random) 3. Default gentle chime - **Random Selection:** When set to `random`, randomly picks one of the 5 bundled sounds each time - **Asset Location:** Uses `path.join(__dirname, '..', soundFile)` for npx compatibility --- ## 🔧 Dependencies & Build System ### **Production Dependencies** - `@modelcontextprotocol/sdk: 1.12.1` - Official MCP SDK for TypeScript ### **Development Dependencies** - `@types/node: ^22.15.26` - Node.js type definitions - `typescript: ^5.8.3` - TypeScript compiler ### **Build Process** 1. TypeScript compilation (`tsc`) 2. Executable permissions setup (`chmod 755`) 3. Asset bundling (sounds directory included in npm package) 4. Prepared for npm distribution with bundled assets ### **Package Distribution** - **Files included:** `build/`, `sounds/` - **Binary entry:** `./build/index.js` - **NPX compatibility:** Full asset resolution support ### **Available Scripts** - `npm run build` - Compile and prepare for distribution - `npm run prepare` - Auto-build on install - `npm run watch` - Development with auto-rebuild - `npm run inspector` - MCP debugging tools --- ## 🚀 Installation & Usage ### **Installation Methods** #### NPX (Recommended - Bundled Sounds) ⭐ ```json { "mcpServers": { "notifications": { "command": "npx", "args": ["-y", "@pinkpixel/notification-mcp"] } } } ``` #### Choose Bundled Sound ```json { "mcpServers": { "notifications": { "command": "npx", "args": ["-y", "@pinkpixel/notification-mcp"], "env": { "MCP_NOTIFICATION_SOUND": "cosmic" } } } } ``` #### Custom Sound File ```json { "mcpServers": { "notifications": { "command": "npx", "args": ["-y", "@pinkpixel/notification-mcp"], "env": { "MCP_NOTIFICATION_SOUND_PATH": "C:\\path\\to\\sound.mp3" } } } } ``` #### Local Development ```json { "mcpServers": { "notifications": { "command": "node", "args": ["./build/index.js"], "env": { "MCP_NOTIFICATION_SOUND": "retro" } } } } ``` ### **Usage Example** ```typescript await client.request({ method: "tools/call", params: { name: "play_notification", arguments: { message: "Task completed successfully! 🎉" } } }); ``` --- ## 🔒 Security & Compliance ### **Security Features** - **Sandboxed Execution:** Runs in isolated stdio transport - **No Network Access:** Local-only operation - **File System Limits:** Only accesses bundled/configured MP3 files - **Error Containment:** Graceful failure without system compromise - **Asset Validation:** Secure path resolution using Node.js built-ins ### **MCP Security Alignment** - Follows MCP security principles - Requires explicit user consent for tool execution - No access to conversation history - Isolated from other MCP servers - Host-controlled authorization --- ## 📊 Project Metrics ### **Code Statistics** - **Total Lines of Code:** ~100 lines (main implementation) - **Language Distribution:** 100% TypeScript - **Complexity:** Low (single-purpose tool) - **Dependencies:** Minimal (1 production dependency) - **Asset Size:** ~40KB total (5 MP3 files) ### **File Inventory** - **Source Files:** 1 (index.ts) - **Configuration Files:** 3 (package.json, tsconfig.json, .gitignore) - **Documentation:** 4 (README.md, OVERVIEW.md, CHANGELOG.md, CONTRIBUTING.md) - **Legal:** 1 (LICENSE) - **Audio Assets:** 5 MP3 files (bundled in sounds/) - **Build Artifacts:** Generated in build/ directory --- ## 🎵 Audio Assets ### **Bundled Notification Sounds** 1. **cosmic_chime.mp3** - 🌌 Space-themed notification 2. **fairy_chime.mp3** - 🧚‍♀️ Magical, whimsical tone 3. **gentle_chime.mp3** - 🔔 Soft, pleasant default sound 4. **pleasant_chime.mp3** - 📞 Balanced, professional tone 5. **retro_chime.mp3** - 🕹️ Nostalgic, vintage-style notification *All sounds are included in the npm package and work automatically with npx.* --- ## 🔍 Development & Debugging ### **Development Workflow** 1. Clone repository 2. Run `npm install` 3. Use `npm run watch` for development 4. Test with `npm run inspector` 5. Build with `npm run build` ### **Debugging Tools** - **MCP Inspector:** Interactive debugging interface - **Stdio Transport:** Standard protocol debugging - **Error Logging:** Comprehensive error reporting - **Platform Detection:** Cross-platform compatibility checks - **Asset Resolution:** Debug bundled file paths --- ## 🛠️ Extensibility & Future Enhancements ### **Potential Improvements** - **Linux support** (pulseaudio/aplay) - **Volume control** configuration - **Multiple notification types** - **Integration with system notifications** - **Playlist support** for sequential notifications - **Sound rotation** (auto-cycle through sounds) ### **Integration Opportunities** - Task management systems - CI/CD pipelines - Development environments - Productivity applications - Automation workflows --- ## 📝 Documentation Status ### **Available Documentation** - ✅ README.md - Comprehensive user guide with bundled sound examples - ✅ OVERVIEW.md - Complete project analysis (this document) - ✅ CHANGELOG.md - Version history and changes - ✅ CONTRIBUTING.md - Contribution guidelines and development setup - ✅ LICENSE - MIT license - ✅ Package.json - Complete metadata with bundled asset configuration - ✅ TypeScript configuration - ✅ MCP protocol compliance - ✅ Installation instructions for all methods ### **Documentation Quality** - **User-Friendly:** Clear installation steps for npx/bundled sounds - **Technical:** Complete API documentation - **Examples:** Working code samples for all configuration methods - **Troubleshooting:** Error handling guidance - **Cross-Platform:** Windows and macOS support - **Community:** Contributing guidelines and development setup --- ## 🎯 Project Status ### **Current State** - ✅ **Stable:** Ready for production use - ✅ **Published:** Available on npm registry with bundled assets - ✅ **Documented:** Comprehensive documentation suite - ✅ **Tested:** MCP Inspector compatible - ✅ **Cross-Platform:** Windows and macOS support - ✅ **NPX Ready:** Full npx compatibility with bundled sounds - ✅ **Community Ready:** Contributing guidelines and MIT license ### **Recent Major Improvements** - **Bundled Sound Assets:** MP3s now included in npm package - **NPX Compatibility:** Works out-of-the-box with npx using `import.meta.url` - **Enhanced Configuration:** Multiple ways to configure sounds - **Better Documentation:** Complete documentation suite - **Community Support:** Contributing guidelines and MIT license ### **Maintenance Level** - **Active Development:** Pink Pixel maintained - **Community Ready:** Open source contributions welcome - **MCP Compliant:** Follows latest MCP specification - **Semantic Versioning:** Professional release management --- *This overview was generated on May 31, 2025, based on comprehensive analysis of the notification-mcp codebase and recent improvements including bundled sound support and enhanced npx compatibility.* **Analysis Depth:** Complete codebase review, dependency analysis, asset bundling assessment, and comprehensive documentation review