npm package: @opsnow-mcp/opsnow-mcp-common-ui-server
Description: OpsNow MCP Common UI Server - Model Context Protocol implementation for common UI components
Author: OpsNow
Latest version: 1.0.23

# OpsNow MCP Common UI Server

## Installation

Install the globally-available CLI from npm (선택사항):

```bash
npm install -g @opsnow-mcp/opsnow-mcp-common-ui-server
```

## Usage

### Claude Desktop Configuration

To integrate with Claude Desktop, add the following snippet to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "opsnow-mcp-common-ui-server": {
      "command": "npx",
      "args": [
        "-y",
        "@opsnow-mcp/opsnow-mcp-common-ui-server"
      ]
    }
  }
}
```

### nvm(Node Version Manager) 사용 시 설정 예시

nvm을 사용하여 Node.js 22.x를 설치한 경우, 다음과 같이 설정할 수 있습니다. `{사용자명}` 부분은 본인의 사용자명으로 변경해주세요.

```json
{
  "mcpServers": {
    "opsnow-mcp-common-ui-server": {
      "command": "npx",
      "args": [
        "@opsnow-mcp/opsnow-mcp-common-ui-server"
      ],
      "env": {
        "NODE_EXTRA_CA_CERTS": "/Users/{사용자명}/ZscalerRootCA.pem",
        "PATH": "/Users/{사용자명}/.nvm/versions/node/v22.14.0/bin:/usr/local/bin:/usr/bin:/bin",
        "NODE_PATH": "/Users/{사용자명}/.nvm/versions/node/v22.14.0/lib/node_modules"
      }
    }
  }
}
```

> **참고**: 
> 1. `{사용자명}`을 본인의 사용자명으로 변경하세요.
> 2. Node.js 22.x가 설치되어 있는지 확인하세요. 설치가 필요하다면 `nvm install 22` 명령어로 설치할 수 있습니다.
> 3. 사용 중인 Node.js 버전이 22.x가 아니라면, 위 설정에서 `v22.14.0`을 실제 사용 중인 22.x 버전으로 변경하세요.

## 소개
OpsNow MCP Common UI Server는 OpsNow의 공통 UI 컴포넌트(캘린더, 차트, 폼 등)를 Model Context Protocol(MCP)을 통해 AI 기반 어시스턴트 및 기타 MCP 클라이언트에 동적으로 제공하는 서버입니다. 이 서버를 사용하면 사용자가 "캘린더 컴포넌트를 생성해줘"와 같은 자연어 명령으로 UI 컴포넌트를 즉시 생성하고 활용할 수 있습니다.

## 시스템 구조
```mermaid
graph LR
    A[LLM Vendor Desktop App] --> |MCP Protocol| B[OpsNow MCP Common UI Server]:::highlight
    B --> C[OpsNow MCP Provider]
    C --> D[OpsNow Resources]
    
    classDef highlight fill:#2e8b57,stroke:#333,stroke-width:2px;
```
- **LLM Vendor Desktop App**: Claude와 같은 LLM 기반 데스크톱 애플리케이션
- **OpsNow MCP Common UI Server**: 비용 및 사용량 데이터를 MCP 형식으로 제공하는 서버
- **OpsNow MCP Provider**: OpsNow API Bridge를 통해 자원 데이터를 처리
- **OpsNow Resources**: 실제 OpsNow 리소스 데이터를 가정한 목데이터로 구현 (개발 및 테스트 목적)

## 사용 방법

이 MCP 서버는 AI 어시스턴트 또는 기타 MCP 클라이언트를 통해 다음과 같은 자연어 명령으로 OpsNow Common UI 컴포넌트를 생성·활용할 수 있습니다:

- "캘린더 UI를 만들어줘"
- "차트 UI를 만들어줘"
- "인풋 UI를 만들어줘"
- "팝업 UI를 만들어줘"
- "셀렉트상자 UI를 만들어줘"

생성된 컴포넌트 코드는 JSX 형식의 코드 스니펫으로 반환되며, 클라이언트 애플리케이션에 그대로 붙여넣어 사용할 수 있습니다.

## 개발자 가이드
## 프로젝트 구조
```
src/
├── index.ts                    # 메인 MCP 서버 진입점
└── components/                 # 개별 컴포넌트 정의
    ├── opsnow-common-calendar.ts
    ├── opsnow-common-chart.ts
    ├── opsnow-common-data-status.ts
    ├── opsnow-common-dropdown.ts
    ├── opsnow-common-file-upload.ts
    ├── opsnow-common-forms.ts
    ├── opsnow-common-grid.ts
    ├── opsnow-common-icons.ts
    ├── opsnow-common-notification.ts
    ├── opsnow-common-pagination.ts
    ├── opsnow-common-popup.ts
    ├── opsnow-common-progress.ts
    ├── opsnow-common-stepper.ts
    ├── opsnow-common-storage.ts
    ├── opsnow-common-tab.ts
    ├── opsnow-common-tooltip.ts
    ├── opsnow-finops-common-axios.ts
    └── opsnow-finops-common-utils.ts
