gearvn-pages-mcp-server 1.1.0 → 1.2.0

package/README.md

@@ -2,63 +2,19 @@
 
 MCP (Model Context Protocol) Server cho việc deploy và quản lý các trang HTML tĩnh lên GearVN Pages.
 
-## Tính năng
-
-### 1. deploy-page
-Deploy hoặc update một trang HTML tĩnh.
-
-**Parameters:**
-- `title` (string): Tiêu đề của trang - **AI Agent tự động generate dựa trên nội dung**
-- `content` (string): HTML document đầy đủ với TailwindCSS CDN. JavaScript libraries được phép qua CDN (Alpine.js, Chart.js, GSAP, etc.)
-- `slug` (string): URL slug - **AI Agent tự động generate theo format kebab-case từ title hoặc nội dung**
-
-**Lưu ý quan trọng:**
-- User **KHÔNG cần** cung cấp `title` và `slug`
-- AI Agent sẽ tự động generate dựa trên yêu cầu của user
-- Ví dụ: "tạo website quản lý thu chi" → title: "Quản Lý Thu Chi", slug: "quan-ly-thu-chi"
-
-**Response:**
-```json
-{
-  "success": true,
-  "message": "Page deployed successfully",
-  "url": "https://pages.react.uat.gearvn.xyz/pages/my-page-123"
-}
-```
-
-### 2. list-pages
-Liệt kê tất cả các pages của API key.
-
-**Response:**
-```json
-{
-  "success": true,
-  "count": 2,
-  "pages": [
-    {
-      "id": 1,
-      "slug": "my-page-123",
-      "title": "My Page",
-      "created_at": "2025-01-20T10:00:00Z",
-      "updated_at": "2025-01-20T10:00:00Z"
-    }
-  ]
-}
-```
-
 ## Cài đặt
 
 ### Prerequisites
 - Node.js 18+
 - API key từ GearVN Pages (liên hệ admin để lấy)
 
-## Sử dụng với Claude Desktop
+### Sử dụng với Claude Desktop
 
-### Bước 1: Mở file config
+**Bước 1: Mở file config**
 - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
 - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
 
-### Bước 2: Thêm MCP server config
+**Bước 2: Thêm MCP server config**
 
 ```json
 {
@@ -77,16 +33,16 @@ Liệt kê tất cả các pages của API key.
 }
 ```
 
-### Bước 3: Restart Claude Desktop
+**Bước 3: Restart Claude Desktop**
 
-## Sử dụng với Cline (VS Code)
+### Sử dụng với Cline (VS Code)
 
-### Bước 1: Mở VS Code Settings
+**Bước 1: Mở VS Code Settings**
 
 1. Command Palette (Cmd+Shift+P / Ctrl+Shift+P)
 2. "Preferences: Open User Settings (JSON)"
 
-### Bước 2: Thêm config
+**Bước 2: Thêm config**
 
 ```json
 {
@@ -105,7 +61,62 @@ Liệt kê tất cả các pages của API key.
 }
 ```
 
-### Bước 3: Reload VS Code
+**Bước 3: Reload VS Code**
+
+## Tính năng
+
+### 1. deploy-page
+Deploy hoặc update một trang HTML tĩnh.
+
+**Parameters:**
+- `title` (string): Tiêu đề của trang - **AI Agent tự động generate**
+- `content` (string): HTML document đầy đủ với TailwindCSS CDN. JavaScript libraries được phép qua CDN (Alpine.js, Chart.js, GSAP, etc.)
+- `slug` (string): URL slug - **AI Agent tự động generate hoặc dùng slug có sẵn**
+
+**Workflow:**
+
+**TẠO TRANG MỚI:**
+1. User: "Tạo website quản lý thu chi"
+2. AI generate slug đơn giản: `"quan-ly-thu-chi"`
+3. AI gọi deploy-page với slug: `"quan-ly-thu-chi"`
+4. Backend thêm timestamp: `"quan-ly-thu-chi-1730229600"`
+5. URL: `https://pages.react.uat.gearvn.xyz/pages/quan-ly-thu-chi-1730229600`
+
+**UPDATE TRANG CŨ:**
+1. User: "Sửa trang quản lý thu chi, thêm tính năng X"
+2. AI gọi `list-pages` → tìm thấy slug: `"quan-ly-thu-chi-1730229600"`
+3. AI gọi `deploy-page` với slug đầy đủ: `"quan-ly-thu-chi-1730229600"`
+4. Backend update trang cũ (không tạo mới)
+5. URL giữ nguyên: `https://pages.react.uat.gearvn.xyz/pages/quan-ly-thu-chi-1730229600`
+
+**Response:**
+```json
+{
+  "success": true,
+  "message": "Page deployed successfully",
+  "url": "https://pages.react.uat.gearvn.xyz/pages/quan-ly-thu-chi-1730229600"
+}
+```
+
+### 2. list-pages
+Liệt kê tất cả các pages của API key.
+
+**Response:**
+```json
+{
+  "success": true,
+  "count": 2,
+  "pages": [
+    {
+      "id": 1,
+      "slug": "my-page-123",
+      "title": "My Page",
+      "created_at": "2025-01-20T10:00:00Z",
+      "updated_at": "2025-01-20T10:00:00Z"
+    }
+  ]
+}
+```
 
 ## Ví dụ sử dụng trong Claude
 
