README

Disclosure: This package was designed and written Entirely by claude ai. I may have guided and nuggged it in a few places, but the code was written by claude ai.

Laravel MCP (Message Context Protocol) Client is a package that integrates Anthropic's Claude AI model with custom tool servers, allowing you to extend Claude's capabilities with your own tools and services.

Features

• Seamless integration with Anthropic's Claude API
• Tool server management and execution
• Built-in queuing support for long-running tools
• Event-driven architecture
• Automatic chat title generation
• Complete chat history management
• Database persistence for conversations and tool executions
• Soft deletes support
• Comprehensive logging system

Requirements

• PHP 8.3 or higher
• Laravel 11.0 or higher
• Anthropic API key

Installation

You can install the package via composer:

composer require scriptoshi/laravel-mcp-client

Configuration

1. Publish the configuration file:

php artisan vendor:publish --provider="Scriptoshi\McpClient\McpClientServiceProvider"

1. Add your Anthropic API key to your .env file:

ANTHROPIC_API_KEY=your-api-key-here
ANTHROPIC_MODEL=claude-3-sonnet-20240229
ANTHROPIC_MAX_TOKENS=1024

1. Run the migrations:

php artisan migrate

Usage

Basic Usage

use Scriptoshi\McpClient\Facades\McpClient;

// Start a new chat
McpClient::processRequest("What's the weather like?", $chatUuid);

Implementing a Custom Tool Server

Create a new server class that implements McpServerInterface:

use Scriptoshi\McpClient\Contracts\McpServerInterface;

class WeatherServer implements McpServerInterface
{
    public function initialize(): array
    {
        return [
            'serverInfo' => [
                'name' => 'WeatherServer',
                'version' => '1.0.0'
            ],
            'capabilities' => [
                'tools' => true
            ]
        ];
    }

    public function listTools(): array
    {
        return [
            'tools' => [
                [
                    'name' => 'get_weather',
                    'description' => 'Get current weather for a location',
                    'inputSchema' => [
                        'type' => 'object',
                        'properties' => [
                            'location' => [
                                'type' => 'string',
                                'description' => 'City name or coordinates'
                            ]
                        ],
                        'required' => ['location']
                    ]
                ]
            ]
        ];
    }

    public function toolShouldQueue(string $toolname): bool
    {
        return false;
    }

    public function executeTool(string $name, array $arguments, LoggerInterface $logger): array
    {
        // Implement your tool logic here
    }
}

Registering a Tool Server

You can register tool servers in your AppServiceProvider or create a dedicated service provider:

use Scriptoshi\McpClient\Facades\McpClient;

public function boot()
{
    McpClient::registerServer('weather', new WeatherServer());
}

Using the Queue

For long-running tools, implement queueing:

public function toolShouldQueue(string $toolname): bool
{
    return match($toolname) {
        'long_running_process' => true,
        default => false
    };
}

Working with Chat History

use Scriptoshi\McpClient\Models\Chat;

// Find a chat by UUID
$chat = Chat::findByUuid($uuid);

// Get chat messages
$messages = $chat->messages;

// Get message responses
$responses = $message->responses;

// Get tool executions
$runners = $response->runners;

Error Handling

The package includes comprehensive error handling and logging:

$runner->error('Something went wrong', [
    'context' => 'Additional error details'
]);

// Different log levels
$runner->info('Processing started');
$runner->warning('Resource usage high');
$runner->success('Operation completed');

Events

The package dispatches several events you can listen for:

• MessageCreatedEvent
• MessageProcessedEvent
• MessageErrorEvent

Testing

composer test

Security

If you discover any security-related issues, please email security@scriptoshi.com instead of using the issue tracker.

Credits

• Scriptoshi
• All Contributors

License

The MIT License (MIT). Please see License File for more information.