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

package/bin/definitions/compliance-rules.json

@@ -0,0 +1,64 @@
+{
+  "patterns": [
+    {
+      "match": { "tag": "button" },
+      "ncuaComponent": "button",
+      "confidence": "high"
+    },
+    {
+      "match": { "tag": "input", "hints": [{ "attr": "type", "values": ["text", "search", "email", "url", "tel"] }] },
+      "ncuaComponent": "input-base",
+      "confidence": "high"
+    },
+    {
+      "match": { "tag": "input", "hints": [{ "attr": "type", "values": ["checkbox"] }] },
+      "ncuaComponent": "checkbox",
+      "confidence": "high"
+    },
+    {
+      "match": { "tag": "input", "hints": [{ "attr": "type", "values": ["radio"] }] },
+      "ncuaComponent": "radio",
+      "confidence": "high"
+    },
+    {
+      "match": { "tag": "input", "hints": [{ "attr": "type", "values": ["range"] }] },
+      "ncuaComponent": "slider",
+      "confidence": "high"
+    },
+    {
+      "match": { "tag": "textarea" },
+      "ncuaComponent": "textarea",
+      "confidence": "high"
+    },
+    {
+      "match": { "tag": "select" },
+      "ncuaComponent": "select",
+      "confidence": "high"
+    },
+    {
+      "match": { "tag": "dialog" },
+      "ncuaComponent": "modal",
+      "confidence": "high"
+    },
+    {
+      "match": { "tag": "progress" },
+      "ncuaComponent": "progress-bar",
+      "confidence": "high"
+    },
+    {
+      "match": { "tag": "nav", "hints": [{ "attr": "aria-label", "values": ["breadcrumb"] }] },
+      "ncuaComponent": "bread-crumb",
+      "confidence": "high"
+    },
+    {
+      "match": { "tag": "nav", "hints": [{ "attr": "aria-label", "values": ["pagination"] }] },
+      "ncuaComponent": "pagination",
+      "confidence": "medium"
+    },
+    {
+      "match": { "tag": "table" },
+      "ncuaComponent": "table",
+      "confidence": "medium"
+    }
+  ]
+}

package/bin/definitions/instructions.md

