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

package/bin/server.js

@@ -0,0 +1,217 @@
+"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"));
+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 getComponentProps_js_1 = require("./tools/getComponentProps.js");
+const validateHtml_js_1 = require("./tools/validateHtml.js");
+const ping_js_1 = require("./tools/ping.js");
+const listIcons_js_1 = require("./tools/listIcons.js");
+const searchIcon_js_1 = require("./tools/searchIcon.js");
+const renderToHtml_js_1 = require("./tools/renderToHtml.js");
+const response_js_1 = require("./utils/response.js");
+const getDesignTokens_js_1 = require("./tools/getDesignTokens.js");
+const version_js_1 = require("./version.js");
+const domEnvironment_js_1 = require("./utils/domEnvironment.js");
+// ── definitions/ 로딩 헬퍼 (Action) ─────────────────────────────────────────
+/** tool-definitions.json을 1회 로딩하여 descriptions + capabilities를 분리 반환 */
+const loadToolDefinitions = (definitionsDir) => {
+    const raw = fs_1.default.readFileSync(path_1.default.resolve(definitionsDir, 'tool-definitions.json'), 'utf-8');
+    const data = JSON.parse(raw);
+    // JSON 구조 검증 — 타입 단언만으로 신뢰하지 않음 (§ 2.5)
+    const tools = data.tools;
+    if (!tools || typeof tools !== 'object') {
+        throw new Error('tool-definitions.json에 tools 키가 없거나 올바르지 않습니다');
+    }
+    const descriptions = {};
+    for (const [name, def] of Object.entries(tools)) {
+        if (def.description)
+            descriptions[name] = def.description;
+    }
+    const capabilities = data.capabilities;
+    if (!Array.isArray(capabilities)) {
+        throw new Error('tool-definitions.json에 capabilities 배열이 없습니다');
+    }
+    return { descriptions, capabilities };
+};
+/** 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);
+    const RULE_KEYS = [
+        'workflow',
+        'componentSelection',
+        'version',
+        'cdn',
+        'react',
+        'forbidden',
+        'customArea',
+        'compliance',
+        'category',
+    ];
+    const flat = [];
+    for (const key of RULE_KEYS) {
+        const arr = data[key];
+        if (!Array.isArray(arr)) {
+            throw new Error(`rules.json에 ${key} 배열이 없습니다`);
+        }
+        flat.push(...arr);
+    }
+    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 { 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 { 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);
+    const bundlePath = path_1.default.resolve(__dirname, '..', 'bin', 'components.bundle.js');
+    // 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 런타임 초기화 완료');
+    // ── 파생 데이터 사전 계산 (code-guide § 5.1 반복 계산 제거) ──
+    const rootClassMap = (0, validateHtml_js_1.buildRootClassMap)(componentMap);
+    const tokenValueMap = (0, validateHtml_js_1.buildTokenValueMap)(tokenData);
+    const groupedComponents = (0, listComponents_js_1.buildGroupedComponents)(componentMap);
+    const iconSummary = (0, listIcons_js_1.buildIconSummary)(iconData);
+    const listComponentsResponse = (0, listComponents_js_1.buildListComponentsResponse)(groupedComponents);
+    const listIconsResponse = (0, listIcons_js_1.buildListIconsResponse)(iconSummary);
+    // ── MCP 서버 생성 + tool 등록 ──
+    const server = new mcp_js_1.McpServer({ name: 'ncds-ui-admin', version: version_js_1.VERSION }, { instructions });
+    // 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 }) => 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('search_component', {
+        description: descriptions['search_component'],
+        inputSchema: { query: zod_1.z.string().describe('Search keyword (Korean/English, case-insensitive)') },
+    }, ({ 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 }) => withPingReminder((0, getComponentProps_js_1.getComponentProps)(componentMap, name)));
+    server.registerTool('validate_html', {
+        description: descriptions['validate_html'],
+        inputSchema: {
+            html: zod_1.z
+                .string()
+                .min(1)
+                .describe('HTML markup to validate (e.g. \'<button class="ncua-btn ncua-btn--primary"></button>\')'),
+        },
+    }, ({ 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: {
+            name: zod_1.z.string().min(1).describe('Component name (e.g. "button", "modal", "password-input")'),
+            props: zod_1.z
+                .record(zod_1.z.string(), zod_1.z.unknown())
+                .optional()
+                .describe('Component props (e.g. { label: "OK", hierarchy: "primary" })'),
+        },
+    }, ({ name, props }) => withPingReminder((0, renderToHtml_js_1.renderToHtml)({
+        componentMap,
+        bundle,
+        iconBundle,
+        cdnMeta,
+        iconMeta,
+        reactRuntime,
+        jsApiMap,
+        name,
+        props: props,
+    })));
+    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,
+        }));
+        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: {
+            category: zod_1.z
+                .string()
+                .optional()
+                .describe('Token category filter (e.g. "color", "typography", "shadow", "spacing"). Omit to get all tokens.'),
+        },
+    }, ({ 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})`);
+};
+main().catch((err) => {
+    process.stderr.write(`[ERROR] 서버 시작 실패: ${err instanceof Error ? err.message : String(err)}\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/getComponentProps.d.ts

@@ -0,0 +1,4 @@
+import type { ComponentData } from '../types.js';
+import { type McpToolResponse } from '../utils/response.js';
+/** get_component_props tool — 컴포넌트의 props 스펙을 JSON으로 반환 */
+export declare const getComponentProps: (componentMap: Map<string, ComponentData>, name: string) => McpToolResponse;

