README

A Laravel package that provides seamless integration with Model Context Protocol (MCP) servers. This package allows you to connect to any MCP server defined in your configuration, whether it's a remote HTTP-based server or a local process using STDIO communication.

Key features:

Connect to multiple MCP servers defined in your configuration
Support for HTTP and STDIO transport methods
Simple API for retrieving tools and resources from MCP servers
Flexible configuration options for different server types
Laravel-friendly integration with dependency injection

Note that while project is running with php artisan serve STDIO transporter doesn't work

Installation

You can install the package via composer:

composer require redberry/mcp-client-laravel

After installation, publish the configuration file:

php artisan vendor:publish --tag="mcp-client-config"

This will create a config/mcp-client.php file in your application.

Configuration

The published configuration file contains settings for your MCP servers. Here's an example configuration:

return [
    'servers' => [
        'github' => [
            'type' => \Redberry\MCPClient\Enums\Transporters::HTTP,
            'base_url' => 'https://api.githubcopilot.com/mcp',
            'timeout' => 30,
            'token' => env('GITHUB_API_TOKEN', null),
        ],
        'npx_mcp_server' => [
            'type' => \Redberry\MCPClient\Enums\Transporters::STDIO,
            'command' => [
                'npx',
                '-y',
                '@modelcontextprotocol/server-memory',
            ],
            'timeout' => 30,
            'cwd' => base_path(),
        ],
    ],
];

Configuration Options

HTTP Transporter

type: Set to Redberry\MCPClient\Enums\Transporters::HTTP for HTTP connections
base_url: The base URL of the MCP server
timeout: Request timeout in seconds
token: Authentication token (if required)

STDIO Transporter

type: Set to Redberry\MCPClient\Enums\Transporters::STDIO for STDIO connections
command: Array of command parts to execute the MCP server
timeout: Command timeout in seconds
cwd: Current working directory for the command

Usage

Basic Usage

use Redberry\MCPClient\Facades\MCPClient;

// Connect to a specific MCP server defined in your config
$client = MCPClient::connect('github');

// Get available tools from the MCP server
$tools = $client->tools();

// Get available resources from the MCP server
$resources = $client->resources();

Using Dependency Injection

use Redberry\MCPClient\MCPClient;

class MyService
{
    public function __construct(private MCPClient $mcpClient)
    {
    }

    public function getToolsFromGithub()
    {
        return $this->mcpClient->connect('github')->tools();
    }
}

Working with Collections

The tools() and resources() methods return a Collection object that provides helpful methods for working with the results:

// Get all tools as an array
$allTools = $client->tools()->all();

// Get only specific tools by name
$specificTools = $client->tools()->only('tool1', 'tool2');

// Exclude specific tools
$filteredTools = $client->tools()->except('tool3');

// Map over tools
$mappedTools = $client->tools()->map(function ($tool) {
    return $tool['name'];
});

Call tools

The callTool method is used to execute specific tool. Here is the signature:

public function callTool(string $toolName, mixed $params = []): mixed;

Example:

$result = $client->callTool('create_entities', [
    'entities' => [
        [
            'name' => 'John Doe',
            'entityType' => 'PERSON',
            'observations' => ['Test observation 1', 'Test observation 2'],
        ]
    ],
]);

Read Resources

The readResource method is used to retrieve the resource by the uri.

public function readResource(string $uri): mixed;

Example:

$result = $client->readResource("file:///project/src/main.rs");

Advanced Usage

Creating Custom Transporters

If you need to create a custom transporter, you can extend the Transporter interface and implement your own transport mechanism. Then register it in the TransporterFactory.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

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

redberry / mcp-client-laravel

Maintainers

Details