@@ -0,0 +1,96 @@
+# NCUA MCP Server — Required Workflow
+
+You are an agent that builds UI using NCUA (NCDS UI Admin) design system components from NHN Commerce.
+
+## Absolute Rules
+
+1. You MUST generate NCUA component HTML using the render_to_html tool only. Never write HTML/CSS manually.
+2. Do NOT define or guess CSS variables (--ncua-\*), color values, or BEM classes. They are all included in the CDN CSS.
+3. Do NOT write SVG icons manually. Use search_icon or list_icons to find icons.
+4. If an NCUA component exists for the use case, you MUST use it. Do NOT recreate it manually.
+
+## Required Workflow (follow this order strictly)
+
+### Step 0: Version Check (do this once per session)
+
+1. Call `ping` to get the MCP server info. Note `cdn.version` (ui-admin) and `icon.version` (ui-admin-icon).
+2. Check the project's `package.json` for `@ncds/ui-admin`:
+   - **Not found** → The project uses HTML+CDN mode. Skip version comparison and proceed to Step 1.
+   - **Found** → Compare the project's `@ncds/ui-admin` major.minor version with `cdn.version` (ignore patch).
+3. If versions **match** → Proceed to Step 1.
+4. If versions **differ**:
+   - Warn the user: "MCP data is based on @ncds/ui-admin X.Y, but your project uses Z.W. Generated code may not match your installed version."
+   - Wait for the user's confirmation before proceeding. Do NOT upgrade or downgrade package versions on your own.
+5. For **React projects**, also compare `@ncds/ui-admin-icon` major.minor in `package.json` with `icon.version` from ping. Apply the same mismatch rules.
+6. `ping.version` is the MCP server's own release version — do NOT compare it with any project package. Only `cdn.version` and `icon.version` matter.
+7. The `dataVersion` field in `render_to_html` responses shows the same versions as ping. One ping call per session is sufficient — no need to re-check on every `render_to_html` call.
+
+### Step 1: Component Discovery
+
+- Use **search_component** with Korean/English keywords to find the right component
+- Example: "비밀번호" → password-input, "모달" → modal
+- **IMPORTANT**: input is for plain text only. For passwords, always use password-input.
+
+### Step 2: Props Check
+
+- Use **get_component_props** to see available properties
+- Pass all required props. Choose enum values only from the allowed list.
+
+### Step 3: HTML Generation
+
+- Use **render_to_html** to get the exact HTML for each component
+- Use the returned html as-is. Do NOT modify class names, structure, or attributes.
+
+### Step 4: CDN Inclusion
+
+- Get CSS/JS URLs from the **cdn** field in the render_to_html response
+- Include them in <head>/<body> of the final HTML
+- When **js.required is true**, include the CDN JS <script> tag. This is mandatory.
+
+### Step 5: Composition
+
+- Combine render_to_html results to build the final page
+- Do NOT modify NCUA component styles
+
+## Building Custom Areas (not covered by NCUA)
+
+When NCUA does not have a component for your needs, you may write custom HTML/CSS with these rules:
+
+1. **No ncua- prefix** — Use a unique BEM prefix to avoid confusion with NCUA components (e.g. pw-form, order-summary)
+2. **BEM naming** — Write custom classes using BEM convention (e.g. pw-form**title, pw-form**field--error)
+3. **Reuse NCUA design tokens ONLY** — Use ONLY CSS variables that actually exist in the CDN CSS. Do NOT invent tokens.
+   - Colors: var(--color-text-primary), var(--color-border-secondary), var(--color-background-primary), etc.
+   - Fonts: var(--font-size-_), var(--font-weight-_), etc.
+   - Spacing: var(--spacing-\*), etc.
+   - Do NOT hardcode hex values like #5B5BD6 or rgb values. Always use existing token variables.
+   - If no exact token exists for your need, choose the closest available token. Do NOT create new tokens or hex values.
+4. **Clear separation** — NCUA component areas (from render_to_html) and custom areas must be clearly distinguishable
+
+## Step 6: Design System Compliance Check (after Step 5)
+
+After composing the final HTML, validate design system compliance:
+
+1. Call **validate_html** with the generated HTML
+2. Check `compliance.score` in the response:
+   - **score = 1.0** → All design system rules followed. Proceed.
+   - **score < 1.0** → Fix the reported errors and re-validate.
+3. **Self-correction loop** (max 3 attempts):
+   - Read `compliance.errors` — each error has a `type`, `target`, and `suggestion`
+   - Fix based on error type:
+     - `ncua_not_used` → Replace native HTML element with the suggested NCUA component (call search_component)
+     - `token_not_used` → Replace hardcoded color with the suggested CSS variable
+     - `invalid_token` → Call get_design_tokens to find the correct token name
+     - `custom_not_separated` → Move custom styles to a wrapper outside the NCUA component
+   - Re-call validate_html with the fixed HTML
+   - Repeat until score = 1.0 or 3 attempts reached
+
+**Note:** `compliance.score` is independent from `valid`. `valid=true` with `score<1.0` means BEM classes are correct but design system usage can be improved.
+
+## Component Selection Guide
+
+- Password → **password-input** (never use input)
+- Numbers → **number-input**
+- File upload → **file-input**
+- Image upload → **image-file-input**
+- Plain text → **input**
+- Each component's description includes usage guidance and alternatives.

package/bin/definitions/rules.json

