README

Search

Unified search service with provider registry, query parser, result ranking, spotlight UI, and caching. An Orchestra MCP plugin that provides a Jira/SQL-like query language and extensible provider architecture for searching across any data source.

How It Works

The Search plugin provides a pipeline architecture — a query string is tokenized by the lexer, parsed into a structured query, dispatched to matching providers, then results are filtered, deduplicated, ranked by relevance, and returned.

Query String ("status:open fix login")
    ↓ QueryLexer (tokenize)
Token Stream ([Field:status] [Text:open] [Text:fix] [Text:login])
    ↓ QueryParser (parse)
SearchQuery { text: "fix login", filters: [status=open] }
    ↓ SearchService (dispatch to providers)
Provider Results (merged from all matching providers)
    ↓ ResultRanker (filter → deduplicate → rank)
Sorted SearchResult[]

Features

Extensible Provider Registry — Any plugin can contribute search providers via HasSearchProviders
16 Built-in Result Types — File, Symbol, Text, Task, Command, Setting, Snippet, Workspace, Project, Epic, Story, Bug, Hotfix, and more
Jira/SQL-like Query Parser — status:open AND type:bug priority > 3 sort:created desc
Multi-factor Result Ranking — Text match, fuzzy matching, history boost, provider priority
Spotlight UI — Raycast-style frameless search panel with keyboard navigation
Tray Menu Integration — Open spotlight from the system tray
LRU Cache — Configurable TTL and size for repeated queries
3 MCP Tools — search-query, search-providers, search-parse
3 Artisan Commands — orchestra:search, orchestra:search-providers, orchestra:search-status

Installation

composer require orchestra-mcp/search

The service provider is auto-discovered. No manual registration is needed.

Configuration

Publish the config:

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

Option	Default	Description
`default_limit`	`50`	Max results per search
`cache.max_age`	`300`	Cache TTL (seconds)
`cache.max_size`	`100`	Max cached queries
`recent.max_items`	`20`	Recent searches stored
`preferences.fuzzy_match`	`true`	Enable fuzzy matching in ranker
`preferences.case_sensitive`	`false`	Case-insensitive filtering

Query Syntax

Two syntax styles are supported:

Style	Example	Description
Jira-like	`status:open`	`field:value` filters
SQL-like	`priority > 3`	`field operator value` filters

Logical operators: AND, OR, NOT. Sorting: sort:field desc. Pagination: limit:10 offset:20.

status:open AND type:bug priority > 3 fix login sort:created desc limit:10

Search Providers

Any plugin can contribute search results by implementing HasSearchProviders. This is how you make the search system aware of your data.

File Search (Explorer Plugin)

use OrchestraMcp\Search\Contracts\HasSearchProviders;
use OrchestraMcp\Search\Contracts\SearchProviderInterface;
use OrchestraMcp\Search\Data\SearchQuery;
use OrchestraMcp\Search\Data\SearchResult;
use OrchestraMcp\Search\Data\SearchResultType;

class FileSearchProvider implements SearchProviderInterface
{
    public function name(): string { return 'files'; }
    public function priority(): int { return 150; }
    public function types(): array { return [SearchResultType::File]; }

    public function search(SearchQuery $query): array
    {
        $files = $this->findFiles($query->text);

        return array_map(fn (string $path) => new SearchResult(
            id: 'file:' . $path,
            title: basename($path),
            type: SearchResultType::File,
            provider: $this->name(),
            subtitle: dirname($path),
            path: $path,
            icon: $this->iconForExtension(pathinfo($path, PATHINFO_EXTENSION)),
        ), $files);
    }

    public function canHandle(SearchQuery $query): bool { return $query->text !== ''; }
    public function suggestions(): array { return []; }
}

// In your Explorer plugin:
class ExplorerPlugin extends Plugin implements HasSearchProviders
{
    public function searchProviders(): array
    {
        return [FileSearchProvider::class];
    }
}

Content Search (Editor Plugin)

