@mastergo/magic-mcp 0.0.4-beta.1 → 0.0.4-beta.11

package/README.md

@@ -0,0 +1,162 @@
+# MasterGo Magic MCP
+
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/mastergo-design/mastergo-magic-mcp)
+
+MasterGo Magic MCP is a standalone MCP (Model Context Protocol) service designed to connect MasterGo design tools with AI models. It enables AI models to directly retrieve DSL data from MasterGo design files.
+
+## Key Features
+
+- Retrieves DSL data from MasterGo design files
+- Runs directly with npx
+- No external dependencies required, only Node.js environment needed
+
+## Tutorial
+
+- https://mastergo.com/file/155675508499265?page_id=158:0002
+
+## Usage
+
+### Obtaining MG_MCP_TOKEN
+
+1. Visit https://mastergo.com
+2. Enter personal settings
+3. Click the Security Settings tab
+4. Find the personal access token
+5. Click to generate the token
+
+### Command Line Options
+
+```
+npx @mastergo/magic-mcp --token=YOUR_TOKEN [--url=API_URL] [--rule=RULE_NAME] [--debug]
+```
+
+#### Parameters:
+
+- `--token=YOUR_TOKEN` (required): MasterGo API token for authentication
+- `--url=API_URL` (optional): API base URL, defaults to http://localhost:3000
+- `--rule=RULE_NAME` (optional): Add design rules to apply, can be used multiple times
+- `--debug` (optional): Enable debug mode for detailed error information
+
+You can also use space-separated format for parameters:
+
+```
+npx @mastergo/magic-mcp --token YOUR_TOKEN --url API_URL --rule RULE_NAME --debug
+```
+
+### LINGMA Usage
+
+Search for LINGMA in the VSCode extension marketplace and install it.
+
+<img src="https://github.com/mastergo-design/mastergo-magic-mcp/blob/main/images/image-20250507174245589.png" alt="image-20250507174245589" style="zoom:25%;" />
+
+After logging in, click on [MCP tools] in the chat box.
+
+<img src="https://github.com/mastergo-design/mastergo-magic-mcp/blob/main/images/image-20250507174511910.png" alt="image-20250507174511910" style="zoom:25%;" />
+
+Click on [MCP Square] at the top to enter the MCP marketplace, find the MasterGo design collaboration tool and install it.
+
+<img src="https://github.com/mastergo-design/mastergo-magic-mcp/blob/main/images/image-20250507174840456.png" alt="image-20250507174840456" style="zoom:25%;" />
+
+After installation, go back to [MCP Servers], and edit our MCP service to replace it with your own MasterGo token.
+
+<img src="https://github.com/mastergo-design/mastergo-magic-mcp/blob/main/images/image-20250507175005364.png" alt="image-20250507175005364" style="zoom:25%;" />
+
+Finally, switch the chat mode to agent mode in the chat interface.
+
+<img src="https://github.com/mastergo-design/mastergo-magic-mcp/blob/main/images/image-20250507175107044.png" alt="image-20250507175107044" style="zoom:25%;" />
+
+### cursor Usage
+
+Cursor Mcp usage guide reference: https://docs.cursor.com/context/model-context-protocol#using-mcp-tools-in-agent
+
+```json
+{
+  "mcpServers": {
+    "mastergo-magic-mcp": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@mastergo/magic-mcp",
+        "--token=<MG_MCP_TOKEN>",
+        "--url=https://mastergo.com"
+      ],
+      "env": {}
+    }
+  }
+}
+```
+
+### cline Usage
+
+```json
+{
+  "mcpServers": {
+    "@master/mastergo-magic-mcp": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@mastergo/magic-mcp",
+        "--token=<MG_MCP_TOKEN>",
+        "--url=https://mastergo.com"
+      ],
+      "env": {}
+    }
+  }
+}
+```
+
+## Project Structure
+
+### src Directory
+
+The `src` directory contains the core implementation of the MasterGo Magic MCP service:
+
+- `index.ts`: Entry point of the application that initializes the MCP server and registers all tools
+- `http-util.ts`: Utility for handling HTTP requests to the MasterGo API
+- `types.d.ts`: TypeScript type definitions for the project
+
+#### src/tools
+
+Contains implementations of MCP tools:
+
+- `base-tool.ts`: Base class for all MCP tools
+- `get-dsl.ts`: Tool for retrieving DSL (Domain Specific Language) data from MasterGo design files
+- `get-component-link.ts`: Tool for retrieving component documentation from links
+- `get-meta.ts`: Tool for retrieving metadata information
+- `get-component-workflow.ts`: Tool providing structured component development workflow for Vue and React components, generating workflow files and component specifications
+
+#### src/markdown
+
+Contains markdown files with additional documentation:
+
+- `meta.md`: Documentation about metadata structure and usage
+- `component-workflow.md`: Component development workflow documentation guiding structured component development process
+
+## Local Development
+
+1. Run `yarn` and `yarn build` to install dependencies and build the code
+2. Find the absolute path of `bin/cli.js`
+3. Add local MCP configuration with your token
+
+```json
+"mastergo-mcp-local": {
+  "command": "node",
+  "args": [
+    "absolute/path/to/bin/cli.js",
+    "--token=mg_xxxxxx",
+    "--url=https://mastergo.com",
+    "--debug"
+  ],
+  "env": {}
+},
+```
+
+4. Restart your editor to ensure the local MCP is enabled
+
+After successful execution, you can debug based on the local running results. You can build your own MCP service based on your modifications.
+
+We welcome your code contributions and look forward to building MasterGo's MCP service together.
+
+## License
+
+ISC

