@ncds/ui-admin-mcp 1.0.0-alpha.10

package/bin/tools/renderToHtml.js

@@ -0,0 +1,267 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderToHtml = void 0;
+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', '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) => 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']);
+    return Object.fromEntries(Object.entries(userProps).filter(([key]) => allowedKeys.has(key)));
+};
+/** 아이콘 prop의 icon 문자열을 실제 React 컴포넌트로 resolve */
+const resolveIconProps = (props, iconBundle, propsSpec) => {
+    const resolved = { ...props };
+    for (const key of ICON_PROP_NAMES) {
+        const value = resolved[key];
+        const spec = propsSpec?.[key];
+        // bare function prop (FeaturedIcon 등) — 문자열 이름을 컴포넌트 함수로 직접 resolve
+        if (spec?.type === 'function' && typeof value === 'string') {
+            const iconComponent = iconBundle[value];
+            if (typeof iconComponent === 'function') {
+                resolved[key] = iconComponent;
+            }
+            continue;
+        }
+        // IconSlotType 래퍼 (Button leadingIcon 등) — 래퍼 내부 icon을 컴포넌트로 교체
+        if (!isIconSlot(value))
+            continue;
+        const iconComponent = iconBundle[value.icon];
+        if (typeof iconComponent === 'function') {
+            resolved[key] = { ...value, icon: iconComponent };
+        }
+    }
+    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;
+    // bare function icon prop (FeaturedIcon 등) — icon={SearchLg} 형태
+    if (ICON_PROP_NAMES.has(key) && spec?.type === 'function' && typeof value === 'string')
+        return `${key}={${value}}`;
+    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) => 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 ?? [];
+    const correction = spec.default !== undefined ? ` Corrected to default '${spec.default}'.` : ' Removed (no default).';
+    return `Invalid enum value '${value}' for prop '${key}'.${correction} 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]));
+    const missingArrays = Object.entries(propsSpec)
+        .filter(([key, spec]) => spec.rawType?.includes('[]') && !(key in userProps))
+        .map(([key]) => `Array prop '${key}' is missing. Filled with empty array []. Pass data for meaningful rendering.`);
+    return [...missingRequired, ...invalidEnums, ...missingArrays];
+};
+/** invalid enum 값을 default 또는 제거로 교정 — 할루시네이션 HTML 방지 */
+const correctInvalidEnums = (userProps, propsSpec) => {
+    const corrected = { ...userProps };
+    for (const [key, value] of Object.entries(corrected)) {
+        const spec = propsSpec[key];
+        if (spec?.type !== 'enum' || !spec.values || typeof value !== 'string')
+            continue;
+        if (spec.values.includes(value))
+            continue;
+        if (spec.default !== undefined) {
+            corrected[key] = spec.default;
+        }
+        else {
+            delete corrected[key];
+        }
+    }
+    return corrected;
+};
+/** required prop 누락 시 type별 safe default 주입 — React crash 방지 (fillMissingArrayProps 통합) */
+const correctMissingRequired = (userProps, propsSpec) => {
+    const corrected = { ...userProps };
+    for (const [key, spec] of Object.entries(propsSpec)) {
+        // array prop — required 여부와 무관하게 [] 주입 (.map() crash 방지)
+        if (spec.rawType?.includes('[]') && !(key in corrected && Array.isArray(corrected[key]))) {
+            corrected[key] = [];
+            continue;
+        }
+        // required가 아니거나 이미 값이 있으면 스킵
+        if (!spec.required || key in corrected)
+            continue;
+        // default가 있으면 사용
+        if (spec.default !== undefined) {
+            corrected[key] = spec.default;
+            continue;
+        }
+        // icon function prop (FeaturedIcon 등) — 빈 span 반환 스텁 주입하여 crash 방지
+        if (spec.type === 'function' && ICON_PROP_NAMES.has(key)) {
+            corrected[key] = () => null;
+            continue;
+        }
+        // 일반 function/ReactNode는 HTML에 영향 없으므로 주입하지 않음
+        if (spec.type === 'function' || spec.type === 'ReactNode')
+            continue;
+        // type별 safe default
+        const safeDefaults = {
+            string: '',
+            object: {},
+            boolean: false,
+            number: 0,
+            enum: spec.values?.[0] ?? '',
+        };
+        if (spec.type in safeDefaults) {
+            corrected[key] = safeDefaults[spec.type];
+        }
+    }
+    return corrected;
+};
+// ── 응답 조립 ──────────────────────────────────────────────────────
+/** 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;
+    const imports = [`import { ${exportName} } from '${importPath}';`];
+    const dependencies = [importPath];
+    const iconNames = extractIconNames(appliedProps);
+    if (iconNames.length > 0 && iconMeta) {
+        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}${attrsPrefix}>${String(children)}</${exportName}>`
+        : `<${exportName}${attrsPrefix} />`;
+    return { imports, jsx, cssImport: `import '${importPath}/style.css';`, dependencies };
+};
+/** dataVersion 객체를 생성 */
+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, iconBundle, cdnMeta, iconMeta, reactRuntime, jsApiMap, name, props } = params;
+    const normalized = (0, response_js_1.normalizeName)(name);
+    const componentData = componentMap.get(normalized);
+    if (!componentData)
+        return (0, response_js_1.componentNotFoundResponse)(normalized);
+    const exportName = componentData.exportName;
+    if (!exportName) {
+        return (0, response_js_1.errorResponse)('EXPORT_NAME_MISSING', `'${normalized}' 컴포넌트에 exportName이 없습니다.`, '데이터를 재추출해주세요 (yarn extract).');
+    }
+    const Component = bundle[exportName] ?? null;
+    if (!Component) {
+        return (0, response_js_1.errorResponse)('COMPONENT_NOT_IN_BUNDLE', `'${normalized}' (${exportName}) 컴포넌트가 번들에 없습니다.`, '번들을 재빌드해주세요 (yarn build:bundle).');
+    }
+    try {
+        const safeProps = removeBlockedProps(props ?? {});
+        const sanitized = componentData.props ? sanitizeProps(safeProps, componentData.props) : safeProps;
+        const enumWarnings = componentData.props ? validateProps(sanitized, componentData.props) : [];
+        const enumCorrected = componentData.props ? correctInvalidEnums(sanitized, componentData.props) : sanitized;
+        const corrected = componentData.props ? correctMissingRequired(enumCorrected, componentData.props) : enumCorrected;
+        const postWarnings = componentData.props ? validateProps(corrected, componentData.props) : [];
+        const warnings = [...enumWarnings, ...postWarnings.filter((w) => !enumWarnings.includes(w))];
+        const resolvedProps = resolveIconProps(corrected, iconBundle, componentData.props);
+        const rawHtml = reactRuntime.renderToStaticMarkup(reactRuntime.createElement(Component, resolvedProps));
+        const html = `<!-- ncua:${normalized} start -->\n${rawHtml}\n<!-- ncua:${normalized} end -->`;
+        const hasDefaults = componentData.props ? calcDefaultsUsed(componentData.props, corrected) : {};
+        return (0, response_js_1.successResponse)({
+            html,
+            component: normalized,
+            exportName,
+            importPath: componentData.importPath,
+            appliedProps: corrected,
+            ...(Object.keys(hasDefaults).length > 0 && { defaultsUsed: hasDefaults }),
+            ...(warnings.length > 0 && { warnings }),
+            js: buildJsField(componentData, jsApiMap),
+            cdn: cdnMeta ?? undefined,
+            dataVersion: buildDataVersion(cdnMeta, iconMeta),
+            react: buildReactOutput(componentData, corrected, iconMeta),
+        });
+    }
+    catch (err) {
+        // catch에서 warnings 재계산 (let 금지 규칙 준수 — validateProps는 순수 함수이므로 동일 결과 보장)
+        const catchWarnings = componentData.props ? validateProps(props ?? {}, componentData.props) : [];
+        const suggestion = componentData.usageExamples
+            ? 'get_component_props로 usageExamples를 확인하고 해당 props로 재시도하세요.'
+            : '사용 가능한 속성을 확인하려면 get_component_props를 사용하세요.';
+        return (0, response_js_1.errorResponse)('RENDER_FAILED', `'${normalized}' 렌더링 실패: ${(0, response_js_1.toErrorMessage)(err)}`, suggestion, catchWarnings.length > 0 ? catchWarnings : undefined);
+    }
+};
+exports.renderToHtml = renderToHtml;

