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 仓库