@ncds/ui-admin-mcp 1.0.0-alpha.5 → 1.0.0-alpha.7

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/definitions/js-api.json

@@ -0,0 +1,165 @@
+{
+  "Modal": {
+    "className": "Modal",
+    "constructor": "new window.ncua.Modal(options?)",
+    "constructorParams": {
+      "size": "'sm' | 'md' | 'lg' (default: 'md')",
+      "closeOnBackdropClick": "boolean (default: false)",
+      "closeOnEsc": "boolean (default: true)",
+      "onClose": "() => void"
+    },
+    "methods": ["open()", "close()", "destroy()", "setContent(html: string | HTMLElement)", "isModalOpen()"],
+    "example": "const modal = new window.ncua.Modal({ size: 'sm', onClose: () => {} });\nmodal.setContent('<p>Content</p>');\nmodal.open();"
+  },
+  "SelectBox": {
+    "className": "SelectBox",
+    "constructor": "new window.ncua.SelectBox(element, config?)",
+    "constructorParams": {
+      "element": "HTMLElement — target container",
+      "config.options": "Array<{ id: string, text: string, disabled?: boolean }>",
+      "config.placeholder": "string (default: '선택하세요')",
+      "config.value": "string | number",
+      "config.onChange": "(value) => void",
+      "config.size": "'xs' | 'sm' | 'md'",
+      "config.multiple": "boolean",
+      "config.disabled": "boolean"
+    },
+    "methods": ["getValues()", "setValues(options[])", "getSelectedCount()"],
+    "example": "const select = new window.ncua.SelectBox(document.getElementById('my-select'), {\n  options: [{ id: '1', text: 'Option 1' }],\n  onChange: (value) => console.log(value)\n});"
+  },
+  "ComboBox": {
+    "className": "ComboBox",
+    "constructor": "new window.ncua.ComboBox(element, config?)",
+    "constructorParams": {
+      "element": "HTMLElement — target container",
+      "config.options": "Array<{ id: string, label: string, disabled?: boolean }>",
+      "config.placeholder": "string (default: '검색하고 선택하세요')",
+      "config.value": "string | number",
+      "config.onChange": "(value) => void",
+      "config.onSearch": "(searchValue: string) => void",
+      "config.size": "'xs' | 'sm'",
+      "config.multiple": "boolean"
+    },
+    "methods": ["getValues()", "setValues(options[])", "clearInput()", "getSelectedCount()"],
+    "example": "const combo = new window.ncua.ComboBox(document.getElementById('my-combo'), {\n  options: [{ id: '1', label: 'React' }],\n  onSearch: (q) => console.log(q)\n});"
+  },
+  "DatePicker": {
+    "className": "DatePicker",
+    "constructor": "new window.ncua.DatePicker(wrapper, options)",
+    "constructorParams": {
+      "wrapper": "HTMLElement — container element",
+      "options.size": "'xs' | 'sm'",
+      "options.datePickerOptions": "Array<{ element: string, placeholder?: string, options: FlatpickrOptions }>",
+      "options.buttons": "Array<{ text: string, period: number, unit: 'days'|'months', isCurrent: boolean }>",
+      "options.onValidationError": "(error) => void"
+    },
+    "methods": ["getDates()", "setDate(dates: string[])", "setMultipleDates(dates: string[])"],
+    "example": "const dp = new window.ncua.DatePicker(document.getElementById('my-dp'), {\n  size: 'xs',\n  datePickerOptions: [{ element: 'date-input', placeholder: 'Select date', options: { dateFormat: 'Y-m-d' } }]\n});"
+  },
+  "Slider": {
+    "className": "Slider",
+    "constructor": "new window.ncua.Slider(element, options)",
+    "constructorParams": {
+      "element": "HTMLElement — container",
+      "options.min": "number (default: 0)",
+      "options.max": "number (default: 100)",
+      "options.step": "number (default: 1)",
+      "options.value": "number | [number, number]",
+      "options.onChange": "(value) => void",
+      "options.disabled": "boolean"
+    },
+    "methods": ["getValue()", "setValue(value)", "enable()", "disable()", "destroy()"],
+    "example": "const slider = new window.ncua.Slider(document.getElementById('my-slider'), {\n  min: 0, max: 100, value: 50,\n  onChange: (v) => console.log(v)\n});"
+  },
+  "Tab": {
+    "className": "Tab",
+    "constructor": "new window.ncua.Tab(element)",
+    "constructorParams": {
+      "element": "HTMLElement — container with swiper structure"
+    },
+    "methods": ["destroy()"],
+    "example": "const tab = new window.ncua.Tab(document.getElementById('my-tab'));"
+  },
+  "Tooltip": {
+    "className": "Tooltip",
+    "constructor": "window.ncua.Tooltip.createShort(title, content?, options?)",
+    "constructorParams": {
+      "title": "string",
+      "content": "string (HTML supported)",
+      "options.position": "'top' | 'bottom' | 'left' | 'right' (default: 'top')"
+    },
+    "methods": ["getElement()", "showTooltip()", "hideTooltip()", "destroy()"],
+    "example": "const tip = window.ncua.Tooltip.createShort('Help', 'Tooltip content');\ndocument.getElementById('container').appendChild(tip.getElement());"
+  },
+  "Notification": {
+    "className": "Notification",
+    "constructor": "window.ncua.Notification.success(title, supportingText?, options?)",
+    "constructorParams": {
+      "title": "string",
+      "supportingText": "string",
+      "options.autoClose": "number (ms, 0 = no auto-close)"
+    },
+    "methods": ["show(parent?)", "remove()", "destroy()"],
+    "staticMethods": ["success()", "error()", "warning()", "info()", "neutral()"],
+    "example": "window.ncua.Notification.success('Saved', 'Changes saved successfully');"
+  },
+  "ProgressBar": {
+    "className": "ProgressBar",
+    "constructor": "new window.ncua.ProgressBar(options?)",
+    "constructorParams": {
+      "options.value": "number (0-100)",
+      "options.label": "'right' | 'bottom' | 'top-float' | 'bottom-float'"
+    },
+    "methods": ["getElement()", "updateOptions(newOptions)", "toHTML()"],
+    "example": "const bar = new window.ncua.ProgressBar({ value: 65, label: 'right' });\ndocument.getElementById('container').appendChild(bar.getElement());"
+  },
+  "Tag": {
+    "className": "Tag",
+    "constructor": "new window.ncua.Tag(options)",
+    "constructorParams": {
+      "options.text": "string",
+      "options.size": "'sm' | 'md' (default: 'sm')",
+      "options.close": "boolean — show close button",
+      "options.onButtonClick": "() => void — close handler"
+    },
+    "methods": ["getElement()", "setText(text)", "setCount(count)", "destroy()"],
+    "example": "const tag = new window.ncua.Tag({ text: 'Label', close: true, onButtonClick: () => tag.destroy() });\ndocument.getElementById('container').appendChild(tag.getElement());"
+  },
+  "FileInput": {
+    "className": "FileInput",
+    "constructor": "new window.ncua.FileInput(options)",
+    "constructorParams": {
+      "options.container": "HTMLElement | string — auto-append target",
+      "options.onChange": "(files: File[]) => void",
+      "options.onFail": "(invalidFiles: File[]) => void",
+      "options.disabled": "boolean"
+    },
+    "methods": ["getElement()", "setDisabled(boolean)", "destroy()"],
+    "example": "const fi = new window.ncua.FileInput({\n  container: 'file-container',\n  onChange: (files) => console.log(files)\n});"
+  },
+  "ImageFileInput": {
+    "className": "ImageFileInput",
+    "constructor": "new window.ncua.ImageFileInput(options)",
+    "constructorParams": {
+      "options.container": "HTMLElement | string — auto-append target",
+      "options.onChange": "(files: File[]) => void",
+      "options.maxFileCount": "number",
+      "options.acceptedFileTypes": "string[]",
+      "options.maxFileSize": "number"
+    },
+    "methods": ["getElement()", "getFiles()", "clearFiles()", "setDisabled(boolean)", "destroy()"],
+    "example": "const img = new window.ncua.ImageFileInput({\n  container: 'image-container',\n  maxFileCount: 5,\n  onChange: (files) => console.log(files)\n});"
+  },
+  "FeaturedIcon": {
+    "className": "FeaturedIcon",
+    "constructor": "new window.ncua.FeaturedIcon(options)",
+    "constructorParams": {
+      "options.svgString": "string — SVG content",
+      "options.theme": "'light-circle' | 'dark-circle' | 'outline-circle' | 'square-outline'",
+      "options.color": "'neutral' | 'error' | 'warning' | 'success'",
+      "options.size": "'sm' | 'md' | 'lg' | 'xl'"
+    },
+    "methods": ["getElement()", "updateColor(color)", "updateSize(size)", "destroy()"],
+    "example": "const icon = new window.ncua.FeaturedIcon({ svgString: '<svg>...</svg>', color: 'success', size: 'md' });\ndocument.getElementById('container').appendChild(icon.getElement());"
+  }
+}

