Laravel MCP

• 簡介
• 安裝
  • 發佈路由
• 建立伺服器
  • 伺服器註冊
  • Web 伺服器
  • 本地伺服器
• 工具
  • 建立工具
  • 工具輸入綱要
  • 工具輸出綱要
  • 驗證工具參數
  • 工具依賴注入
  • 工具標註
  • 條件式工具註冊
  • 工具回應
• 提示詞
  • 建立提示詞
  • 提示詞參數
  • 驗證提示詞參數
  • 提示詞依賴注入
  • 條件式提示詞註冊
  • 提示詞回應
• 資源
  • 建立資源
  • 資源模板
  • 資源 URI 與 MIME 類型
  • 資源請求
  • 資源依賴注入
  • 資源標註
  • 條件式資源註冊
  • 資源回應
• 應用程式
  • 建立應用程式資源
  • 從工具渲染應用程式
  • 應用程式工具可見性
  • 應用程式配置
  • 使用 Boost 建立應用程式
• 元資料
• 圖示
• 認證
  • OAuth 2.1
  • Sanctum
• 授權
• MCP 客戶端
  • 連接伺服器
  • 命名客戶端
  • 客戶端認證
  • 工具
  • 提示詞
  • 資源
• 測試伺服器
  • MCP Inspector
  • 單元測試

簡介

Laravel MCP 提供了一種簡單優雅的方式，讓 AI 客戶端透過模型上下文協定與您的 Laravel 應用程式互動。它提供了一個表達力強、流暢的介面來定義伺服器、工具、資源和提示詞，從而實現 AI 驅動的應用程式互動。

安裝

首先，使用 Composer 套件管理器將 Laravel MCP 安裝到您的專案中：

composer require laravel/mcp

發佈路由

安裝 Laravel MCP 後，執行 vendor:publish Artisan 命令來發佈 routes/ai.php 檔案，您將在此定義 MCP 伺服器：

php artisan vendor:publish --tag=ai-routes

此命令在應用程式的 routes 目錄中建立 routes/ai.php 檔案，您將用它來註冊 MCP 伺服器。

建立伺服器

您可以使用 make:mcp-server Artisan 命令建立 MCP 伺服器。伺服器作為中央通訊點，向 AI 客戶端公開工具、資源和提示詞等 MCP 功能：

php artisan make:mcp-server WeatherServer

此命令將在 app/Mcp/Servers 目錄中建立一個新的伺服器類別。生成的伺服器類別擴展了 Laravel MCP 的基礎 Laravel\Mcp\Server 類別，並提供了用於配置伺服器和註冊工具、資源和提示詞的屬性和方法。

伺服器註冊

建立伺服器後，您必須在 routes/ai.php 檔案中註冊它，使其可被存取。Laravel MCP 提供了兩種註冊伺服器的方法：web 用於 HTTP 可存取的伺服器，local 用於命令列伺服器。

Web 伺服器

Web 伺服器是最常見的伺服器類型，可透過 HTTP POST 請求存取，非常適合遠端 AI 客戶端或基於 Web 的整合。使用 web 方法註冊 Web 伺服器：

use App\Mcp\Servers\WeatherServer;
use Laravel\Mcp\Facades\Mcp;

Mcp::web('/mcp/weather', WeatherServer::class);

就像常規路由一樣，您可以應用中介層來保護 Web 伺服器：

Mcp::web('/mcp/weather', WeatherServer::class)
    ->middleware(['throttle:mcp']);

本地伺服器

本地伺服器作為 Artisan 命令執行，非常適合建立本地 AI 助手整合，如 Laravel Boost。使用 local 方法註冊本地伺服器：

use App\Mcp\Servers\WeatherServer;
use Laravel\Mcp\Facades\Mcp;

Mcp::local('weather', WeatherServer::class);

註冊後，您通常不需要手動執行 mcp:start Artisan 命令。相反，請配置您的 MCP 客戶端（AI 代理）來啟動伺服器，或使用 MCP Inspector。