package/README.zh-CN.md

@@ -1,5 +1,7 @@
 # MasterGo Magic MCP
 
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/mastergo-design/mastergo-magic-mcp)
+
 MasterGo Magic MCP 是一个独立的 MCP（Model Context Protocol）服务，旨在连接 MasterGo 设计工具与 AI 模型。它使 AI 模型能够直接从 MasterGo 设计文件中获取 DSL 数据。
 
 ## 主要特性
@@ -8,7 +10,7 @@ MasterGo Magic MCP 是一个独立的 MCP（Model Context Protocol）服务，
 - 可直接通过 npx 运行
 - 仅需 Node.js 环境，无需其他外部依赖
 
-### 教程
+## 教程
 
 - https://mastergo.com/file/155675508499265?page_id=158:0002
 
@@ -22,6 +24,47 @@ MasterGo Magic MCP 是一个独立的 MCP（Model Context Protocol）服务，
 4. 找到个人访问令牌
 5. 点击生成令牌
 
+### 命令行选项
+
+```
+npx @mastergo/magic-mcp --token=YOUR_TOKEN [--url=API_URL] [--rule=RULE_NAME] [--debug]
+```
+
+#### 参数:
+
+- `--token=YOUR_TOKEN` (必需): MasterGo API 认证令牌
+- `--url=API_URL` (可选): API 基础 URL，默认为 http://localhost:3000
+- `--rule=RULE_NAME` (可选): 添加要应用的设计规则，可多次使用
+- `--debug` (可选): 启用调试模式，提供详细错误信息
+
+你也可以使用空格分隔的参数格式:
+
+```
+npx @mastergo/magic-mcp --token YOUR_TOKEN --url API_URL --rule RULE_NAME --debug
+```
+
+### LINGMA 使用方法
+
+在 vscode 拓展市场中搜索 LINGMA -> 然后安装该拓展
+
+<img src="https://github.com/mastergo-design/mastergo-magic-mcp/blob/main/images/image-20250507174245589.png" alt="image-20250507174245589" style="zoom:25%;" />
+
+登录后 -> 在聊天框中点击 [MCP tools]
+
+<img src="https://github.com/mastergo-design/mastergo-magic-mcp/blob/main/images/image-20250507174511910.png" alt="image-20250507174511910" style="zoom:25%;" />
+
+点击顶部 [MCP Sqaure] 进入mcp市场，在市场中找到 Mastergo设计协作工具并安装
+
+<img src="https://github.com/mastergo-design/mastergo-magic-mcp/blob/main/images/image-20250507174840456.png" alt="image-20250507174840456" style="zoom:25%;" />
+
+安装完成后，需要回到 [MCP Servers], 并编辑我们的mcp服务，将自己的mastergo token 替换上去
+
+<img src="https://github.com/mastergo-design/mastergo-magic-mcp/blob/main/images/image-20250507175005364.png" alt="image-20250507175005364" style="zoom:25%;" />
+
+最后在聊天界面中将聊天模式切换为agent模式。
+
+<img src="https://github.com/mastergo-design/mastergo-magic-mcp/blob/main/images/image-20250507175107044.png" alt="image-20250507175107044" style="zoom:25%;" />
+
 ### Cursor 使用方法
 
 Cursor Mcp 使用指南参考：https://docs.cursor.com/context/model-context-protocol#using-mcp-tools-in-agent
