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

package/bin/definitions/instructions.md

@@ -5,7 +5,7 @@ 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 or guess NCUA CSS variables (--ncua-*). NCUA component styles are controlled by CDN CSS only.
+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.
@@ -30,20 +30,29 @@ You are an agent that builds UI using NCUA (NCDS UI Admin) design system compone
 
 ### Step 1: Component Discovery
 
+- Call **list_components** first to see all available components and their categories. This prevents reinventing components that already exist.
 - Use **search_component** with Korean/English keywords to find the right component
 - Example: "비밀번호" → password-input, "모달" → modal
 - **IMPORTANT**: input is for plain text only. For passwords, always use password-input.
 
 ### Step 2: Props Check
 
-- Use **get_component_props** to see available properties
+- Use **get_component_props** to see available properties BEFORE calling render_to_html.
 - Pass all required props. Choose enum values only from the allowed list.
+- Check `type: "object"` props carefully — they often expect arrays or structured objects. Read the `rawType` field for the actual TypeScript type.
+- For icon props (`leadingIcon`, `trailingIcon`, `icon`), pass `{ type: "icon", icon: "IconName" }` where IconName is a PascalCase name from search_icon.
 
 ### Step 3: HTML Generation
 
 - When building a page with multiple components, use **render_to_html_batch** to render them all in one call (max 30). This is much more efficient than calling render_to_html repeatedly.
 - For a single component, use **render_to_html**.
 - Use the returned html as-is. Do NOT modify class names, structure, or attributes.
+- Check the `warnings` field in the response — it reports invalid enum values and missing required props.
+- **If render returns empty or minimal HTML**, the component likely needs data props (e.g. `menus` for HorizontalTab, `items` for BreadCrumb). Check get_component_props and retry with proper data.
+- **Empty result recovery** (max 3 attempts):
+  1. Call get_component_props to identify required/data props
+  2. Retry render_to_html with meaningful prop values
+  3. If still empty after 3 attempts, report the issue to the user
 
 ### Step 4: CDN Inclusion
 
@@ -55,6 +64,9 @@ You are an agent that builds UI using NCUA (NCDS UI Admin) design system compone
 
 - Combine render_to_html results to build the final page
 - Do NOT modify NCUA component styles
+- Apply spacing between components using NCUA design tokens: call **get_design_tokens** with category "spacing" to get available spacing values (e.g. var(--spacing-4), var(--spacing-8))
+- When deciding component size or hierarchy, document your reasoning in an HTML comment (e.g. `<!-- size:sm chosen for compact sidebar layout -->`)
+- If a commerce-rag MCP server is available, query it for page layout patterns and spacing guidelines specific to the project
 
 ## Building Custom Areas (not covered by NCUA)
 

package/bin/definitions/rules.json

@@ -54,5 +54,6 @@
   ],
   "category": [
     "Component categories follow the design team standard (DES INDEX): action, input, icon, overlay, navigation, feedback, data-display."
-  ]
+  ],
+  "pingReminder": "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."
 }

package/bin/server.js

@@ -48,7 +48,7 @@ const loadToolDefinitions = (definitionsDir) => {
     }
     return { descriptions, capabilities };
 };
