README

Tray

Orchestra MCP Tray plugin — provides a system tray service with extensible menu contributions, a driver-based architecture, and priority-sorted menu building from active plugins.

Features

Driver Pattern — Swappable tray backends: NativeTrayDriver (NativePHP), NullTrayDriver (no-op for testing), or auto-detection
Menu Contributions — Plugins implement HasTrayMenu to contribute items with priority-based sorting and group separators
4 Menu Item Types — Label, separator, checkbox, and submenu via TrayMenuItem static factories
Menu Groups — Organize contributions into named groups with priority and nesting
4 Events — TrayCreated, TrayClicked, TrayMenuRebuilt, MenuContributionRegistered
Desktop Integration — Implements HasNativeBootCallbacks for automatic tray boot via the desktop package

Installation

composer require orchestra-mcp/tray
php artisan orchestra:desktop-install

The service provider is auto-discovered. The install command (from the desktop package) publishes the config and creates the NativeAppServiceProvider. Then publish the tray config:

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

Run the Desktop App

php artisan native:serve
# or
composer native

Quick Start

Create the Tray

use OrchestraMcp\Tray\Facades\Tray;

Tray::create();
Tray::setIcon(storage_path('app/icon.png'));
Tray::setTooltip('My App');

Contribute Menu Items from a Plugin

Implement HasTrayMenu in your plugin to contribute items:

use OrchestraMcp\Tray\Contracts\HasTrayMenu;
use OrchestraMcp\Tray\Menu\TrayMenuItem;
use OrchestraMcp\Plugins\Plugin\Plugin;

class MyPlugin extends Plugin implements HasTrayMenu
{
    public function id(): string
    {
        return 'my-org/my-plugin';
    }

    public function name(): string
    {
        return 'My Plugin';
    }

    public function trayMenuItems(): array
    {
        return [
            TrayMenuItem::label('Do Something', 'my-plugin.action'),
            TrayMenuItem::checkbox('Auto Mode', 'my-plugin.auto', checked: true),
        ];
    }

    public function trayMenuPriority(): int
    {
        return 50;
    }

    public function trayMenuGroup(): ?string
    {
        return 'tools';
    }
}

Register Menu Groups

use OrchestraMcp\Tray\Menu\MenuGroup;
use OrchestraMcp\Tray\Facades\Tray;

Tray::menuContributions()->registerGroup(
    new MenuGroup(id: 'tools', label: 'Tools', priority: 50)
);

Rebuild the Menu

Tray::rebuildMenu(); // collects plugin contributions, sorts by priority, adds separators

Configuration

Publish the config:

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

Key	Default	Env Variable	Description
`enabled`	`true`	`ORCHESTRA_TRAY_ENABLED`	Enable/disable the tray plugin
`driver`	`'auto'`	`ORCHESTRA_TRAY_DRIVER`	Driver: `'auto'`, `'native'`, `'null'`
`icon`	`''`	`ORCHESTRA_TRAY_ICON`	Absolute path to tray icon image
`tooltip`	`'Orchestra Desktop'`	`ORCHESTRA_TRAY_TOOLTIP`	Tooltip text on hover
`marketplace`	`false`	—	Marketplace visibility

Artisan Commands

Command	Description
`orchestra:tray-status`	Show tray config, driver, icon, tooltip, contributions, groups

Documentation

Full documentation is available in the docs/ directory:

Getting Started — Installation, configuration
Architecture — Driver pattern, services, plugin integration
Contracts — TrayDriverInterface, HasTrayMenu
Menu — TrayMenuItem, MenuGroup, TrayIcon DTOs
Events — Event reference
Commands — Artisan command reference
Configuration — Full config key reference
API Reference — Facades, services, plugin class

Development

# Install dependencies
composer install

# Run tests
composer test

# Format code
composer format

# Static analysis
composer check

# Lint
composer lint

License

MIT

orchestra-mcp / tray

Maintainers

Details