README

Socket

WebSocket RPC layer built on Laravel Reverb for real-time client-server communication. An Orchestra MCP plugin that provides bidirectional RPC (invoke/response) and push events over WebSocket.

How It Works

The Socket plugin hooks into Laravel Reverb — it does not run its own WebSocket server. It listens for incoming client whisper events via Reverb's MessageReceived listener and broadcasts responses/events back using Laravel Broadcasting with ShouldBroadcastNow for immediate delivery.

Client (Laravel Echo)
    ↕ WebSocket (Pusher protocol)
Laravel Reverb
    ↕ MessageReceived event
Socket Plugin (HandlerRegistry → RPC routing)
    ↕ broadcast()
Back to Client (RpcResponse / RpcEvent)

Installation

composer require orchestra-mcp/socket

The service provider is auto-discovered. Requires Laravel Reverb for WebSocket transport:

composer require laravel/reverb
php artisan install:broadcasting --reverb

Configuration

Publish the config:

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

Option	Env	Default	Description
`channel`	`ORCHESTRA_RPC_CHANNEL`	`orchestra-rpc`	Reverb channel for RPC messages
`invoke_timeout`	`ORCHESTRA_RPC_TIMEOUT`	`30`	Max seconds to wait for a response

RPC Protocol

Three message types enable bidirectional communication:

Type	Direction	Description
Invoke	Client → Server	Call a registered handler by channel name
Response	Server → Client	Return result or error for an invoke
Event	Server → Client	Push notification to all clients

Default Handlers

Channel	Response	Description
`ping`	`"pong"`	Health check
`status`	`{running, uptime, channels, channel}`	Service info

Registering Custom Handlers

use OrchestraMcp\Socket\Services\SocketService;

$service = app(SocketService::class);

$service->registerHandler('greet', fn (string $name) => "Hello, {$name}!");

Broadcasting Events

$service->broadcast('file-changed', '/path/to/file');

Client Integration (Chrome Extension)

The Chrome extension connects via laravel-echo + pusher-js, which speaks the Pusher protocol that Reverb understands. The OrchestraClient wraps Echo and keeps the same API:

import { getOrchestraClient } from '@/transport/orchestraClient'

const client = getOrchestraClient()

// Request/response
const result = await client.invoke('ping')  // 'pong'

// Listen for server push events
client.on('file-changed', (path) => {
  console.log('File changed:', path)
})

// Fire-and-forget
client.send('log', 'info', 'Hello from extension')

// Connection state
client.on('connection', (connected) => {
  console.log('Connected:', connected)
})

See docs/client/ for full details on the Chrome extension client and custom client integration.

MCP Tools

Tool	Annotation	Description
`socket-status`	`#[IsReadOnly]`	Service status, uptime, registered channels
`socket-broadcast`	`#[IsIdempotent]`	Broadcast events to connected clients

Testing

# Run socket tests
php artisan test --compact --filter=Socket

# From package directory
cd packages/orchestra-mcp/socket
../../vendor/bin/pest

31 tests, 51 assertions covering plugin registration, service lifecycle, handler registry, and RPC message DTOs.

Documentation

Full documentation is available in the docs/ directory:

Getting Started — Installation, configuration
Architecture — Design overview, RPC protocol
Client Integration — Chrome extension and custom clients
Tools — MCP tool reference
Configuration — Config key reference
Testing — Test guide
API Reference — Services, events, RPC types

Development

# Install dependencies
composer install

# Run tests
composer test

# Format code
composer format

# Static analysis
composer check

# Lint
composer lint

License

MIT

orchestra-mcp / socket

Maintainers

Details