-/** rules.json을 로딩하여 flat 배열로 반환 */
+/** rules.json을 로딩하여 flat 배열 + pingReminder 반환 */
 const loadRules = (definitionsDir) => {
     const raw = fs_1.default.readFileSync(path_1.default.join(definitionsDir, 'rules.json'), 'utf-8');
     const data = JSON.parse(raw);
@@ -63,22 +63,23 @@ const loadRules = (definitionsDir) => {
         'compliance',
         'category',
     ];
-    const rules = [];
+    const flat = [];
     for (const key of RULE_KEYS) {
         const arr = data[key];
         if (!Array.isArray(arr)) {
             throw new Error(`rules.json에 ${key} 배열이 없습니다`);
         }
-        rules.push(...arr);
+        flat.push(...arr);
     }
-    return rules;
+    const pingReminder = typeof data.pingReminder === 'string' ? data.pingReminder : '';
+    return { flat, pingReminder };
 };
 // ── 진입점 ───────────────────────────────────────────────────────────────────
 const main = async () => {
     const definitionsDir = path_1.default.resolve(__dirname, 'definitions');
     // ── definitions/ 로딩 (main() 안에서 실행하여 catch에 포함) ──
     const { descriptions, capabilities } = loadToolDefinitions(definitionsDir);
-    const rules = loadRules(definitionsDir);
+    const { flat: rules, pingReminder } = 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);
@@ -91,6 +92,16 @@ const main = async () => {
     // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
     const bundle = require(bundlePath);
     logger_js_1.logger.info('컴포넌트 번들 로딩 완료');
+    // 아이콘 번들 로딩 — renderToHtml에서 아이콘 이름 문자열을 실제 React 컴포넌트로 resolve
+    let iconBundle = {};
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+        iconBundle = require('@ncds/ui-admin-icon');
+        logger_js_1.logger.info('아이콘 번들 로딩 완료');
+    }
+    catch {
+        logger_js_1.logger.warn('아이콘 번들 로딩 실패 — 아이콘 resolve 비활성화');
+    }
     // ── DOM + React 런타임 초기화 (유틸로 추출 § 3.9) ──
     const reactRuntime = (0, domEnvironment_js_1.setupDomEnvironment)();
     logger_js_1.logger.info('DOM + React 런타임 초기화 완료');
@@ -103,21 +114,31 @@ 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 의도적 사용)
+    let pinged = false;
+    const withPingReminder = (response) => {
+        if (pinged || !pingReminder)
+            return response;
+        return (0, response_js_1.appendPingReminder)(response, pingReminder);
+    };
+    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 +147,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,18 +157,17 @@ 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,
+        iconBundle,
         cdnMeta,
         iconMeta,
         reactRuntime,
         jsApiMap,
         name,
         props: props,
