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

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,164 @@
+# 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 (VIOLATION = CRITICAL FAILURE)
+
+1. Call ping ONCE at the start of every session before using any other tool. This loads version info and usage rules.
+2. NEVER define or guess NCUA CSS variables (--ncua-\*). NCUA component styles are controlled by CDN CSS only.
+3. NEVER write SVG icons or icon markup manually. ALL icons MUST come from search_icon or list_icons. If you write a single svg tag by hand, you have FAILED.
+4. NEVER use emoji in generated HTML, CSS, or any output. No exceptions.
+5. You MUST generate NCUA component HTML using render_to_html or render_to_html_batch only. Never write component HTML/CSS manually.
+6. If an NCUA component exists for the use case, you MUST use it. Do NOT recreate it manually.
+7. For custom areas, call get_design_tokens FIRST and prefer NCUA tokens for colors, spacing, typography, and shadows to maintain visual consistency. If no suitable token exists, you may use standard CSS values (hex, rgb, px).
+
+## 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
+
+- Call **list_components** first to see all available components and their categories. This prevents reinventing components that already exist.
+- 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 BEFORE calling render_to_html.
+- Pass all required props. Choose enum values only from the allowed list.
+- Check `type: "object"` props carefully — they often expect arrays or structured objects. Read the `rawType` field for the actual TypeScript type.
+- For icon props (`leadingIcon`, `trailingIcon`, `icon`), pass `{ type: "icon", icon: "IconName" }` where IconName is a PascalCase name from search_icon.
+
+### Step 3: HTML Generation
+
+- When building a page with multiple components, use **render_to_html_batch** to render them all in one call (max 30). This is much more efficient than calling render_to_html repeatedly.
+- For a single component, use **render_to_html**.
+- Use the returned html as-is. Do NOT modify class names, structure, or attributes.
+- Check the `warnings` field in the response — it reports invalid enum values and missing required props.
+- **If render returns empty or minimal HTML**, the component likely needs data props (e.g. `menus` for HorizontalTab, `items` for BreadCrumb). Check get_component_props and retry with proper data.
+- **Empty result recovery** (max 3 attempts):
+  1. Call get_component_props to identify required/data props
+  2. Retry render_to_html with meaningful prop values
+  3. If still empty after 3 attempts, report the issue to the user
+
+### 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
+- Apply spacing between components using NCUA design tokens: call **get_design_tokens** with category "spacing" to get available spacing values (e.g. var(--spacing-4), var(--spacing-8))
+- When deciding component size or hierarchy, document your reasoning in an HTML comment (e.g. `<!-- size:sm chosen for compact sidebar layout -->`)
+- If a commerce-rag MCP server is available, query it for page layout patterns and spacing guidelines specific to the project
+
+## 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.
+
+## Props Usage Guide
+
+When calling `get_component_props`, the response includes:
+
+- `props`: Full props specification with types, defaults, and allowed values
+- `usageExamples` (if available): Ready-to-use props objects for `render_to_html`
+
+For components with complex object/array props (e.g., dropdown, range-date-picker), always check `usageExamples` first. Copy the example and modify values as needed — this avoids required prop omission errors.
+
+If you call `render_to_html` with missing required props:
+
+- The server auto-fills safe defaults (empty string, empty array, etc.) to prevent crashes
+- `warnings` field lists what was missing and what was auto-filled
+- The rendered HTML may be incomplete — check warnings and retry with proper values
+
+## 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.
+
+## Rules Schema
+
+The `rules` array in ping response is a flat list of strings grouped by category. Categories:
+
+| Category           | Purpose                                            |
+| ------------------ | -------------------------------------------------- |
+| workflow           | Required tool call order and HTML generation rules |
+| componentSelection | Which component to use for each use case           |
+| version            | MCP↔project version comparison rules               |
+| cdn                | CDN CSS/JS inclusion rules                         |
+| react              | React-specific package and import rules            |
+| forbidden          | Actions that must never be performed               |
+| customArea         | Rules for building areas not covered by NCUA       |
+| compliance         | validate_html self-correction loop rules           |
+| category           | Component category naming standard                 |
+
+## Error Response Format
+
+All tool errors follow a consistent JSON structure:
+
+```json
+{ "code": "ERROR_CODE", "message": "Human-readable description", "suggestion": "What to do next" }
+```
+
+Error codes:
+
+| Code                    | When                                                                 |
+| ----------------------- | -------------------------------------------------------------------- |
+| COMPONENT_NOT_FOUND     | Component name does not exist                                        |
+| EXPORT_NAME_MISSING     | Component data is corrupted — re-extract needed                      |
+| COMPONENT_NOT_IN_BUNDLE | Component exists in data but not in runtime bundle — re-build needed |
+| RENDER_FAILED           | React rendering threw an error — check props                         |
+| INVALID_TOKEN_CATEGORY  | get_design_tokens called with unknown category                       |
+| ICON_NOT_FOUND          | Icon name does not exist in the icon library                         |
+| INVALID_PARAMS          | Tool called with invalid or missing parameters                       |
+| INTERNAL_ERROR          | Unexpected server error                                              |