package/bin/tools/searchComponent.d.ts

@@ -0,0 +1,4 @@
+import type { ComponentData } from '../types.js';
+import { type McpToolResponse } from '../utils/response.js';
+/** search_component tool — name/description/aliases 퍼지 검색 후 점수순 반환 */
+export declare const searchComponent: (componentMap: Map<string, ComponentData>, query: string) => McpToolResponse;

package/bin/tools/searchComponent.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.searchComponent = void 0;
+/**
+ * search_component tool — name/description/aliases 퍼지 키워드 검색 (순수 함수)
+ *
+ * Calculator: searchComponent — 입력(componentMap, query) → 출력(매칭 결과, 점수순 정렬)
+ */
+const dataLoader_js_1 = require("../utils/dataLoader.js");
+const response_js_1 = require("../utils/response.js");
+const fuzzyMatch_js_1 = require("../utils/fuzzyMatch.js");
+/** search_component tool — name/description/aliases 퍼지 검색 후 점수순 반환 */
+const searchComponent = (componentMap, query) => {
+    if (!query.trim())
+        return (0, response_js_1.successResponse)([]);
+    const scored = (0, dataLoader_js_1.getAllComponents)(componentMap)
+        .map((c) => {
+        // name, description, aliases 모두에 대해 퍼지 매칭 → 최고 점수 채택
+        const targets = [c.name, c.description, ...c.aliases];
+        const match = (0, fuzzyMatch_js_1.bestFuzzyMatch)(query, targets);
+        return { component: c, score: match?.score ?? 0 };
+    })
+        .filter((item) => item.score > 0)
+        .sort((a, b) => b.score - a.score);
+    const results = scored.map(({ component: { name, category, description, aliases } }) => ({
+        name,
+        category,
+        description,
+        aliases,
+    }));
+    return (0, response_js_1.successResponse)(results);
+};
+exports.searchComponent = searchComponent;