package/bin/server.js

@@ -81,6 +81,7 @@ const main = async () => {
     const rules = loadRules(definitionsDir);
     const instructions = (0, dataLoader_js_1.loadInstructions)(definitionsDir);
     const complianceRules = (0, dataLoader_js_1.loadComplianceRules)(definitionsDir);
+    const jsApiMap = (0, dataLoader_js_1.loadJsApi)(definitionsDir);
     // ── 데이터 로딩 ──
     const componentMap = (0, dataLoader_js_1.loadComponentsFromDir)(dataLoader_js_1.DEFAULT_DATA_DIR);
     const { cdn: cdnMeta, icon: iconMeta } = (0, dataLoader_js_1.loadMeta)(dataLoader_js_1.DEFAULT_DATA_DIR);
@@ -143,6 +144,7 @@ const main = async () => {
         cdnMeta,
         iconMeta,
         reactRuntime,
+        jsApiMap,
         name,
         props: props,
     }));
@@ -165,6 +167,7 @@ const main = async () => {
             cdnMeta,
             iconMeta,
             reactRuntime,
+            jsApiMap,
             name,
             props: props,
         }));

package/bin/tools/renderToHtml.d.ts

@@ -5,7 +5,7 @@
  * 이 파일에는 fs, path, require, let이 없다.
  */
 import type { ComponentData, ReactRuntime } from '../types.js';