@@ -0,0 +1,57 @@
+{
+  "workflow": [
+    "You MUST generate component HTML using the render_to_html tool. Never write HTML/CSS manually.",
+    "Use the HTML returned by render_to_html as-is. Do NOT modify class names, structure, or attributes.",
+    "Use search_component to find the right component by Korean/English keywords before building any UI.",
+    "Use list_components to browse available components by category and choose the appropriate one."
+  ],
+  "componentSelection": [
+    "For password fields, you MUST use password-input. The input component is for plain text only.",
+    "For numbers use number-input, for file uploads use file-input, for image uploads use image-file-input.",
+    "Each component's description lists its intended use case and alternative components. Always read it."
+  ],
+  "version": [
+    "The MCP server's own version (ping.version) is independent from the design system packages. Do NOT compare it with project packages.",
+    "ping.cdn.version shows which @ncds/ui-admin version this MCP data was built from. ping.icon.version shows the @ncds/ui-admin-icon version.",
+    "The dataVersion field in render_to_html response contains the same values as ping.cdn.version and ping.icon.version. One ping per session is sufficient.",
+    "HTML (CDN) mode: if the project does not have @ncds/ui-admin in package.json, it uses CDN-only mode. Skip version comparison.",
+    "If the project has @ncds/ui-admin in package.json, compare its major.minor version with ping.cdn.version (ignore patch). For React projects, also compare @ncds/ui-admin-icon with ping.icon.version.",
+    "If versions match, proceed normally. If versions differ, warn the user and wait for their confirmation BEFORE proceeding.",
+    "Do NOT upgrade or downgrade @ncds/ui-admin or @ncds/ui-admin-icon versions on your own. Version changes require explicit team approval."
+  ],
+  "cdn": [
+    "You MUST include CDN CSS and JS URLs in the final HTML. The cdn field in render_to_html response has the exact URLs.",
+    "When js.required is true in render_to_html response, include the CDN JS <script> tag. This is mandatory.",
+    "In HTML mode, icons are rendered as SVG via CDN JS. No separate package installation is needed.",
+    "When js.required is true, the component needs its own JS for interactivity — ensure the CDN JS script is loaded."
+  ],
+  "react": [
+    "React projects require @ncds/ui-admin and @ncds/ui-admin-icon packages. Install ONLY packages listed in react.dependencies.",
+    "For non-developer users, the agent should check package.json and auto-install required packages.",
+    "Use react.jsx code as-is from render_to_html response. Do NOT write JSX manually — this prevents hallucination.",
+    "Icons in React are imported as components from @ncds/ui-admin-icon (e.g. import { ChevronDown } from '@ncds/ui-admin-icon')."
+  ],
+  "forbidden": [
+    "Do NOT override ncua-* classes with custom CSS. Control appearance through component props only.",
+    "Do NOT define CSS variables (--ncua-*) yourself. They are already included in the CDN CSS.",
+    "Do NOT write SVG icons manually. Use search_icon to find icons from the icon library."
+  ],
+  "customArea": [
+    "When building areas not covered by NCUA components, do NOT use the ncua- prefix. Use a unique BEM prefix (e.g. pw-form, order-summary).",
+    "Custom areas MUST use ONLY existing NCUA design tokens (CSS variables from CDN) for colors, fonts, spacing, and shadows. Do NOT hardcode hex values like #5B5BD6 or rgb values.",
+    "Do NOT invent token names. If no exact token exists, choose the closest available token. Never fall back to raw color/size values.",
+    "Before writing custom CSS, call get_design_tokens to see available tokens. Filter by category (color, typography, spacing, shadow) to reduce response size.",
+    "For spacing, use spacing tokens (--spacing-xs through --spacing-xxl) instead of hardcoded px values. Follow the principle: inner-block spacing < between-block spacing."
+  ],
+  "compliance": [
+    "After generating HTML, call validate_html to check the compliance score. If compliance.score < 1.0, fix the reported errors and re-validate.",
+    "Self-correction loop: generate HTML → validate_html → fix errors → re-validate. Repeat until score = 1.0 (max 3 attempts).",
+    "If validate_html reports ncua_not_used, replace native HTML elements with the suggested NCUA component using search_component.",
+    "If validate_html reports token_not_used, replace hardcoded color values with the suggested CSS variable (var(--token-name)).",
+    "If validate_html reports invalid_token, call get_design_tokens to find the correct token name.",
+    "If validate_html reports custom_not_separated, move custom styles to a wrapper element outside the NCUA component."
+  ],
+  "category": [
+    "Component categories follow the design team standard (DES INDEX): action, input, icon, overlay, navigation, feedback, data-display."
+  ]
+}

