Download the PHP package projectsaturnstudios/laravel-vibes without Composer

🤖 Laravel Vibes

A powerful Laravel package for implementing the Machine Control Protocol (MCP) server, enabling seamless integration with AI agents in your applications. Build intelligent, interactive features with structured tool definitions and real-time communication.

✨ Key Features

• 🔧 Tool Registration System - Define, register, and expose tools for AI agents to use
• 🔄 Server-Sent Events (SSE) - Real-time communication with AI agents via event streams
• 🛣️ API Endpoints - Ready-to-use endpoints for MCP protocol implementation
• 🧩 Primitive Handlers - Extensible system for various MCP primitives
• 🔍 Auto-Discovery - Automatic discovery of tool implementations in your codebase
• 🦺 Type Safety - Full PHP 8.2+ type hinting and return type declarations
• 🔮 Future-Ready - Foundation for upcoming MCP features (resources, prompts, samples, and roots) with framework in place

🚦 Implementation Status

This section provides a clear overview of which MCP primitives are currently implemented and which are planned for future releases.

Primitive Implementation Status

Feature Availability Matrix

Legend:

• ✅ Full implementation
• 🚧 Partial implementation
• ❌ Not implemented

📚 Documentation

Comprehensive documentation for Laravel Vibes is available in the docs/ directory:

Class Diagram

Below is a simplified class diagram showing the main components of Laravel Vibes:

🔧 Installation

You can install the package via composer:

The package will automatically register its service provider with Laravel.

⚙️ Configuration

Publish the configuration files with:

This will publish the configuration file to config/vibes.php and config/cors.vibes.php.

Key configuration options:

👉 Learn more: For advanced configuration options, see the Configuration section in TheAgency.md.

🚀 Usage

Registering Tools

Register AI tools in your service provider:

Or register via the config file:

Defining a Custom Tool

Create a tool that AI agents can use:

Using Server-Sent Events

Connect AI agents to your application using SSE:

Handling AI Agent Messages

Process incoming MCP messages from agents:

👉 Learn more: Detailed usage examples are available in the UsageExamples.md documentation.

🔍 Tool Discovery & Registration

Laravel Vibes follows a similar approach to Laravel Event Sourcing for loading primitives, using automatic discovery and registration patterns. For more detailed examples, see the UsageExamples.md documentation.

Auto-Discovery

The package automatically discovers and registers tools and other MCP primitives in the configured directories:

During application bootstrapping, Laravel Vibes scans these directories for classes that implement the PrimitiveHandler interface and automatically registers them with TheAgency:

Manual Registration

For manual registration, modify your AppServiceProvider or create a dedicated service provider:

Then add your provider to config/app.php:

Caching Primitives

For production environments, Laravel Vibes provides caching mechanisms to improve performance. The discovered primitives are cached at bootstrap/cache/vibes.php.

To clear the cache during development:

