gem-design-mcp-server 1.0.1

package/README.md

@@ -0,0 +1,79 @@
+# GemDesign MCP Server
+
+GemDesign 的官方 Model Context Protocol (MCP) 服务端。允许 AI 助手（如 Trae, Claude Desktop）直接访问 GemDesign API，执行页面查询、内容获取和项目还原等操作。
+
+## 功能特性
+
+- **页面列表查询**: 获取应用下的所有页面结构。
+- **页面内容获取**: 获取特定页面的 HTML 源码。
+
+## 安装与使用
+
+### 方式一：使用 npx (推荐)
+
+无需安装，直接在 MCP Host (如 Trae) 的配置中使用：
+
+```json
+{
+  "mcpServers": {
+    "GemDesign": {
+      "command": "npx",
+      "args": ["-y", "gem-design-mcp-server"],
+      "env": {
+        "GEMDESIGN_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+### 方式二：全局安装
+
+```bash
+npm install -g gem-design-mcp-server
+```
+
+配置：
+
+```json
+{
+  "mcpServers": {
+    "gem-design": {
+      "command": "gem-design-mcp-server",
+      "env": {
+        "GEMDESIGN_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+### 方式三：源码运行
+
+1. Clone 仓库
+2. `npm install`
+3. `npm run build`
+4. 配置 command 为 `node`，args 为 `["/path/to/build/index.js"]`
+
+## 环境变量
+
+| 变量名               | 说明                        | 默认值                             | 必填 |
+| :------------------- | :-------------------------- | :--------------------------------- | :--- |
+| `GEMDESIGN_API_KEY`  | 您的 GemDesign API 访问令牌 | -                                  | 是   |
+| `GEMDESIGN_BASE_URL` | API 基础地址                | `http://localhost:8000` (开发环境) | 否   |
+
+## 开发调试
+
+```bash
+# 安装依赖
+npm install
+
+# 编译
+npm run build
+
+# 启动模拟服务器
+node mock-api.js
+
+# 运行测试客户端
+node test-client.js
+```

package/build/index.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const zod_1 = require("zod");
+const axios_1 = __importDefault(require("axios"));
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+// --- 1. Environment Variables & Configuration ---
+const API_KEY = process.env.GEMDESIGN_API_KEY;
+// Default to localhost:8000 as requested if not provided
+const BASE_URL = process.env.GEMDESIGN_BASE_URL || "http://localhost:8000";
+if (!API_KEY) {
+    console.error("Error: GEMDESIGN_API_KEY environment variable is required.");
+    process.exit(1);
+}
+class GemDesignClient {
+    client;
+    constructor(baseURL, token) {
+        this.client = axios_1.default.create({
+            baseURL,
+            headers: {
+                "X-GemDesign-AccessToken": token,
+                "Content-Type": "application/json",
+            },
+            timeout: 10000, // 10s timeout
+        });
+    }
+    /**
+     * Generic POST request handler
+     */
+    async post(endpoint, payload) {
+        try {
+            const response = await this.client.post(endpoint, payload);
+            // Basic validation of response status
+            if (response.status < 200 || response.status >= 300) {
+                throw new types_js_1.McpError(types_js_1.ErrorCode.InternalError, `[GemDesign API Error] HTTP ${response.status}: ${response.statusText}`);
+            }
+            const body = response.data;
+            // Handle "data wrapper" logic
+            // Assuming if body has 'data' property, we return that.
+            // If 'code' exists and indicates error, we throw.
+            // This is a heuristic based on common patterns.
+            if (body && typeof body === 'object' && 'data' in body) {
+                // Check for business logic error codes if present
+                // Example: if (body.code && body.code !== 200) ...
+                // For now, we return data.
+                return body.data;
+            }
+            // Fallback: return the whole body if structure is unexpected but valid JSON
+            return body;
+        }
+        catch (error) {
+            this.handleError(error);
+            throw error; // Make TS happy, handleError always throws
+        }
+    }
+    handleError(error) {
+        if (axios_1.default.isAxiosError(error)) {
+            const axiosError = error;
+            // 401/403 -> InvalidRequest (Auth Error)
+            if (axiosError.response?.status === 401 || axiosError.response?.status === 403) {
+                throw new types_js_1.McpError(types_js_1.ErrorCode.InvalidRequest, "[GemDesign Auth Error] Invalid AccessToken. Please check your environment configuration.");
+            }
+            // 404/500 or others -> InternalError
+            const msg = axiosError.response?.data?.message || axiosError.message;
+            throw new types_js_1.McpError(types_js_1.ErrorCode.InternalError, `[GemDesign API Error] ${msg}`);
+        }
+        // Unknown error
+        throw new types_js_1.McpError(types_js_1.ErrorCode.InternalError, `[GemDesign Unknown Error] ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+const apiClient = new GemDesignClient(BASE_URL, API_KEY);
+// --- 3. MCP Server Setup ---
+const server = new mcp_js_1.McpServer({
+    name: "gem-design-mcp",
+    version: "1.0.0",
+});
+// --- 4. Tool Definitions ---
+/**
+ * Tool: gemdesign_list_pages
+ * Description: Get list of pages for a given App UUID
+ */
+server.tool("gemdesign_list_pages", {
+    appuuid: zod_1.z.string().describe("The unique identifier of the GemDesign App"),
+}, async ({ appuuid }) => {
+    try {
+        const pages = await apiClient.post("/api/v1/listPages", { appuuid });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(pages, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        // McpErrors are already thrown by apiClient, but we ensure they propagate correctly
+        // The SDK handles threw errors by returning an error response
+        throw error;
+    }
+});
+/**
+ * Tool: gemdesign_get_page_content
+ * Description: Get raw HTML content for a specific page
+ */
+server.tool("gemdesign_get_page_content", {
+    appuuid: zod_1.z.string().describe("The unique identifier of the GemDesign App"),
+    pageuuid: zod_1.z.string().describe("The unique identifier of the Page"),
+}, async ({ appuuid, pageuuid }) => {
+    try {
+        // The user mentioned this returns HTML string. 
+        // It might be wrapped in JSON { data: "<html>..." } or direct string.
+        // Our apiClient handles { data: ... } unwrapping.
+        const htmlContent = await apiClient.post("/api/v1/getPageHtml", { appuuid, pageuuid });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: typeof htmlContent === 'string' ? htmlContent : JSON.stringify(htmlContent),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        throw error;
+    }
+});
+// --- 5. Start Server ---
+async function main() {
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    console.error("GemDesign MCP Server running on stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error in main loop:", error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "gem-design-mcp-server",
+  "version": "1.0.1",
+  "description": "MCP Server for GemDesign API",
+  "main": "build/index.js",
+  "bin": {
+    "gem-design-mcp-server": "./build/index.js"
+  },
+  "files": [
+    "build"
+  ],
+  "scripts": {
+    "build": "tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"",
+    "start": "node build/index.js",
+    "dev": "ts-node src/index.ts"
+  },
+  "keywords": [
+    "mcp",
+    "gemdesign",
+    "ai"
+  ],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.1",
+    "axios": "^1.6.0",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "ts-node": "^10.9.0",
+    "typescript": "^5.0.0"
+  }
+}