Laravel MCP Server (bramatolaravel MCP Server)

🚀 Laravel MCP 服務器

Laravel MCP 服務器是一個基於模型上下文協議（Model Context Protocol，簡稱 MCP）的擴展包，為 Laravel 應用提供統一接口，用於管理模型資源和執行工具。該協議明確了客戶端與服務器的交互方式，讓客戶端能通過標準方法請求模型數據或執行特定操作。

🚀 快速開始

Laravel MCP 服務器是基於模型上下文協議（MCP）的擴展包，為 Laravel 應用管理模型資源和執行工具提供統一接口，使客戶端能通過標準方法與服務器交互。

✨ 主要特性

• 提供統一接口管理 Laravel 應用的模型資源和工具執行。
• 支持標準輸入輸出（Stdio）、HTTP 運行時和 WebSocket（通過 Reverb）三種啟動方式。
• 具備工具白名單和基本令牌認證等安全特性。

📦 安裝指南

依賴安裝

要在你的 Laravel 項目中使用 Laravel MCP 服務器，請先安裝以下依賴：

composer require bramato/laravel-mcp-server

配置發佈

將包的配置文件發佈到項目的配置目錄：

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

安裝後配置

完成安裝後，請在 config/mcp.php 文件中根據你的需求進行相應的配置。

💻 使用示例

基礎用法

啟動 MCP 服務器

標準輸入輸出（Stdio）

要啟動一個基於標準輸入輸出的 MCP 服務器，可以在控制檯執行以下命令：

php artisan mcp:server --transport=stdio

這將啟動一個交互式的 MCP 服務器，支持通過標準輸入發送請求，並在標準輸出返回響應。

HTTP 運行時

要啟用 HTTP 運行時，請確保配置了 MCP 的 HTTP 路徑。默認情況下，MCP 使用 /mcp-rpc 路徑來處理 HTTP 請求。啟動你的 Laravel 開發服務器或配置好反向代理後，可以通過發送 POST 請求到該路徑來與 MCP 服務進行交互。

WebSocket（通過 Reverb）

要啟用 WebSocket 支持，請先安裝並配置好 Laravel 的 Reverb 擴展包：

php artisan reverb:install

然後在 config/mcp.php 文件中將 websocket 加入到 enabled_transports 數組，並啟動 Reverb 服務器：

php artisan reverb:start

高級用法

客戶端代碼示例

use Bramato\LaravelMcpServer\Client\McpClient;

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

// 獲取資源數據
$response = $client->get('example.resource', $modelId);
echo json_encode($response);

// 執行工具操作
$response = $client->execute('example.tool', [
    'parameter1' => 'value1',
]);
echo json_encode($response);

服務器端代碼示例

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

class ExampleResource extends McpResource {
    public function get(Model $model) {
        // 返回模型數據
        return [
            'id' => $model->id,
            'name' => $model->name,
        ];
    }
}

class ExampleTool extends McpTool {
    public function execute(array $parameters) {
        // 執行工具操作
        return 'Operation completed successfully';
    }
}

📚 詳細文檔

安全注意事項

MCP 協議本身並未定義客戶端與服務器之間的身份驗證或授權機制。因此，我們提供以下安全特性來保護你的 MCP 服務：

• 工具白名單：只有在 config/mcp.php 文件中明確列出的工具才能被執行。
• 基本令牌認證：可以通過配置啟用基於令牌的身份驗證。

⚠️ 重要提示

你必須自行實現精細的授權邏輯，以確保客戶端請求的資源或執行的操作符合你的應用權限策略。建議使用 Laravel 的 Gates 和 Policies 來管理這些權限。

測試

運行測試套件

要運行內置的 PHPUnit 測試套件，請按照以下步驟操作：

• 在包目錄中運行：

../../vendor/bin/phpunit

• 或者在項目根目錄中運行：

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

編寫自定義測試

為了確保 MCP 服務的功能正常，建議編寫自定義的集成測試。你可以參考 tests/_factory.php 文件中的示例來創建和配置 MCP 客戶端實例，併發送各種請求以驗證預期的行為。

配置選項

以下是 MCP 服務器的主要配置選項：

return [
    // 啟用的傳輸方式
    'enabled_transports' => ['http', 'stdio', 'websocket'],

    // HTTP 相關配置
    'http' => [
        'path' => '/mcp-rpc',
        'middleware' => [
            \Bramato\LaravelMcpServer\Http\Middleware\McpAuthentication::class,
        ],
    ],

    // WebSocket 相關配置（僅當使用 Reverb 時生效）
    'websocket' => [
        'driver' => 'reverb',
        'prefix' => 'mcp-ws',
    ],

    // 資源和工具的定義
    'resources' => [
        // 示例資源定義
        'example.resource' => [
            'description' => '這是一個示例資源',
            'schema' => [
                // 定義資源的輸入和輸出 schema
            ],
        ],
    ],

    'tools' => [
        // 示例工具定義
        'example.tool' => [
            'description' => '這是一個示例工具，用於執行特定操作',
            'parameters' => [
                // 工具所需的參數定義
            ],
        ],
    ],
];

創建資源

基本結構

每個資源應該包含以下屬性：

public function __construct() {
}

/**
 * 獲取資源的元數據。
 *
 * @return array
 */
public function meta(): array {
    return [];
}

/**
 * 獲取指定模型實例的數據。
 *
 * @param Model $model
 * @return mixed
 */
public function get(Model $model) {
    // 返回模型數據
}

/**
 * 處理客戶端對資源的請求。
 *
 * @param Request $request
 * @return Response
 */
public function handle(Request $request): Response {
    // 根據請求類型處理邏輯
}

創建工具

基本結構

每個工具應該包含以下屬性：

public function __construct() {
}

/**
 * 獲取工具的元數據。
 *
 * @return array
 */
public function meta(): array {
    return [];
}

/**
 * 執行工具操作。
 *
 * @param array $parameters
 * @return mixed
 */
public function execute(array $parameters) {
    // 返回執行結果
}

🔧 技術細節

Laravel MCP 服務器基於模型上下文協議（MCP），該協議定義了客戶端與服務器之間的交互方式。服務器通過不同的傳輸方式（如 Stdio、HTTP、WebSocket）接收客戶端的請求，並根據配置的資源和工具定義進行處理。在安全方面，通過工具白名單和基本令牌認證來保護服務，但需要開發者自行實現精細的授權邏輯。

📄 許可證

文檔中未提及許可證相關信息。

更多資源

• 官方文檔：Laravel MCP 服務器文檔
• GitHub 倉庫：Bramato/LaravelMcpServer