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

package/bin/server.d.ts

@@ -0,0 +1 @@
+export {};

package/bin/server.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * MCP 서버 진입점 — componentMap 소유, tool 등록, transport 연결
+ */
+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");
+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 getComponentHtml_js_1 = require("./tools/getComponentHtml.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 version_js_1 = require("./version.js");
+const server = new mcp_js_1.McpServer({
+    name: 'ncds-ui-admin',
+    version: version_js_1.VERSION,
+});
+const main = async () => {
+    // server.ts가 componentMap 소유 — tool 핸들러에 파라미터로 전달
+    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);
+    server.registerTool('ping', {
+        description: 'NCUA MCP 서버 연결 확인 + 버전 + capabilities/rules 조회',
+    }, () => (0, ping_js_1.ping)(componentMap, cdnMeta, version_js_1.VERSION));
+    server.registerTool('list_components', {
+        description: '사용 가능한 전체 UI 컴포넌트 목록을 가져옵니다.',
+    }, () => (0, listComponents_js_1.listComponents)(componentMap));
+    server.registerTool('search_component', {
+        description: '이름이나 설명으로 UI 컴포넌트를 찾습니다.',
+        inputSchema: { query: zod_1.z.string().describe('검색 키워드 (대소문자 무관)') },
+    }, ({ query }) => (0, searchComponent_js_1.searchComponent)(componentMap, query));
+    server.registerTool('get_component_html', {
+        description: '컴포넌트의 HTML 마크업 예시를 가져옵니다. variant를 지정하면 해당 옵션이 적용된 HTML을 반환합니다.',
+        inputSchema: {
+            name: zod_1.z.string().min(1).describe('컴포넌트명 (예: "button", "badge")'),
+            variant: zod_1.z
+                .record(zod_1.z.string(), zod_1.z.string())
+                .optional()
+                .describe('옵션 조합 (예: { hierarchy: "primary", size: "md" })'),
+        },
+    }, ({ name, variant }) => (0, getComponentHtml_js_1.getComponentHtml)(componentMap, name, variant));
+    server.registerTool('get_component_props', {
+        description: '컴포넌트에서 사용할 수 있는 옵션(속성) 목록을 가져옵니다.',
+        inputSchema: { name: zod_1.z.string().min(1).describe('컴포넌트명 (예: "button", "badge")') },
+    }, ({ name }) => (0, getComponentProps_js_1.getComponentProps)(componentMap, name));
+    server.registerTool('validate_html', {
+        description: 'HTML 마크업에 사용된 컴포넌트 클래스가 유효한지 검증합니다. 잘못된 클래스 사용 시 오류 위치와 자동 수정본을 반환합니다.',
+        inputSchema: {
+            html: zod_1.z
+                .string()
+                .min(1)
+                .describe('검증할 HTML 마크업 (예: \'<button class="ncua-btn ncua-btn--primary"></button>\')'),
+        },
+    }, ({ html }) => (0, validateHtml_js_1.validateHtml)(componentMap, html));
+    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})`);
+};
+main().catch((err) => {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`[ERROR] 서버 시작 실패: ${message}\n`);
+    process.exit(1);
+});

package/bin/server.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * NCUA MCP Server Entry Point
+ *
+ * @ncds/ui-admin-mcp 패키지의 진입점.
+ * npx @ncds/ui-admin-mcp 으로 실행됩니다.
+ */
+import './server.js';

package/bin/tools/getComponentHtml.d.ts

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

package/bin/tools/getComponentHtml.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getComponentHtml = void 0;
+/**
+ * get_component_html tool — 컴포넌트 HTML 스니펫 반환 (순수 함수)
+ */
+const dataLoader_js_1 = require("../utils/dataLoader.js");
+const response_js_1 = require("../utils/response.js");
+/** default HTML에서 태그명 추출 */
+const extractTag = (defaultHtml) => {
+    const match = defaultHtml.match(/^<(\w+)/);
+    return match ? match[1] : 'div';
+};
+const getComponentHtml = (componentMap, name, variant) => {
+    const normalized = (0, response_js_1.normalizeName)(name);
+    const component = (0, dataLoader_js_1.getComponent)(componentMap, normalized);
+    if (!component)
+        return (0, response_js_1.componentNotFoundResponse)(normalized);
+    if (!variant || Object.keys(variant).length === 0) {
+        return (0, response_js_1.successResponse)(component.html);
+    }
+    const rootClass = component.bemClasses.find((c) => !c.includes('--') && !c.includes('__')) ?? `ncua-${normalized}`;
+    const tag = extractTag(component.html.default);
+    const modifiers = Object.values(variant).map((v) => `${rootClass}--${v}`);
+    const classes = [rootClass, ...modifiers].join(' ');
+    const isVoid = /^<\w+\s[^>]*\/>$/.test(component.html.default);
+    const html = isVoid ? `<${tag} class="${classes}" />` : `<${tag} class="${classes}"></${tag}>`;
+    return (0, response_js_1.successResponse)({ variant, html });
+};
+exports.getComponentHtml = getComponentHtml;

package/bin/tools/getComponentProps.d.ts

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

package/bin/tools/getComponentProps.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getComponentProps = void 0;
+/**
+ * get_component_props tool — 컴포넌트 props 스펙 반환 (순수 함수)
+ */
+const dataLoader_js_1 = require("../utils/dataLoader.js");
+const response_js_1 = require("../utils/response.js");
+const getComponentProps = (componentMap, name) => {
+    const normalized = (0, response_js_1.normalizeName)(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);
+};
+exports.getComponentProps = getComponentProps;

package/bin/tools/listComponents.d.ts

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

package/bin/tools/listComponents.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listComponents = void 0;
+/**
+ * list_components tool — 전체 컴포넌트 이름 목록 반환 (순수 함수)
+ */
+const dataLoader_js_1 = require("../utils/dataLoader.js");
+const response_js_1 = require("../utils/response.js");
+const listComponents = (componentMap) => {
+    const names = (0, dataLoader_js_1.getAllComponents)(componentMap)
+        .map((c) => c.name)
+        .sort();
+    return (0, response_js_1.successResponse)(names);
+};
+exports.listComponents = listComponents;

package/bin/tools/ping.d.ts

@@ -0,0 +1,11 @@
+/**
+ * ping tool — NCUA MCP 서버 health check + capabilities/rules 제공 (순수 함수)
+ */
+import type { ComponentData } from '../types.js';
+import type { CdnMeta } from '../utils/dataLoader.js';
+import { type McpToolResponse } from '../utils/response.js';
+export interface Capability {
+    tool: string;
+    description: string;
+}
+export declare const ping: (componentMap: Map<string, ComponentData>, cdnMeta: CdnMeta | null, version: string) => McpToolResponse;

package/bin/tools/ping.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ping = void 0;
+const response_js_1 = require("../utils/response.js");
+const CAPABILITIES = [
+    { tool: 'ping', description: '서버 연결 확인 + 버전 + capabilities/rules 조회' },
+    { tool: 'list_components', description: '전체 컴포넌트 목록 조회' },
+    { tool: 'search_component', description: '키워드로 컴포넌트 검색' },
+    { tool: 'get_component_html', description: '컴포넌트 HTML 마크업 조회 (variant 지원)' },
+    { tool: 'get_component_props', description: '컴포넌트 Props 스펙 조회' },
+    { tool: 'validate_html', description: 'HTML BEM 클래스 유효성 검증 + 자동 수정' },
+];
+const RULES = [
+    '이 라이브러리의 컴포넌트를 사용할 때는 CDN CSS/JS를 포함하세요',
+    'HTML 스니펫은 get_component_html에서 받은 구조를 그대로 사용하세요',
+    '커스텀 CSS로 ncua- 클래스를 재정의하지 마세요',
+];
+const ping = (componentMap, cdnMeta, version) => {
+    return (0, response_js_1.successResponse)({
+        status: 'ok',
+        name: 'ncds-ui-admin',
+        description: 'NCDS UI Admin 컴포넌트 라이브러리',
+        version,
+        componentCount: componentMap.size,
+        cdn: cdnMeta ?? undefined,
+        capabilities: CAPABILITIES,
+        rules: RULES,
+    });
+};
+exports.ping = ping;

package/bin/tools/searchComponent.d.ts

@@ -0,0 +1,3 @@
+import type { ComponentData } from '../types.js';
+import { type McpToolResponse } from '../utils/response.js';
+export declare const searchComponent: (componentMap: Map<string, ComponentData>, query: string) => McpToolResponse;

package/bin/tools/searchComponent.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.searchComponent = void 0;
+/**
+ * search_component tool — name/description/aliases 키워드 검색 (순수 함수)
+ */
+const dataLoader_js_1 = require("../utils/dataLoader.js");
+const response_js_1 = require("../utils/response.js");
+const searchComponent = (componentMap, query) => {
+    const lower = (0, response_js_1.normalizeName)(query);
+    if (!lower)
+        return (0, response_js_1.successResponse)([]);
+    const results = (0, dataLoader_js_1.getAllComponents)(componentMap)
+        .filter((c) => c.name.toLowerCase().includes(lower) ||
+        c.description.toLowerCase().includes(lower) ||
+        c.aliases.some((a) => a.toLowerCase().includes(lower)))
+        .map(({ name, description, aliases }) => ({ name, description, aliases }));
+    return (0, response_js_1.successResponse)(results);
+};
+exports.searchComponent = searchComponent;

package/bin/tools/validateHtml.d.ts

@@ -0,0 +1,10 @@
+import type { ComponentData } from '../types.js';
+import { type McpToolResponse } from '../utils/response.js';
+export interface ValidationError {
+    type: 'invalid_modifier' | 'invalid_element' | 'unknown_component';
+    class: string;
+    component: string;
+    message: string;
+    suggestion: string;
+}
+export declare const validateHtml: (componentMap: Map<string, ComponentData>, html: string) => McpToolResponse;

package/bin/tools/validateHtml.js

@@ -0,0 +1,142 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateHtml = void 0;
+/**
+ * validate_html tool — NCUA HTML 마크업 검증 (순수 함수)
+ */
+const node_html_parser_1 = require("node-html-parser");
+const response_js_1 = require("../utils/response.js");
+// ── 순수 함수 (헬퍼) ──────────────────────────────────────────────────────
+/** root class → component name 매핑 빌드 */
+const buildRootClassMap = (componentMap) => {
+    const rootClassMap = new Map();
+    for (const [name, data] of componentMap) {
+        for (const cls of data.bemClasses) {
+            if (!cls.includes('--') && !cls.includes('__')) {
+                rootClassMap.set(cls, name);
+            }
+        }
+    }
+    return rootClassMap;
+};
+/** ncua- 클래스에서 root class를 결정 (modifier/element 제외, 가장 짧은 것) */
+const findRootClass = (ncuaClasses) => {
+    const roots = ncuaClasses.filter((c) => !c.includes('--') && !c.includes('__'));
+    if (roots.length === 0)
+        return undefined;
+    return roots.sort((a, b) => a.length - b.length)[0];
+};
+/** modifier/element 클래스에서 root class를 추론 (예: ncua-btn--primary → ncua-btn) */
+const inferRootClass = (ncuaClasses, rootClassMap) => {
+    for (const cls of ncuaClasses) {
+        const dashIdx = cls.indexOf('--');
+        const underIdx = cls.indexOf('__');
+        const sepIdx = dashIdx >= 0 && underIdx >= 0 ? Math.min(dashIdx, underIdx) : dashIdx >= 0 ? dashIdx : underIdx;
+        if (sepIdx > 0) {
+            const candidate = cls.substring(0, sepIdx);
+            if (rootClassMap.has(candidate))
+                return candidate;
+        }
+    }
+    return undefined;
+};
+/** 문자열 유사도 — 공통 접두사 길이 기반 */
+const similarity = (a, b) => {
+    let i = 0;
+    while (i < a.length && i < b.length && a[i] === b[i])
+        i++;
+    return i;
+};
+/** 유사도 상위 N개 제안 — modifier 오류면 modifier만, element 오류면 element만 */
+const suggestSimilar = (invalidClass, validClasses, max = 3) => {
+    const isElement = invalidClass.includes('__');
+    return validClasses
+        .filter((c) => (isElement ? c.includes('__') : c.includes('--')))
+        .map((c) => ({ class: c, score: similarity(invalidClass, c) }))
+        .sort((a, b) => b.score - a.score)
+        .slice(0, max)
+        .map((item) => item.class);
+};
+// ── 순수 함수 (검증 로직) ──────────────────────────────────────────────────
+/** HTML에서 ncua- 클래스 포함 여부 확인 */
+const hasNcuaClasses = (elements) => elements.some((el) => {
+    const classes = el.getAttribute('class')?.split(/\s+/) ?? [];
+    return classes.some((c) => c.startsWith('ncua-'));
+});
+/** 엘리먼트별 BEM 클래스 검증 → errors + invalidClasses 수집 */
+const collectErrors = (elements, rootClassMap, componentMap) => {
+    const errors = [];
+    const invalidClassesSet = new Set();
+    for (const el of elements) {
+        const classes = el.getAttribute('class')?.split(/\s+/) ?? [];
+        const ncuaClasses = classes.filter((c) => c.startsWith('ncua-'));
+        if (ncuaClasses.length === 0)
+            continue;
+        let rootClass = findRootClass(ncuaClasses);
+        if (!rootClass || !rootClassMap.has(rootClass)) {
+            const inferred = inferRootClass(ncuaClasses, rootClassMap);
+            if (inferred)
+                rootClass = inferred;
+        }
+        if (!rootClass || !rootClassMap.has(rootClass)) {
+            for (const cls of ncuaClasses) {
+                errors.push({
+                    type: 'unknown_component',
+                    class: cls,
+                    component: 'unknown',
+                    message: `Unknown component class '${cls}'. No matching component found.`,
+                    suggestion: 'Use list_components to see all available components.',
+                });
+                invalidClassesSet.add(cls);
+            }
+            continue;
+        }
+        const componentName = rootClassMap.get(rootClass);
+        const component = componentMap.get(componentName);
+        const validSet = new Set(component.bemClasses);
+        for (const cls of ncuaClasses) {
+            if (!validSet.has(cls)) {
+                const similar = suggestSimilar(cls, component.bemClasses);
+                errors.push({
+                    type: cls.includes('__') ? 'invalid_element' : 'invalid_modifier',
+                    class: cls,
+                    component: componentName,
+                    message: `Invalid BEM class '${cls}' for component '${componentName}'.`,
+                    suggestion: similar.length > 0 ? `Similar: ${similar.join(', ')}` : 'Use get_component_html to see valid classes.',
+                });
+                invalidClassesSet.add(cls);
+            }
+        }
+    }
+    return { errors, invalidClassesSet };
+};
+/** 잘못된 클래스를 제거하여 fixed_html 생성 */
+const buildFixedHtml = (root, invalidClassesSet) => {
+    for (const el of root.querySelectorAll('[class]')) {
+        const classes = el.getAttribute('class')?.split(/\s+/) ?? [];
+        const filtered = classes.filter((c) => !invalidClassesSet.has(c));
+        if (filtered.length > 0) {
+            el.setAttribute('class', filtered.join(' '));
+        }
+        else {
+            el.removeAttribute('class');
+        }
+    }
+    return root.toString();
+};
+// ── 진입점 ────────────────────────────────────────────────────────────────
+const validateHtml = (componentMap, html) => {
+    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]');
+    if (!hasNcuaClasses(elements))
+        return (0, response_js_1.successResponse)({ valid: true });
+    const rootClassMap = buildRootClassMap(componentMap);
+    const { errors, invalidClassesSet } = collectErrors(elements, rootClassMap, componentMap);
+    if (errors.length === 0)
+        return (0, response_js_1.successResponse)({ valid: true });
+    return (0, response_js_1.successResponse)({ valid: false, errors, fixed_html: buildFixedHtml(root, invalidClassesSet) });
+};
+exports.validateHtml = validateHtml;

package/bin/types.d.ts

@@ -0,0 +1,28 @@
+/**
+ * MCP 서버 공통 타입 정의
+ */
+export interface PropSpec {
+    type: 'string' | 'enum' | 'boolean' | 'number' | 'ReactNode';
+    required: boolean;
+    default?: unknown;
+    values?: string[];
+}
+export interface ComponentUsage {
+    import: string;
+    react: Record<string, string>;
+}
+export interface ComponentData {
+    name: string;
+    description: string;
+    aliases: string[];
+    props: Record<string, PropSpec>;
+    html: Record<string, string>;
+    bemClasses: string[];
+    usage: ComponentUsage;
+}
+export type McpErrorCode = 'COMPONENT_NOT_FOUND' | 'INVALID_PROP' | 'INVALID_HTML' | 'MISSING_REQUIRED_PROP' | 'DATA_LOAD_ERROR';
+export interface McpErrorResponse {
+    code: McpErrorCode;
+    message: string;
+    suggestion?: string;
+}

package/bin/types.js

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

package/bin/utils/dataLoader.d.ts

@@ -0,0 +1,11 @@
+import type { ComponentData } from '../types.js';
+export declare const DEFAULT_DATA_DIR: string;
+export declare const loadComponentsFromDir: (dataDir: string) => Map<string, ComponentData>;
+export declare const getComponent: (map: Map<string, ComponentData>, name: string) => ComponentData | undefined;
+export declare const getAllComponents: (map: Map<string, ComponentData>) => ComponentData[];
+export interface CdnMeta {
+    version: string;
+    css: string;
+    js: string;
+}
+export declare const loadCdnMeta: (dataDir: string) => CdnMeta | null;

package/bin/utils/dataLoader.js

@@ -0,0 +1,68 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadCdnMeta = exports.getAllComponents = exports.getComponent = exports.loadComponentsFromDir = exports.DEFAULT_DATA_DIR = void 0;
+/**
+ * dataLoader — mcp/data/*.json 파일을 읽어 Map으로 반환
+ *
+ * 함수 분류:
+ *   loadComponentsFromDir  → 부수효과 (fs I/O, logger, process.exit)
+ *   getComponent           → 순수 함수 (Map 조회, 외부 상태 없음)
+ *   getAllComponents        → 순수 함수 (Map 전체 반환, 외부 상태 없음)
+ *
+ * Map 소유권은 server.ts가 가진다. 이 파일은 상태를 보유하지 않는다.
+ */
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const logger_js_1 = require("./logger.js");
+exports.DEFAULT_DATA_DIR = path_1.default.resolve(__dirname, '../../data');
+// ── 부수효과 함수 (fs I/O) ────────────────────────────────────────────────
+const loadComponentsFromDir = (dataDir) => {
+    if (!fs_1.default.existsSync(dataDir)) {
+        logger_js_1.logger.error(`mcp/data/ 디렉토리가 없습니다: ${dataDir}`);
+        process.exit(1);
+    }
+    const jsonFiles = fs_1.default.readdirSync(dataDir).filter((f) => f.endsWith('.json') && !f.startsWith('_'));
+    if (jsonFiles.length === 0) {
+        logger_js_1.logger.error(`mcp/data/ 디렉토리에 JSON 파일이 없습니다: ${dataDir}`);
+        process.exit(1);
+    }
+    const map = new Map();
+    for (const file of jsonFiles) {
+        const filePath = path_1.default.join(dataDir, file);
+        try {
+            const raw = fs_1.default.readFileSync(filePath, 'utf-8');
+            const component = JSON.parse(raw);
+            map.set(component.name, component);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            logger_js_1.logger.error(`JSON 파싱 실패 (${file}): ${message}`);
+            process.exit(1);
+        }
+    }
+    logger_js_1.logger.info(`컴포넌트 ${map.size}개 로딩 완료`);
+    return map;
+};
+exports.loadComponentsFromDir = loadComponentsFromDir;
+// ── 순수 함수 (외부 상태 없음, Map을 파라미터로 받음) ──────────────────────
+const getComponent = (map, name) => map.get(name);
+exports.getComponent = getComponent;
+const getAllComponents = (map) => Array.from(map.values());
+exports.getAllComponents = getAllComponents;
+const loadCdnMeta = (dataDir) => {
+    const metaPath = path_1.default.join(dataDir, '_meta.json');
+    if (!fs_1.default.existsSync(metaPath))
+        return null;
+    try {
+        const raw = fs_1.default.readFileSync(metaPath, 'utf-8');
+        const meta = JSON.parse(raw);
+        return meta.cdn ?? null;
+    }
+    catch {
+        return null;
+    }
+};
+exports.loadCdnMeta = loadCdnMeta;

package/bin/utils/logger.d.ts

@@ -0,0 +1,18 @@
+/**
+ * stderr 전용 logger 유틸리티 — 부수효과 함수 (stderr I/O)
+ *
+ * ⚠️ console.log / console.warn / console.error 직접 사용 금지
+ *
+ * MCP stdio 프로토콜은 채널 역할이 엄격히 분리됩니다.
+ *   stdin  → 클라이언트 → 서버 요청(JSON-RPC)
+ *   stdout → 서버 → 클라이언트 응답(JSON-RPC) ← 프로토콜 전용 채널
+ *   stderr → 로그 전용 (프로토콜 밖)
+ *
+ * console.log는 stdout에 출력되어 JSON-RPC 스트림을 오염시킵니다.
+ * 모든 로깅은 반드시 이 logger를 통해 stderr로 출력해야 합니다.
+ */
+export declare const logger: {
+    info: (msg: string) => void;
+    warn: (msg: string) => void;
+    error: (msg: string) => void;
+};

package/bin/utils/logger.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logger = void 0;
+/**
+ * stderr 전용 logger 유틸리티 — 부수효과 함수 (stderr I/O)
+ *
+ * ⚠️ console.log / console.warn / console.error 직접 사용 금지
+ *
+ * MCP stdio 프로토콜은 채널 역할이 엄격히 분리됩니다.
+ *   stdin  → 클라이언트 → 서버 요청(JSON-RPC)
+ *   stdout → 서버 → 클라이언트 응답(JSON-RPC) ← 프로토콜 전용 채널
+ *   stderr → 로그 전용 (프로토콜 밖)
+ *
+ * console.log는 stdout에 출력되어 JSON-RPC 스트림을 오염시킵니다.
+ * 모든 로깅은 반드시 이 logger를 통해 stderr로 출력해야 합니다.
+ */
+exports.logger = {
+    info: (msg) => {
+        process.stderr.write(`[INFO] ${msg}\n`);
+    },
+    warn: (msg) => {
+        process.stderr.write(`[WARN] ${msg}\n`);
+    },
+    error: (msg) => {
+        process.stderr.write(`[ERROR] ${msg}\n`);
+    },
+};

package/bin/utils/response.d.ts

@@ -0,0 +1,23 @@
+/**
+ * MCP tool 응답 헬퍼 — 순수 함수
+ *
+ * 모든 tool이 동일한 응답 구조를 사용하도록 통일합니다.
+ * AI가 tool 코드를 읽을 때 응답 구조를 이 파일 하나로 파악할 수 있습니다.
+ */
+/** MCP tool 응답 타입 — registerTool 콜백 반환 타입과 호환 */
+export type McpToolResponse = {
+    [key: string]: unknown;
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: true;
+};
+/** 성공 응답 — data를 JSON.stringify하여 반환 */
+export declare const successResponse: (data: unknown) => McpToolResponse;
+/** 오류 응답 — code + message + suggestion 구조로 isError: true 반환 */
+export declare const errorResponse: (code: string, message: string, suggestion: string) => McpToolResponse;
+/** COMPONENT_NOT_FOUND 오류 — 여러 tool에서 공통 사용 */
+export declare const componentNotFoundResponse: (name: string) => McpToolResponse;
+/** 입력 정규화 — name.trim().toLowerCase() */
+export declare const normalizeName: (name: string) => string;

package/bin/utils/response.js

@@ -0,0 +1,31 @@
+"use strict";
+/**
+ * MCP tool 응답 헬퍼 — 순수 함수
+ *
+ * 모든 tool이 동일한 응답 구조를 사용하도록 통일합니다.
+ * AI가 tool 코드를 읽을 때 응답 구조를 이 파일 하나로 파악할 수 있습니다.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeName = exports.componentNotFoundResponse = exports.errorResponse = exports.successResponse = void 0;
+/** 성공 응답 — data를 JSON.stringify하여 반환 */
+const successResponse = (data) => ({
+    content: [{ type: 'text', text: JSON.stringify(data) }],
+});
+exports.successResponse = successResponse;
+/** 오류 응답 — code + message + suggestion 구조로 isError: true 반환 */
+const errorResponse = (code, message, suggestion) => ({
+    content: [
+        {
+            type: 'text',
+            text: JSON.stringify({ code, message, suggestion }),
+        },
+    ],
+    isError: true,
+});
+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;
+/** 입력 정규화 — name.trim().toLowerCase() */
+const normalizeName = (name) => name.trim().toLowerCase();
+exports.normalizeName = normalizeName;

package/bin/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION = "1.6.4-alpha.2";

package/bin/version.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERSION = void 0;
+exports.VERSION = '1.6.4-alpha.2';

package/data/_meta.json

@@ -0,0 +1,7 @@
+{
+  "cdn": {
+    "version": "1.6",
+    "css": "https://fe-sdk.cdn-nhncommerce.com/@ncds/ui-admin/1.6/main.min.css",
+    "js": "https://fe-sdk.cdn-nhncommerce.com/@ncds/ui-admin/1.6/main.min.js"
+  }
+}