工具

工具使您的伺服器能夠公開 AI 客戶端可以呼叫的功能。它們允許語言模型執行操作、執行程式碼或與外部系統互動。

建立工具

要建立工具，請執行 make:mcp-tool Artisan 命令：

php artisan make:mcp-tool CurrentWeatherTool

建立工具後，在伺服器的 $tools 屬性中註冊它。

工具輸入綱要

工具可以定義輸入綱要來指定它們從 AI 客戶端接受哪些參數。使用 Laravel 的 Illuminate\Contracts\JsonSchema\JsonSchema 建構器來定義工具的輸入要求。

工具輸出綱要

工具可以定義輸出綱要來指定其回應的結構。這使得與需要可解析工具結果的 AI 客戶端更好地整合。

驗證工具參數

JSON Schema 定義為工具參數提供了基本結構，但您可能還希望強制執行更複雜的驗證規則。Laravel MCP 與 Laravel 的驗證功能無縫整合。您可以在工具的 handle 方法中驗證傳入的工具參數。

工具依賴注入

Laravel 服務容器用於解析所有工具。因此，您可以在建構函數中類型提示工具可能需要的任何依賴項。除了建構函數注入之外，您還可以在工具的 handle() 方法中類型提示依賴項。

工具標註

您可以使用標註來增強工具，為 AI 客戶端提供額外的元資料。可用標註包括 IsReadOnly、IsDestructive、IsIdempotent 和 IsOpenWorld。

條件式工具註冊

您可以透過在工具類別中實作 shouldRegister 方法來在運行時有條件地註冊工具。當此方法返回 false 時，該工具不會出現在可用工具列表中。

工具回應

工具必須返回一個 Laravel\Mcp\Response 實例。Response 類別提供了多種便捷方法來建立不同類型的回應：text、error、image、audio、fromStorage、structured 等。工具可以透過返回 Response 實例陣列來返回多個內容，也可以透過從 handle 方法返回生成器來進行串流回應。

提示詞

提示詞使您的伺服器能夠共享可重用的提示模板，AI 客戶端可以使用它們與語言模型互動。它們提供了一種標準化方式來建構常見查詢和互動。

建立提示詞

執行 make:mcp-prompt Artisan 命令來建立提示詞：

php artisan make:mcp-prompt DescribeWeatherPrompt

建立後，在伺服器的 $prompts 屬性中註冊它。

提示詞參數

提示詞可以定義參數，允許 AI 客戶端使用特定值自訂提示模板。

驗證提示詞參數

提示詞參數會根據其定義自動驗證，但您也可以強制執行更複雜的驗證規則。

提示詞依賴注入

服務容器用於解析所有提示詞，支援建構函數和方法注入。

條件式提示詞註冊

透過實作 shouldRegister 方法有條件地註冊提示詞。

提示詞回應

提示詞可以返回單個 Laravel\Mcp\Response 或可迭代的 Response 實例。使用 asAssistant() 方法指示回應消息應被視為來自 AI 助手。

資源

資源使您的伺服器能夠公開資料和內容，AI 客戶端可以讀取並用作與語言模型互動時的上下文。

建立資源

執行 make:mcp-resource Artisan 命令來建立資源，然後在伺服器的 $resources 屬性中註冊它。

資源模板

資源模板使您的伺服器能夠公開與包含變數的 URI 模式匹配的動態資源。透過實作 HasUriTemplate 介面並定義 uriTemplate 方法來建立資源模板。

資源 URI 與 MIME 類型

每個資源由一個唯一的 URI 標識，並具有一個關聯的 MIME 類型。可以使用 Uri 和 MimeType 屬性自訂這些值。

資源請求

與工具和提示詞不同，資源不能定義輸入綱要或參數。但是，您仍然可以在資源的 handle 方法中與請求物件互動。

