@ncds/ui-admin-mcp 1.0.0-alpha.6 → 1.0.0-alpha.8

package/bin/definitions/instructions.md

@@ -5,12 +5,12 @@ You are an agent that builds UI using NCUA (NCDS UI Admin) design system compone
 ## Absolute Rules (VIOLATION = CRITICAL FAILURE)
 
 1. Call ping ONCE at the start of every session before using any other tool. This loads version info and usage rules.
-2. NEVER define, invent, or guess CSS variables, design tokens, or color values. Use ONLY tokens returned by get_design_tokens. If you write a custom CSS variable (e.g. --custom-anything) or hardcode a hex/rgb value (e.g. #5B5BD6, rgb(91,91,214)), you have FAILED.
-3. NEVER write SVG icons or icon markup manually. ALL icons MUST come from search_icon or list_icons. If you write a single <svg> tag by hand, you have FAILED.
+2. NEVER define or guess NCUA CSS variables (--ncua-*). NCUA component styles are controlled by CDN CSS only.
+3. NEVER write SVG icons or icon markup manually. ALL icons MUST come from search_icon or list_icons. If you write a single svg tag by hand, you have FAILED.
 4. NEVER use emoji in generated HTML, CSS, or any output. No exceptions.
 5. You MUST generate NCUA component HTML using render_to_html or render_to_html_batch only. Never write component HTML/CSS manually.
 6. If an NCUA component exists for the use case, you MUST use it. Do NOT recreate it manually.
-7. For custom areas not covered by NCUA, use ONLY tokens from get_design_tokens for all colors, spacing, typography, and shadows. Call get_design_tokens BEFORE writing any custom CSS.
+7. For custom areas, call get_design_tokens FIRST and prefer NCUA tokens for colors, spacing, typography, and shadows to maintain visual consistency. If no suitable token exists, you may use standard CSS values (hex, rgb, px).
 
 ## Required Workflow (follow this order strictly)
 

package/bin/server.js

@@ -103,21 +103,37 @@ const main = async () => {
     const listIconsResponse = (0, listIcons_js_1.buildListIconsResponse)(iconSummary);
     // ── MCP 서버 생성 + tool 등록 ──
     const server = new mcp_js_1.McpServer({ name: 'ncds-ui-admin', version: version_js_1.VERSION }, { instructions });
-    server.registerTool('ping', { description: descriptions['ping'] }, () => (0, ping_js_1.ping)({ componentMap, cdnMeta, iconMeta, version: version_js_1.VERSION, rules, capabilities }));
-    server.registerTool('list_icons', { description: descriptions['list_icons'] }, () => (0, listIcons_js_1.listIcons)(listIconsResponse));
+    // ping 호출 추적 — 미호출 시 다른 tool 응답에 핵심 rules 주입
+    let pinged = false;
+    const PING_REMINDER = '\n\n⚠ IMPORTANT: You have NOT called ping yet. Call ping ONCE before proceeding. ' +
+        'Rules: (1) NEVER hardcode hex/rgb colors — use get_design_tokens. ' +
+        '(2) NEVER write SVG icons — use search_icon. ' +
+        '(3) Use render_to_html or render_to_html_batch for all NCUA components. ' +
+        '(4) For custom CSS, prefer NCUA tokens. Call get_design_tokens first.';
+    const withPingReminder = (response) => {
+        if (pinged)
+            return response;
+        const text = response.content[0].text + PING_REMINDER;
+        return { ...response, content: [{ type: 'text', text }] };
+    };
+    server.registerTool('ping', { description: descriptions['ping'] }, () => {
+        pinged = true;
+        return (0, ping_js_1.ping)({ componentMap, cdnMeta, iconMeta, version: version_js_1.VERSION, rules, capabilities });
+    });
+    server.registerTool('list_icons', { description: descriptions['list_icons'] }, () => withPingReminder((0, listIcons_js_1.listIcons)(listIconsResponse)));
     server.registerTool('search_icon', {
         description: descriptions['search_icon'],
         inputSchema: { query: zod_1.z.string().describe('Search keyword (e.g. "search", "alert", "arrow")') },
-    }, ({ query }) => (0, searchIcon_js_1.searchIcon)(iconData, query));
-    server.registerTool('list_components', { description: descriptions['list_components'] }, () => (0, listComponents_js_1.listComponents)(listComponentsResponse));
+    }, ({ query }) => withPingReminder((0, searchIcon_js_1.searchIcon)(iconData, query)));
+    server.registerTool('list_components', { description: descriptions['list_components'] }, () => withPingReminder((0, listComponents_js_1.listComponents)(listComponentsResponse)));
     server.registerTool('search_component', {
         description: descriptions['search_component'],
         inputSchema: { query: zod_1.z.string().describe('Search keyword (Korean/English, case-insensitive)') },
-    }, ({ query }) => (0, searchComponent_js_1.searchComponent)(componentMap, query));
+    }, ({ query }) => withPingReminder((0, searchComponent_js_1.searchComponent)(componentMap, query)));
     server.registerTool('get_component_props', {
         description: descriptions['get_component_props'],
         inputSchema: { name: zod_1.z.string().min(1).describe('Component name (e.g. "button", "password-input")') },
-    }, ({ name }) => (0, getComponentProps_js_1.getComponentProps)(componentMap, name));
+    }, ({ name }) => withPingReminder((0, getComponentProps_js_1.getComponentProps)(componentMap, name)));
     server.registerTool('validate_html', {
         description: descriptions['validate_html'],
         inputSchema: {
@@ -126,7 +142,7 @@ const main = async () => {
                 .min(1)
                 .describe('HTML markup to validate (e.g. \'<button class="ncua-btn ncua-btn--primary"></button>\')'),
         },
-    }, ({ html }) => (0, validateHtml_js_1.validateHtml)({ componentMap, rootClassMap, html, cdnMeta, tokenData, complianceRules, tokenValueMap }));
+    }, ({ html }) => withPingReminder((0, validateHtml_js_1.validateHtml)({ componentMap, rootClassMap, html, cdnMeta, tokenData, complianceRules, tokenValueMap })));
     server.registerTool('render_to_html', {
         description: descriptions['render_to_html'],
         inputSchema: {
@@ -136,9 +152,7 @@ const main = async () => {
                 .optional()
                 .describe('Component props (e.g. { label: "OK", hierarchy: "primary" })'),
         },
-    }, 
-    // MCP SDK의 zod 추론 타입이 Record<string, unknown> | undefined와 미스매치하여 as 필요
-    ({ name, props }) => (0, renderToHtml_js_1.renderToHtml)({
+    }, ({ name, props }) => withPingReminder((0, renderToHtml_js_1.renderToHtml)({
         componentMap,
         bundle,
         cdnMeta,
@@ -147,7 +161,7 @@ const main = async () => {
         jsApiMap,
         name,
         props: props,
-    }));
+    })));
     server.registerTool('render_to_html_batch', {
         description: descriptions['render_to_html_batch'],
         inputSchema: {
@@ -175,7 +189,7 @@ const main = async () => {
             const text = r.content[0].text;
             return r.isError ? { error: JSON.parse(text) } : JSON.parse(text);
         });
-        return (0, response_js_1.successResponse)(parsed);
+        return withPingReminder((0, response_js_1.successResponse)(parsed));
     });
     server.registerTool('get_design_tokens', {
         description: descriptions['get_design_tokens'],
@@ -185,7 +199,7 @@ const main = async () => {
                 .optional()
                 .describe('Token category filter (e.g. "color", "typography", "shadow", "spacing"). Omit to get all tokens.'),
         },
-    }, ({ category }) => (0, getDesignTokens_js_1.getDesignTokens)({ tokenData, category }));
+    }, ({ category }) => withPingReminder((0, getDesignTokens_js_1.getDesignTokens)({ tokenData, category })));
     const transport = new stdio_js_1.StdioServerTransport();
     await server.connect(transport);
     logger_js_1.logger.info(`NCUA MCP 서버 시작됨 (ncds-ui-admin v${version_js_1.VERSION})`);

