@ncds/ui-admin-mcp 1.0.0-alpha.2 → 1.0.0-alpha.20

package/bin/server.d.ts

@@ -1 +1,6 @@
+/**
+ * MCP 서버 진입점 — 모든 데이터 소유, tool 등록, transport 연결
+ *
+ * 이 파일만 Action(부수효과)을 포함한다. tool 핸들러는 모두 Calculation.
+ */
 export {};

package/bin/server.js

@@ -1,31 +1,37 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
 /**
  * MCP 서버 진입점 — 모든 데이터 소유, tool 등록, transport 연결
  *
  * 이 파일만 Action(부수효과)을 포함한다. tool 핸들러는 모두 Calculation.
  */
-const path_1 = __importDefault(require("path"));
-const fs_1 = __importDefault(require("fs"));
+// biome-ignore-all lint/complexity/useLiteralKeys: descriptions['key'] 형태가 tool 이름과 일관성 (Story 5.8 scope 외)
+// biome-ignore-all lint/style/noMagicNumbers: 기존 코드의 zod .max(N) 등 (Story 5.8 scope 외)
+// biome-ignore-all lint/complexity/noExcessiveCognitiveComplexity: main() 진입점 (Story 5.8 scope 외, 별도 refactor 스토리)
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_crypto_1 = require("node:crypto");
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
 const zod_1 = require("zod");
-const dataLoader_js_1 = require("./utils/dataLoader.js");
-const logger_js_1 = require("./utils/logger.js");
-const listComponents_js_1 = require("./tools/listComponents.js");
-const searchComponent_js_1 = require("./tools/searchComponent.js");
 const getComponentProps_js_1 = require("./tools/getComponentProps.js");
-const validateHtml_js_1 = require("./tools/validateHtml.js");
-const ping_js_1 = require("./tools/ping.js");
+const getDesignTokens_js_1 = require("./tools/getDesignTokens.js");
+const listComponents_js_1 = require("./tools/listComponents.js");
+const listCompositionOverrides_js_1 = require("./tools/listCompositionOverrides.js");
 const listIcons_js_1 = require("./tools/listIcons.js");
-const searchIcon_js_1 = require("./tools/searchIcon.js");
+const ping_js_1 = require("./tools/ping.js");
 const renderToHtml_js_1 = require("./tools/renderToHtml.js");
-const getDesignTokens_js_1 = require("./tools/getDesignTokens.js");
-const version_js_1 = require("./version.js");
+const searchComponent_js_1 = require("./tools/searchComponent.js");
+const searchIcon_js_1 = require("./tools/searchIcon.js");
+const validateHtml_js_1 = require("./tools/validateHtml.js");
+const dataLoader_js_1 = require("./utils/dataLoader.js");
 const domEnvironment_js_1 = require("./utils/domEnvironment.js");
