@opsnow-mcp/opsnow-mcp-common-ui-server 1.0.11 → 1.0.16

package/README.md

@@ -209,3 +209,108 @@ MCP 플랫폼의 설정 파일(예: `mcp.config.json` 또는 유사 파일)에
 
 ### 3. MCP 플랫폼에서 서버 인식 확인
 MCP 플랫폼을 재시작하거나 서버 목록을 새로고침하면, `opsnow-mcp-common-ui-server`가 정상적으로 등록되어야 합니다.
+
+---
+
+## Claude Code Skills 생성
+
+MCP 서버를 Claude Code에서 사용할 수 있는 **정적 Skills**로 변환할 수 있습니다.
+
+### MCP vs Skills 비교
+
+| 구분 | MCP Server | Claude Code Skills |
+|------|------------|-------------------|
+| 실행 방식 | 런타임 (Node.js 프로세스) | 정적 문서 (마크다운) |
+| 호출 방식 | Tool 호출 | `/skill-name` 슬래시 커맨드 |
+| 배포 | npm 패키지 | Plugin Marketplace 또는 로컬 |
+| 오프라인 | ❌ | ✅ |
+
+### Skills 빌드 명령어
+
+```bash
+# Skills 빌드 (기존 파일 유지)
+npm run build:skill
+
+# Skills 클린 빌드 (기존 파일 삭제 후 새로 생성)
+npm run build:skill:clean
+```
+
+### 빌드 출력물
+
+```
+skills/plugins/opsnow-common-ui-skill/
+├── .claude-plugin/
+│   └── plugin.json          # 플러그인 매니페스트
+└── skills/opsnow-common-ui/
+    ├── SKILL.md              # 메인 스킬 정의 (컴포넌트 카탈로그)
+    ├── references/           # Props 레퍼런스 (35개)
+    │   ├── button.md
+    │   ├── datagrid.md
+    │   └── ...
+    ├── examples/             # 상세 예제 (40개 파일, 463개 예제)
+    │   ├── button.md
+    │   ├── datagrid.md
+    │   └── ...
+    └── components/           # Zod 스키마 복사본 (18개)
+        ├── opsnow-common-button.ts
+        └── ...
+```
+
+### 문서 구조 (Progressive Disclosure)
+
+| 깊이 | 경로 | 용도 | 언제 참조? |
+|------|------|------|-----------|
+| 1 | `SKILL.md` | 컴포넌트 카탈로그, 개요 | 뭐가 있는지 파악할 때 |
+| 2 | `references/*.md` | Props 테이블, 기본 사용법 | 컴포넌트 처음 사용할 때 |
+| 3 | `examples/*.md` | 케이스별 상세 예제 | 특정 패턴 구현할 때 |
+| 4 | `components/*.ts` | Zod 스키마, 타입 정의 | 타입/옵션 상세 확인할 때 |
+
+### 로컬 테스트
+
+생성된 Skills를 로컬에서 테스트하려면:
+
+```bash
+# 프로젝트 루트에서
+cd skills/plugins/opsnow-common-ui-skill
+
+# Claude Code에서 직접 테스트
+claude
+
+# 또는 skills 폴더를 Claude Code 설정에 추가
+```
+
+### 새 컴포넌트 추가 시 수정 필요 사항
+
+`scripts/build-skill.ts`에서 다음 5개 매핑을 업데이트해야 합니다:
+
+1. **`CATEGORIES[]`** - 카탈로그 분류 (차트, 폼, 레이아웃 등)
+2. **`COMPONENT_NAME_MAP{}`** - React 컴포넌트명 매핑
+3. **`COMPONENT_PURPOSE{}`** - 용도 설명
+4. **`SCHEMA_TO_COMPONENT{}`** - Zod 스키마 → 컴포넌트 매핑
+5. **`INTERNAL_SCHEMAS`** - 제외할 내부 스키마
+
+### MCP 소스 작성 규칙
+
+Skills가 올바르게 생성되려면 MCP 소스 파일이 다음 규칙을 따라야 합니다:
+
+**Zod 스키마** (`src/components/*.ts`):
+```typescript
+// .describe()로 Props 설명 필수
+export const ButtonPropsSchema = z.object({
+  label: z.string().describe('버튼 라벨'),
+  size: z.enum(['large', 'medium', 'small']).describe('버튼 크기'),
+}).describe('버튼 컴포넌트');
+```
+
+**예제 파일** (`src/components/examples/*-examples-data.ts`):
+```typescript
+// 파일명: opsnow-common-{component}-examples-data.ts
+// Export 명명: {PascalCase}Examples
+export const ButtonExamples: Example[] = [
+  {
+    title: '기본 버튼',
+    props: { label: '버튼', size: 'medium' },
+    code: `<OpsnowCommonButton label="버튼" size="medium" />`,
+  },
+];
+```