package/bin/tools/searchIcon.d.ts

@@ -0,0 +1,7 @@
+/**
+ * search_icon tool — 키워드로 아이콘 검색 (순수 함수)
+ */
+import type { IconData } from '../types.js';
+import { type McpToolResponse } from '../utils/response.js';
+/** search_icon tool — 키워드로 아이콘 이름/kebab을 검색 */
+export declare const searchIcon: (iconData: IconData, query: string) => McpToolResponse;

package/bin/tools/searchIcon.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.searchIcon = void 0;
+const response_js_1 = require("../utils/response.js");
+/** search_icon tool — 키워드로 아이콘 이름/kebab을 검색 */
+const searchIcon = (iconData, query) => {
+    const lower = query.trim().toLowerCase();
+    if (!lower)
+        return (0, response_js_1.successResponse)([]);
+    const results = iconData.icons
+        .filter((icon) => icon.name.toLowerCase().includes(lower) || icon.kebab.includes(lower))
+        .map((icon) => ({
+        name: icon.name,
+        kebab: icon.kebab,
+        fill: icon.fill,
+    }));
+    return (0, response_js_1.successResponse)(results);
+};
+exports.searchIcon = searchIcon;

package/bin/tools/validateHtml.d.ts

@@ -0,0 +1,18 @@
+import type { ComponentData, ComplianceRulesData, TokenData } from '../types.js';
+import type { CdnMeta } from '../utils/dataLoader.js';
+import { type McpToolResponse } from '../utils/response.js';
+export type { ValidationError } from '../utils/bemValidator.js';
+export { buildRootClassMap } from '../utils/bemValidator.js';
+export { buildTokenValueMap } from '../utils/tokenValidator.js';
+/** validate_html tool 파라미터 */
+export interface ValidateHtmlParams {
+    componentMap: Map<string, ComponentData>;
+    rootClassMap: Map<string, string>;
+    html: string;
+    cdnMeta?: CdnMeta | null;
+    tokenData?: TokenData | null;
+    complianceRules?: ComplianceRulesData | null;
+    tokenValueMap?: Map<string, string[]> | null;
+}
+/** validate_html tool — HTML의 NCUA BEM 클래스 정합성 + 디자인 시스템 준수도 검증 */
+export declare const validateHtml: (params: ValidateHtmlParams) => McpToolResponse;