package/bin/tools/getComponentProps.js

@@ -0,0 +1,20 @@
+"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");
+/** get_component_props tool — 컴포넌트의 props 스펙을 JSON으로 반환 */
+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)({
+        props: component.props,
+        ...(component.usageExamples && { usageExamples: component.usageExamples }),
+    });
+};
+exports.getComponentProps = getComponentProps;

package/bin/tools/getDesignTokens.d.ts

@@ -0,0 +1,13 @@
+/**
+ * get_design_tokens tool — 디자인 토큰(CSS 변수) 조회
+ *
+ * 커스텀 영역 작성 시 에이전트가 실제 존재하는 토큰만 사용하도록
+ * 빌드타임 추출된 토큰 목록을 카테고리별로 제공한다.
+ */
+import type { TokenData } from '../types.js';
+import { type McpToolResponse } from '../utils/response.js';
+export interface GetDesignTokensParams {
+    tokenData: TokenData;
+    category?: string;
+}
+export declare const getDesignTokens: ({ tokenData, category }: GetDesignTokensParams) => McpToolResponse;

package/bin/tools/getDesignTokens.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDesignTokens = void 0;
+const response_js_1 = require("../utils/response.js");
+const getDesignTokens = ({ tokenData, category }) => {
+    if (!category) {
+        return (0, response_js_1.successResponse)(tokenData);
+    }
+    if (!tokenData.categories.includes(category)) {
+        return (0, response_js_1.errorResponse)('INVALID_TOKEN_CATEGORY', `Category '${category}' not found. Available: ${tokenData.categories.join(', ')}`, 'Use get_design_tokens without category to see all available categories and tokens.');
+    }
+    const filteredGroups = tokenData.groups.filter((group) => group.category === category);
+    const filteredCount = filteredGroups.reduce((sum, group) => sum + group.tokens.length, 0);
+    return (0, response_js_1.successResponse)({
+        totalCount: filteredCount,
+        categories: [category],
+        groups: filteredGroups,
+    });
+};
+exports.getDesignTokens = getDesignTokens;

package/bin/tools/listComponents.d.ts

@@ -0,0 +1,16 @@
+/**
+ * list_components tool — 사전 계산된 카테고리별 컴포넌트 목록 반환 (순수 함수)
+ */
+import type { ComponentData } from '../types.js';
+import { type McpToolResponse } from '../utils/response.js';
+/** 카테고리별 컴포넌트 그룹 타입 */
+export type GroupedComponents = Record<string, Array<{
+    name: string;
+    description: string;
+}>>;
+/** componentMap에서 카테고리별 그룹을 사전 계산 — server.ts에서 1회 호출 */
+export declare const buildGroupedComponents: (componentMap: Map<string, ComponentData>) => GroupedComponents;
+/** GroupedComponents를 사전 직렬화 — server.ts에서 1회 호출 */
+export declare const buildListComponentsResponse: (grouped: GroupedComponents) => McpToolResponse;
+/** list_components tool — 사전 직렬화된 응답을 그대로 반환 */
+export declare const listComponents: (prebuilt: McpToolResponse) => McpToolResponse;

package/bin/tools/listComponents.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listComponents = exports.buildListComponentsResponse = exports.buildGroupedComponents = void 0;
+const response_js_1 = require("../utils/response.js");
+/** componentMap에서 카테고리별 그룹을 사전 계산 — server.ts에서 1회 호출 */
+const buildGroupedComponents = (componentMap) => {
+    const sorted = [...componentMap.values()]
+        .map((c) => ({ name: c.name, category: c.category, description: c.description }))
+        .sort((a, b) => a.category.localeCompare(b.category) || a.name.localeCompare(b.name));
+    const grouped = {};
+    for (const c of sorted) {
+        if (!grouped[c.category])
+            grouped[c.category] = [];
+        grouped[c.category].push({ name: c.name, description: c.description });
+    }
+    return grouped;
+};
+exports.buildGroupedComponents = buildGroupedComponents;
+/** GroupedComponents를 사전 직렬화 — server.ts에서 1회 호출 */
+const buildListComponentsResponse = (grouped) => (0, response_js_1.successResponse)(grouped);
+exports.buildListComponentsResponse = buildListComponentsResponse;
+/** list_components tool — 사전 직렬화된 응답을 그대로 반환 */
+const listComponents = (prebuilt) => prebuilt;
+exports.listComponents = listComponents;

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