package/build/components/examples/opsnow-common-chart-examples-data.js

@@ -502,7 +502,7 @@ export const BarChartExamples = [
             width: 'p50',
             hover: {
               enabled: true,
-              grouped: true
+              : true
             }
           },
           tooltip: {
@@ -2109,6 +2109,81 @@ export const LineChartExamples = [
         chartData={chartData}
       />`
     },
+    {
+        title: '라인 차트 - Bullet Label (데이터 포인트에 값 표시)',
+        description: '라인 차트의 각 데이터 포인트 위에 값을 라벨로 표시하는 bullet label 예제입니다. format, prefix, suffix를 사용하여 값 형식을 지정할 수 있습니다.',
+        code_props_usage: `
+      const chartId = 'line-chart-bullet-label-${generateUniqueGeneralId()}'
+      const chartRef = useRef(null)
+      const [chartProps, setChartProps] = useState({
+        chart: {
+          paddingTop: 30,
+          paddingBottom: 30
+        },
+        xAxis: {
+          type: 'date',
+          dateFormats: [
+            { type: 'day', dateFormat: 'MM-dd' },
+            { type: 'month', dateFormat: 'yy-MM' }
+          ],
+          baseInterval: { timeUnit: 'month', count: 1 },
+          gridHidden: true
+        },
+        yAxis: {
+          type: 'value',
+          extraMax: 0.15,
+          min: 0,
+          numberFormat: '$#,###'
+        },
+        series: {
+          valueXField: 'date',
+          dataProcessor: {
+            dateFields: ['date'],
+            dateFormat: 'yyyy-MM-dd'
+          },
+          bullet: {
+            type: 'label',        // 'label' 타입으로 설정
+            locationX: 0.5,       // X축 위치 (0~1, 0.5 = 중앙)
+            locationY: 1,         // Y축 위치 (0~1, 1 = 상단)
+            label: {
+              dy: -15,            // Y축 오프셋 (음수: 위로 이동)
+              format: '#,###',    // 숫자 포맷
+              prefix: '$',        // 접두사
+              fontSize: 9
+            }
+          }
+        },
+        legend: { useExtension: false }
+      })
+      const [chartCategory, setChartCategory] = useState(['cost1', 'cost2'])
+      const [chartData, setChartData] = useState([
+        { date: '2024-10-01', cost1: 70000, cost2: 8000 },
+        { date: '2024-11-01', cost1: 85000, cost2: 10000 },
+        { date: '2024-12-01', cost1: 170000, cost2: 15000 },
+        { date: '2025-01-01', cost1: 165000, cost2: 14000 },
+        { date: '2025-02-01', cost1: 95000, cost2: 10000 },
+        { date: '2025-03-01', cost1: 115000, cost2: 12000 },
+        { date: '2025-04-01', cost1: 140000, cost2: 13000 },
+        { date: '2025-05-01', cost1: 270000, cost2: 18000 },
+        { date: '2025-06-01', cost1: 135000, cost2: 13500 },
+        { date: '2025-07-01', cost1: 140000, cost2: 14000 },
+        { date: '2025-08-01', cost1: 135000, cost2: 13800 },
+        { date: '2025-09-01', cost1: 159857, cost2: 14334 }
+      ])
+      const chartCategoryLocaleMapping = [
+        { name: 'cost1', value: '계정 1 비용' },
+        { name: 'cost2', value: '계정 2 비용' }
+      ]
+    `,
+        code: `<OpsnowCommonLineChart
+        chartId={chartId}
+        chartRef={chartRef}
+        chartProps={chartProps}
+        chartCategory={chartCategory}
+        chartData={chartData}
+        chartCategoryLocaleMapping={chartCategoryLocaleMapping}
+      />`
+    },
 ];
 export const StackChartExamples = [
     {
@@ -5980,4 +6055,331 @@ export const XyMultiChartExamples = [
         chartUserDefinedFunc={udf()}
       />`
     },
+    {
+        title: 'XY 멀티 차트 - Bullet Label (Line + Stack)',
+        description: 'XY 멀티 차트에서 Line과 Stack 시리즈 모두에 bullet label을 적용하여 데이터 포인트에 값을 표시하는 예제입니다.',
+        code_props_usage: `
+      const chartId = 'xy-multi-bullet-label-${generateUniqueGeneralId()}'
+      const chartRef = useRef(null)
+      const [chartProps, setChartProps] = useState({
+        chart: {
+          paddingTop: 30
+        },
+        xAxis: {
+          type: 'date',
+          dateFormats: [
+            { type: 'day', dateFormat: 'MM-dd' },
+            { type: 'month', dateFormat: 'yy-MM' }
+          ],
+          baseInterval: { timeUnit: 'month', count: 1 },
+          gridHidden: true
+        },
+        yAxis: {
+          type: 'value',
+          extraMax: 0.15,
+          min: 0,
+          numberFormat: '$#,###'
+        },
+        series: {
+          valueXField: 'date',
+          dataProcessor: {
+            dateFields: ['date'],
+            dateFormat: 'yyyy-MM-dd'
+          },
+          seriesTypes: [
+            {
+              type: 'line',
+              order: 'front',
+              categoryGroupName: 'cost_line',
+              bullet: {
+                type: 'label',        // 라벨 타입 bullet
+                locationX: 0.5,
+                locationY: 1,
+                label: {
+                  dy: -10,            // 위로 이동
+                  format: '#,###',    // 숫자 포맷
+                  prefix: '$',        // 달러 기호 접두사
+                  fontSize: 9
+                }
+              }
+            },
+            {
+              type: 'stack',
+              categoryGroupName: 'cost_stack',
+              bullet: {
+                type: 'label',
+                locationX: 0.5,
+                locationY: 1,
+                label: {
+                  dy: -10,
+                  format: '#,###',
+                  prefix: '$',
+                  fontSize: 9
+                }
+              }
+            }
+          ],
+          tooltip: {
+            type: 'CG',
+            header: { name: '{category}' },
+            body: {
+              name: '{name}',
+              value: '\${valueY.formatNumber("#,###")}',
+              useMarker: true
+            }
+          }
+        },
+        legend: { useExtension: false }
+      })
+      const [chartData, setChartData] = useState([
+        { date: '2024-10-01', totalCost: 79580, cloudCost: 50000, onpremCost: 29580 },
+        { date: '2024-11-01', totalCost: 95812, cloudCost: 60000, onpremCost: 35812 },
+        { date: '2024-12-01', totalCost: 182965, cloudCost: 120000, onpremCost: 62965 },
+        { date: '2025-01-01', totalCost: 178695, cloudCost: 115000, onpremCost: 63695 },
+        { date: '2025-02-01', totalCost: 103273, cloudCost: 70000, onpremCost: 33273 },
+        { date: '2025-03-01', totalCost: 122976, cloudCost: 82000, onpremCost: 40976 },
+        { date: '2025-04-01', totalCost: 151876, cloudCost: 100000, onpremCost: 51876 },
+        { date: '2025-05-01', totalCost: 288608, cloudCost: 190000, onpremCost: 98608 },
+        { date: '2025-06-01', totalCost: 146040, cloudCost: 95000, onpremCost: 51040 },
+        { date: '2025-07-01', totalCost: 151794, cloudCost: 100000, onpremCost: 51794 },
+        { date: '2025-08-01', totalCost: 147177, cloudCost: 97000, onpremCost: 50177 },
+        { date: '2025-09-01', totalCost: 196047, cloudCost: 130000, onpremCost: 66047 }
+      ])
+      const [chartCategory, setChartCategory] = useState([
+        { name: 'cost_line', categories: ['totalCost'] },
+        { name: 'cost_stack', categories: ['cloudCost', 'onpremCost'] }
+      ])
+      const chartCategoryLocaleMapping = [
+        { name: 'totalCost', value: '총 비용' },
+        { name: 'cloudCost', value: '클라우드 비용' },
+        { name: 'onpremCost', value: '온프레미스 비용' }
+      ]
+    `,
+        code: `<OpsnowCommonXyMultiChart
+        chartId={chartId}
+        chartRef={chartRef}
+        chartProps={chartProps}
+        chartCategory={chartCategory}
+        chartData={chartData}
+        chartCategoryLocaleMapping={chartCategoryLocaleMapping}
+      />`
+    },
+    {
+        title: 'XY 멀티 차트 - Bullet Label (Dual Axis: Bar + Line)',
+        description: 'Dual Axis(Y축 2개) 차트에서 Bar와 Line 시리즈에 각각 다른 bullet label을 적용하는 예제입니다. 비용(Bar)에는 달러 기호, 증감률(Line)에는 % 기호를 사용합니다.',
+        code_props_usage: `
+      const chartId = 'xy-multi-dual-axis-${generateUniqueGeneralId()}'
+      const chartRef = useRef(null)
+      const [chartProps, setChartProps] = useState({
+        chart: {
+          paddingTop: 30,
+          paddingRight: 50
+        },
+        xAxis: {
+          type: 'date',
+          dateFormats: [
+            { type: 'day', dateFormat: 'MM-dd' },
+            { type: 'month', dateFormat: 'MMM\\nyyyy' }
+          ],
+          baseInterval: { timeUnit: 'month', count: 1 },
+          gridHidden: true
+        },
+        yAxis: {
+          type: 'value',
+          numberFormat: "'$'#,###",
+          extraMax: 0.15,
+          min: 0
+        },
+        yAxis2: {
+          type: 'value',
+          numberFormat: "#'%'",
+          opposite: true,
+          gridHidden: true
+        },
+        series: {
+          valueXField: 'date',
+          dataProcessor: {
+            dateFields: ['date'],
+            dateFormat: 'yyyy-MM-dd'
+          },
+          seriesTypes: [
+            {
+              type: 'bar',
+              categoryGroupName: 'bar_group',
+              bullet: {
+                type: 'label',
+                locationX: 0.5,
+                locationY: 1,
+                label: {
+                  dy: -5,
+                  format: '#,###',
+                  prefix: '$',        // 비용에 달러 기호
+                  fontSize: 9
+                }
+              }
+            },
+            {
+              type: 'line',
+              order: 'front',
+              categoryGroupName: 'line_group',
+              yAxis: 'yAxis2',         // 두 번째 Y축 사용
+              bullet: {
+                type: 'label',
+                locationX: 0.5,
+                locationY: 1,
+                label: {
+                  dy: -10,
+                  format: '#.#',
+                  suffix: '%',        // 증감률에 % 기호
+                  fontSize: 9
+                }
+              }
+            }
+          ],
+          tooltip: {
+            type: 'CG',
+            header: { name: '{valueX.formatDate("yyyy년 M월")}' },
+            body: {
+              name: '{name}',
+              value: '{valueY}',
+              useMarker: true
+            }
+          }
+        },
+        legend: { useExtension: false }
+      })
+      const [chartData, setChartData] = useState([
+        { date: '2024-10-01', cost: 11255, changeRate: null },
+        { date: '2024-11-01', cost: 18464, changeRate: 64.1 },
+        { date: '2024-12-01', cost: 17335, changeRate: -6.1 },
+        { date: '2025-01-01', cost: 18731, changeRate: 8.1 },
+        { date: '2025-02-01', cost: 20358, changeRate: 8.7 },
+        { date: '2025-03-01', cost: 27291, changeRate: 34.1 },
+        { date: '2025-04-01', cost: 40417, changeRate: 48.1 },
+        { date: '2025-05-01', cost: 39887, changeRate: -1.3 },
+        { date: '2025-06-01', cost: 41529, changeRate: 4.1 },
+        { date: '2025-07-01', cost: 49871, changeRate: 20.1 },
+        { date: '2025-08-01', cost: 50659, changeRate: 1.6 },
+        { date: '2025-09-01', cost: 58388, changeRate: 15.3 }
+      ])
+      const [chartCategory, setChartCategory] = useState([
+        { name: 'bar_group', categories: ['cost'] },
+        { name: 'line_group', categories: ['changeRate'] }
+      ])
+      const chartCategoryLocaleMapping = [
+        { name: 'cost', value: 'Cost' },
+        { name: 'changeRate', value: '증감률' }
+      ]
+      const chartCustomCategory = [
+        { name: 'cost', color: '#C8A2C8' },
+        { name: 'changeRate', color: '#2E4A62' }
+      ]
+    `,
+        code: `<OpsnowCommonXyMultiChart
+        chartId={chartId}
+        chartRef={chartRef}
+        chartProps={chartProps}
+        chartCategory={chartCategory}
+        chartData={chartData}
+        chartCategoryLocaleMapping={chartCategoryLocaleMapping}
+        chartCustomCategory={chartCustomCategory}
+      />`
+    },
+    {
+        title: 'XY 멀티 차트 - Bullet Label (Grouped Bar)',
+        description: 'Grouped Bar 차트에서 bullet label을 사용하여 각 바 위에 값을 표시하는 예제입니다. text 속성으로 amCharts5 포맷 문자열을 직접 사용할 수 있습니다.',
+        code_props_usage: `
+      const chartId = 'xy-multi-grouped-bar-${generateUniqueGeneralId()}'
+      const chartRef = useRef(null)
+      const [chartProps, setChartProps] = useState({
+        chart: {
+          paddingTop: 30
+        },
+        xAxis: {
+          type: 'date',
+          dateFormats: [
+            { type: 'day', dateFormat: 'MM-dd' },
+            { type: 'month', dateFormat: 'yy년 M월' }
+          ],
+          baseInterval: { timeUnit: 'month', count: 1 },
+          gridHidden: true,
+          cellStartLocation: 0.1,
+          cellEndLocation: 0.9
+        },
+        yAxis: {
+          type: 'value',
+          numberFormat: '$#,###',
+          extraMax: 0.08
+        },
+        series: {
+          valueXField: 'date',
+          dataProcessor: {
+            dateFields: ['date'],
+            dateFormat: 'yyyy-MM-dd'
+          },
+          bullet: {
+            type: 'label',
+            locationX: 0.5,
+            locationY: 1,
+            label: {
+              dy: -2,
+              text: '\${valueY.formatNumber("#,###")}',  // amCharts5 포맷 문자열 직접 사용
+              fontSize: 9
+            }
+          },
+          seriesTypes: [
+            {
+              type: 'bar',
+              categoryGroupName: 'cost_group',
+              grouped: true
+            }
+          ],
+          tooltip: {
+            type: 'CG',
+            header: { name: '{valueX.formatDate("yyyy년 M월")}' },
+            body: {
+              name: '{name}',
+              value: '\${valueY.formatNumber("#,###")}',
+              useMarker: true
+            }
+          }
+        },
+        legend: { useExtension: false }
+      })
+      const [chartData, setChartData] = useState([
+        { date: '2024-10-01', costUsd: 79580, cloudCost: 81530 },
+        { date: '2024-11-01', costUsd: 95812, cloudCost: 98903 },
+        { date: '2024-12-01', costUsd: 182965, cloudCost: 188854 },
+        { date: '2025-01-01', costUsd: 178695, cloudCost: 184359 },
+        { date: '2025-02-01', costUsd: 103273, cloudCost: 106587 },
+        { date: '2025-03-01', costUsd: 122976, cloudCost: 126556 },
+        { date: '2025-04-01', costUsd: 151876, cloudCost: 155737 },
+        { date: '2025-05-01', costUsd: 288608, cloudCost: 296687 },
+        { date: '2025-06-01', costUsd: 146040, cloudCost: 149912 },
+        { date: '2025-07-01', costUsd: 151794, cloudCost: 155419 },
+        { date: '2025-08-01', costUsd: 147177, cloudCost: 150342 },
+        { date: '2025-09-01', costUsd: 220261, cloudCost: 196047 }
+      ])
+      const [chartCategory, setChartCategory] = useState([
+        { name: 'cost_group', categories: ['costUsd', 'cloudCost'] }
+      ])
+      const chartCategoryLocaleMapping = [
+        { name: 'costUsd', value: 'Cost(USD, 청구)' },
+        { name: 'cloudCost', value: '클라우드 사용요금' }
+      ]
+      const chartCustomCategory = [
+        { name: 'costUsd', color: '#6B8E23' },
+        { name: 'cloudCost', color: '#1976d2' }
+      ]
+    `,
+        code: `<OpsnowCommonXyMultiChart
+        chartId={chartId}
+        chartRef={chartRef}
+        chartProps={chartProps}
+        chartCategory={chartCategory}
+        chartData={chartData}
+        chartCategoryLocaleMapping={chartCategoryLocaleMapping}
+        chartCustomCategory={chartCustomCategory}
+      />`
+    },
 ];