MCP

🚀 Vendure MCP Server

Vendure MCP Server 是一個獨立的模型上下文協議（MCP）服務器，用於 Vendure CLI 編排。該軟件包按項目運行，允許像 Cursor 這樣的外部客戶端以編程和上下文感知的方式與你本地的 Vendure 項目的 CLI 命令進行交互。

✨ 主要特性

• 項目集成：直接在你的 Vendure 項目中運行，提供上下文感知工具。
• CLI 集成：可直接訪問 Vendure CLI 的 add 和 migrate 命令。
• 項目分析：分析項目結構，列出插件、實體和服務。
• 雙傳輸支持：可通過標準輸入輸出（STDIO）供像 Cursor 這樣的本地客戶端連接，或通過 HTTP 供網絡客戶端連接。
• 環境檢查：驗證項目內的 Vendure 安裝和依賴項。
• 訪問文檔：MCP 可以在需要時獲取官方 Vendure 文檔作為上下文。
• 實時性：可直接用於任何本地 Vendure 項目，無需修改。

📚 詳細文檔

動態 CLI 集成

服務器會根據你項目中安裝的 Vendure CLI 命令定義動態生成 MCP 工具。這確保了：

• 單一事實來源：CLI 的更改會自動反映在 MCP 工具中。
• 面向未來：新的 CLI 命令和選項會自動可用。
• 無幻覺輸出：工具生成的代碼始終正確，因為它基於你項目中的實際 CLI 定義。

📦 安裝指南

⚠️ 重要提示 要使用 MCP 的 CLI 命令編排功能，目標項目應運行版本大於 3.4.0 的 @vendure/cli 軟件包。目前，這應該是在我們的次要分支中。 要更改軟件包版本，請打開項目的 package.json，將 "@vendure/cli" 版本更改為 "minor"，然後刪除 package-lock.json 文件和 node_modules 文件夾，並運行 npm install。

服務器設計為直接從你的 Vendure 項目中安裝和運行，以確保它始終可以訪問正確的依賴項和項目上下文。

配置你的 MCP 客戶端（例如 Cursor）

創建或更新你的 MCP 客戶端使用的 mcp.json 文件。該文件通常位於項目根文件夾內的 .cursor/mcp.json。

選項 1：STDIO 連接（推薦用於本地客戶端）

這是最簡單、最直接的連接方式。

{
    "mcpServers": {
        "vendure-local-mcp": {
            "command": "npx",
            "args": ["@vendure/mcp-server@latest", "--projectPath", "/path/to/your/vendure-project"]
        }
    }
}

⚠️ 重要提示 你必須將 /path/to/your/vendure-project 替換為你的 Vendure 項目根目錄的絕對路徑。

選項 2：HTTP 連接

如果你的客戶端不支持 STDIO 或你需要通過網絡連接，可以在 HTTP 模式下運行服務器。 首先，在你的Vendure 項目根目錄的終端中啟動服務器：

npx @vendure/mcp-server@latest --transport http --projectPath .

這將在默認端口（8000）上啟動服務器，你可以使用 --port <0000> 標誌顯式定義端口。 然後，配置你的 mcp.json 以連接到正在運行的服務器的 URL：

{
    "mcpServers": {
        "vendure": {
            "url": "http://localhost:8000/mcp"
        }
    }
}

選項 3：Docker

這將啟動一個 Docker 容器，服務器將以 stdio 模式運行。有關使用 Docker 運行的更多信息，請參閱 Docker 指南。

{
    "mcpServers": {
        "vendure-mcp-docker": {
            "command": "docker",
            "args": [
                "run",
                "--rm",
                "-i",
                "--env",
                "PROJECT_PATH=/workspace",
                "--volume",
                "/absolute/path/to-your-vendure-project:/workspace",
                "vendure/mcp:latest",
                "--projectPath",
                "/workspace"
            ]
        }
    }
}

⚠️ 重要提示 你必須將 /path/to-your-vendure-project 替換為你的 Vendure 項目根目錄的絕對路徑。

💻 使用示例

開發

如果你要為 Vendure MCP 服務器本身做貢獻，你需要從源代碼運行它。

從源代碼構建

git clone https://github.com/vendure-ecommerce/mcp.git
cd vendure-mcp-server # 或者正確的目錄名稱
npm install
npm run build

開發模式

要將 MCP 客戶端連接到你的本地開發服務器，請使用 npm run dev 腳本並將其指向一個測試 Vendure 項目。你可以在 STDIO 或 HTTP 模式下運行它。

• STDIO 模式：npm run dev -- --projectPath /path/to/your/test-vendure-project
• HTTP 模式：npm run dev:http -- --projectPath /path/to/your/test-vendure-project

按照設置部分的描述配置你的 mcp.json 以連接到你的開發服務器。-- 是正確將參數傳遞給 npm 腳本所必需的。

🔧 故障排除和問題報告

如果你在使用或運行 MCP 時遇到問題，請提供有助於我們重現問題的信息。

💡 使用建議 你可以向我們提供由你的 MCP 客戶端創建的 MCP 日誌。 在 Cursor 中，你可以在命令面板（默認情況下為 Shift + Cmd/Ctrl/Super + P）中查找 Developer: Open Log File... > MCP Logs 來找到它們。

📚 相關鏈接

• Vendure 核心
• Vendure 文檔
• MCP 規範
• GitHub 倉庫