package/bin/definitions/js-api.json

@@ -0,0 +1,165 @@
+{
+  "Modal": {
+    "className": "Modal",
+    "constructor": "new window.ncua.Modal(options?)",
+    "constructorParams": {
+      "size": "'sm' | 'md' | 'lg' (default: 'md')",
+      "closeOnBackdropClick": "boolean (default: false)",
+      "closeOnEsc": "boolean (default: true)",
+      "onClose": "() => void"
+    },
+    "methods": ["open()", "close()", "destroy()", "setContent(html: string | HTMLElement)", "isModalOpen()"],
+    "example": "const modal = new window.ncua.Modal({ size: 'sm', onClose: () => {} });\nmodal.setContent('<p>Content</p>');\nmodal.open();"
+  },
+  "SelectBox": {
+    "className": "SelectBox",
+    "constructor": "new window.ncua.SelectBox(element, config?)",
+    "constructorParams": {
+      "element": "HTMLElement — target container",
+      "config.options": "Array<{ id: string, text: string, disabled?: boolean }>",
+      "config.placeholder": "string (default: '선택하세요')",
+      "config.value": "string | number",
+      "config.onChange": "(value) => void",
+      "config.size": "'xs' | 'sm' | 'md'",
+      "config.multiple": "boolean",
+      "config.disabled": "boolean"
+    },
+    "methods": ["getValues()", "setValues(options[])", "getSelectedCount()"],
+    "example": "const select = new window.ncua.SelectBox(document.getElementById('my-select'), {\n  options: [{ id: '1', text: 'Option 1' }],\n  onChange: (value) => console.log(value)\n});"
+  },
+  "ComboBox": {
+    "className": "ComboBox",
+    "constructor": "new window.ncua.ComboBox(element, config?)",
+    "constructorParams": {
+      "element": "HTMLElement — target container",
+      "config.options": "Array<{ id: string, label: string, disabled?: boolean }>",
+      "config.placeholder": "string (default: '검색하고 선택하세요')",
+      "config.value": "string | number",
+      "config.onChange": "(value) => void",
+      "config.onSearch": "(searchValue: string) => void",
+      "config.size": "'xs' | 'sm'",
+      "config.multiple": "boolean"
+    },
+    "methods": ["getValues()", "setValues(options[])", "clearInput()", "getSelectedCount()"],
+    "example": "const combo = new window.ncua.ComboBox(document.getElementById('my-combo'), {\n  options: [{ id: '1', label: 'React' }],\n  onSearch: (q) => console.log(q)\n});"
+  },
+  "DatePicker": {
+    "className": "DatePicker",
+    "constructor": "new window.ncua.DatePicker(wrapper, options)",
+    "constructorParams": {
+      "wrapper": "HTMLElement — container element",
+      "options.size": "'xs' | 'sm'",
+      "options.datePickerOptions": "Array<{ element: string, placeholder?: string, options: FlatpickrOptions }>",
+      "options.buttons": "Array<{ text: string, period: number, unit: 'days'|'months', isCurrent: boolean }>",
+      "options.onValidationError": "(error) => void"
+    },
+    "methods": ["getDates()", "setDate(dates: string[])", "setMultipleDates(dates: string[])"],
+    "example": "const dp = new window.ncua.DatePicker(document.getElementById('my-dp'), {\n  size: 'xs',\n  datePickerOptions: [{ element: 'date-input', placeholder: 'Select date', options: { dateFormat: 'Y-m-d' } }]\n});"
+  },
+  "Slider": {
+    "className": "Slider",
+    "constructor": "new window.ncua.Slider(element, options)",
+    "constructorParams": {
+      "element": "HTMLElement — container",
+      "options.min": "number (default: 0)",
+      "options.max": "number (default: 100)",
+      "options.step": "number (default: 1)",
+      "options.value": "number | [number, number]",
+      "options.onChange": "(value) => void",
+      "options.disabled": "boolean"
+    },
+    "methods": ["getValue()", "setValue(value)", "enable()", "disable()", "destroy()"],
+    "example": "const slider = new window.ncua.Slider(document.getElementById('my-slider'), {\n  min: 0, max: 100, value: 50,\n  onChange: (v) => console.log(v)\n});"
+  },
+  "Tab": {
+    "className": "Tab",
+    "constructor": "new window.ncua.Tab(element)",
+    "constructorParams": {
+      "element": "HTMLElement — container with swiper structure"
+    },
+    "methods": ["destroy()"],
+    "example": "const tab = new window.ncua.Tab(document.getElementById('my-tab'));"
+  },
+  "Tooltip": {
+    "className": "Tooltip",
+    "constructor": "window.ncua.Tooltip.createShort(title, content?, options?)",
+    "constructorParams": {
+      "title": "string",
+      "content": "string (HTML supported)",
+      "options.position": "'top' | 'bottom' | 'left' | 'right' (default: 'top')"
+    },
+    "methods": ["getElement()", "showTooltip()", "hideTooltip()", "destroy()"],
+    "example": "const tip = window.ncua.Tooltip.createShort('Help', 'Tooltip content');\ndocument.getElementById('container').appendChild(tip.getElement());"
+  },
+  "Notification": {
+    "className": "Notification",
+    "constructor": "window.ncua.Notification.success(title, supportingText?, options?)",
+    "constructorParams": {
+      "title": "string",
+      "supportingText": "string",
+      "options.autoClose": "number (ms, 0 = no auto-close)"
+    },
+    "methods": ["show(parent?)", "remove()", "destroy()"],
+    "staticMethods": ["success()", "error()", "warning()", "info()", "neutral()"],
+    "example": "window.ncua.Notification.success('Saved', 'Changes saved successfully');"
+  },
+  "ProgressBar": {
+    "className": "ProgressBar",
+    "constructor": "new window.ncua.ProgressBar(options?)",
+    "constructorParams": {
+      "options.value": "number (0-100)",
+      "options.label": "'right' | 'bottom' | 'top-float' | 'bottom-float'"
+    },
+    "methods": ["getElement()", "updateOptions(newOptions)", "toHTML()"],
+    "example": "const bar = new window.ncua.ProgressBar({ value: 65, label: 'right' });\ndocument.getElementById('container').appendChild(bar.getElement());"
+  },
+  "Tag": {
+    "className": "Tag",
+    "constructor": "new window.ncua.Tag(options)",
+    "constructorParams": {
+      "options.text": "string",
+      "options.size": "'sm' | 'md' (default: 'sm')",
+      "options.close": "boolean — show close button",
+      "options.onButtonClick": "() => void — close handler"
+    },
+    "methods": ["getElement()", "setText(text)", "setCount(count)", "destroy()"],
+    "example": "const tag = new window.ncua.Tag({ text: 'Label', close: true, onButtonClick: () => tag.destroy() });\ndocument.getElementById('container').appendChild(tag.getElement());"
+  },
+  "FileInput": {
+    "className": "FileInput",
+    "constructor": "new window.ncua.FileInput(options)",
+    "constructorParams": {
+      "options.container": "HTMLElement | string — auto-append target",
+      "options.onChange": "(files: File[]) => void",
+      "options.onFail": "(invalidFiles: File[]) => void",
+      "options.disabled": "boolean"
+    },
+    "methods": ["getElement()", "setDisabled(boolean)", "destroy()"],
+    "example": "const fi = new window.ncua.FileInput({\n  container: 'file-container',\n  onChange: (files) => console.log(files)\n});"
+  },
+  "ImageFileInput": {
+    "className": "ImageFileInput",
+    "constructor": "new window.ncua.ImageFileInput(options)",
+    "constructorParams": {
+      "options.container": "HTMLElement | string — auto-append target",
+      "options.onChange": "(files: File[]) => void",
+      "options.maxFileCount": "number",
+      "options.acceptedFileTypes": "string[]",
+      "options.maxFileSize": "number"
+    },
+    "methods": ["getElement()", "getFiles()", "clearFiles()", "setDisabled(boolean)", "destroy()"],
+    "example": "const img = new window.ncua.ImageFileInput({\n  container: 'image-container',\n  maxFileCount: 5,\n  onChange: (files) => console.log(files)\n});"
+  },
+  "FeaturedIcon": {
+    "className": "FeaturedIcon",
+    "constructor": "new window.ncua.FeaturedIcon(options)",
+    "constructorParams": {
+      "options.svgString": "string — SVG content",
+      "options.theme": "'light-circle' | 'dark-circle' | 'outline-circle' | 'square-outline'",
+      "options.color": "'neutral' | 'error' | 'warning' | 'success'",
+      "options.size": "'sm' | 'md' | 'lg' | 'xl'"
+    },
+    "methods": ["getElement()", "updateColor(color)", "updateSize(size)", "destroy()"],
+    "example": "const icon = new window.ncua.FeaturedIcon({ svgString: '<svg>...</svg>', color: 'success', size: 'md' });\ndocument.getElementById('container').appendChild(icon.getElement());"
+  }
+}