```

## 지원 컴포넌트
### UI 컴포넌트
- **opsnow-common-calendar**: 캘린더 컴포넌트 - 날짜 선택 및 이벤트 관리
- **opsnow-common-chart**: 차트 컴포넌트 - 다양한 타입의 데이터 시각화
- **opsnow-common-data-status**: 데이터 상태 컴포넌트 - 로딩, 성공, 에러, 빈 상태 표시
- **opsnow-common-dropdown**: 드롭다운 컴포넌트 - 옵션 선택 인터페이스
- **opsnow-common-file-upload**: 파일 업로드 컴포넌트 - 파일 선택 및 업로드 기능
- **opsnow-common-forms**: 폼 컴포넌트 - 다양한 입력 필드와 유효성 검사
- **opsnow-common-data-grid**: 그리드 컴포넌트 - 데이터 테이블 표시 및 관리
- **opsnow-common-icons**: 아이콘 컴포넌트 - 다양한 아이콘 표시
- **opsnow-common-notification**: 알림 컴포넌트 - 토스트 메시지 및 알림 표시
- **opsnow-common-pagination**: 페이지네이션 컴포넌트 - 페이지 이동 및 크기 조절
- **opsnow-common-popup**: 팝업 컴포넌트 - 모달 다이얼로그 표시
- **opsnow-common-progress**: 진행률 컴포넌트 - 작업 진행 상황 표시
- **opsnow-common-stepper**: 스텝퍼 컴포넌트 - 단계별 진행 상황 표시
- **opsnow-common-storage**: 스토리지 컴포넌트 - 로컬/세션 스토리지 및 쿠키 관리
- **opsnow-common-tab**: 탭 컴포넌트 - 탭 인터페이스 및 콘텐츠 관리
- **opsnow-common-tooltip**: 툴팁 컴포넌트 - 요소에 대한 추가 정보 표시

### FinOps 컴포넌트
- **opsnow-finops-common-axios**: Axios 컴포넌트 - HTTP 요청 처리 및 응답 관리
- **opsnow-finops-common-utils**: 유틸리티 컴포넌트 - 공통 유틸리티 함수들 (포맷팅, 검증, 생성 등)

## 기술 스택
- **Node.js**: 서버 런타임
- **TypeScript**: 타입 안전성과 개발자 경험 향상
- **MCP SDK**: Model Context Protocol 구현
- **Zod**: 스키마 검증 및 타입 정의

## 설치 및 시작 방법

### 1. 저장소 클론
```bash
git clone <이 저장소 주소>
cd opsnow-mcp-common-ui
```

### 2. 패키지 설치
```bash
npm install
```

### 3. MCP 서버 실행
```bash
npm start
```


### 4. 빌드 후 실행 테스트
```bash
npm run build && npm start
```

## MCP 도구 사용 예시
각 컴포넌트는 MCP 도구로 등록되어 AI 어시스턴트가 직접 호출할 수 있습니다:

- "캘린더 컴포넌트를 생성해줘"
- "차트 컴포넌트로 데이터를 시각화해줘"
- "폼 컴포넌트로 사용자 입력을 받아줘"
- "그리드 컴포넌트로 데이터를 표시해줘"

## 라이선스
MIT License - 누구나 자유롭게 사용할 수 있습니다.

## 기여하기
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## MCP 플랫폼에 서버 추가 방법

### 1. 프로젝트 빌드
```bash
npm run build
```

### 2. MCP 설정에 서버 등록
MCP 플랫폼의 설정 파일(예: `mcp.config.json` 또는 유사 파일)에 아래와 같이 서버를 추가하세요:

```json
{
  "mcpServers": {
    "opsnow-mcp-common-ui-server": {
      "command": "node",
      "args": [
        "/Users/xxxx/myProject/opsnow-mcp-common-ui-server/build/index.js"
      ]
    }
  }
}
```

- `command`: MCP 서버를 실행할 명령어 (여기서는 node)
- `args`: 빌드된 index.js의 절대 경로

### 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" />`,
  },
];
```