README

Widgets

Orchestra MCP Widgets plugin — a widget control system for registering, positioning, resizing, and managing widget lifecycle with grid snap, z-ordering, and event-driven state changes.

Features

Widget Definitions — Register widgets with metadata (title, icon, component, group, default position/size, min/max constraints)
Runtime State — Track visibility, position, size, z-index, and collapsed state per widget
Grid Snap — Configurable snap-to-grid for move and resize operations
Z-Order Management — Bring widgets to front with auto-incrementing z-index
Min/Max Constraints — Enforce minimum and maximum size limits on resize
Event-Driven — Lifecycle events for registered, shown, hidden, moved, resized
Widget Registry — In-memory store with group filtering, visibility queries
5 MCP Tools — List, info, show, hide, toggle
2 Artisan Commands — List widgets and reset all state

Requirements

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

Installation

composer require orchestra-mcp/widgets

The service provider is auto-discovered.

Quick Start

Register a Widget

use OrchestraMcp\Widgets\Facades\Widgets;
use OrchestraMcp\Widgets\Data\WidgetDefinition;

Widgets::register(WidgetDefinition::fromArray([
    'id' => 'clock',
    'title' => 'Clock',
    'component' => 'clock-widget',
    'icon' => 'clock',
    'group' => 'utilities',
    'defaultWidth' => 200,
    'defaultHeight' => 100,
]));

Show / Hide / Toggle

Widgets::show('clock');
Widgets::hide('clock');
Widgets::toggle('clock');

Move and Resize

Widgets::move('clock', 100, 200);      // respects grid snap
Widgets::resize('clock', 300, 150);    // respects min/max constraints
Widgets::bringToFront('clock');

List Widgets via Artisan

php artisan widgets:list
php artisan widgets:list --group=utilities --visible

MCP Tools

Tool	Annotation	Description
`widget-list`	`#[IsReadOnly]`	List widgets with group/visibility filter
`widget-info`	`#[IsReadOnly]`	Widget details with definition and state
`widget-show`	`#[IsIdempotent]`	Show a widget by ID
`widget-hide`	`#[IsIdempotent]`	Hide a widget by ID
`widget-toggle`	`#[IsIdempotent]`	Toggle widget visibility

Artisan Commands

Command	Description
`widgets:list`	List registered widgets with group/visibility filters
`widgets:reset`	Reset all widget states to defaults

Configuration

Publish the config:

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

Key	Default	Env Variable	Description
`enabled`	`true`	`ORCHESTRA_WIDGETS_ENABLED`	Enable/disable widgets plugin
`grid_snap`	`true`	`ORCHESTRA_WIDGETS_GRID_SNAP`	Snap to grid on move/resize
`grid_size`	`10`	`ORCHESTRA_WIDGETS_GRID_SIZE`	Grid size in pixels
`persistence`	`'memory'`	`ORCHESTRA_WIDGETS_PERSISTENCE`	State persistence driver
`default_layout`	`'free'`	`ORCHESTRA_WIDGETS_LAYOUT`	Default layout strategy
`z_index_base`	`100`	—	Starting z-index for layers
`marketplace`	`true`	—	Marketplace visibility

Documentation

Full documentation is available in the docs/ directory:

Getting Started — Installation, configuration, quick start
Architecture — Widget system design, data classes, registry
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 / widgets

Maintainers

Details