You can also implement a dedicated command to manage the primitive cache (similar to Laravel Event Sourcing's event-sourcing:cache-event-handlers):

🧪 Comprehensive Testing Guide

This section provides guidance and examples for testing Laravel Vibes components, focusing on custom tools and AI agent interactions.

Unit Testing Custom Tools

Test your custom tools to ensure they properly handle inputs and produce expected outputs:

Mocking External Services

Test tools that interact with external services by mocking the HTTP responses:

Integration Testing with TheAgency

Test the integration of tools with TheAgency:

Testing SSE Connections

Test Server-Sent Events (SSE) connections using the following approach:

Mocking AI Agent Interactions

Test components that interact with AI agents:

PHPUnit Configuration Recommendations

Here's a sample PHPUnit configuration for optimal testing of Laravel Vibes components:

Testing Best Practices

When testing Laravel Vibes components, follow these best practices:

1. Isolate your tests: Ensure each test is independent and can run in any order.
2. Use test doubles: Mock external dependencies like HTTP APIs, databases, and services.
3. Test edge cases: Verify behavior with invalid inputs, error conditions, and boundary values.
4. Emulate real-world scenarios: Create tests that mirror actual usage patterns.
5. Test asynchronous behavior: Verify SSE connections and event listeners work correctly.
6. Use data providers: Test tools with multiple input/output combinations.
7. Check exception handling: Verify tools throw appropriate exceptions for invalid inputs.
8. Test middleware independently: Isolate middleware functionality from controller logic.

For detailed example tests, check out the tests directory in the Laravel Vibes repository.

👉 Learn more: For more detailed testing examples and strategies, see the Testing section in UsageExamples.md.

🔄 Laravel 12 Compatibility

Laravel Vibes is designed to be fully compatible with Laravel 12.x, leveraging many of its new features and improvements to provide optimal performance and developer experience.

Version Compatibility Matrix

The following table shows Laravel Vibes package version compatibility with Laravel framework versions:

Laravel 12 Features Utilized

Laravel Vibes takes advantage of several new features introduced in Laravel 12:

Improved Rate Limiting

Laravel Vibes uses the enhanced rate limiting capabilities in Laravel 12 to manage AI agent connections and prevent resource abuse:

Route Grouping Improvements

The package uses Laravel 12's improved route group definitions for cleaner organization:

PHP 8.2 Readonly Classes

Laravel Vibes models use PHP 8.2 readonly classes for improved type safety and performance:

First-class Enum Support

Laravel 12's improved support for PHP enums is used throughout the package:

Upgrading from Previous Laravel Versions

If you're upgrading from a previous Laravel version, follow these steps to ensure compatibility with Laravel Vibes:

From Laravel 11.x

1. Update your dependencies in composer.json:

2. Run Composer update:

3. Update configuration if needed:

4. Update any custom tool implementations to use the new tool signature format:

From Laravel 10.x or Earlier

1. First upgrade to Laravel 11.x following the official upgrade guide.
2. Update to Laravel Vibes 0.9.x.
3. Test thoroughly that all tools and functionality work correctly.
4. Then follow the steps above to upgrade to Laravel 12 and Laravel Vibes 1.0.x.

Known Issues & Limitations

Session Handling in Laravel 12

Laravel 12 implements stricter session handling. When using SSE connections with Laravel Vibes, you must use the provided ScaffoldSSEConnection middleware to avoid session conflicts:

Service Container Changes

Laravel 12's service container features improved dependency resolution. If you've extended Laravel Vibes core classes, ensure your bindings are properly registered:

Queue System Changes

If you're using Laravel Vibes with background jobs, note that Laravel 12 introduces changes to the queue system:

Composer Requirements

To use Laravel Vibes with Laravel 12, ensure your composer.json includes the following requirements:

Specific extension requirements:

• ext-json: Required for JSON processing
• ext-curl: Required for HTTP client functionality
• ext-mbstring: Required for string manipulation

For development environments, we recommend:

👉 Learn more: Check the compatibility documentation for detailed information about supported features and versions.

🚀 Deployment Considerations

This section provides guidance for deploying Laravel Vibes in production environments, focusing on performance, scaling, and security considerations.

Production Environment Configuration

When preparing your Laravel Vibes application for production, ensure these environment-specific settings:

Enable production-optimized caching:

Performance Optimization

Optimize your Laravel Vibes application for high traffic and AI agent interactions:

Tool Execution Optimization

Queue Configuration for Tool Processing

Move long-running operations to background queues:

Compression and Response Optimization

Scaling Strategies

Laravel Vibes can be scaled horizontally or vertically depending on your needs:

Horizontal Scaling with Load Balancing

For handling many concurrent AI agent connections:

If implementing horizontal scaling, ensure:

• Session persistence via Redis/Memcached
• Sticky sessions for SSE connections
• Shared storage for file uploads/resources

Queue Workers for Tool Processing

Monitoring and Logging

Implement robust monitoring for AI agent interactions:

Log Configuration

Telemetry Integration

Key Metrics to Monitor

• Tool execution time and success rate: Track performance of individual tools
• SSE connection count and duration: Monitor active AI agent connections
• Queue processing rate: Ensure background tasks aren't backing up
• Memory usage: Watch for memory leaks during long-running SSE connections
• Redis/database connection saturation: Ensure sufficient pool for connections

Resource Management

AI interactions can be resource-intensive. Configure proper limits:

PHP-FPM configuration for SSE connections:

Security in Production

Implement additional security measures for production:

CORS Configuration

Input Validation

All tool parameters should be thoroughly validated:

Rate Limiting

Configure tiered rate limiting for different operations:

Hosting Platform-Specific Guidelines

Laravel Forge

Docker Deployment

AWS Elastic Beanstalk

For .ebextensions/01-laravel-vibes.config:

These deployment considerations will help ensure your Laravel Vibes application is robust, performant, and secure in production environments. Always test thoroughly in a staging environment that mirrors your production configuration before deploying updates.

👉 Learn more: For detailed performance benchmarks and advanced scaling strategies, see the Deployment section in UsageExamples.md.

📊 Architecture

Laravel Vibes is built with a modular architecture focusing on these components:

• TheAgency: Central manager for all MCP primitives
• VibeTool: Base class for implementing tools
• Primitive Handlers: Extensible system for different primitive types
• MCPAgentEntryController: Handles SSE and agent message endpoints
• ServiceProvider: Auto-registration and configuration

The package uses these Laravel packages:

• spatie/laravel-package-tools for package configuration
• spatie/laravel-data for data objects
• lorisleiva/laravel-actions for single-responsibility actions

For a detailed overview of component implementation status, refer to the TheAgency.md documentation files.

👉 Learn more: View the complete class diagram and architectural details in ClassDiagram.md.

📅 Roadmap

Future development plans aligned with our implementation status:

The current focus is on completing the Resources primitive implementation for the upcoming 0.5.0 release. Contributions are welcome for any of the planned features.

👥 Credits

• Project Saturn Studios - Package development and maintenance

🔒 Security

If you discover any security-related issues, please email [email protected] instead of using the issue tracker.

📄 License

This package is licensed under the MIT License. See the LICENSE.md file for more information.

🤝 Contributing

We welcome contributions to Laravel Vibes! Please see our Contributing Guidelines for details on how to get started, coding standards, and our pull request process.

🔄 Flow Diagrams

Visual diagrams of Laravel Vibes architecture and interaction flows are available in the Flow Diagrams documentation. These diagrams help developers understand how the components work together and implement the package effectively.

🌟 Real-World Examples

For comprehensive real-world implementation examples, check out our Examples documentation. These examples demonstrate practical use cases and implementation patterns to help you get started quickly.