class ContentSearchProvider implements SearchProviderInterface
{
    public function name(): string { return 'content'; }
    public function priority(): int { return 100; }
    public function types(): array { return [SearchResultType::Text, SearchResultType::Symbol]; }

    public function search(SearchQuery $query): array
    {
        $matches = $this->grepFiles($query->text);

        return array_map(fn (array $match) => new SearchResult(
            id: 'content:' . $match['file'] . ':' . $match['line'],
            title: $match['text'],
            type: SearchResultType::Text,
            provider: $this->name(),
            subtitle: basename($match['file']) . ':' . $match['line'],
            path: $match['file'],
            line: $match['line'],
            preview: $match['context'],
        ), $matches);
    }

    public function canHandle(SearchQuery $query): bool { return strlen($query->text) >= 2; }
    public function suggestions(): array { return []; }
}

Direct Registration

use OrchestraMcp\Search\Services\SearchService;

$search = app(SearchService::class);
$search->registerProvider(new FileSearchProvider);

Result Types

The search system ships with 16 built-in result types. Providers declare which types they return, and the spotlight UI renders type-specific icons.

Type	Value	Use Case
`File`	`file`	File system results (explorer)
`Symbol`	`symbol`	Code symbols — classes, functions (editor)
`Text`	`text`	Content/grep matches (editor)
`Task`	`task`	Todo/issue tracker items
`Command`	`command`	CLI/Artisan commands
`Setting`	`setting`	Configuration options
`Recent`	`recent`	Recently accessed items
`Suggestion`	`suggestion`	Auto-complete suggestions
`Extension`	`extension`	Plugin/extension results
`Snippet`	`snippet`	Code snippets
`Workspace`	`workspace`	Workspace items
`Project`	`project`	Project-level items
`Epic`	`epic`	Epic issues
`Story`	`story`	Story issues
`Bug`	`bug`	Bug reports
`Hotfix`	`hotfix`	Hotfix items

Spotlight UI

The search plugin includes a Raycast-style spotlight panel:

Frameless, transparent window with backdrop blur and vibrancy
Keyboard navigation — Arrow keys to navigate, Enter to open, Escape to close
Click-away dismiss — Window closes when it loses focus
Tray menu integration — "Search Spotlight" entry opens the panel
Type-grouped results with icons and subtitles

The spotlight uses window.remote.getCurrentWindow().close() (Electron Remote API) for reliable window closing from the renderer process.

Usage

use OrchestraMcp\Search\Facades\Search;

// Execute a search
$results = Search::search('fix login', ['limit' => 10]);

// Filter by type
$results = Search::search('User', ['types' => ['file', 'symbol']]);

// Filter by provider
$results = Search::search('config', ['providers' => ['settings']]);

// Parse without executing
$query = Search::parse('status:open AND type:bug');

// Get suggestions
$suggestions = Search::suggestions();

MCP Tools

Tool	Annotation	Description
`search-query`	`#[IsReadOnly]`	Execute search queries with filters
`search-providers`	`#[IsReadOnly]`	List registered providers
`search-parse`	`#[IsReadOnly]`	Parse query without executing

Artisan Commands

Command	Description
`orchestra:search {query}`	Execute a search from the CLI
`orchestra:search-providers`	List all registered providers
`orchestra:search-status`	Show service status and cache info

Testing

# Run search tests
php artisan test --compact --filter=Search

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

90 tests, 225 assertions covering query lexer, parser, result ranking, provider registry, plugin registration, spotlight routes, panel integration, and service lifecycle.

Documentation

Full documentation is available in the docs/ directory:

Getting Started — Installation, configuration, quick start
Architecture — Design overview, query pipeline
Query Syntax — Filters, operators, examples
Providers — Provider interface, plugin integration, examples
Spotlight — Spotlight UI, panel configuration, keyboard shortcuts
Tools — MCP tool reference
Commands — Artisan commands
Configuration — Config key reference
Testing — Test guide
API Reference — Services, events, data 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 / search

Maintainers

Details