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

package/bin/tools/listIcons.d.ts

@@ -0,0 +1,22 @@
+/**
+ * list_icons tool — 사전 계산된 아이콘 요약 반환 (순수 함수)
+ *
+ * 아이콘 이름을 전부 반환하면 토큰 낭비이므로,
+ * 요약 정보만 반환하고 search_icon으로 검색을 유도한다.
+ */
+import type { IconData } from '../types.js';
+import { type McpToolResponse } from '../utils/response.js';
+/** 아이콘 요약 데이터 타입 */
+export interface IconSummary {
+    totalCount: number;
+    fillCount: number;
+    uniqueIcons: number;
+    hint: string;
+    sample: string[];
+}
+/** iconData에서 요약을 사전 계산 — server.ts에서 1회 호출 */
+export declare const buildIconSummary: (iconData: IconData) => IconSummary;
+/** IconSummary를 사전 직렬화 — server.ts에서 1회 호출 */
+export declare const buildListIconsResponse: (summary: IconSummary) => McpToolResponse;
+/** list_icons tool — 사전 직렬화된 응답을 그대로 반환 */
+export declare const listIcons: (prebuilt: McpToolResponse) => McpToolResponse;

package/bin/tools/listIcons.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listIcons = exports.buildListIconsResponse = exports.buildIconSummary = void 0;
+const response_js_1 = require("../utils/response.js");
+const ICON_SAMPLE_SIZE = 20;
+/** iconData에서 요약을 사전 계산 — server.ts에서 1회 호출 */
+const buildIconSummary = (iconData) => {
+    const prefixes = new Set(iconData.icons.map((i) => i.name.replace(/Fill$/, '')));
+    return {
+        totalCount: iconData.totalCount,
+        fillCount: iconData.fillCount,
+        uniqueIcons: prefixes.size,
+        hint: '아이콘이 많으므로 search_icon tool로 키워드 검색을 권장합니다. 예: search_icon("arrow"), search_icon("check")',
+        sample: iconData.icons.slice(0, ICON_SAMPLE_SIZE).map((i) => i.name),
+    };
+};
+exports.buildIconSummary = buildIconSummary;
+/** IconSummary를 사전 직렬화 — server.ts에서 1회 호출 */
+const buildListIconsResponse = (summary) => (0, response_js_1.successResponse)(summary);
+exports.buildListIconsResponse = buildListIconsResponse;
+/** list_icons tool — 사전 직렬화된 응답을 그대로 반환 */
+const listIcons = (prebuilt) => prebuilt;
+exports.listIcons = listIcons;

package/bin/tools/ping.d.ts

@@ -0,0 +1,17 @@
+/**
+ * ping tool — NCUA MCP 서버 health check + capabilities/rules 제공 (순수 함수)
+ */
+import type { ComponentData, Capability } from '../types.js';
+import type { CdnMeta, IconMeta } from '../utils/dataLoader.js';
+import { type McpToolResponse } from '../utils/response.js';
+/** ping tool 파라미터 — server.ts에서 모든 데이터를 소유하고 전달한다 */
+export interface PingParams {
+    componentMap: Map<string, ComponentData>;
+    cdnMeta: CdnMeta | null;
+    iconMeta: IconMeta | null;
+    version: string;
+    rules: string[];
+    capabilities: Capability[];
+}
+/** ping tool — 서버 상태, capabilities, rules를 반환 */
+export declare const ping: (params: PingParams) => McpToolResponse;

package/bin/tools/ping.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ping = void 0;
+const response_js_1 = require("../utils/response.js");
+/** ping tool — 서버 상태, capabilities, rules를 반환 */
+const ping = (params) => {
+    const { componentMap, cdnMeta, iconMeta, version, rules, capabilities } = params;
+    return (0, response_js_1.successResponse)({
+        status: 'ok',
+        name: 'ncds-ui-admin',
+        description: 'NCDS UI Admin component library',
+        version,
+        componentCount: componentMap.size,
+        cdn: cdnMeta ?? undefined,
+        icon: iconMeta ?? undefined,
+        capabilities,
+        rules,
+    });
+};
+exports.ping = ping;

package/bin/tools/renderToHtml.d.ts