package/bin/tools/validateHtml.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateHtml = exports.buildTokenValueMap = exports.buildRootClassMap = void 0;
+/**
+ * validate_html tool — NCUA HTML BEM 검증 + 디자인 시스템 준수도 검증 진입점
+ *
+ * BEM 검증: utils/bemValidator.ts
+ * Compliance 검증: utils/compliance.ts
+ * 이 파일은 오케스트레이션만 담당한다.
+ */
+const node_html_parser_1 = require("node-html-parser");
+const response_js_1 = require("../utils/response.js");
+const bemValidator_js_1 = require("../utils/bemValidator.js");
+const compliance_js_1 = require("../utils/compliance.js");
+var bemValidator_js_2 = require("../utils/bemValidator.js");
+Object.defineProperty(exports, "buildRootClassMap", { enumerable: true, get: function () { return bemValidator_js_2.buildRootClassMap; } });
+var tokenValidator_js_1 = require("../utils/tokenValidator.js");
+Object.defineProperty(exports, "buildTokenValueMap", { enumerable: true, get: function () { return tokenValidator_js_1.buildTokenValueMap; } });
+/** validate_html tool — HTML의 NCUA BEM 클래스 정합성 + 디자인 시스템 준수도 검증 */
+const validateHtml = (params) => {
+    const { componentMap, rootClassMap, html, cdnMeta, tokenData, complianceRules, tokenValueMap } = params;
+    const trimmed = html.trim();
+    if (trimmed.length === 0)
+        return (0, response_js_1.successResponse)({ valid: true });
+    const root = (0, node_html_parser_1.parse)(trimmed);
+    const elements = root.querySelectorAll('[class]');
+    const { errors, warnings, invalidClassesSet, hasNcuaClasses } = (0, bemValidator_js_1.collectBemErrors)({
+        elements,
+        rootClassMap,
+        componentMap,
+    });
+    if (!hasNcuaClasses)
+        return (0, response_js_1.successResponse)({ valid: true });
+    if (cdnMeta)
+        errors.push(...(0, bemValidator_js_1.checkCdnInclusion)(trimmed, cdnMeta));
+    const compliance = buildCompliance({
+        root,
+        componentMap,
+        rootClassMap,
+        warnings,
+        tokenData,
+        complianceRules,
+        tokenValueMap,
+    });
+    return buildResponse({ errors, warnings, invalidClassesSet, root, compliance });
+};
+exports.validateHtml = validateHtml;
+/** compliance 검증 오케스트레이션 — tokenData 또는 complianceRules가 있을 때만 실행 */
+const buildCompliance = (params) => {
+    const { root, componentMap, rootClassMap, warnings, tokenData, complianceRules, tokenValueMap } = params;
+    if (!complianceRules && !tokenData)
+        return undefined;
+    const ncuaResult = complianceRules
+        ? (0, compliance_js_1.detectNcuaOmission)({ root, complianceRules, componentMap })
+        : { errors: [], ncuaUsage: { used: 0, available: 0 } };
+    const tokenResult = tokenData && tokenValueMap
+        ? (0, compliance_js_1.detectTokenIssues)({ root, tokenData, tokenValueMap })
+        : { errors: [], tokenUsage: { correct: 0, missing: 0, invalid: 0 } };
+    const customResult = (0, compliance_js_1.detectCustomNotSeparated)({ root, rootClassMap, warnings });
+    return (0, compliance_js_1.buildComplianceSummary)({
+        ncuaErrors: ncuaResult.errors,
+        tokenErrors: tokenResult.errors,
+        customErrors: customResult.errors,
+        ncuaUsage: ncuaResult.ncuaUsage,
+        tokenUsage: tokenResult.tokenUsage,
+        customSeparation: customResult.customSeparation,
+    });
+};
+/** 최종 응답 빌드 */
+const buildResponse = (params) => {
+    const { errors, warnings, invalidClassesSet, root, compliance } = params;
+    if (errors.length === 0 && warnings.length === 0 && !compliance)
+        return (0, response_js_1.successResponse)({ valid: true });
+    if (errors.length === 0 && warnings.length === 0 && compliance)
+        return (0, response_js_1.successResponse)({ valid: true, compliance });
+    if (errors.length === 0)
+        return (0, response_js_1.successResponse)({ valid: true, warnings, ...(compliance && { compliance }) });
+    return (0, response_js_1.successResponse)({
+        valid: false,
+        errors,
+        ...(warnings.length > 0 && { warnings }),
+        fixed_html: (0, bemValidator_js_1.buildFixedHtml)(root, invalidClassesSet),
+        ...(compliance && { compliance }),
+    });
+};

package/bin/types.d.ts

