README

Settings

Orchestra MCP Settings plugin — key/value settings store with UI schema, theme picker, extensible settings panel, and NativePHP system tray integration.

Features

Typed Settings Registry — Define settings with type, default, enum, min/max, grouping, and display order
JSON Storage — Simple file-based persistence; no database required
Settings Panel — NativePHP native window with sidebar navigation, search, theme picker, and grouped sections
Theme Integration — Built-in theme picker with live AJAX switching (requires orchestra-mcp/themes)
Plugin Extensibility — Other plugins register settings via the HasSettings contract
VS Code Compatibility — Settings definitions follow the contributes.configuration pattern
Tray Menu Integration — "Settings" entry in system tray, positioned before Close/Quit
3 MCP Tools — List, get, and set settings programmatically
3 Artisan Commands — CLI management for settings

Requirements

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

Installation

composer require orchestra-mcp/settings

The service provider is auto-discovered.

Quick Start

List Settings

php artisan settings:list
php artisan settings:list --group=Appearance

Get / Set a Setting

php artisan settings:get appearance.theme
php artisan settings:set appearance.theme dracula

Programmatic Usage

use OrchestraMcp\Settings\Facades\Settings;

// Get a setting (returns default if not set)
$theme = Settings::get('appearance.theme');

// Set a setting
Settings::set('appearance.font_size', 16);

// Get all settings
$all = Settings::all();

Register Plugin Settings

Implement HasSettings in your plugin to contribute settings to the panel:

use OrchestraMcp\Settings\Contracts\HasSettings;
use OrchestraMcp\Settings\Data\SettingDefinition;
use OrchestraMcp\Settings\Data\SettingType;

class MyPlugin extends Plugin implements HasSettings
{
    public function settings(): array
    {
        return [
            new SettingDefinition(
                key: 'myplugin.auto_save',
                type: SettingType::Boolean,
                default: true,
                label: 'Auto Save',
                description: 'Automatically save changes',
                group: 'My Plugin',
                order: 10,
            ),
            new SettingDefinition(
                key: 'myplugin.interval',
                type: SettingType::Integer,
                default: 30,
                label: 'Save Interval',
                description: 'Auto-save interval in seconds',
                group: 'My Plugin',
                min: 5,
                max: 300,
                order: 20,
            ),
        ];
    }
}

Built-in Settings

Group	Key	Type	Default
General	`general.timezone`	string (enum)	`UTC`
Appearance	`appearance.theme`	string	`deep-ocean`
Appearance	`appearance.font_size`	integer	`14`
Appearance	`appearance.font_family`	string (enum)	`JetBrains Mono`
Editor	`editor.tab_size`	integer	`4`
Editor	`editor.word_wrap`	boolean	`true`
Editor	`editor.line_numbers`	boolean	`true`
Editor	`editor.minimap`	boolean	`true`
Notifications	`notifications.enabled`	boolean	`true`
Notifications	`notifications.sound`	boolean	`true`

MCP Tools

Tool	Annotation	Description
`settings-list`	`#[IsReadOnly]`	List all settings grouped by category
`settings-get`	`#[IsReadOnly]`	Get a specific setting value
`settings-set`	`#[IsIdempotent]`	Set a specific setting value

Artisan Commands

Command	Description
`settings:list`	List all settings, optionally filtered by group
`settings:get`	Get the value of a specific setting
`settings:set`	Set the value of a specific setting

Configuration

Publish the config:

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

Key	Default	Env Variable	Description
`enabled`	`true`	`ORCHESTRA_SETTINGS_ENABLED`	Enable/disable settings plugin
`driver`	`'json'`	`ORCHESTRA_SETTINGS_DRIVER`	Storage driver (`json` or `database`)
`json_path`	`storage/orchestra/settings.json`	—	JSON file path
`defaults`	(see config)	—	Default setting values
`marketplace`	`true`	—	Marketplace visibility

Settings Panel UI

General	Appearance	Themes

The settings panel renders as a NativePHP native window with:

Sidebar navigation — Grouped sections (General, Appearance, Editor, Notifications, Theme)
Search — Filter settings by label or key
Type-aware inputs — Toggles for booleans, dropdowns for enums, number inputs for integers, text inputs for strings
Theme picker — Visual grid of theme swatches with live AJAX switching
Hidden title bar — Clean frameless look with custom drag region

Plugin Integration: Provider Cards Pattern

The settings panel is designed to be extended by plugins that need to display provider cards (e.g., account integrations, service connections). The recommended UI pattern for provider cards:

CSS Pattern

.provider-card {
    background: var(--mt-bg-alt);
    border: 1px solid var(--mt-border);
    border-radius: 10px;
    padding: 20px;
    transition: border-color 0.15s;
}
.provider-card:hover { border-color: var(--mt-accent); }
.provider-card.connected { border-color: var(--mt-accent); }

.provider-icon {
    width: 40px; height: 40px;
    border-radius: 10px;
    display: flex; align-items: center; justify-content: center;
}

.provider-badge {
    font-size: 11px;
    padding: 2px 8px;
    border-radius: 4px;
    background: rgba(var(--mt-accent-rgb), 0.15);
    color: var(--mt-accent);
}

Auth Flow Patterns

Provider Type	Auth Method	UI Pattern
GitHub	Device Code	Display code + copy button + device login link + waiting status
GitLab	Personal Access Token	Token input + URL input + generate link + connect button
Bitbucket	App Password	Username + password inputs + connect button
Google/Generic	OAuth 2.0	Single "Connect" button redirecting to OAuth

Connected State

<div class="provider-card connected">
    <div class="connected-info">
        <span class="connected-name">{{ displayName }}</span>
        <span class="connected-email">{{ email }}</span>
    </div>
    <button class="btn-disconnect">Disconnect</button>
</div>

Plugins implementing account connections should provide their own routes, services, and views, then register a settings section via the HasSettings contract.

Documentation

Full documentation is available in the docs/ directory:

Getting Started — Installation, configuration, quick start
Architecture — Settings system design, registries, schema definitions
Tools — MCP tool reference
Commands — Artisan command reference
Configuration — Full config key reference
API Reference — Facades and services

Development

# Install dependencies
composer install

# Run tests
composer test

# Format code
composer format

# Static analysis
composer check

# Lint
composer lint

License

MIT

orchestra-mcp / settings

Maintainers

Details