@@ -0,0 +1,21 @@
+/**
+ * render_to_html tool — 컴포넌트 속성을 전달하면 정확한 HTML + React 매핑을 반환 (순수 함수)
+ *
+ * DOM 환경과 React/ReactDOM은 server.ts에서 초기화하고 파라미터로 전달한다.
+ * 이 파일에는 fs, path, require, let이 없다.
+ */
+import type { ComponentData, ReactRuntime } 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>;
+    cdnMeta: CdnMeta | null;
+    iconMeta: IconMeta | null;
+    reactRuntime: ReactRuntime;
+    name: string;
+    props?: Record<string, unknown>;
+}
+/** render_to_html tool — props로 React 컴포넌트를 렌더링하여 HTML + React 매핑 반환 */
+export declare const renderToHtml: (params: RenderToHtmlParams) => McpToolResponse;

package/bin/tools/renderToHtml.js

@@ -0,0 +1,177 @@
+"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']);
+// ── 순수 함수 (헬퍼) ──────────────────────────────────────────────
+/** 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;
+};
+/** 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;
+};
+/** 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;
+};
+/** 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')
+            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)}}`);
+        }
+    }
+    return attrs.join(' ');
+};
+/** 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;
+};
+/** 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) {
+        const iconImport = `import { ${iconNames.join(', ')} } from '${iconMeta.packageName}';`;
+        imports.push(iconImport);
+        if (!dependencies.includes(iconMeta.packageName)) {
+            dependencies.push(iconMeta.packageName);
+        }
+    }
+    const attrsStr = propsSpec ? propsToJsxAttrs(appliedProps, propsSpec) : '';
+    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,
+    };
+};
+/** dataVersion 객체를 생성 */
+const buildDataVersion = (cdnMeta, iconMeta) => {
+    const versions = {};
+    if (cdnMeta)
+        versions['@ncds/ui-admin'] = cdnMeta.version;
+    if (iconMeta)
+        versions[iconMeta.packageName] = iconMeta.version;
+    return versions;
+};
+// ── 진입점 ────────────────────────────────────────────────────────
+/** render_to_html tool — props로 React 컴포넌트를 렌더링하여 HTML + React 매핑 반환 */
+const renderToHtml = (params) => {
+    const { componentMap, bundle, cdnMeta, iconMeta, reactRuntime, 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 = findComponent(bundle, exportName);
+    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 html = `<!-- ncua:${normalized} -->\n${rawHtml}\n<!-- /ncua:${normalized} -->`;
+        const defaultsUsed = componentData.props ? calcDefaultsUsed(componentData.props, userProps) : {};
+        const react = buildReactOutput(componentData, userProps, iconMeta);
+        const dataVersion = buildDataVersion(cdnMeta, iconMeta);
+        return (0, response_js_1.successResponse)({
+            html,
+            component: normalized,
+            exportName,
+            importPath: componentData.importPath,
+            appliedProps: userProps,
+            ...(Object.keys(defaultsUsed).length > 0 && { defaultsUsed }),
+            js: componentData.jsRequired
+                ? { required: true, description: '이 컴포넌트는 인터랙션을 위해 CDN JS가 필요합니다' }
+                : { required: false },
+            cdn: cdnMeta ?? undefined,
+            dataVersion,
+            react,
+        });
+    }
+    catch (err) {
+        return (0, response_js_1.errorResponse)('RENDER_FAILED', `'${normalized}' 렌더링 실패: ${(0, response_js_1.toErrorMessage)(err)}`, '사용 가능한 속성을 확인하려면 get_component_props를 사용하세요.');
+    }
+};
+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,111 @@
+/**
+ * MCP 서버 공통 타입 정의
+ */
+export interface PropSpec {
+    type: 'string' | 'enum' | 'boolean' | 'number' | 'ReactNode' | 'function' | 'object';
+    required: boolean;
+    default?: unknown;
+    values?: string[];
+    rawType?: string;
+}
+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;
+    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;
+}
+export type McpErrorCode = 'COMPONENT_NOT_FOUND' | 'EXPORT_NAME_MISSING' | 'COMPONENT_NOT_IN_BUNDLE' | 'RENDER_FAILED' | 'INVALID_TOKEN_CATEGORY';
+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 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[];