package/bin/definitions/rules.json

@@ -0,0 +1,59 @@
+{
+  "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.",
+    "When building a page with multiple components, use render_to_html_batch to render them all in one call instead of calling render_to_html repeatedly."
+  ],
+  "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."
+  ],
+  "pingReminder": "IMPORTANT: You have NOT called ping yet. Call ping ONCE before proceeding. Rules: (1) NEVER hardcode hex/rgb colors - use get_design_tokens. (2) NEVER write SVG icons - use search_icon. (3) Use render_to_html or render_to_html_batch for all NCUA components. (4) For custom CSS, prefer NCUA tokens. Call get_design_tokens first."
+}

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,58 @@
+{
+  "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."
+    },
+    "render_to_html_batch": {
+      "description": "Render multiple NCUA components in a single call (max 30). Pass an array of {name, props} objects. Returns an array of render results. Use this instead of calling render_to_html repeatedly when building a page."
+    },
+    "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", "available": true },
+    { "tool": "list_components", "description": "Browse all components by category", "available": true },
+    { "tool": "search_component", "description": "Find components by keyword", "available": true },
+    { "tool": "list_icons", "description": "Browse all available icons", "available": true },
+    { "tool": "search_icon", "description": "Find icons by keyword", "available": true },
+    { "tool": "get_component_props", "description": "Get component props spec", "available": true },
+    {
+      "tool": "validate_html",
+      "description": "Validate HTML BEM classes + design system compliance score + auto-fix",
+      "available": true
+    },
+    {
+      "tool": "render_to_html",
+      "description": "Props-based dynamic HTML rendering + icon SVG resolve",
+      "available": true
+    },
+    {
+      "tool": "render_to_html_batch",
+      "description": "Batch render multiple components in one call (max 30)",
+      "available": true
+    },
+    { "tool": "get_design_tokens", "description": "Design token (CSS variable) lookup by category", "available": true }
+  ]
+}

package/bin/server.d.ts

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