package/bin/definitions/token-descriptions.json

@@ -0,0 +1,27 @@
+{
+  "categoryDescriptions": {
+    "color": "Design system color tokens. Use these CSS variables instead of hex/rgb values in custom areas.",
+    "typography": "Typography tokens: font-size, line-height, font-weight, font-family.",
+    "shadow": "Shadow and focus-ring tokens for elevation and focus states."
+  },
+  "groupDescriptions": {
+    "primary-red": "Brand primary. 450 is the default CTA color.",
+    "secondary-gray-blue": "Secondary accent color.",
+    "base": "Pure white (#fff) and black (#000).",
+    "gray": "Neutral color. Text (700-500), border (200-300), background (50-100).",
+    "green": "Success / positive state.",
+    "cyan": "Informational accent.",
+    "blue": "Information / link state.",
+    "violet": "Accent / decorative.",
+    "pink": "Accent / decorative.",
+    "orange": "Warning state.",
+    "yellow": "Caution / highlight.",
+    "font-families": "Base font family (Commerce Sans).",
+    "font-size": "Font size scale: 0 (12px) to 10 (72px).",
+    "line-heights": "Line height scale: 0 (90) to 10 (18). Pair with font-size.",
+    "font-weights": "Font weight: 0 (Regular), 1 (Medium), 2 (Bold).",
+    "focus-ring": "Focus ring shadows for interactive elements.",
+    "shadow": "Elevation shadow scale: xs to 3xl.",
+    "shadow-portfolio-mockup": "Portfolio mockup layout shadows."
+  }
+}

package/bin/definitions/tool-definitions.json

@@ -0,0 +1,42 @@
+{
+  "tools": {
+    "ping": {
+      "description": "Check NCUA MCP server health, version, capabilities, and usage rules."
+    },
+    "list_icons": {
+      "description": "List all available icons from the @ncds/ui-admin-icon package."
+    },
+    "search_icon": {
+      "description": "Search icons by keyword. Supports name and kebab-case lookups."
+    },
+    "list_components": {
+      "description": "List all available UI components grouped by category. Check this before building any UI to understand what components exist."
+    },
+    "search_component": {
+      "description": "Search components by Korean/English keyword. Returns name, category, description, aliases."
+    },
+    "get_component_props": {
+      "description": "Get the available props (properties) for a component. Use this before render_to_html to understand what props you can pass."
+    },
+    "validate_html": {
+      "description": "Validate HTML markup for NCUA BEM class correctness AND design system compliance (component usage, token usage, custom separation). Returns errors, auto-fix suggestions, and a compliance score (0-1)."
+    },
+    "render_to_html": {
+      "description": "Generate exact HTML for an NCUA component with given props. Returns html, appliedProps, defaultsUsed, js, cdn."
+    },
+    "get_design_tokens": {
+      "description": "Get available design tokens (CSS variables) for colors, typography, spacing, and shadows. Use when building custom areas to pick real tokens instead of guessing."
+    }
+  },
+  "capabilities": [
+    { "tool": "ping", "description": "Server health check + version + capabilities/rules" },
+    { "tool": "list_components", "description": "Browse all components by category" },
+    { "tool": "search_component", "description": "Find components by keyword" },
+    { "tool": "list_icons", "description": "Browse all available icons" },
+    { "tool": "search_icon", "description": "Find icons by keyword" },
+    { "tool": "get_component_props", "description": "Get component props spec" },
+    { "tool": "validate_html", "description": "Validate HTML BEM classes + design system compliance score + auto-fix" },
+    { "tool": "render_to_html", "description": "Props-based dynamic HTML rendering" },
+    { "tool": "get_design_tokens", "description": "Design token (CSS variable) lookup by category" }
+  ]
+}

