# CQA Test App - MCP Server Implementation

## Overview

CQA Test App에 Flava MCP Hub 검증을 위한 MCP(Model Context Protocol) 서버를 구현합니다.

이 페이지에서는 CQA Test App에 Jira API client를 추가하고, 이를 MCP tools로 구현하여 chat 인터페이스를 통해 동작을 검증하는 전체 과정을 설명합니다.

### MCP 서버 구현 과정

1. **MCP Protocol 이해**: MCP는 AI 모델과 외부 도구 간의 표준화된 통신 프로토콜
2. **도구 정의**: Jira API를 MCP tool로 래핑하여 표준화된 인터페이스 제공
3. **서버 구현**: `mcp` 라이브러리를 사용한 독립형 서버 및 Flask 통합 API 구축
4. **연결 설정**: stdio, HTTP 등 다양한 전송 방식 지원
5. **Hub 연동**: Flava MCP Hub에 서버 등록 및 검증

### 구현 요구사항

- **MCP Streamable HTTP**: HTTP 기반 MCP 프로토콜 구현
- **Jira Integration**: `pip install jira` - Jira API 클라이언트
- **Flask Framework**: 기존 CQA Test App과의 통합
- **Authentication**: Jira Personal Access Token 인증
- **Error Handling**: 안정적인 도구 실행 및 예외 처리

### 연결 방식

1. **Flask Integration with MCP Streamable HTTP**
   ```bash
   python run_cqa_test_app.py  # Flask 앱 + MCP Streamable HTTP API
   ```

2. **Docker Container**
   ```bash
   docker build -t cqa-test-app .
   docker run -p 80:80 --env-file .env cqa-test-app
   ```

3. **MCP Hub 연동**
   - Hub에서 MCP Streamable HTTP 엔드포인트 등록
   - 도구 목록 자동 검색 및 실행
   - 실시간 상태 모니터링

## 목적

- **Flava MCP Hub 검증**: MCP Hub에 서버를 등록하고 동작을 검증
- **QA 자동화**: Jira 연동을 통한 이슈 관리 자동화  
- **테스트 도구 통합**: 기존 CQA 테스트 기능을 MCP 환경에서 활용
- **프로토콜 표준화**: 다양한 QA 도구를 MCP 표준으로 통합

## 주요 기능

### 🎯 MCP Tools 제공
- **Jira Integration**: 프로젝트 조회, 이슈 검색, 티켓 생성 등
- **System Tools**: 명령 실행, 네트워크 테스트 등
- **QA Testing**: 기존 CQA 테스트 기능들의 MCP 인터페이스

### 🔧 실행 모드
- **Flask Integration**: Flask 앱과 통합된 HTTP API
- **Web UI**: 브라우저 기반 테스트 인터페이스

## 빠른 시작

### 1. 환경 설정

```bash
# 프로젝트 클론
git clone <repository-url>
cd cqa-test-app

# 환경 변수 설정
cp .env.example .env
# .env 파일을 편집하여 Jira 크리덴셜 설정
```

### 2. 의존성 설치

```bash
pip install -r requirements.txt
```

### 3. Jira 인증 설정

`.env` 파일에 다음 중 하나를 설정:

```bash
# Jira Personal Access Token
JIRA_URL=https://your-domain.atlassian.net
JIRA_PERSONAL_TOKEN=your-personal-access-token
```

### 4. 실행

```bash
# Flask 앱 실행 (MCP Streamable HTTP API 포함)
python run_cqa_test_app.py

# 또는 Docker 실행
docker build -t cqa-test-app .
docker run -p 80:80 --env-file .env cqa-test-app
```

## MCP Tools 목록

| Tool Name | 설명 | 매개변수 |
|-----------|------|----------|
| `jira_list_projects` | Jira 프로젝트 목록 조회 | 없음 |
| `jira_search_issues` | JQL을 사용한 이슈 검색 | `jql`, `max_results` |
| `jira_get_issue` | 특정 이슈 상세 정보 조회 | `issue_key` |
| `jira_get_comments` | 이슈 댓글 조회 | `issue_key` |
| `jira_create_issue` | 새 이슈 생성 | `project_key`, `summary`, `description`, `issue_type`, `priority` |
| `run_command` | 시스템 명령 실행 | `command` |
| `network_test` | iperf3 네트워크 성능 테스트 | `server`, `port`, `duration` |

## 테스트 방법

### 자동화된 테스트
```bash
# 통합 테스트 실행
python test_jira_integration.py
```

### 수동 테스트
```bash
# 웹 UI 테스트
http://localhost/jira_test_ui/

# MCP Streamable HTTP 테스트 (Claude Code 연동용)
curl -X POST http://localhost/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}'

# REST API 직접 테스트
curl http://localhost/api/mcp/tools
curl -X POST http://localhost/api/mcp/execute \
  -H "Content-Type: application/json" \
  -d '{"tool_name": "jira_list_projects", "arguments": {}}'
```

## Flava MCP Hub 연동

### MCP 서버 등록
1. Flava MCP Hub에 서버 정보 등록
2. **MCP Streamable HTTP 엔드포인트**: `http://your-server/mcp`
3. **REST API 엔드포인트**: `http://your-server/api/mcp/` (대체 접근 방식)
4. 인증 정보 및 환경 변수 설정

#### Claude Code 연동 설정
```json
{
  "mcpServers": {
    "cqa-test-app": {
      "command": "docker",
      "args": ["run", "--rm", "-p", "8080:80", "--env-file", ".env", "cqa-test-app"],
      "transport": {
        "type": "http",
        "host": "localhost",
        "port": 8080,
        "path": "/mcp"
      }
    }
  }
}
```

### 검증 시나리오
- MCP Hub에서 Jira tools 호출 테스트
- 프로젝트 조회 및 이슈 검색 검증
- 에러 핸들링 및 응답 형식 확인

## 디렉토리 구조

```
cqa-test-app/
├── README_MCP.md              # 이 파일
├── run_cqa_test_app.py        # Flask 앱 (MCP Streamable HTTP 포함)
├── lib/
│   └── jira_client.py         # Jira API 클라이언트
├── products/
│   ├── jira/api.py           # Jira REST API
│   ├── mcp/api.py            # MCP REST API
│   └── mcp/streamable_http.py # MCP Streamable HTTP Protocol
├── templates/
│   └── jira_test.html        # 웹 테스트 UI
├── docs/                     # 상세 문서들
├── Dockerfile                # Docker 컨테이너 설정
└── test_jira_integration.py  # 통합 테스트
```

## 다음 단계

- [아키텍처 문서](docs/mcp-architecture.md) - 시스템 구조 및 다이어그램
- [Jira 도구 가이드](docs/jira-tools.md) - Jira 연동 상세 설명
- [배포 가이드](docs/deployment-guide.md) - 프로덕션 배포 방법
- [테스트 가이드](docs/testing-guide.md) - 상세 테스트 시나리오

## 지원 및 문의

- **이슈 트래킹**: GitHub Issues
- **문서**: `docs/` 디렉토리
- **테스트**: `test_jira_integration.py` 실행

---

> 이 프로젝트는 Flava MCP Hub 검증 및 QA 자동화를 위해 개발되었습니다.