Laravel Mcp Espectro Laravel Package

Getting Started

Minimal Steps

1. Install the package:

   composer require labrodev/laravel-mcp-espectro
   php artisan espectro:install
   

   This generates .mcp.json in your project root and outputs the MCP endpoint URL.

2. Configure your AI client:

   • Cursor: Restart Cursor to auto-detect .mcp.json.
   • Claude Desktop: Add the endpoint https://espectro.dev/mcp/espectro in MCP server settings.
   • Other clients: Use the HTTP transport with the same URL.

3. First use case: Ask your AI assistant to:

   "Search for colors named 'cerulean' using the search-colors tool."
   

   Verify the response includes color details (name, hex, palette).

Implementation Patterns

Workflows

1. AI-Assisted Color Selection:

   • Prompt: "Find a 3-color palette for a winter-themed UI."
   • Tool: Use search-combinations with paletteSize: 3.
   • Output: AI returns a structured palette (e.g., ["#E6E6FA", "#F0F8FF", "#DDA0DD"]).

2. Dynamic Theming:

   • Prompt: "Get the hex code for 'sacred gold' and suggest a complementary color."
   • Tools: Chain get-color (slug: sacred-gold) + search-combinations (filter by paletteSize: 2).
   • Output: AI generates a theme with primary/secondary colors.

3. Debugging UI Issues:

   • Prompt: "Why does this button look washed out? Analyze its hex (#4A90E2) against the palette."
   • Tool: Use get-color to fetch contrast metrics or search-combinations to find high-contrast pairs.

Integration Tips

• Laravel Artisan Commands: Cache color/combination data locally (e.g., in storage/app/espectro-cache.json) to reduce API calls:

  // Example: Fetch and cache combinations
  $combinations = Cache::remember('espectro-combinations', now()->addHours(1), function () {
      return Http::post('https://espectro.dev/mcp/espectro', [
          'tool' => 'search-combinations',
          'paletteSize' => 3,
      ])->json();
  });
  

• AI Prompt Templates: Store reusable prompts in a resources/ai-prompts/ directory and reference them in your AI client:

  // resources/ai-prompts/color-palette.md
  Use the `search-combinations` tool to find a {paletteSize}-color palette for {theme}.
  Return the hex codes and suggest a use case (e.g., "primary/secondary/accent").
  

• Laravel Blade Directives: Create a custom Blade directive to embed color data in views:

  // app/Providers/BladeServiceProvider.php
  Blade::directive('color', function ($hex) {
      return "<?php echo app(\\Labrodev\\Espectro\\Color::fromHex('{$hex}')->toHtml(); ?>";
  });
  

  Usage:

  <div style="background: {{ $color->hex }}">{{ $color->name }}</div>
  

Gotchas and Tips

Pitfalls

1. Rate Limiting:

   • Issue: 15 requests/minute per IP. Exceeding this may block your AI client.
   • Fix: Cache responses aggressively (e.g., 1-hour TTL for combinations) or use a proxy server to rotate IPs.

2. Tool Name Sensitivity:

   • Issue: Typos in tool names (e.g., search-colors vs. searchColor) break requests.
   • Fix: Use the exact names from the README table or inspect the .mcp.json schema.

3. AI Client Quirks:

   • Cursor: May require a full restart to detect .mcp.json changes.
   • Claude Desktop: Ensure the MCP server URL is copied verbatim (no trailing slashes).

4. Hex Case Inconsistency:

   • Issue: Some tools return lowercase hex (e.g., #4a90e2), others uppercase.
   • Fix: Normalize with PHP:

     $hex = strtoupper($color['hex']);
     

Debugging

• Validate .mcp.json: Ensure the file contains:

  {
    "mcp": {
      "servers": {
        "espectro": {
          "url": "https://espectro.dev/mcp/espectro",
          "transport": "http"
        }
      }
    }
  }
  

  Use php artisan espectro:install --force to regenerate.

• Test Tools Manually: Use curl to verify endpoints:

  curl -X POST https://espectro.dev/mcp/espectro \
    -H "Content-Type: application/json" \
    -d '{"tool":"search-colors","query":"blue"}'
  

Extension Points

1. Custom Tools: Extend the package by adding a tools/ directory in your project root. Example:

   // .mcp.json
   {
     "mcp": {
       "tools": {
         "my-custom-tool": {
           "description": "Fetches color accessibility metrics",
           "parameters": {
             "hex": "string"
           }
         }
       }
     }
   }
   

   Register the tool in AppServiceProvider:

   MCP::extend('my-custom-tool', function ($hex) {
       return Http::post('https://espectro.dev/mcp/espectro', [
           'tool' => 'my-custom-tool',
           'hex' => $hex,
       ])->json();
   });
   

2. Local Overrides: Override the default MCP endpoint in .env:

   ESPECTRO_MCP_URL=https://your-proxy.espectro.dev/mcp/espectro
   

   Then publish the config:

   php artisan vendor:publish --provider="Labrodev\Espectro\EspectroServiceProvider"
   

3. Webhook Integration: Use Laravel’s HandleIncomingWebhook to process Espectro responses as webhooks:

   // routes/web.php
   Route::post('/espectro-webhook', [EspectroWebhookHandler::class, 'handle']);
   

   Example handler:

   class EspectroWebhookHandler {
       public function handle(Request $request) {
           $data = $request->json();
           if ($data['tool'] === 'search-colors') {
               Cache::put('latest-colors', $data['result'], now()->addMinutes(5));
           }
       }
   }