OpsNow MCP Common UI Server

Installation

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

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:

{
  "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를 설치한 경우, 다음과 같이 설정할 수 있습니다. {사용자명} 부분은 본인의 사용자명으로 변경해주세요.

{
  "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 컴포넌트를 즉시 생성하고 활용할 수 있습니다.

시스템 구조

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. 저장소 클론

git clone <이 저장소 주소>
cd opsnow-mcp-common-ui

2. 패키지 설치

npm install

3. MCP 서버 실행

npm start

4. 빌드 후 실행 테스트

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. 프로젝트 빌드

npm run build

2. MCP 설정에 서버 등록

MCP 플랫폼의 설정 파일(예: mcp.config.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 빌드 명령어

# 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를 로컬에서 테스트하려면:

# 프로젝트 루트에서
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):

// .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):

// 파일명: opsnow-common-{component}-examples-data.ts
// Export 명명: {PascalCase}Examples
export const ButtonExamples: Example[] = [
  {
    title: '기본 버튼',
    props: { label: '버튼', size: 'medium' },
    code: `<OpsnowCommonButton label="버튼" size="medium" />`,
  },
];