package/bin/instructions.d.ts

@@ -0,0 +1 @@
+export declare const INSTRUCTIONS: string;

package/bin/instructions.js

@@ -0,0 +1,14 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INSTRUCTIONS = void 0;
+/**
+ * AI 에이전트가 MCP 서버 연결 시 자동으로 수신하는 필수 지침.
+ * definitions/instructions.md에서 로드한다.
+ */
+const path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
+const INSTRUCTIONS_PATH = path_1.default.resolve(__dirname, 'definitions', 'instructions.md');
+exports.INSTRUCTIONS = fs_1.default.readFileSync(INSTRUCTIONS_PATH, 'utf-8').trim();

package/bin/server.d.ts

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

package/bin/server.js

@@ -0,0 +1,164 @@
+"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 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 배열로 반환 */
+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 rules = [];
+    for (const key of RULE_KEYS) {
+        const arr = data[key];
+        if (!Array.isArray(arr)) {
+            throw new Error(`rules.json에 ${key} 배열이 없습니다`);
+        }
+        rules.push(...arr);
+    }
+    return rules;
+};
+// ── 진입점 ───────────────────────────────────────────────────────────────────
+const main = async () => {
+    const definitionsDir = path_1.default.resolve(__dirname, 'definitions');
+    // ── definitions/ 로딩 (main() 안에서 실행하여 catch에 포함) ──
+    const { descriptions, capabilities } = loadToolDefinitions(definitionsDir);
+    const rules = loadRules(definitionsDir);
+    const instructions = (0, dataLoader_js_1.loadInstructions)(definitionsDir);
+    const complianceRules = (0, dataLoader_js_1.loadComplianceRules)(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('컴포넌트 번들 로딩 완료');
+    // ── 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 });
+    server.registerTool('ping', { description: descriptions['ping'] }, () => (0, ping_js_1.ping)({ componentMap, cdnMeta, iconMeta, version: version_js_1.VERSION, rules, capabilities }));
+    server.registerTool('list_icons', { description: descriptions['list_icons'] }, () => (0, listIcons_js_1.listIcons)(listIconsResponse));
+    server.registerTool('search_icon', {
+        description: descriptions['search_icon'],
+        inputSchema: { query: zod_1.z.string().describe('Search keyword (e.g. "search", "alert", "arrow")') },
+    }, ({ query }) => (0, searchIcon_js_1.searchIcon)(iconData, query));
+    server.registerTool('list_components', { description: descriptions['list_components'] }, () => (0, listComponents_js_1.listComponents)(listComponentsResponse));
+    server.registerTool('search_component', {
+        description: descriptions['search_component'],
+        inputSchema: { query: zod_1.z.string().describe('Search keyword (Korean/English, case-insensitive)') },
+    }, ({ query }) => (0, searchComponent_js_1.searchComponent)(componentMap, query));
+    server.registerTool('get_component_props', {
+        description: descriptions['get_component_props'],
+        inputSchema: { name: zod_1.z.string().min(1).describe('Component name (e.g. "button", "password-input")') },
+    }, ({ name }) => (0, getComponentProps_js_1.getComponentProps)(componentMap, name));
+    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 }) => (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" })'),
+        },
+    }, 
+    // MCP SDK의 zod 추론 타입이 Record<string, unknown> | undefined와 미스매치하여 as 필요
+    ({ name, props }) => (0, renderToHtml_js_1.renderToHtml)({
+        componentMap,
+        bundle,
+        cdnMeta,
+        iconMeta,
+        reactRuntime,
+        name,
+        props: props,
+    }));
+    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 }) => (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/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,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,17 @@
+"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)(component.props);
+};
+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;