@@ -113,7 +124,7 @@ Liệt kê tất cả các pages của API key.
 
 **Prompt của user (đơn giản):**
 ```
-Tạo cho tôi một trang web quản lý thu chi cá nhân với các tính năng:
+Sử dụng gearvn-pages để: Tạo cho tôi một trang web quản lý thu chi cá nhân với các tính năng:
 - Form thêm giao dịch (loại: thu/chi, số tiền, mô tả, ngày)
 - Hiển thị danh sách giao dịch dưới dạng bảng
 - Tổng thu, tổng chi, số dư
@@ -141,7 +152,7 @@ URL: https://pages.react.uat.gearvn.xyz/pages/quan-ly-thu-chi-ca-nhan
 
 **Prompt của user:**
 ```
-Tạo landing page bán khóa học lập trình với:
+Sử dụng gearvn-pages để: Tạo landing page bán khóa học lập trình với:
 - Hero section với CTA button
 - Sections: Lợi ích, Nội dung khóa học, Giảng viên, Testimonials
 - Pricing table với 3 gói
@@ -158,7 +169,7 @@ Tạo landing page bán khóa học lập trình với:
 
 **Prompt của user:**
 ```
-Tạo portfolio website cho developer với:
+Sử dụng gearvn-pages để: Tạo portfolio website cho developer với:
 - About me section
 - Skills với progress bars
 - Projects showcase với images
@@ -172,13 +183,27 @@ Tạo portfolio website cho developer với:
 - Thêm Alpine.js CDN cho dark mode
 - Deploy và trả về URL
 
-### Liệt kê các pages đã tạo
+### Ví dụ 4: Liệt kê các pages đã tạo
+
+```
+Sử dụng gearvn-pages để: Liệt kê tất cả các trang web mà tôi đã deploy
+```
+
+Claude sẽ hiển thị danh sách pages với title, slug (có timestamp) và thời gian tạo/cập nhật.
+
+### Ví dụ 5: Update trang đã tồn tại
 
+**Prompt của user:**
 ```
-Hãy liệt kê tất cả các trang web mà tôi đã deploy
+Sử dụng gearvn-pages để: Sửa trang quản lý thu chi của tôi, thêm tính năng filter theo tháng
 ```
 
-Claude sẽ hiển thị danh sách pages với title, slug và thời gian tạo/cập nhật.
+**AI Agent sẽ tự động:**
+1. ✅ Gọi `list-pages` để tìm trang quản lý thu chi
+2. ✅ Lấy slug đầy đủ có timestamp: `"quan-ly-thu-chi-ca-nhan-1730229600"`
+3. ✅ Gọi `deploy-page` với slug đầy đủ đó
+4. ✅ Backend update trang cũ (không tạo trang mới)
+5. ✅ URL giữ nguyên: `https://pages.react.uat.gearvn.xyz/pages/quan-ly-thu-chi-ca-nhan-1730229600`
 
 ## Technical Requirements
 

package/dist/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAQA,wBAAsB,OAAO,CAAC,CAAC,EAC7B,QAAQ,EAAE,MAAM,EAChB,MAAM,GAAE,MAAc,EACtB,IAAI,CAAC,EAAE,OAAO,GACb,OAAO,CAAC,CAAC,CAAC,CAsBZ"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAQA,wBAAsB,OAAO,CAAC,CAAC,EAC7B,QAAQ,EAAE,MAAM,EAChB,MAAM,GAAE,MAAc,EACtB,IAAI,CAAC,EAAE,OAAO,GACb,OAAO,CAAC,CAAC,CAAC,CAuCZ"}

package/dist/api.js