@@ -0,0 +1,123 @@
+/**
+ * MCP 서버 공통 타입 정의
+ */
+export interface PropSpec {
+    type: 'string' | 'enum' | 'boolean' | 'number' | 'ReactNode' | 'function' | 'object';
+    required: boolean;
+    default?: unknown;
+    values?: string[];
+    rawType?: string;
+    properties?: Record<string, PropSpec>;
+}
+export interface ComponentUsage {
+    import: string;
+    react: Record<string, string>;
+}
+export interface ComponentData {
+    name: string;
+    exportName: string;
+    importPath: string;
+    jsRequired: boolean;
+    category: string;
+    description: string;
+    aliases: string[];
+    hasChildren: boolean;
+    whenToUse: string[];
+    forbiddenRules: string[];
+    seeAlso: string[];
+    /** Props가 확장하는 HTML 요소 — 에이전트가 표준 HTML 속성 사용 가능 여부를 판단 */
+    htmlElement?: string;
+    /** render_to_html에 전달할 실제 사용 예시 props — meta.ts에서 추출 */
+    usageExamples?: Record<string, Record<string, unknown>>;
+    props: Record<string, PropSpec>;
+    html?: Record<string, string>;
+    bemClasses: string[];
+    usage: ComponentUsage;
+}
+export interface IconEntry {
+    name: string;
+    kebab: string;
+    fill: boolean;
+}
+export interface IconData {
+    totalCount: number;
+    fillCount: number;
+    icons: IconEntry[];
+}
+/** server.ts에서 주입하는 React 런타임 의존성 */
+export interface ReactRuntime {
+    createElement: (type: unknown, props?: Record<string, unknown>) => unknown;
+    renderToStaticMarkup: (element: unknown) => string;
+}
+export interface Capability {
+    tool: string;
+    description: string;
+    available: boolean;
+}
+export type McpErrorCode = 'COMPONENT_NOT_FOUND' | 'EXPORT_NAME_MISSING' | 'COMPONENT_NOT_IN_BUNDLE' | 'RENDER_FAILED' | 'INVALID_TOKEN_CATEGORY' | 'ICON_NOT_FOUND' | 'INVALID_PARAMS' | 'INTERNAL_ERROR';
+export interface TokenEntry {
+    name: string;
+    value: string;
+    description: string;
+}
+export interface TokenGroup {
+    name: string;
+    category: string;
+    description: string;
+    tokens: TokenEntry[];
+}
+export interface TokenData {
+    totalCount: number;
+    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[];
+}
+export interface ComplianceRuleMatch {
+    tag: string;
+    hints?: ComplianceRuleHint[];
+}
+export interface ComplianceRule {
+    match: ComplianceRuleMatch;
+    ncuaComponent: string;
+    confidence: 'high' | 'medium';
+}
+export interface ComplianceRulesData {
+    patterns: ComplianceRule[];
+}
+export interface ComplianceError {
+    type: 'ncua_not_used' | 'token_not_used' | 'invalid_token' | 'custom_not_separated';
+    severity?: 'warning';
+    target: string;
+    component: string;
+    message: string;
+    suggestion: string;
+}
+export interface ComplianceSummary {
+    score: number;
+    errors: ComplianceError[];
+    ncuaUsage: {
+        used: number;
+        available: number;
+    };
+    tokenUsage: {
+        correct: number;
+        missing: number;
+        invalid: number;
+    };
+    customSeparation: {
+        clean: number;
+        violated: number;
+    };
+    totalViolations: number;
+}

package/bin/types.js

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * MCP 서버 공통 타입 정의
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/bin/utils/bemValidator.d.ts

@@ -0,0 +1,36 @@
+/**
+ * BEM 클래스 검증 순수 함수 — NCUA HTML의 BEM 클래스 정합성 검증 + CDN 링크 검증
+ *
+ * validateHtml.ts에서 분리. 모든 함수는 순수 함수(Calculation).
+ */
+import type { parse } from 'node-html-parser';
+import type { ComponentData } from '../types.js';
+import type { CdnMeta } from './dataLoader.js';
+export interface ValidationError {
+    type: 'invalid_modifier' | 'invalid_element' | 'unknown_component' | 'missing_root_class' | 'mixed_namespace' | 'missing_cdn';
+    class: string;
+    component: string;
+    message: string;
+    suggestion: string;
+}
+/** 엘리먼트에서 class 목록을 파싱 */
+export declare const getClassList: (el: {
+    getAttribute: (name: string) => string | undefined;
+}) => string[];
+/** root class → component name 매핑 빌드 — server.ts에서 1회 호출 */
+export declare const buildRootClassMap: (componentMap: Map<string, ComponentData>) => Map<string, string>;
+/** 엘리먼트별 BEM 클래스 검증 → errors + warnings + invalidClasses 수집 */
+export declare const collectBemErrors: (params: {
+    elements: ReturnType<ReturnType<typeof parse>['querySelectorAll']>;
+    rootClassMap: Map<string, string>;
+    componentMap: Map<string, ComponentData>;
+}) => {
+    errors: ValidationError[];
+    warnings: ValidationError[];
+    invalidClassesSet: Set<string>;
+    hasNcuaClasses: boolean;
+};
+/** 잘못된 클래스를 제거하여 fixed_html 생성 */
+export declare const buildFixedHtml: (root: ReturnType<typeof parse>, invalidClassesSet: Set<string>) => string;
+/** CDN CSS/JS 링크 포함 여부 검증 */
+export declare const checkCdnInclusion: (html: string, cdnMeta: CdnMeta) => ValidationError[];