-import type { CdnMeta, IconMeta } from '../utils/dataLoader.js';
+import type { CdnMeta, IconMeta, JsApiInfo } from '../utils/dataLoader.js';
 import { type McpToolResponse } from '../utils/response.js';
 /** render_to_html tool 파라미터 */
 export interface RenderToHtmlParams {
@@ -14,6 +14,7 @@ export interface RenderToHtmlParams {
     cdnMeta: CdnMeta | null;
     iconMeta: IconMeta | null;
     reactRuntime: ReactRuntime;
+    jsApiMap: Map<string, JsApiInfo>;
     name: string;
     props?: Record<string, unknown>;
 }

package/bin/tools/renderToHtml.js

@@ -132,7 +132,7 @@ const buildDataVersion = (cdnMeta, iconMeta) => {
 // ── 진입점 ────────────────────────────────────────────────────────
 /** render_to_html tool — props로 React 컴포넌트를 렌더링하여 HTML + React 매핑 반환 */
 const renderToHtml = (params) => {
-    const { componentMap, bundle, cdnMeta, iconMeta, reactRuntime, name, props } = params;
+    const { componentMap, bundle, cdnMeta, iconMeta, reactRuntime, jsApiMap, name, props } = params;
     const normalized = (0, response_js_1.normalizeName)(name);
     const componentData = componentMap.get(normalized);
     if (!componentData)
@@ -155,6 +155,22 @@ const renderToHtml = (params) => {
         const defaultsUsed = componentData.props ? calcDefaultsUsed(componentData.props, userProps) : {};
         const react = buildReactOutput(componentData, userProps, iconMeta);
         const dataVersion = buildDataVersion(cdnMeta, iconMeta);
+        const jsApi = jsApiMap.get(exportName);
+        const js = componentData.jsRequired
+            ? {
+                required: true,
+                description: '이 컴포넌트는 인터랙션을 위해 CDN JS가 필요합니다',
+                ...(jsApi && {
+                    api: {
+                        className: jsApi.className,
+                        constructor: jsApi.constructor,
+                        constructorParams: jsApi.constructorParams,
+                        methods: jsApi.methods,
+                        example: jsApi.example,
+                    },
+                }),
+            }
+            : { required: false };
         return (0, response_js_1.successResponse)({
             html,
             component: normalized,
@@ -162,9 +178,7 @@ const renderToHtml = (params) => {
             importPath: componentData.importPath,
             appliedProps: userProps,
             ...(Object.keys(defaultsUsed).length > 0 && { defaultsUsed }),
-            js: componentData.jsRequired
-                ? { required: true, description: '이 컴포넌트는 인터랙션을 위해 CDN JS가 필요합니다' }
-                : { required: false },
+            js,
             cdn: cdnMeta ?? undefined,
             dataVersion,
             react,

package/bin/utils/dataLoader.d.ts

@@ -27,6 +27,17 @@ export declare const loadTokenData: (dataDir: string) => TokenData;
 export declare const loadComplianceRules: (definitionsDir: string) => ComplianceRulesData | null;
 /** definitions/instructions.md를 로드하여 문자열 반환 */
 export declare const loadInstructions: (definitionsDir: string) => string;
+/** JS API 정보 타입 */
+export interface JsApiInfo {
+    className: string;
+    constructor: string;
+    constructorParams: Record<string, string>;
+    methods: string[];
+    staticMethods?: string[];
+    example: string;
+}
+/** definitions/js-api.json을 로드하여 exportName→JsApiInfo Map 반환 */
+export declare const loadJsApi: (definitionsDir: string) => Map<string, JsApiInfo>;
 /** componentMap에서 이름으로 단일 컴포넌트 조회 */
 export declare const getComponent: (map: Map<string, ComponentData>, name: string) => ComponentData | undefined;
 /** componentMap의 모든 컴포넌트를 배열로 반환 */

package/bin/utils/dataLoader.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getAllComponents = exports.getComponent = exports.loadInstructions = exports.loadComplianceRules = exports.loadTokenData = exports.loadMeta = exports.loadIconData = exports.loadComponentsFromDir = exports.DEFAULT_DATA_DIR = void 0;
+exports.getAllComponents = exports.getComponent = exports.loadJsApi = exports.loadInstructions = exports.loadComplianceRules = exports.loadTokenData = exports.loadMeta = exports.loadIconData = exports.loadComponentsFromDir = exports.DEFAULT_DATA_DIR = void 0;
 /**
  * dataLoader — mcp/data/*.json + definitions/ 파일을 읽어 반환
  *
@@ -165,6 +165,24 @@ const loadInstructions = (definitionsDir) => {
     return fs_1.default.readFileSync(instructionsPath, 'utf-8').trim();
 };
 exports.loadInstructions = loadInstructions;
+/** definitions/js-api.json을 로드하여 exportName→JsApiInfo Map 반환 */
+const loadJsApi = (definitionsDir) => {
+    const filePath = path_1.default.resolve(definitionsDir, 'js-api.json');
+    if (!fs_1.default.existsSync(filePath)) {
+        logger_js_1.logger.info('js-api.json이 없습니다 — JS API 힌트 비활성화');
+        return new Map();
+    }
+    try {
+        const raw = fs_1.default.readFileSync(filePath, 'utf-8');
+        const data = JSON.parse(raw);
+        return new Map(Object.entries(data));
+    }
+    catch (err) {
+        logger_js_1.logger.error(`js-api.json 파싱 실패: ${(0, response_js_1.toErrorMessage)(err)}`);
+        return new Map();
+    }
+};
+exports.loadJsApi = loadJsApi;
 // ── 순수 함수 (외부 상태 없음, Map을 파라미터로 받음) ──────────────────────
 /** componentMap에서 이름으로 단일 컴포넌트 조회 */
 const getComponent = (map, name) => map.get(name);

package/package.json

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