@ncds/ui-admin-mcp 1.6.4-alpha.5 → 1.6.4-alpha.6

package/README.md

@@ -79,6 +79,8 @@ Claude에게 자연어로 물어보면 됩니다:
 "어드민 컴포넌트 목록 보여줘"
 "버튼 컴포넌트 어떤 속성 사용할 수 있어?"
 "input 컴포넌트 HTML 마크업 보여줘"
+"화살표 관련 아이콘 검색해줘"
+"버튼 컴포넌트를 label은 저장, primary로 렌더링해줘"
 "이 HTML에 사용된 클래스가 맞는지 검증해줘"
 ```
 
@@ -90,9 +92,12 @@ Claude에게 자연어로 물어보면 됩니다:
 | --------------------- | -------------------------------------------------------------- |
 | 📋 컴포넌트 목록 조회 | 사용 가능한 전체 UI 컴포넌트를 확인합니다                      |
 | 🔍 컴포넌트 검색      | 키워드로 원하는 컴포넌트를 찾습니다                            |
+| 🎨 아이콘 목록 조회   | 사용 가능한 아이콘 요약 정보를 확인합니다                      |
+| 🔍 아이콘 검색        | 키워드로 원하는 아이콘을 찾습니다                              |
 | 🧩 HTML 마크업 조회   | 컴포넌트의 정확한 HTML 구조와 React 사용 예시를 확인합니다     |
 | ⚙️ 속성(Props) 조회   | 컴포넌트에 사용할 수 있는 옵션과 기본값을 확인합니다           |
 | ✅ HTML 검증          | 작성한 HTML의 클래스명이 올바른지 검증하고 자동으로 수정합니다 |
+| 🔄 동적 HTML 렌더링   | props를 전달하면 실제 렌더링된 정확한 HTML을 받을 수 있습니다  |
 | 📡 서버 상태 확인     | 연결 상태, 버전, 사용 규칙을 확인합니다                        |
 
 <br />

package/bin/server.js

@@ -1,8 +1,12 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 /**
  * MCP 서버 진입점 — componentMap 소유, tool 등록, transport 연결
  */
+const path_1 = __importDefault(require("path"));
 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");
@@ -16,6 +20,7 @@ const validateHtml_js_1 = require("./tools/validateHtml.js");
 const ping_js_1 = require("./tools/ping.js");
 const listIcons_js_1 = require("./tools/listIcons.js");
 const searchIcon_js_1 = require("./tools/searchIcon.js");
+const renderToHtml_js_1 = require("./tools/renderToHtml.js");
 const version_js_1 = require("./version.js");
 const server = new mcp_js_1.McpServer({
     name: 'ncds-ui-admin',
@@ -26,6 +31,7 @@ const main = async () => {
     const componentMap = (0, dataLoader_js_1.loadComponentsFromDir)(dataLoader_js_1.DEFAULT_DATA_DIR);
     const cdnMeta = (0, dataLoader_js_1.loadCdnMeta)(dataLoader_js_1.DEFAULT_DATA_DIR);
     const iconData = (0, dataLoader_js_1.loadIconData)(dataLoader_js_1.DEFAULT_DATA_DIR);
+    const bundlePath = path_1.default.resolve(__dirname, '../bin/components.bundle.js');
     server.registerTool('ping', {
         description: 'NCUA MCP 서버 연결 확인 + 버전 + capabilities/rules 조회',
     }, () => (0, ping_js_1.ping)(componentMap, cdnMeta, version_js_1.VERSION));
@@ -66,6 +72,13 @@ const main = async () => {
                 .describe('검증할 HTML 마크업 (예: \'<button class="ncua-btn ncua-btn--primary"></button>\')'),
         },
     }, ({ html }) => (0, validateHtml_js_1.validateHtml)(componentMap, html));
+    server.registerTool('render_to_html', {
+        description: '컴포넌트명과 props를 전달하면 실제 렌더링된 HTML을 반환합니다. 어떤 props 조합이든 정확한 DOM 구조의 HTML을 받을 수 있습니다.',
+        inputSchema: {
+            name: zod_1.z.string().min(1).describe('컴포넌트명 (예: "button", "modal", "input")'),
+            props: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional().describe('컴포넌트 props (예: { label: "확인", hierarchy: "primary" })'),
+        },
+    }, ({ name, props }) => (0, renderToHtml_js_1.renderToHtml)(componentMap, bundlePath, name, props));
     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/listIcons.d.ts

@@ -1,5 +1,8 @@
 /**
- * list_icons tool — 전체 아이콘 목록 반환 (순수 함수)
+ * list_icons tool — 아이콘 요약 정보 반환 (순수 함수)
+ *
+ * 아이콘 이름을 전부 반환하면 토큰 낭비이므로,
+ * 요약 정보만 반환하고 search_icon으로 검색을 유도한다.
  */
 import { type McpToolResponse } from '../utils/response.js';
 export interface IconEntry {

package/bin/tools/listIcons.js

@@ -2,14 +2,20 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.listIcons = void 0;
 /**
- * list_icons tool — 전체 아이콘 목록 반환 (순수 함수)
+ * list_icons tool — 아이콘 요약 정보 반환 (순수 함수)
+ *
+ * 아이콘 이름을 전부 반환하면 토큰 낭비이므로,
+ * 요약 정보만 반환하고 search_icon으로 검색을 유도한다.
  */
 const response_js_1 = require("../utils/response.js");
 const listIcons = (iconData) => {
+    const prefixes = new Set(iconData.icons.map((i) => i.name.replace(/Fill$/, '')));
     return (0, response_js_1.successResponse)({
         totalCount: iconData.totalCount,
         fillCount: iconData.fillCount,
-        icons: iconData.icons.map((i) => i.name).sort(),
+        uniqueIcons: prefixes.size,
+        hint: '아이콘이 많으므로 search_icon tool로 키워드 검색을 권장합니다. 예: search_icon("arrow"), search_icon("check")',
+        sample: iconData.icons.slice(0, 20).map((i) => i.name),
     });
 };
 exports.listIcons = listIcons;

package/bin/tools/ping.js

@@ -11,6 +11,7 @@ const CAPABILITIES = [
     { tool: 'get_component_html', description: '컴포넌트 HTML 마크업 조회 (variant 지원)' },
     { tool: 'get_component_props', description: '컴포넌트 Props 스펙 조회' },
     { tool: 'validate_html', description: 'HTML BEM 클래스 유효성 검증 + 자동 수정' },
+    { tool: 'render_to_html', description: 'Props 기반 동적 HTML 렌더링' },
 ];
 const RULES = [
     '이 라이브러리의 컴포넌트를 사용할 때는 CDN CSS/JS를 포함하세요',

package/bin/tools/renderToHtml.d.ts

@@ -0,0 +1,3 @@
+import type { ComponentData } from '../types.js';
+import { type McpToolResponse } from '../utils/response.js';
+export declare const renderToHtml: (componentMap: Map<string, ComponentData>, bundlePath: string, name: string, props?: Record<string, unknown>) => McpToolResponse;

package/bin/tools/renderToHtml.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderToHtml = void 0;
+const response_js_1 = require("../utils/response.js");
+// eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+const { JSDOM } = require('jsdom');
+/** jsdom + createPortal mock 환경을 세팅한다 */
+const setupDomEnvironment = () => {
+    if (typeof globalThis.document === 'undefined') {
+        const dom = new JSDOM('<!DOCTYPE html><html><body></body></html>');
+        globalThis.document = dom.window.document;
+        // window/navigator는 이미 존재할 수 있으므로 (vitest 등) 없을 때만 세팅
+        if (typeof globalThis.window === 'undefined') {
+            globalThis.window = dom.window;
+        }
+        if (typeof globalThis.navigator === 'undefined') {
+            Object.defineProperty(globalThis, 'navigator', { value: dom.window.navigator, writable: true });
+        }
+    }
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+    const ReactDOM = require('react-dom');
+    if (!ReactDOM._portalMocked) {
+        ReactDOM.createPortal = (children) => children;
+        ReactDOM._portalMocked = true;
+    }
+};
+/** kebab-case → PascalCase 변환 */
+const toPascalCase = (kebab) => kebab
+    .split('-')
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('');
+/** 번들에서 컴포넌트를 찾는다 */
+const findComponent = (bundle, name) => {
+    const pascalName = toPascalCase(name);
+    // 정확한 이름 매칭
+    if (bundle[pascalName])
+        return { Component: bundle[pascalName], exportName: pascalName };
+    // InputBase 등 특수 매핑
+    const SPECIAL_MAPPINGS = {
+        Input: 'InputBase',
+        PasswordInput: 'PasswordInput',
+        NumberInput: 'NumberInput',
+        Textarea: 'Textarea',
+    };
+    const special = SPECIAL_MAPPINGS[pascalName];
+    if (special && bundle[special])
+        return { Component: bundle[special], exportName: special };
+    // 대소문자 무관 검색
+    const key = Object.keys(bundle).find((k) => k.toLowerCase() === pascalName.toLowerCase());
+    if (key && bundle[key])
+        return { Component: bundle[key], exportName: key };
+    return null;
+};
+const renderToHtml = (componentMap, bundlePath, name, props) => {
+    const normalized = (0, response_js_1.normalizeName)(name);
+    const componentData = componentMap.get(normalized);
+    if (!componentData)
+        return (0, response_js_1.componentNotFoundResponse)(normalized);
+    setupDomEnvironment();
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+    const React = require('react');
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+    const { renderToStaticMarkup } = require('react-dom/server');
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+    const bundle = require(bundlePath);
+    const found = findComponent(bundle, normalized);
+    if (!found) {
+        return (0, response_js_1.successResponse)({
+            error: 'COMPONENT_NOT_IN_BUNDLE',
+            message: `'${normalized}' 컴포넌트가 번들에 없습니다. get_component_html을 사용하세요.`,
+        });
+    }
+    try {
+        const element = React.createElement(found.Component, props ?? {});
+        const html = renderToStaticMarkup(element);
+        return (0, response_js_1.successResponse)({
+            html,
+            component: normalized,
+            exportName: found.exportName,
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return (0, response_js_1.successResponse)({
+            error: 'RENDER_FAILED',
+            message: `'${normalized}' 렌더링 실패: ${message}`,
+            component: normalized,
+        });
+    }
+};
+exports.renderToHtml = renderToHtml;

package/bin/utils/dataLoader.d.ts

@@ -8,15 +8,7 @@ export interface CdnMeta {
     css: string;
     js: string;
 }
-export interface IconEntry {
-    name: string;
-    kebab: string;
-    fill: boolean;
-}
-export interface IconData {
-    totalCount: number;
-    fillCount: number;
-    icons: IconEntry[];
-}
+import type { IconData } from '../tools/listIcons.js';
+export type { IconData };
 export declare const loadIconData: (dataDir: string) => IconData;
 export declare const loadCdnMeta: (dataDir: string) => CdnMeta | null;

package/package.json

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