-    }));
+    })));
     server.registerTool('render_to_html_batch', {
         description: descriptions['render_to_html_batch'],
         inputSchema: {
@@ -164,6 +184,7 @@ const main = async () => {
         const results = components.map(({ name, props }) => (0, renderToHtml_js_1.renderToHtml)({
             componentMap,
             bundle,
+            iconBundle,
             cdnMeta,
             iconMeta,
             reactRuntime,
@@ -175,7 +196,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 +206,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/bin/tools/renderToHtml.d.ts

@@ -4,13 +4,14 @@
  * DOM 환경과 React/ReactDOM은 server.ts에서 초기화하고 파라미터로 전달한다.
  * 이 파일에는 fs, path, require, let이 없다.
  */
-import type { ComponentData, ReactRuntime } from '../types.js';
-import type { CdnMeta, IconMeta, JsApiInfo } from '../utils/dataLoader.js';
+import type { ComponentData, ReactRuntime, JsApiInfo } from '../types.js';
+import type { CdnMeta, IconMeta } from '../utils/dataLoader.js';
 import { type McpToolResponse } from '../utils/response.js';
 /** render_to_html tool 파라미터 */
 export interface RenderToHtmlParams {
     componentMap: Map<string, ComponentData>;
     bundle: Record<string, unknown>;
+    iconBundle: Record<string, unknown>;
     cdnMeta: CdnMeta | null;
     iconMeta: IconMeta | null;
     reactRuntime: ReactRuntime;

package/bin/tools/renderToHtml.js

@@ -6,95 +6,95 @@ const response_js_1 = require("../utils/response.js");
 /** React 특수 props 차단 — injection 방지 */
 const BLOCKED_PROPS = new Set(['dangerouslySetInnerHTML', 'ref', '__self', '__source']);
 /** 아이콘 관련 props — React 변환 시 import 생성 대상 */
-const ICON_PROP_NAMES = new Set(['leadingIcon', 'trailingIcon', 'icon']);
-// ── 순수 함수 (헬퍼) ──────────────────────────────────────────────
-/** componentData.exportName으로 번들에서 컴포넌트를 찾는다 */
-const findComponent = (bundle, exportName) => {
-    return bundle[exportName] ?? null;
-};
-/** componentMap의 props 스펙에서 defaultsUsed를 자동 계산 */
-const calcDefaultsUsed = (propsSpec, userProps) => {
-    const defaults = {};
-    for (const [key, spec] of Object.entries(propsSpec)) {
-        if (spec.default !== undefined && !(key in userProps)) {
-            defaults[key] = spec.default;
-        }
-    }
-    return defaults;
-};
+const ICON_PROP_NAMES = new Set(['leadingIcon', 'trailingIcon', 'icon', 'groupIcon']);
+// ── 타입 가드 ──────────────────────────────────────────────────────
+/** { type: 'icon', icon: string } 형태인지 판별 */
+const isIconSlot = (value) => typeof value === 'object' &&
+    value !== null &&
+    value.type === 'icon' &&
+    typeof value.icon === 'string';
+// ── Props 변환 ──────────────────────────────────────────────────────
 /** BLOCKED_PROPS를 제거 — props spec 유무와 무관하게 항상 적용 */
-const removeBlockedProps = (props) => {
-    const safe = {};
-    for (const [key, value] of Object.entries(props)) {
-        if (!BLOCKED_PROPS.has(key))
-            safe[key] = value;
-    }
-    return safe;
-};
+const removeBlockedProps = (props) => Object.fromEntries(Object.entries(props).filter(([key]) => !BLOCKED_PROPS.has(key)));
 /** componentData.props에 정의된 키 + children만 허용하는 화이트리스트 필터 */
 const sanitizeProps = (userProps, propsSpec) => {
     const allowedKeys = new Set([...Object.keys(propsSpec), 'children']);
-    const sanitized = {};
-    for (const [key, value] of Object.entries(userProps)) {
-        if (allowedKeys.has(key))
-            sanitized[key] = value;
-    }
-    return sanitized;
+    return Object.fromEntries(Object.entries(userProps).filter(([key]) => allowedKeys.has(key)));
 };
-/** JSX attribute 값에서 " 를 이스케이프 */
-const escapeJsxAttrValue = (value) => value.replace(/"/g, '"');
-/** props 값을 JSX attribute 문자열로 변환 */
-const propsToJsxAttrs = (props, propsSpec) => {
-    const attrs = [];
-    for (const [key, value] of Object.entries(props)) {
-        if (key === 'children')
+/** 아이콘 prop의 icon 문자열을 실제 React 컴포넌트로 resolve */
+const resolveIconProps = (props, iconBundle) => {
+    const resolved = { ...props };
+    for (const key of ICON_PROP_NAMES) {
+        const iconObj = resolved[key];
+        if (!isIconSlot(iconObj))
             continue;
-        const spec = propsSpec[key];
-        if (typeof value === 'boolean' && value) {
-            attrs.push(key);
-        }
-        else if (typeof value === 'string') {
-            attrs.push(`${key}="${escapeJsxAttrValue(value)}"`);
-        }
-        else if (typeof value === 'number') {
-            attrs.push(`${key}={${value}}`);
-        }
-        else if (ICON_PROP_NAMES.has(key) && typeof value === 'object' && value !== null) {
-            const iconObj = value;
-            if (iconObj.type === 'icon' && typeof iconObj.icon === 'string') {
-                attrs.push(`${key}={{ type: 'icon', icon: ${iconObj.icon} }}`);
-            }
-            else {
-                attrs.push(`${key}={${JSON.stringify(value)}}`);
-            }
-        }
-        else if (spec?.type === 'enum' || spec?.type === 'string') {
-            attrs.push(`${key}="${String(value)}"`);
-        }
-        else {
-            attrs.push(`${key}={${JSON.stringify(value)}}`);
+        const iconComponent = iconBundle[iconObj.icon];
+        if (typeof iconComponent === 'function') {
+            resolved[key] = { ...iconObj, icon: iconComponent };
         }
     }
-    return attrs.join(' ');
+    return resolved;
+};
+// ── JSX 변환 ──────────────────────────────────────────────────────
+/** JSX attribute 값에서 " 를 이스케이프 */
+const escapeJsxAttrValue = (value) => value.replace(/"/g, '"');
+/** 단일 prop을 JSX attribute 문자열로 변환 */
+const toJsxAttr = (key, value, spec) => {
+    if (typeof value === 'boolean' && value)
+        return key;
+    if (typeof value === 'string')
+        return `${key}="${escapeJsxAttrValue(value)}"`;
+    if (typeof value === 'number')
+        return `${key}={${value}}`;
+    if (ICON_PROP_NAMES.has(key) && isIconSlot(value))
+        return `${key}={{ type: 'icon', icon: ${value.icon} }}`;
+    if (spec?.type === 'enum' || spec?.type === 'string')
+        return `${key}="${String(value)}"`;
+    return `${key}={${JSON.stringify(value)}}`;
+};
+/** props 객체를 JSX attribute 문자열로 변환 */
+const propsToJsxAttrs = (props, propsSpec) => Object.entries(props)
+    .filter(([key]) => key !== 'children')
+    .map(([key, value]) => toJsxAttr(key, value, propsSpec[key]))
+    .join(' ');
+// ── 아이콘 추출 ──────────────────────────────────────────────────
+/** icon prop 값에서 아이콘 이름을 추출 */
+const extractIconName = (value) => {
+    if (isIconSlot(value))
+        return value.icon;
+    if (typeof value === 'string' && value.length > 0)
+        return value;
+    return null;
 };
 /** appliedProps에서 아이콘 이름을 추출 (PascalCase) */
-const extractIconNames = (props) => {
-    const icons = [];
-    for (const [key, value] of Object.entries(props)) {
-        if (!ICON_PROP_NAMES.has(key))
-            continue;
-        if (typeof value === 'object' && value !== null) {
-            const iconObj = value;
-            if (iconObj.type === 'icon' && typeof iconObj.icon === 'string') {
-                icons.push(iconObj.icon);
-            }
-        }
-        else if (typeof value === 'string' && value.length > 0) {
-            icons.push(value);
-        }
-    }
-    return icons;
+const extractIconNames = (props) => Object.entries(props)
+    .filter(([key]) => ICON_PROP_NAMES.has(key))
+    .map(([, value]) => extractIconName(value))
+    .filter((name) => name !== null);
+// ── 검증 ────────────────────────────────────────────────────────
+/** 잘못된 enum 값을 경고 문자열로 변환 */
+const formatInvalidEnum = (key, value, spec) => {
+    const allowed = spec.values ?? [];
+    return `Invalid enum value '${value}' for prop '${key}'. Allowed: ${allowed.join(', ')}.`;
 };
+/** props 검증 — enum 불일치, 필수 prop 누락을 warnings로 반환 */
+const validateProps = (userProps, propsSpec) => {
+    const missingRequired = Object.entries(propsSpec)
+        .filter(([key, spec]) => spec.required && !(key in userProps))
+        .map(([key]) => `Required prop '${key}' is missing.`);
+    const invalidEnums = Object.entries(userProps)
+        .filter(([key, value]) => {
+        const spec = propsSpec[key];
+        return spec?.type === 'enum' && spec.values && typeof value === 'string' && !spec.values.includes(value);
+    })
+        .map(([key, value]) => formatInvalidEnum(key, value, propsSpec[key]));
+    return [...missingRequired, ...invalidEnums];
+};
+// ── 응답 조립 ──────────────────────────────────────────────────────
+/** componentMap의 props 스펙에서 defaultsUsed를 자동 계산 */
+const calcDefaultsUsed = (propsSpec, userProps) => Object.fromEntries(Object.entries(propsSpec)
+    .filter(([key, spec]) => spec.default !== undefined && !(key in userProps))
+    .map(([key, spec]) => [key, spec.default]));
 /** React 변환 매핑 정보를 생성 */
 const buildReactOutput = (componentData, appliedProps, iconMeta) => {
     const { exportName, importPath, props: propsSpec } = componentData;
@@ -102,37 +102,47 @@ const buildReactOutput = (componentData, appliedProps, iconMeta) => {
     const dependencies = [importPath];
     const iconNames = extractIconNames(appliedProps);
     if (iconNames.length > 0 && iconMeta) {
-        const iconImport = `import { ${iconNames.join(', ')} } from '${iconMeta.packageName}';`;
-        imports.push(iconImport);
+        imports.push(`import { ${iconNames.join(', ')} } from '${iconMeta.packageName}';`);
         if (!dependencies.includes(iconMeta.packageName)) {
             dependencies.push(iconMeta.packageName);
         }
     }
     const attrsStr = propsSpec ? propsToJsxAttrs(appliedProps, propsSpec) : '';
+    const attrsPrefix = attrsStr ? ' ' + attrsStr : '';
     const children = appliedProps.children;
     const jsx = children
-        ? `<${exportName}${attrsStr ? ' ' + attrsStr : ''}>${String(children)}</${exportName}>`
-        : `<${exportName}${attrsStr ? ' ' + attrsStr : ''} />`;
-    return {
-        imports,
-        jsx,
-        cssImport: `import '${importPath}/style.css';`,
-        dependencies,
-    };
+        ? `<${exportName}${attrsPrefix}>${String(children)}</${exportName}>`
+        : `<${exportName}${attrsPrefix} />`;
+    return { imports, jsx, cssImport: `import '${importPath}/style.css';`, dependencies };
 };
 /** dataVersion 객체를 생성 */
-const buildDataVersion = (cdnMeta, iconMeta) => {
-    const versions = {};
-    if (cdnMeta)
-        versions['@ncds/ui-admin'] = cdnMeta.version;
-    if (iconMeta)
-        versions[iconMeta.packageName] = iconMeta.version;
-    return versions;
+const buildDataVersion = (cdnMeta, iconMeta) => ({
+    ...(cdnMeta && { '@ncds/ui-admin': cdnMeta.version }),
+    ...(iconMeta && { [iconMeta.packageName]: iconMeta.version }),
+});
+/** jsRequired에 따라 js 필드를 생성 */
+const buildJsField = (componentData, jsApiMap) => {
+    if (!componentData.jsRequired)
+        return { required: false };
+    const jsApi = jsApiMap.get(componentData.exportName);
+    return {
+        required: true,
+        description: '이 컴포넌트는 인터랙션을 위해 CDN JS가 필요합니다',
+        ...(jsApi && {
+            api: {
+                className: jsApi.className,
+                constructor: jsApi.constructor,
+                constructorParams: jsApi.constructorParams,
+                methods: jsApi.methods,
+                example: jsApi.example,
+            },
+        }),
+    };
 };
 // ── 진입점 ────────────────────────────────────────────────────────
 /** render_to_html tool — props로 React 컴포넌트를 렌더링하여 HTML + React 매핑 반환 */
 const renderToHtml = (params) => {
-    const { componentMap, bundle, cdnMeta, iconMeta, reactRuntime, jsApiMap, name, props } = params;
+    const { componentMap, bundle, iconBundle, cdnMeta, iconMeta, reactRuntime, jsApiMap, name, props } = params;
     const normalized = (0, response_js_1.normalizeName)(name);
     const componentData = componentMap.get(normalized);
     if (!componentData)
@@ -141,47 +151,30 @@ const renderToHtml = (params) => {
     if (!exportName) {
         return (0, response_js_1.errorResponse)('EXPORT_NAME_MISSING', `'${normalized}' 컴포넌트에 exportName이 없습니다.`, '데이터를 재추출해주세요 (yarn extract).');
     }
-    const Component = findComponent(bundle, exportName);
+    const Component = bundle[exportName] ?? null;
     if (!Component) {
         return (0, response_js_1.errorResponse)('COMPONENT_NOT_IN_BUNDLE', `'${normalized}' (${exportName}) 컴포넌트가 번들에 없습니다.`, '번들을 재빌드해주세요 (yarn build:bundle).');
     }
     try {
-        const rawProps = props ?? {};
-        const safeProps = removeBlockedProps(rawProps);
-        const userProps = componentData.props ? sanitizeProps(safeProps, componentData.props) : safeProps;
-        const element = reactRuntime.createElement(Component, userProps);
-        const rawHtml = reactRuntime.renderToStaticMarkup(element);
+        const safeProps = removeBlockedProps(props ?? {});
+        const sanitized = componentData.props ? sanitizeProps(safeProps, componentData.props) : safeProps;
+        const resolvedProps = resolveIconProps(sanitized, iconBundle);
+        const rawHtml = reactRuntime.renderToStaticMarkup(reactRuntime.createElement(Component, resolvedProps));
         const html = `<!-- ncua:${normalized} start -->\n${rawHtml}\n<!-- ncua:${normalized} end -->`;
-        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 };
+        const warnings = componentData.props ? validateProps(sanitized, componentData.props) : [];
+        const hasDefaults = componentData.props ? calcDefaultsUsed(componentData.props, sanitized) : {};
         return (0, response_js_1.successResponse)({
             html,
             component: normalized,
             exportName,
             importPath: componentData.importPath,
-            appliedProps: userProps,
-            ...(Object.keys(defaultsUsed).length > 0 && { defaultsUsed }),
-            js,
+            appliedProps: sanitized,
+            ...(Object.keys(hasDefaults).length > 0 && { defaultsUsed: hasDefaults }),
+            ...(warnings.length > 0 && { warnings }),
+            js: buildJsField(componentData, jsApiMap),
             cdn: cdnMeta ?? undefined,
-            dataVersion,
-            react,
+            dataVersion: buildDataVersion(cdnMeta, iconMeta),
+            react: buildReactOutput(componentData, sanitized, iconMeta),
         });
     }
     catch (err) {

package/bin/types.d.ts

@@ -7,6 +7,7 @@ export interface PropSpec {
     default?: unknown;
     values?: string[];
     rawType?: string;
+    properties?: Record<string, PropSpec>;
 }
 export interface ComponentUsage {
     import: string;
@@ -67,6 +68,14 @@ export interface TokenData {
     categories: string[];
     groups: TokenGroup[];
 }
+export interface JsApiInfo {
+    className: string;
+    constructor: string;
+    constructorParams: Record<string, string>;
+    methods: string[];
+    staticMethods?: string[];
+    example: string;
+}
 export interface ComplianceRuleHint {
     attr: string;
     values: string[];

package/bin/utils/dataLoader.d.ts

@@ -1,4 +1,4 @@
-import type { ComponentData, IconData, TokenData, ComplianceRulesData } from '../types.js';
+import type { ComponentData, IconData, TokenData, ComplianceRulesData, JsApiInfo } from '../types.js';
 export declare const DEFAULT_DATA_DIR: string;
 export interface CdnMeta {
     version: string;
@@ -27,15 +27,6 @@ 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에서 이름으로 단일 컴포넌트 조회 */

package/bin/utils/response.d.ts

@@ -20,6 +20,8 @@ export declare const successResponse: (data: unknown) => McpToolResponse;
 export declare const errorResponse: (code: McpErrorCode, message: string, suggestion: string) => McpToolResponse;
 /** COMPONENT_NOT_FOUND 오류 — 여러 tool에서 공통 사용 */
 export declare const componentNotFoundResponse: (name: string) => McpToolResponse;
+/** ping 미호출 시 응답에 핵심 rules를 주입하는 래퍼 */
+export declare const appendPingReminder: (response: McpToolResponse, reminder: string) => McpToolResponse;
 /** 입력 정규화 — name.trim().toLowerCase() */
 export declare const normalizeName: (name: string) => string;
 /** catch 블록에서 에러 메시지를 안전하게 추출 */

package/bin/utils/response.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toErrorMessage = exports.normalizeName = exports.componentNotFoundResponse = exports.errorResponse = exports.successResponse = void 0;
+exports.toErrorMessage = exports.normalizeName = exports.appendPingReminder = exports.componentNotFoundResponse = exports.errorResponse = exports.successResponse = void 0;
 /** 성공 응답 — data를 JSON.stringify하여 반환 */
 const successResponse = (data) => ({
     content: [{ type: 'text', text: JSON.stringify(data) }],
@@ -20,6 +20,12 @@ exports.errorResponse = errorResponse;
 /** COMPONENT_NOT_FOUND 오류 — 여러 tool에서 공통 사용 */
 const componentNotFoundResponse = (name) => (0, exports.errorResponse)('COMPONENT_NOT_FOUND', `Component '${name}' not found.`, 'Use search_component to find similar components, or list_components to see all available.');
 exports.componentNotFoundResponse = componentNotFoundResponse;
+/** ping 미호출 시 응답에 핵심 rules를 주입하는 래퍼 */
+const appendPingReminder = (response, reminder) => {
+    const text = response.content[0].text + '\n\n' + reminder;
+    return { ...response, content: [{ type: 'text', text }] };
+};
+exports.appendPingReminder = appendPingReminder;
 /** 입력 정규화 — name.trim().toLowerCase() */
 const normalizeName = (name) => name.trim().toLowerCase();
 exports.normalizeName = normalizeName;