package/data/_tokens.json

@@ -557,42 +557,42 @@
       ]
     },
     {
-      "name": "shadow-elevation",
+      "name": "shadow",
       "category": "shadow",
       "description": "기본 Elevation. 내부 요소는 외부 요소보다 낮은 단계를 사용.",
       "tokens": [
         {
-          "name": "--shadow-elevation-xs",
+          "name": "--shadow-xs",
           "value": "0 1px 2px 0 rgba(16, 24, 40, 0.05)",
           "description": "내부 카드, 버튼, Input"
         },
         {
-          "name": "--shadow-elevation-sm",
+          "name": "--shadow-sm",
           "value": "0 1px 3px 0 rgba(16, 24, 40, 0.10), 0 1px 2px 0 rgba(16, 24, 40, 0.06)",
           "description": "Block Container, PageTitle"
         },
         {
-          "name": "--shadow-elevation-md",
+          "name": "--shadow-md",
           "value": "0 4px 8px -2px rgba(16, 24, 40, 0.10), 0 2px 4px -2px rgba(16, 24, 40, 0.06)",
           "description": "드래그 중, 플로팅"
         },
         {
-          "name": "--shadow-elevation-lg",
+          "name": "--shadow-lg",
           "value": "0 12px 16px -4px rgba(16, 24, 40, 0.08), 0 4px 6px -2px rgba(16, 24, 40, 0.03)",
           "description": "Dropdown 오버레이"
         },
         {
-          "name": "--shadow-elevation-xl",
+          "name": "--shadow-xl",
           "value": "0 20px 24px -4px rgba(16, 24, 40, 0.08), 0 8px 8px -4px rgba(16, 24, 40, 0.03)",
           "description": ""
         },
         {
-          "name": "--shadow-elevation-2xl",
+          "name": "--shadow-2xl",
           "value": "0 24px 48px -12px rgba(16, 24, 40, 0.18)",
           "description": ""
         },
         {
-          "name": "--shadow-elevation-3xl",
+          "name": "--shadow-3xl",
           "value": "0 32px 64px -12px rgba(16, 24, 40, 0.14)",
           "description": ""
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ncds/ui-admin-mcp",
-  "version": "1.0.0-alpha.6",
+  "version": "1.0.0-alpha.8",
   "description": "NCDS UI Admin MCP 서버 — AI 에이전트가 NCUA 컴포넌트를 조회하고 HTML을 검증할 수 있는 MCP 서버",
   "bin": {
     "ncua-mcp": "./bin/server.mjs"