@@ -62,6 +105,58 @@ Cursor Mcp 使用指南参考：https://docs.cursor.com/context/model-context-pr
 }
 ```
 
+## 项目结构
+
+### src 目录
+
+`src` 目录包含 MasterGo Magic MCP 服务的核心实现：
+
+- `index.ts`：应用程序入口点，初始化 MCP 服务器并注册所有工具
+- `http-util.ts`：处理与 MasterGo API 通信的 HTTP 请求工具
+- `types.d.ts`：项目的 TypeScript 类型定义
+
+#### src/tools
+
+包含 MCP 工具的实现：
+
+- `base-tool.ts`：所有 MCP 工具的基类
+- `get-dsl.ts`：从 MasterGo 设计文件中获取 DSL（领域特定语言）数据的工具
+- `get-component-link.ts`：从链接中获取组件文档的工具
+- `get-meta.ts`：获取元数据信息的工具
+- `get-component-workflow.ts`：提供结构化的组件开发工作流工具，支持 Vue 和 React 组件开发，生成所需的工作流文件和组件规范
+
+#### src/markdown
+
+包含附加文档的 markdown 文件：
+
+- `meta.md`：关于元数据结构和用法的文档
+- `component-workflow.md`：组件开发工作流程文档，指导结构化组件开发过程
+
+## 本地开发
+
+1. 运行 `yarn` 和 `yarn build`，安装依赖并构建代码
+2. 查看 `bin/cli.js` 的绝对路径
+3. 在 MCP 配置中添加本地 MCP 配置，其中 token 为您获取的 token
+
+```json
+"mastergo-mcp-local": {
+  "command": "node",
+  "args": [
+    "bin/cli.js绝对路径地址",
+    "--token=mg_xxxxxx",
+    "--url=https://mastergo.com",
+    "--debug"
+  ],
+  "env": {}
+},
+```
+
+4. 重启编辑器，确认本地 MCP 已开启
+
+运行成功后，就可以基于本地运行的结果进行调试。您可以基于自己的修改构建自己的 MCP 服务。
+
+欢迎您为我们提供代码贡献，并期待大家一起共建 MasterGo 的 MCP 服务。
+
 ## 许可证
 
-ISC 
+ISC

package/bin/cli.js

@@ -9,6 +9,8 @@ const args = process.argv.slice(2);
 let token = "";
 let baseUrl = "http://localhost:3000";
 let debug = false;
+// Array to collect rules
+let rules = [];
 
 // Parse arguments
 for (let i = 0; i < args.length; i++) {
@@ -24,14 +26,20 @@ for (let i = 0; i < args.length; i++) {
     baseUrl = args[i].split("=")[1];
   } else if (args[i] === "--debug") {
     debug = true;
+    // Add support for --rule parameter
+  } else if (args[i] === "--rule" && i + 1 < args.length) {
+    rules.push(args[i + 1]);
+    i++;
+  } else if (args[i].startsWith("--rule=")) {
+    rules.push(args[i].split("=")[1]);
   }
 }
 
 // Check required arguments
-if (!token) {
+if (!token && !process.env.MASTERGO_API_TOKEN) {
   console.error("Error: Missing MasterGo API Token");
   console.error(
-    "Usage: npx mastergo-magic-mcp --token=YOUR_TOKEN [--url=API_URL]"
+    "Usage: npx mastergo-magic-mcp --token=YOUR_TOKEN [--url=API_URL] [--rule=RULE_NAME]"
   );
   console.error("Use --help or -h for more information");
   process.exit(1);
@@ -39,10 +47,12 @@ if (!token) {
 
 // Set environment variables
 const env = {
-  ...process.env,
   MASTERGO_API_TOKEN: token,
+  ...process.env,
   API_BASE_URL: baseUrl,
   DEBUG: debug ? "true" : "false",
+  // Add RULES environment variable as stringified array
+  RULES: JSON.stringify(rules),
 };
 
 // Get package path
@@ -51,7 +61,9 @@ const indexPath = path.join(packageDir, "index.js");
 
 // Check if file exists
 if (!fs.existsSync(indexPath)) {
-  console.error("Error: Executable file not found. Please ensure the package is correctly installed.");
+  console.error(
+    "Error: Executable file not found. Please ensure the package is correctly installed."
+  );
   process.exit(1);
 }
 
@@ -60,6 +72,7 @@ if (debug) {
   console.log(`Package path: ${indexPath}`);
   console.log(`Token: ${token ? "set" : "not set"}`);
   console.log(`API URL: ${baseUrl}`);
+  console.log(`Rules: ${rules.length > 0 ? rules.join(", ") : "none"}`);
   console.log(`Debug mode: ${debug ? "enabled" : "disabled"}`);
 }