資源依賴注入

支援建構函數和方法注入。

資源標註

可用標註包括 Audience、Priority 和 LastModified。

條件式資源註冊

透過實作 shouldRegister 方法有條件地註冊資源。

資源回應

資源可以返回文字內容、資源鏈接（resourceLink）、二進位內容（blob）或錯誤回應（error）。

應用程式

Laravel MCP 支援 MCP Apps，這是模型上下文協定的一個擴展，允許工具在支援的主機中的沙箱 iframe 內渲染互動式 HTML 應用程式。

建立應用程式資源

使用 make:mcp-app-resource Artisan 命令建立應用程式資源。這會建立一個 PHP 類別和一個 Blade 檢視。

從工具渲染應用程式

要顯示應用程式資源，使用 RendersApp 屬性將工具鏈接到它。

應用程式工具可見性

每個 RendersApp 工具可以透過 visibility 參數限制誰可以呼叫它。

應用程式配置

AppMeta 屬性配置 iframe 的內容安全政策、瀏覽器權限和應包含在檢視中的庫腳本。

使用 Boost 建立應用程式

Laravel MCP 包含一個專用的 Boost 技能參考。

元資料

Laravel MCP 支援 MCP 規範中定義的 _meta 欄位。元資料可以應用於所有 MCP 基元以及它們的回應。使用 withMeta 方法附加元資料，或使用 $meta 屬性。

圖示

使用 Icon 屬性在伺服器、工具、資源或提示詞上宣告圖示。該屬性可重複使用以提供不同大小或主題變體。

認證

就像路由一樣，您可以使用中介層認證 Web MCP 伺服器。Laravel MCP 支援透過 Sanctum 的基於令牌的認證，以及使用 Laravel Passport 的 OAuth 認證。

OAuth 2.1

透過 OAuth 認證 MCP 伺服器時，在 routes/ai.php 中呼叫 Mcp::oauthRoutes() 方法來註冊所需的 OAuth2 發現和客戶端註冊路由。然後將 Passport 的 auth:api 中介層應用到您的 Mcp::web 路由。

Sanctum

如果您想使用 Sanctum 保護 MCP 伺服器，只需在 routes/ai.php 中將 Sanctum 的認證中介層添加到伺服器。然後確保您的 MCP 客戶端提供 Authorization: Bearer <token> 標頭。

授權

您可以透過 $request->user() 方法存取當前已認證的使用者，從而在 MCP 工具和資源中執行授權檢查。

MCP 客戶端

除了建立伺服器之外，Laravel MCP 還包含一個用於連接到其他 MCP 伺服器的客戶端。客戶端讓您的應用程式發現和呼叫 MCP 伺服器公開的工具。

連接伺服器

使用 Client::web 方法連接到 HTTP 可存取的 MCP 伺服器，或使用 Client::local 方法連接到本地 MCP 伺服器。

命名客戶端

使用 Mcp::registerClient 註冊可重用的命名客戶端。

客戶端認證

使用 withToken 方法進行令牌認證，或使用 withOAuth 方法進行 OAuth 認證。

工具

使用 tools 方法檢索工具，使用 callTool 方法呼叫工具。

提示詞

使用 prompts 方法檢索提示詞，使用 getPrompt 方法獲取提示詞。

資源

使用 resources 方法檢索資源，使用 readResource 方法讀取資源。

測試伺服器

您可以使用內建的 MCP Inspector 或編寫單元測試來測試 MCP 伺服器。

MCP Inspector

MCP Inspector 是一個用於測試和除錯 MCP 伺服器的互動式工具。對任何已註冊的伺服器執行 php artisan mcp:inspector 命令。

單元測試

您可以為 MCP 伺服器編寫單元測試。使用 WeatherServer::tool()、WeatherServer::prompt() 或 WeatherServer::resource() 方法來測試基元。使用 assertOk、assertSee、assertHasErrors 等方法驗證回應。