# @mastergo/vibe-mcp

<div align="center">

**MasterGo MCP 客户端 - 连接 MasterGo 和 IDE / CLI 的桥梁**

通过 MCP 协议连接本地 MasterGo MCP 服务

[快速开始](#快速开始) · [功能特性](#功能特性) · [完整帮助文档](https://mastergo.com/help/MG/MCP)

</div>

---

Server 管理的 Artifact、Asset Session 与 Workspace 演进方案见
[统一架构文档](../docs/server-managed-workspace.md) 和
[实施计划](../docs/implementation-plan.md)。

## 功能特性

- 🔌 **一键安装**：使用 `npx` 无需手动下载
- 📡 **MCP 协议**：完美集成 Cursor 等支持 MCP 的 IDE 或 CLI 工具
- 🔐 **安全认证**：连接本地 MCP 服务，无需配置 AccessKey
- 🛠️ **全能工具箱**：包含代码获取、设计稿生成、变量管理、双向同步等 20+ 个专业工具
- 📦 **清晰的资源边界**：选区、团队库、变量、字体、截图和生成图片由 Server 统一持有；前端代码由 mcp-client 直接返回或导出到用户项目，不写入 Server，也不创建 `.mastergo/workspace.json`

如需完整接入步骤、常用工作流、提示词示例和故障排查，请查看 [完整帮助文档](https://mastergo.com/help/MG/MCP)。

## 快速开始

### 最简单的安装办法

在你当前的 IDE/CLI 或者 Agent 工具里对话：

```text
请为我从 npm 上安装 mastergo/vibe-mcp
```

通常完成后需要重启当前工具。

或者选择下面的手动配置：

### 1. 配置 MCP

例如：编辑 `~/.cursor/mcp.json`（如果文件不存在则创建）：

```json
{
  "mcpServers": {
    "mastergo": {
      "command": "npx",
      "args": ["-y", "@mastergo/vibe-mcp", "--url=http://localhost:30678"]
    }
  }
}
```

**注意事项**： 如果本地 30678 端口被占用，MasterGo 会自动申请新的端口号，同时也需要在 `--url` 配置中改成实际端口。

### 2. 重启 IDE / CLI

重启 Cursor、VSCode、Trae 等 IDE 或者 CLI 工具，或重新加载 MCP 服务器配置。

### 3. 开始使用

在 IDE / CLI 中，您可以：

#### 使用 AI 工具进行设计稿与代码的双向交互

直接在对话框输入指令，AI 会自动识别并调用工具：

- "获取 MasterGo 中选中的图层代码" (**get_selection_node**)
- "使用 MasterGo MCP 设计一个深色模式的统计仪表盘" (**design_page**)
- "修改设计稿选中的图层，改为红色背景" (**agent_update_node**)
- "将我选中的图层删除" (**agent_remove_node**)
- "将本地 HTML 同步到 MasterGo 画布" (**agent_sync_design**)
- "对比本地代码与设计稿的差异" (**get_design_diff**)
- "获取当前文件变量，并创建一套语义变量" (**get_variables** / **agent_update_variables**)

## 许可证

MIT

## 贡献

欢迎提交 Issue 和 Pull Request！

---

Made with ❤️ by MasterGo Team