+const logger_js_1 = require("./utils/logger.js");
+const response_js_1 = require("./utils/response.js");
+const version_js_1 = require("./version.js");
 // ── definitions/ 로딩 헬퍼 (Action) ─────────────────────────────────────────
 /** tool-definitions.json을 1회 로딩하여 descriptions + capabilities를 분리 반환 */
 const loadToolDefinitions = (definitionsDir) => {
@@ -47,7 +53,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);
@@ -58,30 +64,34 @@ const loadRules = (definitionsDir) => {
         'cdn',
         'react',
         'forbidden',
+        'composition',
+        'fontFamily',
         'customArea',
         '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);
     // ── 데이터 로딩 ──
-    const componentMap = (0, dataLoader_js_1.loadComponentsFromDir)(dataLoader_js_1.DEFAULT_DATA_DIR);
+    const { map: componentMap, compositionOverrides } = (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);
     const iconData = (0, dataLoader_js_1.loadIconData)(dataLoader_js_1.DEFAULT_DATA_DIR);
     const tokenData = (0, dataLoader_js_1.loadTokenData)(dataLoader_js_1.DEFAULT_DATA_DIR);
@@ -89,6 +99,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 런타임 초기화 완료');
@@ -99,23 +119,35 @@ const main = async () => {
     const iconSummary = (0, listIcons_js_1.buildIconSummary)(iconData);
     const listComponentsResponse = (0, listComponents_js_1.buildListComponentsResponse)(groupedComponents);
     const listIconsResponse = (0, listIcons_js_1.buildListIconsResponse)(iconSummary);
+    const listCompositionOverridesResponse = (0, listCompositionOverrides_js_1.buildListCompositionOverridesResponse)(compositionOverrides, componentMap);
     // ── 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('list_composition_overrides', { description: descriptions['list_composition_overrides'] }, () => withPingReminder((0, listCompositionOverrides_js_1.listCompositionOverrides)(listCompositionOverridesResponse)));
     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: {
@@ -124,7 +156,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: {
@@ -134,17 +166,49 @@ 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,
-    }));
+        instanceId: (0, node_crypto_1.randomUUID)().slice(0, 6),
+    })));
+    server.registerTool('render_to_html_batch', {
+        description: descriptions['render_to_html_batch'],
+        inputSchema: {
+            components: zod_1.z
+                .array(zod_1.z.object({
+                name: zod_1.z.string().min(1).describe('Component name'),
+                props: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional().describe('Component props'),
+            }))
+                .min(1)
+                .max(30)
+                .describe('Array of components to render (max 30)'),
+        },
+    }, ({ components }) => {
+        const results = components.map(({ name, props }) => (0, renderToHtml_js_1.renderToHtml)({
+            componentMap,
+            bundle,
+            iconBundle,
+            cdnMeta,
+            iconMeta,
+            reactRuntime,
+            jsApiMap,
+            name,
+            props: props,
+            instanceId: (0, node_crypto_1.randomUUID)().slice(0, 6),
+        }));
+        const parsed = results.map((r) => {
+            const text = r.content[0].text;
+            return r.isError ? { error: JSON.parse(text) } : JSON.parse(text);
+        });
+        return withPingReminder((0, response_js_1.successResponse)(parsed));
+    });
     server.registerTool('get_design_tokens', {
         description: descriptions['get_design_tokens'],
         inputSchema: {
@@ -153,7 +217,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/external/editor.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Story 5.10: editor 외부 분기 모듈
+ *
+ * froala 기반 에디터(`@ncds/editor-html`)는 ui-admin 외부 패키지라
+ * ui-admin 흐름(componentMap / data/{name}.json / cdnAssets) 을 거치지 않고
+ * 본 모듈에서 응답을 직접 조립한다. ui-admin 코드 미수정 → 5-8/5-9 회귀 위험 0.
+ *
+ * 호출 진입점: `renderToHtml` 함수 시작부 (Task 1 결정).
+ */
+import { type McpToolResponse } from '../../utils/response.js';
+/** `normalizeName` 적용된 컴포넌트 이름이 editor alias 인지 검사 */
+declare const isEditorAlias: (normalizedName: string) => boolean;
+/**
+ * editor 응답 조립 — ui-admin 흐름 우회.
+ * 5-9 helper(`mergeCdnDefaults` / `stripFunctionProps`) import 재사용 (코드 중복 0).
+ */
+declare const buildEditorResponse: (props: Record<string, unknown>, instanceId: string) => McpToolResponse;
+export { buildEditorResponse, isEditorAlias };

package/bin/tools/external/editor.js

@@ -0,0 +1,88 @@
+"use strict";
+/**
+ * Story 5.10: editor 외부 분기 모듈
+ *
+ * froala 기반 에디터(`@ncds/editor-html`)는 ui-admin 외부 패키지라
+ * ui-admin 흐름(componentMap / data/{name}.json / cdnAssets) 을 거치지 않고
+ * 본 모듈에서 응답을 직접 조립한다. ui-admin 코드 미수정 → 5-8/5-9 회귀 위험 0.
+ *
+ * 호출 진입점: `renderToHtml` 함수 시작부 (Task 1 결정).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isEditorAlias = exports.buildEditorResponse = void 0;
+const editor_js_1 = require("../../definitions/external/editor.js");
+const response_js_1 = require("../../utils/response.js");
+const renderToHtml_js_1 = require("../renderToHtml.js");
+/** editor 컴포넌트로 매칭할 alias 집합 (Task 1 결정 — 보수적 5개) */
+const EDITOR_ALIASES = new Set(['editor', 'ncds-editor', 'ncdseditor', 'ncuaeditor', 'editor-html']);
+/** `normalizeName` 적용된 컴포넌트 이름이 editor alias 인지 검사 */
+const isEditorAlias = (normalizedName) => EDITOR_ALIASES.has(normalizedName);
+exports.isEditorAlias = isEditorAlias;
+/** camelCase → kebab-case (heightMin → height-min) */
+const camelToKebab = (s) => s.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`);
+/** HTML attribute 값 escape (` " ` / ` & ` / ` < ` / ` > `) */
+const escapeHtmlAttr = (s) => s.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+/**
+ * options → data-* 속성 직렬화.
+ * - camelCase → kebab-case
+ * - 값 String(v) (boolean → "true"/"false", number → 숫자 문자열)
+ * - null / undefined / function skip (함수는 stripFunctionProps 로 사전 제거되지만 방어적 추가 필터)
+ */
+const serializeDataAttributes = (options) => Object.entries(options)
+    .filter(([, v]) => v !== null && v !== undefined && typeof v !== 'function')
+    .map(([k, v]) => `data-${camelToKebab(k)}="${escapeHtmlAttr(String(v))}"`)
+    .join(' ');
+/**
+ * patternD: textarea + data-* + element-only init script.
+ * 5-8 의 buildPatternA/B/C 와 동일 시그니처 `(id, className, options) => string`.
+ * patternA/B/C 와 차이:
+ *   - 컨테이너: `<div>` → `<textarea>` (froala 가 textarea 를 in-place 변환)
+ *   - options 위치: `new X(wrapper, options)` 두번째 인자 → textarea 의 `data-*` 속성
+ *   - 글로벌: `ncua.X` → `window.NcdsEditor`
+ *   - 호출 위치: ui-admin 의 `PATTERN_BY_COMPONENT` 분기 → 외부 분기 모듈 안 (이 함수)
+ */
+const buildPatternD = (id, className, options) => {
+    const dataAttrs = serializeDataAttributes(options);
+    const tagBody = dataAttrs ? `id="${id}" ${dataAttrs}` : `id="${id}"`;
+    return [
+        `<textarea ${tagBody}></textarea>`,
+        '<script>',
+        "  document.addEventListener('DOMContentLoaded', function () {",
+        `    new window.${className}(document.querySelector('#${id}'));`,
+        '  });',
+        '</script>',
+    ].join('\n');
+};
+/**
+ * editor 응답 조립 — ui-admin 흐름 우회.
+ * 5-9 helper(`mergeCdnDefaults` / `stripFunctionProps`) import 재사용 (코드 중복 0).
+ */
+const buildEditorResponse = (props, instanceId) => {
+    // 5-9: 함수 prop 사전 제거 + cdnDefaults deep merge (사용자 props 우선)
+    const cleanedProps = (0, renderToHtml_js_1.stripFunctionProps)(props);
+    const { merged, defaultsApplied } = (0, renderToHtml_js_1.mergeCdnDefaults)('editor', editor_js_1.editorDefinition.cdnDefaults, cleanedProps);
+    const id = `ed-${instanceId}`;
+    const html = buildPatternD(id, editor_js_1.editorDefinition.className, merged);
+    // cdnDefaults 적용된 키 → defaultsUsed 응답
+    const defaultsUsed = Object.fromEntries(defaultsApplied.map((key) => [key, editor_js_1.editorDefinition.cdnDefaults[key]]));
+    return (0, response_js_1.successResponse)({
+        html,
+        component: editor_js_1.editorDefinition.name,
+        exportName: editor_js_1.editorDefinition.className,
+        importPath: '@ncds/editor-html',
+        appliedProps: merged,
+        ...(Object.keys(defaultsUsed).length > 0 && { defaultsUsed }),
+        js: {
+            required: true,
+            description: '이 컴포넌트는 인터랙션을 위해 CDN JS가 필요합니다',
+            api: {
+                className: editor_js_1.editorDefinition.className,
+                methods: editor_js_1.editorDefinition.methods,
+            },
+        },
+        cdn: editor_js_1.editorDefinition.cdn,
+        dataVersion: { '@ncds/editor': editor_js_1.editorDefinition.cdn.version },
+        react: { notes: 'React not supported in editor (vanilla JS only)' },
+    });
+};
+exports.buildEditorResponse = buildEditorResponse;

package/bin/tools/external/step-guide.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Story 6.1: step-guide 외부 분기 모듈
+ *
+ * vanilla JS 함수 기반 가이드 투어(`step-guide`)는 ui-admin 외부 패키지이며
+ * 5-10 editor와 동일 패턴으로 ui-admin 흐름을 우회하고 본 모듈에서 응답을 직접 조립한다.
+ * 핵심 차이 — step-guide는 함수 호출(`window.stepGuide({el, options})`) 형식이라
+ * 5-10 patternD(생성자 호출 `new window.NcdsEditor(querySelector)`)와 다른 init 스니펫 패턴 신설.
+ *
+ * 호출 진입점: `renderToHtml` 함수 시작부 (editor 분기 다음).
+ */
+import { type McpToolResponse } from '../../utils/response.js';
+/** `normalizeName` 적용된 컴포넌트 이름이 step-guide alias 인지 검사 */
+declare const isStepGuideAlias: (normalizedName: string) => boolean;
+/**
+ * step-guide 응답 조립 — ui-admin 흐름 우회.
+ * 5-9 helper(`mergeCdnDefaults` / `stripFunctionProps`) import 재사용 (코드 중복 0).
+ */
+declare const buildStepGuideResponse: (props: Record<string, unknown>, _instanceId: string) => McpToolResponse;
+export { buildStepGuideResponse, isStepGuideAlias };

package/bin/tools/external/step-guide.js

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * Story 6.1: step-guide 외부 분기 모듈
+ *
+ * vanilla JS 함수 기반 가이드 투어(`step-guide`)는 ui-admin 외부 패키지이며
+ * 5-10 editor와 동일 패턴으로 ui-admin 흐름을 우회하고 본 모듈에서 응답을 직접 조립한다.
+ * 핵심 차이 — step-guide는 함수 호출(`window.stepGuide({el, options})`) 형식이라
+ * 5-10 patternD(생성자 호출 `new window.NcdsEditor(querySelector)`)와 다른 init 스니펫 패턴 신설.
+ *
+ * 호출 진입점: `renderToHtml` 함수 시작부 (editor 분기 다음).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isStepGuideAlias = exports.buildStepGuideResponse = void 0;
+const step_guide_js_1 = require("../../definitions/external/step-guide.js");
+const response_js_1 = require("../../utils/response.js");
+const renderToHtml_js_1 = require("../renderToHtml.js");
+/** step-guide 컴포넌트로 매칭할 alias 집합 (render_to_html 진입점용, 보수적 4 영문) */
+const STEP_GUIDE_ALIASES = new Set(['step-guide', 'stepguide', 'ncdsstepguide', 'step_guide']);
+/** `normalizeName` 적용된 컴포넌트 이름이 step-guide alias 인지 검사 */
+const isStepGuideAlias = (normalizedName) => STEP_GUIDE_ALIASES.has(normalizedName);
+exports.isStepGuideAlias = isStepGuideAlias;
+/**
+ * init 스니펫 — 함수 호출 형식.
+ * 5-10 patternD(생성자 호출 `new window.NcdsEditor(querySelector)`)와 다른 새 패턴.
+ *   - 컨테이너 div 없음 — step-guide는 document.body 에 overlay를 그리는 도구라 격리 div 의미 없음
+ *   - `el: document.body` — step-guide의 _fetchSteps 가 _targetElement 안에서만 step.element selector를 검색하므로
+ *     사용자가 step.element에 외부 카드 selector를 명시할 수 있도록 document.body를 target으로 지정
+ *   - 함수 호출: `window.stepGuide({ el: document.body, options: ... })`
+ *   - JSON.stringify로 options 직렬화 (data-* 미사용)
+ */
+const buildInitSnippet = (options) => {
+    const optionsJson = JSON.stringify(options);
+    return [
+        '<script>',
+        "  document.addEventListener('DOMContentLoaded', function () {",
+        `    window.stepGuide({ el: document.body, options: ${optionsJson} });`,
+        '  });',
+        '</script>',
+    ].join('\n');
+};
+/**
+ * step-guide 응답 조립 — ui-admin 흐름 우회.
+ * 5-9 helper(`mergeCdnDefaults` / `stripFunctionProps`) import 재사용 (코드 중복 0).
+ */
+const buildStepGuideResponse = (props, _instanceId // 격리 div 제거로 인해 unused — 외부 분기 시그니처 일관성 위해 인자는 유지
+) => {
+    // 5-9: 함수 prop 사전 제거 + cdnDefaults deep merge (사용자 props 우선)
+    const cleanedProps = (0, renderToHtml_js_1.stripFunctionProps)(props);
+    const { merged, defaultsApplied } = (0, renderToHtml_js_1.mergeCdnDefaults)('step-guide', step_guide_js_1.stepGuideDefinition.cdnDefaults, cleanedProps);
+    const html = buildInitSnippet(merged);
+    // cdnDefaults 적용된 키 → defaultsUsed 응답
+    const defaultsUsed = Object.fromEntries(defaultsApplied.map((key) => [
+        key,
+        step_guide_js_1.stepGuideDefinition.cdnDefaults[key],
+    ]));
+    return (0, response_js_1.successResponse)({
+        html,
+        component: step_guide_js_1.stepGuideDefinition.name,
+        exportName: step_guide_js_1.stepGuideDefinition.exportName,
+        importPath: 'step-guide',
+        appliedProps: merged,
+        ...(Object.keys(defaultsUsed).length > 0 && { defaultsUsed }),
+        js: {
+            required: true,
+            description: '이 컴포넌트는 인터랙션을 위해 CDN JS가 필요합니다',
+            api: {
+                exportName: step_guide_js_1.stepGuideDefinition.exportName,
+                methods: step_guide_js_1.stepGuideDefinition.methods,
+            },
+        },
+        cdn: step_guide_js_1.stepGuideDefinition.cdn,
+        dataVersion: { '@ncds/step-guide': step_guide_js_1.stepGuideDefinition.cdn.version },
+        react: {
+            notes: 'React 환경: useEffect 내 window.stepGuide({el, options}) 호출 + cleanup에서 instance.exit() 호출. ' +
+                'StrictMode 이중 마운트 회피 — cleanup 멱등성 보장 필요 (exit()가 이미 호출된 후 다시 호출되어도 안전).',
+        },
+    });
+};
+exports.buildStepGuideResponse = buildStepGuideResponse;

package/bin/tools/getComponentProps.d.ts

@@ -1,3 +1,6 @@
+/**
+ * get_component_props tool — 컴포넌트 props 스펙 반환 (순수 함수)
+ */
 import type { ComponentData } from '../types.js';
 import { type McpToolResponse } from '../utils/response.js';
 /** get_component_props tool — 컴포넌트의 props 스펙을 JSON으로 반환 */

package/bin/tools/getComponentProps.js

@@ -1,9 +1,9 @@
 "use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getComponentProps = void 0;
 /**
  * get_component_props tool — 컴포넌트 props 스펙 반환 (순수 함수)
  */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getComponentProps = void 0;
 const dataLoader_js_1 = require("../utils/dataLoader.js");
 const response_js_1 = require("../utils/response.js");
 /** get_component_props tool — 컴포넌트의 props 스펙을 JSON으로 반환 */
@@ -12,6 +12,15 @@ const getComponentProps = (componentMap, name) => {
     const component = (0, dataLoader_js_1.getComponent)(componentMap, normalized);
     if (!component)
         return (0, response_js_1.componentNotFoundResponse)(normalized);
-    return (0, response_js_1.successResponse)(component.props);
+    return (0, response_js_1.successResponse)({
+        props: component.props,
+        ...(component.subComponents && { subComponents: component.subComponents }),
+        ...(component.usageExamples && { usageExamples: component.usageExamples }),
+        // P8: composition overrides 에서 병합되는 필드들 — AI 가 부모-자식 관계와 권장 조합을 우선 학습
+        ...(component.allowedChildren && { allowedChildren: component.allowedChildren }),
+        ...(component.allowedParents && { allowedParents: component.allowedParents }),
+        ...(component.canonicalExample && { canonicalExample: component.canonicalExample }),
+        ...(component.canonicalExamples && { canonicalExamples: component.canonicalExamples }),
+    });
 };
 exports.getComponentProps = getComponentProps;

package/bin/tools/listCompositionOverrides.d.ts

@@ -0,0 +1,61 @@
+/**
+ * list_composition_overrides tool — composition.json composition overrides 적용 현황 요약
+ *
+ * 신규 프로젝트에서 NCDS MCP 와 연결한 뒤, 어느 컴포넌트에 어떤 composition overrides 보강이
+ * 들어가 있는지 표 형태(컴포넌트별 row)로 한 번에 확인하는 용도. 응답이 크지 않도록
+ * 시나리오 키 목록 + 카운트 위주로 구성하고, 상세는 get_component_props 로 유도.
+ *
+ * 순수 함수 — server.ts 부팅 시 1회 buildListCompositionOverridesResponse() 로 사전 직렬화.
+ */
+import type { ComponentData } from '../types.js';
+import type { CompositionEntry } from '../utils/dataLoader.js';
+import { type McpToolResponse } from '../utils/response.js';
+export interface CompositionOverrideSummary {
+    /** 컴포넌트 이름 (kebab-case) */
+    component: string;
+    /** canonicalExamples 시나리오 key 목록 — 비어있으면 [] */
+    canonicalExamples: string[];
+    /** legacy 단일 시나리오 canonicalExample 존재 여부 */
+    hasCanonicalExample: boolean;
+    /** bemClassesExtra 항목 수 */
+    bemClassesExtra: number;
+    /** allowedChildren 정의된 부모 키 목록 (예: ["Table", "Table.Header", ...]) */
+    allowedChildrenKeys: string[];
+    /** allowedParents 정의된 자식 키 목록 */
+    allowedParentsKeys: string[];
+    /** descriptionExtra 존재 여부 */
+    descriptionExtra: boolean;
+    /** aliasesExtra 항목 수 */
+    aliasesExtra: number;
+    /**
+     * 자기 카테고리 천장 대비 정규화 점수 (0.0 ~ 1.0).
+     * 1.0 = 컴포넌트 구조상 가능한 모든 보강 영역을 완료.
+     * compound 는 5 영역, non-compound 는 4 영역 (allowedChildren n/a 제외) 기준으로 정규화되어
+     * 컴포넌트 종류 무관하게 동일 척도로 비교 가능.
+     */
+    coverageScore: number;
+    /**
+     * 컴포넌트 구조상 적용 불가한 보강 영역 목록 (예: non-compound 는 ['allowedChildren']).
+     * 비어있으면 모든 영역이 적용 가능 (compound).
+     * coverageScore 분모에서 자동 제외되어 천장이 1.0 으로 통일된다.
+     */
+    notApplicable: string[];
+    /** coverageScore 한 줄 해석 — high/medium/low 와 강점 영역 요약 */
+    coverageNote: string;
+}
+export interface ListCompositionOverridesResult {
+    /** composition overrides 적용 컴포넌트 수 */
+    total: number;
+    /** 각 척도가 무엇을 의미하고 AI 의 UI 작성 정확도에 어떻게 영향을 주는지 (AI 가 본 응답을 바로 해석하도록 동봉) */
+    metrics: Record<string, string>;
+    /** coverageScore 산식 (가중치 명시) */
+    coverageScoreFormula: string;
+    /** 컴포넌트별 요약 row 배열 — coverageScore 내림차순, 동률은 컴포넌트 이름 알파벳 */
+    overrides: CompositionOverrideSummary[];
+}
+/** composition overrides map → 요약 결과 (순수 함수). coverageScore 내림차순 + 동률은 이름 알파벳. */
+export declare const buildCompositionOverridesSummary: (compositionOverrides: Record<string, CompositionEntry>, componentMap: Map<string, ComponentData>) => ListCompositionOverridesResult;
+/** server.ts 부팅 시 1회 호출 — 응답 사전 직렬화 */
+export declare const buildListCompositionOverridesResponse: (compositionOverrides: Record<string, CompositionEntry>, componentMap: Map<string, ComponentData>) => McpToolResponse;
+/** list_composition_overrides tool — 사전 직렬화된 응답을 그대로 반환 */
+export declare const listCompositionOverrides: (prebuilt: McpToolResponse) => McpToolResponse;