MCP_INSTALLATION.md•6.05 kB
# WhaTap MXQL MCP 서버 설치 가이드
## 🎯 개요
WhaTap MXQL을 Claude Code에서 사용하기 위한 두 가지 컴포넌트:
1. **MCP Tools** (이 프로젝트) - WhaTap API 실행 도구
2. **Skill** (mxql-for-claude-code) - MXQL 생성 지식/가이드
## 📦 1. MCP Tools 설치 (whatap-mxql)
### 빌드 및 설치
```bash
cd whatap-mxql-cli
# 의존성 설치
npm install
# 빌드
npm run build
# bin 실행 권한 부여
chmod +x bin/whatap-mxql-mcp
```
### Claude Code에 등록
MCP 서버 설정 파일을 Claude Code 설정에 추가합니다.
```bash
# Claude Code MCP 설정 디렉토리 생성 (없는 경우)
mkdir -p ~/.claude/mcp
# MCP 서버 설정 파일 복사 (경로 수정 필요)
cat > ~/.claude/mcp/whatap-mxql.json << 'EOF'
{
"mcpServers": {
"whatap-mxql": {
"command": "node",
"args": [
"/Users/devload/whatap/mxqlMCPWork/whatap-mxql-cli/dist/mcp/index.js"
],
"description": "WhaTap MXQL Query Executor - Execute MXQL queries on WhaTap monitoring data"
}
}
}
EOF
# ⚠️ 중요: 위 경로를 실제 설치 경로로 변경하세요!
# 절대 경로를 사용해야 합니다.
```
또는 수동으로 `~/.claude/mcp/whatap-mxql.json` 파일을 생성하세요:
```json
{
"mcpServers": {
"whatap-mxql": {
"command": "node",
"args": [
"/절대/경로/whatap-mxql-cli/dist/mcp/index.js"
],
"description": "WhaTap MXQL Query Executor"
}
}
}
```
### 사용 가능한 Tools
#### 1. `login`
WhaTap 서비스에 로그인합니다.
```typescript
{
email: string,
password: string,
serviceUrl?: string // 기본값: https://service.whatap.io
}
```
#### 2. `getProjects`
프로젝트 목록을 조회합니다.
```typescript
{
filter?: string // 프로젝트 타입 필터 (MOBILE, BROWSER 등)
}
```
#### 3. `executeMxql`
MXQL 쿼리를 실행합니다.
```typescript
{
pcode: number,
mxql: string,
stime?: number, // Unix timestamp (ms)
etime?: number, // Unix timestamp (ms)
limit?: number // 기본값: 100
}
```
#### 4. `getCategory`
카테고리 데이터를 조회합니다 (편의 메서드).
```typescript
{
pcode: number,
category: string,
timeRange?: string, // 1h, 6h, 24h, 7d, 30d (기본값: 1h)
limit?: number // 기본값: 100
}
```
## 📚 2. Skill 설치 (mxql-for-claude-code)
### 저장소 클론
```bash
cd /tmp
git clone https://github.com/kyupid/mxql-for-claude-code.git
cd mxql-for-claude-code
```
### 설치
```bash
# 설치 스크립트 실행
./install.sh
```
설치 스크립트는 다음을 수행합니다:
- `~/.claude/skills` 디렉토리 생성
- mxql skill을 skills 디렉토리에 링크
- 631개 카테고리 메타데이터 설치
- Python 유틸리티 (validator, category finder 등) 설치
## ✅ 설치 확인
### MCP Tools 확인
Claude Code를 재시작하고 다음 명령어로 확인:
```
Claude, list available tools
```
다음 tools가 보여야 합니다:
- whatap.login
- whatap.getProjects
- whatap.executeMxql
- whatap.getCategory
### Skill 확인
Claude Code에서 다음과 같이 요청:
```
What MXQL categories are available for PostgreSQL?
```
Skill이 제대로 설치되었다면 PostgreSQL 관련 카테고리 목록을 보여줍니다.
## 🚀 사용 예시
### 예시 1: 간단한 쿼리 실행
```
사용자: "PostgreSQL CPU 사용률 조회해줘"
Claude:
1. (Skill 참조) PostgreSQL 카테고리는 db_postgresql_counter
2. (Tool 실행) whatap.getProjects() → 프로젝트 목록 확인
3. (Tool 실행) whatap.executeMxql({
pcode: 27506,
mxql: "CATEGORY db_postgresql_counter"
})
4. 결과 분석 및 응답
```
### 예시 2: 복잡한 쿼리 생성 및 실행
```
사용자: "Kubernetes에서 CPU 90% 이상인 Pod를 네임스페이스별로 그룹핑해서 보여줘"
Claude:
1. (Skill 참조) Kubernetes Pod 카테고리 및 MXQL 패턴 학습
2. (Skill 기반) MXQL 쿼리 생성:
CATEGORY kube_pod
FILTER {cpu_usage > 90}
SELECT [namespace, pod_name, cpu_usage]
GROUP [namespace]
3. (Tool 실행) whatap.getProjects({filter: "KUBERNETES"})
4. (Tool 실행) whatap.executeMxql({pcode, mxql: "..."})
5. 결과 분석 및 시각화
```
### 예시 3: 데이터 분석
```
사용자: "지난 24시간 동안 애플리케이션 에러율 추이 분석해줘"
Claude:
1. (Skill 참조) 애플리케이션 에러 카테고리 및 집계 패턴
2. (Tool 실행) whatap.executeMxql({
pcode: 27506,
mxql: "CATEGORY app_counter SELECT [time, error_rate]",
stime: Date.now() - 86400000,
etime: Date.now()
})
3. 데이터 분석 및 인사이트 제공
```
## 🔄 업데이트
### MCP Tools 업데이트
```bash
cd whatap-mxql-cli
git pull
npm install
npm run build
```
### Skill 업데이트
```bash
cd ~/.claude/skills/mxql # 또는 실제 설치 경로
git pull
```
## 🛠️ 문제 해결
### MCP 서버가 인식되지 않음
1. Claude Code 재시작
2. MCP 설정 파일 경로 확인
3. 빌드 완료 여부 확인 (`dist/mcp/index.js` 파일 존재)
4. 로그 확인: Claude Code → Developer Tools → Console
### Skill이 작동하지 않음
1. 설치 경로 확인: `ls ~/.claude/skills/`
2. Skill 파일 확인: `ls ~/.claude/skills/mxql/`
3. Claude Code 재시작
### 로그인 실패
```bash
# 수동으로 로그인 테스트
./bin/whatap-mxql login
# MCP를 통한 로그인
# Claude Code에서: "login to whatap with email@example.com"
```
## 📖 추가 문서
- [CLI 사용 가이드](./CLI_GUIDE.md)
- [검증 보고서](./VERIFICATION_REPORT.md)
- [자동 로그인 기능](./AUTO_LOGIN_DEMO.md)
- [mxql-for-claude-code README](https://github.com/kyupid/mxql-for-claude-code)
## 🎯 완성!
이제 Claude Code에서 자연어로 MXQL 쿼리를 생성하고 실제 WhaTap 데이터를 조회할 수 있습니다! 🎉
```
사용자: "지난 7일간 데이터베이스 슬로우 쿼리 top 10 보여줘"
Claude: (Skill로 MXQL 생성) → (MCP Tool로 실행) → (결과 분석) → 응답
```