@@ -17,10 +17,23 @@ export async function callAPI(endpoint, method = "GET", body) {
         headers,
         body: body ? JSON.stringify(body) : undefined,
     });
+    // Get response text first
+    const responseText = await response.text();
     if (!response.ok) {
-        const errorText = await response.text();
-        throw new Error(`API request failed: ${response.status} ${errorText}`);
+        // Check if response is HTML (error page)
+        if (responseText.trim().startsWith("<!DOCTYPE") || responseText.trim().startsWith("<html")) {
+            throw new Error(`API request failed with status ${response.status}. Server returned HTML instead of JSON. ` +
+                `This usually means: 1) Invalid API endpoint, 2) API key authentication failed, or 3) Server error. ` +
+                `URL: ${url}`);
+        }
+        throw new Error(`API request failed: ${response.status} ${responseText}`);
+    }
+    // Try to parse as JSON
+    try {
+        return JSON.parse(responseText);
+    }
+    catch (error) {
+        throw new Error(`API returned invalid JSON. Response: ${responseText.substring(0, 200)}...`);
     }
-    return response.json();
 }
 //# sourceMappingURL=api.js.map

package/dist/api.js.map

@@ -1 +1 @@
-{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA,MAAM,YAAY,GAAG,oCAAoC,CAAC;AAC1D,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC;AAEpC,IAAI,CAAC,OAAO,EAAE,CAAC;IACb,OAAO,CAAC,KAAK,CAAC,iDAAiD,CAAC,CAAC;IACjE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,QAAgB,EAChB,SAAiB,KAAK,EACtB,IAAc;IAEd,MAAM,GAAG,GAAG,GAAG,YAAY,GAAG,QAAQ,EAAE,CAAC;IACzC,MAAM,OAAO,GAA2B;QACtC,WAAW,EAAE,OAAQ;KACtB,CAAC;IAEF,IAAI,IAAI,EAAE,CAAC;QACT,OAAO,CAAC,cAAc,CAAC,GAAG,kBAAkB,CAAC;IAC/C,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;QAChC,MAAM;QACN,OAAO;QACP,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;KAC9C,CAAC,CAAC;IAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;QACxC,MAAM,IAAI,KAAK,CAAC,uBAAuB,QAAQ,CAAC,MAAM,IAAI,SAAS,EAAE,CAAC,CAAC;IACzE,CAAC;IAED,OAAO,QAAQ,CAAC,IAAI,EAAgB,CAAC;AACvC,CAAC"}
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA,MAAM,YAAY,GAAG,oCAAoC,CAAC;AAC1D,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC;AAEpC,IAAI,CAAC,OAAO,EAAE,CAAC;IACb,OAAO,CAAC,KAAK,CAAC,iDAAiD,CAAC,CAAC;IACjE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,QAAgB,EAChB,SAAiB,KAAK,EACtB,IAAc;IAEd,MAAM,GAAG,GAAG,GAAG,YAAY,GAAG,QAAQ,EAAE,CAAC;IACzC,MAAM,OAAO,GAA2B;QACtC,WAAW,EAAE,OAAQ;KACtB,CAAC;IAEF,IAAI,IAAI,EAAE,CAAC;QACT,OAAO,CAAC,cAAc,CAAC,GAAG,kBAAkB,CAAC;IAC/C,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;QAChC,MAAM;QACN,OAAO;QACP,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;KAC9C,CAAC,CAAC;IAEH,0BAA0B;IAC1B,MAAM,YAAY,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;IAE3C,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,yCAAyC;QACzC,IAAI,YAAY,CAAC,IAAI,EAAE,CAAC,UAAU,CAAC,WAAW,CAAC,IAAI,YAAY,CAAC,IAAI,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YAC3F,MAAM,IAAI,KAAK,CACb,kCAAkC,QAAQ,CAAC,MAAM,0CAA0C;gBAC3F,qGAAqG;gBACrG,QAAQ,GAAG,EAAE,CACd,CAAC;QACJ,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,uBAAuB,QAAQ,CAAC,MAAM,IAAI,YAAY,EAAE,CAAC,CAAC;IAC5E,CAAC;IAED,uBAAuB;IACvB,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAM,CAAC;IACvC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACb,wCAAwC,YAAY,CAAC,SAAS,CAAC,CAAC,EAAE,GAAG,CAAC,KAAK,CAC5E,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/tools/deploy-page.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deploy-page.d.ts","sourceRoot":"","sources":["../../src/tools/deploy-page.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAI1D,eAAO,MAAM,gBAAgB,EAAE,IAyB9B,CAAC;AAEF,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,OAAO;;;;;GAiCnD"}
+{"version":3,"file":"deploy-page.d.ts","sourceRoot":"","sources":["../../src/tools/deploy-page.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAI1D,eAAO,MAAM,gBAAgB,EAAE,IA4B9B,CAAC;AAEF,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,OAAO;;;;;GAiCnD"}

package/dist/tools/deploy-page.js

@@ -1,7 +1,7 @@
 import { callAPI } from "../api.js";
 export const DEPLOY_PAGE_TOOL = {
     name: "deploy-page",
-    description: "Deploy or update a static HTML page. If the slug already exists, the page will be updated with the new content and title. IMPORTANT: You (AI Agent) must automatically generate appropriate 'title' and 'slug' based on the user's request - user does NOT provide these. The content must be a complete, valid HTML document with TailwindCSS for styling. JavaScript libraries are allowed but MUST be loaded via CDN (e.g., Alpine.js, Chart.js, GSAP, etc.). No build tools or npm packages. No React, Vue, or Angular frameworks allowed.",
+    description: "Deploy or update a static HTML page. If the slug already exists, the page will be updated with the new content and title. IMPORTANT: You (AI Agent) must automatically generate appropriate 'title' and 'slug' based on the user's request - user does NOT provide these. The content must be a complete, valid HTML document with TailwindCSS for styling. JavaScript libraries are allowed but MUST be loaded via CDN (e.g., Alpine.js, Chart.js, GSAP, etc.). No build tools or npm packages. No React, Vue, or Angular frameworks allowed. CRITICAL: When passing HTML content as JSON string, ensure all special characters are properly escaped (double quotes \", backslashes \\, newlines \\n, etc.) to prevent JSON syntax errors.",
     inputSchema: {
         type: "object",
         properties: {
@@ -11,11 +11,14 @@ export const DEPLOY_PAGE_TOOL = {
             },
             content: {
                 type: "string",
-                description: "The complete HTML content of the page. Must include <!DOCTYPE html>, <html>, <head> with TailwindCSS CDN link (https://cdn.tailwindcss.com), and <body> tags. Use TailwindCSS utility classes for all styling. JavaScript libraries are allowed but must be imported via CDN links in <script> tags (e.g., Alpine.js from CDN, Chart.js from CDN). Vanilla JavaScript is also acceptable. NO build tools, npm packages, or SPA frameworks (React/Vue/Angular).",
+                description: "The complete HTML content of the page. Must include <!DOCTYPE html>, <html>, <head> with TailwindCSS CDN link (https://cdn.tailwindcss.com), and <body> tags. Use TailwindCSS utility classes for all styling. JavaScript libraries are allowed but must be imported via CDN links in <script> tags (e.g., Alpine.js from CDN, Chart.js from CDN). Vanilla JavaScript is also acceptable. NO build tools, npm packages, or SPA frameworks (React/Vue/Angular). IMPORTANT: Properly escape all special characters in HTML for JSON (\" for double quotes, \\\\ for backslashes, \\n for newlines, etc.). Example: <div class=\"container\"> should be passed as <div class=\\\"container\\\">",
             },
             slug: {
                 type: "string",
-                description: "The URL slug for the page. AI Agent should generate this automatically in kebab-case format based on the title or user's request (e.g., 'quan-ly-thu-chi-ca-nhan', 'landing-page-khoa-hoc'). This will be used in the URL as /pages/{slug}",
+                description: "The URL slug for the page. IMPORTANT BEHAVIOR: " +
+                    "FOR NEW PAGES: Generate a simple kebab-case slug (e.g., 'quan-ly-thu-chi', 'landing-page'). The backend will automatically append a timestamp (e.g., 'quan-ly-thu-chi-1730229600') to prevent duplicates. " +
+                    "FOR UPDATING EXISTING PAGES: Use the EXACT full slug including timestamp (e.g., 'quan-ly-thu-chi-1730229600') from the list-pages response. " +
+                    "If the exact slug exists for this API key, the page will be updated. Otherwise, a new page with a new timestamp will be created.",
             },
         },
         required: ["title", "content", "slug"],

package/dist/tools/deploy-page.js.map

@@ -1 +1 @@
-{"version":3,"file":"deploy-page.js","sourceRoot":"","sources":["../../src/tools/deploy-page.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC,MAAM,CAAC,MAAM,gBAAgB,GAAS;IACpC,IAAI,EAAE,aAAa;IACnB,WAAW,EACT,ghBAAghB;IAClhB,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,KAAK,EAAE;gBACL,IAAI,EAAE,QAAQ;gBACd,WAAW,EACT,6FAA6F;aAChG;YACD,OAAO,EAAE;gBACP,IAAI,EAAE,QAAQ;gBACd,WAAW,EACT,gcAAgc;aACnc;YACD,IAAI,EAAE;gBACJ,IAAI,EAAE,QAAQ;gBACd,WAAW,EACT,4OAA4O;aAC/O;SACF;QACD,QAAQ,EAAE,CAAC,OAAO,EAAE,SAAS,EAAE,MAAM,CAAC;KACvC;CACF,CAAC;AAEF,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,IAAa;IAClD,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,IAAsB,CAAC;IAExD,kBAAkB;IAClB,IAAI,CAAC,KAAK,IAAI,CAAC,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CACb,oEAAoE,CACrE,CAAC;IACJ,CAAC;IAED,sBAAsB;IACtB,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAqB,YAAY,EAAE,MAAM,EAAE;QACvE,KAAK;QACL,OAAO;QACP,IAAI;KACL,CAAC,CAAC;IAEH,OAAO;QACL,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,MAAe;gBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAClB;oBACE,OAAO,EAAE,IAAI;oBACb,OAAO,EAAE,4BAA4B;oBACrC,GAAG,EAAE,QAAQ,CAAC,GAAG;iBAClB,EACD,IAAI,EACJ,CAAC,CACF;aACF;SACF;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"deploy-page.js","sourceRoot":"","sources":["../../src/tools/deploy-page.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC,MAAM,CAAC,MAAM,gBAAgB,GAAS;IACpC,IAAI,EAAE,aAAa;IACnB,WAAW,EACT,6sBAA6sB;IAC/sB,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,KAAK,EAAE;gBACL,IAAI,EAAE,QAAQ;gBACd,WAAW,EACT,6FAA6F;aAChG;YACD,OAAO,EAAE;gBACP,IAAI,EAAE,QAAQ;gBACd,WAAW,EACT,8pBAA8pB;aACjqB;YACD,IAAI,EAAE;gBACJ,IAAI,EAAE,QAAQ;gBACd,WAAW,EACT,iDAAiD;oBACjD,4MAA4M;oBAC5M,8IAA8I;oBAC9I,kIAAkI;aACrI;SACF;QACD,QAAQ,EAAE,CAAC,OAAO,EAAE,SAAS,EAAE,MAAM,CAAC;KACvC;CACF,CAAC;AAEF,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,IAAa;IAClD,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,IAAsB,CAAC;IAExD,kBAAkB;IAClB,IAAI,CAAC,KAAK,IAAI,CAAC,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CACb,oEAAoE,CACrE,CAAC;IACJ,CAAC;IAED,sBAAsB;IACtB,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAqB,YAAY,EAAE,MAAM,EAAE;QACvE,KAAK;QACL,OAAO;QACP,IAAI;KACL,CAAC,CAAC;IAEH,OAAO;QACL,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,MAAe;gBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAClB;oBACE,OAAO,EAAE,IAAI;oBACb,OAAO,EAAE,4BAA4B;oBACrC,GAAG,EAAE,QAAQ,CAAC,GAAG;iBAClB,EACD,IAAI,EACJ,CAAC,CACF;aACF;SACF;KACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,18 +1,12 @@
 {
   "name": "gearvn-pages-mcp-server",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "MCP Server for GearVN Pages deployment and management",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
     "gearvn-pages-mcp": "dist/index.js"
   },
-  "scripts": {
-    "build": "tsc",
-    "watch": "tsc --watch",
-    "start": "node dist/index.js",
-    "prepublishOnly": "npm run build"
-  },
   "keywords": [
     "mcp",
     "model-context-protocol",
@@ -26,5 +20,10 @@
   "devDependencies": {
     "@types/node": "^22.10.2",
     "typescript": "^5.7.2"
+  },
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "start": "node dist/index.js"
   }
-}
+}

package/src/api.ts

@@ -26,10 +26,27 @@ export async function callAPI<T>(
     body: body ? JSON.stringify(body) : undefined,
   });
 
+  // Get response text first
+  const responseText = await response.text();
+
   if (!response.ok) {
-    const errorText = await response.text();
-    throw new Error(`API request failed: ${response.status} ${errorText}`);
+    // Check if response is HTML (error page)
+    if (responseText.trim().startsWith("<!DOCTYPE") || responseText.trim().startsWith("<html")) {
+      throw new Error(
+        `API request failed with status ${response.status}. Server returned HTML instead of JSON. ` +
+        `This usually means: 1) Invalid API endpoint, 2) API key authentication failed, or 3) Server error. ` +
+        `URL: ${url}`
+      );
+    }
+    throw new Error(`API request failed: ${response.status} ${responseText}`);
   }
 
-  return response.json() as Promise<T>;
+  // Try to parse as JSON
+  try {
+    return JSON.parse(responseText) as T;
+  } catch (error) {
+    throw new Error(
+      `API returned invalid JSON. Response: ${responseText.substring(0, 200)}...`
+    );
+  }
 }

package/src/tools/deploy-page.ts

@@ -5,7 +5,7 @@ import { DeployPageArgs, DeployPageResponse } from "../types.js";
 export const DEPLOY_PAGE_TOOL: Tool = {
   name: "deploy-page",
   description:
-    "Deploy or update a static HTML page. If the slug already exists, the page will be updated with the new content and title. IMPORTANT: You (AI Agent) must automatically generate appropriate 'title' and 'slug' based on the user's request - user does NOT provide these. The content must be a complete, valid HTML document with TailwindCSS for styling. JavaScript libraries are allowed but MUST be loaded via CDN (e.g., Alpine.js, Chart.js, GSAP, etc.). No build tools or npm packages. No React, Vue, or Angular frameworks allowed.",
+    "Deploy or update a static HTML page. If the slug already exists, the page will be updated with the new content and title. IMPORTANT: You (AI Agent) must automatically generate appropriate 'title' and 'slug' based on the user's request - user does NOT provide these. The content must be a complete, valid HTML document with TailwindCSS for styling. JavaScript libraries are allowed but MUST be loaded via CDN (e.g., Alpine.js, Chart.js, GSAP, etc.). No build tools or npm packages. No React, Vue, or Angular frameworks allowed. CRITICAL: When passing HTML content as JSON string, ensure all special characters are properly escaped (double quotes \", backslashes \\, newlines \\n, etc.) to prevent JSON syntax errors.",
   inputSchema: {
     type: "object",
     properties: {
@@ -17,12 +17,15 @@ export const DEPLOY_PAGE_TOOL: Tool = {
       content: {
         type: "string",
         description:
-          "The complete HTML content of the page. Must include <!DOCTYPE html>, <html>, <head> with TailwindCSS CDN link (https://cdn.tailwindcss.com), and <body> tags. Use TailwindCSS utility classes for all styling. JavaScript libraries are allowed but must be imported via CDN links in <script> tags (e.g., Alpine.js from CDN, Chart.js from CDN). Vanilla JavaScript is also acceptable. NO build tools, npm packages, or SPA frameworks (React/Vue/Angular).",
+          "The complete HTML content of the page. Must include <!DOCTYPE html>, <html>, <head> with TailwindCSS CDN link (https://cdn.tailwindcss.com), and <body> tags. Use TailwindCSS utility classes for all styling. JavaScript libraries are allowed but must be imported via CDN links in <script> tags (e.g., Alpine.js from CDN, Chart.js from CDN). Vanilla JavaScript is also acceptable. NO build tools, npm packages, or SPA frameworks (React/Vue/Angular). IMPORTANT: Properly escape all special characters in HTML for JSON (\" for double quotes, \\\\ for backslashes, \\n for newlines, etc.). Example: <div class=\"container\"> should be passed as <div class=\\\"container\\\">",
       },
       slug: {
         type: "string",
         description:
-          "The URL slug for the page. AI Agent should generate this automatically in kebab-case format based on the title or user's request (e.g., 'quan-ly-thu-chi-ca-nhan', 'landing-page-khoa-hoc'). This will be used in the URL as /pages/{slug}",
+          "The URL slug for the page. IMPORTANT BEHAVIOR: " +
+          "FOR NEW PAGES: Generate a simple kebab-case slug (e.g., 'quan-ly-thu-chi', 'landing-page'). The backend will automatically append a timestamp (e.g., 'quan-ly-thu-chi-1730229600') to prevent duplicates. " +
+          "FOR UPDATING EXISTING PAGES: Use the EXACT full slug including timestamp (e.g., 'quan-ly-thu-chi-1730229600') from the list-pages response. " +
+          "If the exact slug exists for this API key, the page will be updated. Otherwise, a new page with a new timestamp will be created.",
       },
     },
     required: ["title", "content", "slug"],