Laravel MCP Server (bramatolaravel MCP Server)

🚀 Laravel MCP Server

Laravel MCP Server is an extension package based on the Model Context Protocol (MCP), aiming to provide a unified interface for Laravel applications to manage model resources and tool execution. The protocol defines the interaction mode between the client and the server, enabling the client to request model data or perform specific operations through standard methods.

🚀 Quick Start

✨ Features

Laravel MCP Server is an extension package based on the Model Context Protocol (MCP), providing a unified interface for Laravel applications to manage model resources and tool execution. The protocol defines how the client interacts with the server, allowing the client to request model data or perform specific operations using standard methods.

📦 Installation

Dependency Installation

To use Laravel MCP Server in your Laravel project, first install the following dependencies:

composer require bramato/laravel-mcp-server

Configuration Publishing

Publish the package's configuration file to the project's configuration directory:

php artisan vendor:publish --provider="Bramato\LaravelMcpServer\ServiceProvider"

After completing the installation, please configure the config/mcp.php file according to your needs.

💻 Usage Examples

Starting the MCP Server

Standard Input/Output (Stdio)

To start an MCP server based on standard input/output, execute the following command in the console:

php artisan mcp:server --transport=stdio

This will start an interactive MCP server that supports sending requests via standard input and returning responses on standard output.

HTTP Runtime

To enable the HTTP runtime, ensure that the MCP's HTTP path is configured. By default, MCP uses the /mcp-rpc path to handle HTTP requests. After starting your Laravel development server or configuring a reverse proxy, you can interact with the MCP service by sending a POST request to this path.

WebSocket (via Reverb)

To enable WebSocket support, first install and configure Laravel's Reverb extension package:

php artisan reverb:install

Then, add websocket to the enabled_transports array in the config/mcp.php file and start the Reverb server:

php artisan reverb:start

🔧 Technical Details

Security Considerations

The MCP protocol itself does not define authentication or authorization mechanisms between the client and the server. Therefore, we provide the following security features to protect your MCP service:

• Tool Whitelist: Only tools explicitly listed in the config/mcp.php file can be executed.
• Basic Token Authentication: Token-based authentication can be enabled through configuration.

⚠️ Important Note

You must implement fine-grained authorization logic yourself to ensure that client requests for resources or operations comply with your application's permission policy. It is recommended to use Laravel's Gates and Policies to manage these permissions.

Testing

Running the Test Suite

To run the built-in PHPUnit test suite, follow these steps:

• Run in the package directory:

../../vendor/bin/phpunit

• Or run in the project root directory:

./vendor/bin/phpunit packages/bramato/laravel-mcp-server/tests

Writing Custom Tests

To ensure the proper functioning of the MCP service, it is recommended to write custom integration tests. You can refer to the example in the tests/_factory.php file to create and configure an MCP client instance and send various requests to verify the expected behavior.

Configuration Options

The following are the main configuration options for the MCP server:

return [
    // Enabled transports
    'enabled_transports' => ['http', 'stdio', 'websocket'],

    // HTTP-related configuration
    'http' => [
        'path' => '/mcp-rpc',
        'middleware' => [
            \Bramato\LaravelMcpServer\Http\Middleware\McpAuthentication::class,
        ],
    ],

    // WebSocket-related configuration (only effective when using Reverb)
    'websocket' => [
        'driver' => 'reverb',
        'prefix' => 'mcp-ws',
    ],

    // Definitions of resources and tools
    'resources' => [
        // Example resource definition
        'example.resource' => [
            'description' => 'This is an example resource',
            'schema' => [
                // Define the input and output schema of the resource
            ],
        ],
    ],

    'tools' => [
        // Example tool definition
        'example.tool' => [
            'description' => 'This is an example tool for performing specific operations',
            'parameters' => [
                // Define the parameters required by the tool
            ],
        ],
    ],
];

Creating Resources

Basic Structure

Each resource should include the following attributes:

public function __construct() {
}

/**
 * Get the metadata of the resource.
 *
 * @return array
 */
public function meta(): array {
    return [];
}

/**
 * Get the data of the specified model instance.
 *
 * @param Model $model
 * @return mixed
 */
public function get(Model $model) {
    // Return the model data
}

/**
 * Handle client requests for the resource.
 *
 * @param Request $request
 * @return Response
 */
public function handle(Request $request): Response {
    // Handle the logic according to the request type
}

Creating Tools

Basic Structure

Each tool should include the following attributes:

public function __construct() {
}

/**
 * Get the metadata of the tool.
 *
 * @return array
 */
public function meta(): array {
    return [];
}

/**
 * Execute the tool operation.
 *
 * @param array $parameters
 * @return mixed
 */
public function execute(array $parameters) {
    // Return the execution result
}

Example Usage

Client Code Example

use Bramato\LaravelMcpServer\Client\McpClient;

$client = new McpClient('http://localhost:8000/mcp-rpc');

// Get resource data
$response = $client->get('example.resource', $modelId);
echo json_encode($response);

// Execute a tool operation
$response = $client->execute('example.tool', [
    'parameter1' => 'value1',
]);
echo json_encode($response);

Server-Side Code Example

use Bramato\LaravelMcpServer\Resource\McpResource;
use Bramato\LaravelMcpServer\Tool\McpTool;

class ExampleResource extends McpResource {
    public function get(Model $model) {
        // Return the model data
        return [
            'id' => $model->id,
            'name' => $model->name,
        ];
    }
}

class ExampleTool extends McpTool {
    public function execute(array $parameters) {
        // Execute the tool operation
        return 'Operation completed successfully';
    }
}

📚 Documentation

• Official Documentation: Laravel MCP Server Documentation
• GitHub Repository: Bramato/LaravelMcpServer