README

Notifications

Orchestra MCP Notifications plugin — multi-channel notification dispatch via desktop (NativePHP), Chrome browser, and Firebase Cloud Messaging (FCM).

Features

3 Notification Channels — Desktop (NativePHP), Chrome (browser notifications), FCM (push notifications)
Multi-Channel Dispatch — Send to one or more channels simultaneously
20 Bundled Sound Events — Cross-platform MP3 playback (macOS, Windows, Linux) with volume control
Firebase Cloud Messaging — Push notifications via FCM HTTP v1 API with OAuth2 service account auth
Chrome Integration — Sends to the Orchestra Chrome extension which uses chrome.notifications.create()
Desktop Notifications — Native OS notifications via NativePHP
Event System — NotificationSent and NotificationFailed events for hooks
Notification History — In-memory history of recent notifications
Priority Levels — Low, normal, high, critical with per-channel mapping
4 MCP Tools — Send, status, history, and sounds
2 Artisan Commands — Send notifications and list channel status

Requirements

PHP 8.2+
Laravel 12.x
orchestra-mcp/plugins package

Installation

composer require orchestra-mcp/notifications

The service provider is auto-discovered.

Quick Start

Send a Notification

use OrchestraMcp\Notifications\Facades\Notifications;

Notifications::notify('Build Complete', 'All tests passed.');

Send to Specific Channels

use OrchestraMcp\Notifications\Data\NotificationPayload;
use OrchestraMcp\Notifications\Enums\NotificationChannel;
use OrchestraMcp\Notifications\Facades\Notifications;

$payload = new NotificationPayload(
    title: 'Deploy Complete',
    body: 'v2.1.0 deployed to production.',
    channels: [NotificationChannel::Desktop, NotificationChannel::Fcm],
);

Notifications::send($payload);

Send with Sound

use OrchestraMcp\Notifications\Data\NotificationPayload;
use OrchestraMcp\Notifications\Enums\SoundEvent;
use OrchestraMcp\Notifications\Facades\Notifications;

// Play a sound with a notification
Notifications::send(new NotificationPayload(
    title: 'Build Complete',
    body: 'All tests passed.',
    sound: SoundEvent::Finished->value,
));

// Play a sound directly
Notifications::playSound(SoundEvent::AgentFinished);

Send via Artisan

php artisan notifications:send "Build Complete" "All tests passed."
php artisan notifications:send "Alert" "Server down" --channel=fcm --priority=critical
php artisan notifications:send "Done" "Task finished" --sound=finished

Check Channel Status

php artisan notifications:channels

Channels

Channel	Provider	Config Key	Description
`desktop`	NativePHP	`desktop.enabled`	Native OS notifications
`chrome`	Chrome Extension	`chrome.enabled`	Browser notifications via Chrome extension bridge
`fcm`	Firebase	`fcm.enabled`	Push notifications via FCM HTTP v1 API

MCP Tools

Tool	Description
`notification-send`	Send a notification through one or more channels
`notification-status`	Get all channel statuses and availability
`notification-history`	View recent notification history
`notification-sounds`	List, play, and manage sound events

Artisan Commands

Command	Description
`notifications:send`	Send a notification with title, body, channels, and priority
`notifications:channels`	List all registered channels and availability

Configuration

Publish the config:

php artisan vendor:publish --tag=orchestra-notifications-config

Key	Default	Env Variable	Description
`enabled`	`true`	`ORCHESTRA_NOTIFICATIONS_ENABLED`	Enable/disable notifications plugin
`default_channels`	`['desktop']`	—	Default channels when none specified
`sound.enabled`	`true`	`ORCHESTRA_NOTIFICATIONS_SOUND_ENABLED`	Enable sound playback
`sound.volume`	`80`	`ORCHESTRA_NOTIFICATIONS_SOUND_VOLUME`	Volume level (0–100)
`sound.muted`	`false`	`ORCHESTRA_NOTIFICATIONS_SOUND_MUTED`	Mute all sounds
`sound.sounds_path`	`resources/sounds`	`ORCHESTRA_NOTIFICATIONS_SOUNDS_PATH`	Path to MP3 sound files
`desktop.enabled`	`true`	`ORCHESTRA_NOTIFICATIONS_DESKTOP_ENABLED`	Enable desktop notifications
`chrome.enabled`	`false`	`ORCHESTRA_NOTIFICATIONS_CHROME_ENABLED`	Enable Chrome notifications
`chrome.bridge_url`	`localhost:8787`	`ORCHESTRA_NOTIFICATIONS_CHROME_BRIDGE_URL`	Chrome extension bridge URL
`fcm.enabled`	`false`	`ORCHESTRA_NOTIFICATIONS_FCM_ENABLED`	Enable FCM push notifications
`fcm.project_id`	`null`	`ORCHESTRA_NOTIFICATIONS_FCM_PROJECT_ID`	Firebase project ID
`fcm.credentials_path`	`null`	`ORCHESTRA_NOTIFICATIONS_FCM_CREDENTIALS_PATH`	Path to service account JSON
`fcm.default_topic`	`'orchestra'`	`ORCHESTRA_NOTIFICATIONS_FCM_DEFAULT_TOPIC`	Default FCM topic
`marketplace`	`true`	—	Marketplace visibility

Documentation

Full documentation is available in the docs/ directory:

Getting Started — Installation, configuration
Architecture — Channel system design, data flow
Channels — Desktop, Chrome, FCM channel details
Tools — MCP tool reference
Commands — Artisan command reference
Configuration — Full config key reference
API Reference — Facades, services, events

Development

# Install dependencies
composer install

# Run tests
composer test

# Format code
composer format

# Static analysis
composer check

# Lint
composer lint

License

MIT

orchestra-mcp / notifications

Maintainers

Details