# MCP Architecture Diagrams

## 전체 아키텍처 개요

```mermaid
graph TB
    subgraph "Client Interfaces"
        A[Chat Client/Claude Desktop]
        A1[Direct HTTP Client]
        A2[Web Browser]
    end
    
    subgraph "Flava MCP Hub"
        B[MCP Hub Server]
        C[Hub Management]
        D[Tool Registry]
    end
    
    subgraph "CQA Test App"
        E[MCP Server Implementation]
        F[Jira API Client]
        G[Flask Web Server]
        H[Test Tools]
        I[HTTP API Endpoints]
        J[Web UI]
    end
    
    subgraph "External Services"
        K[Jira Server]
        L[Other APIs]
    end
    
    %% MCP Hub connection
    A <-->|MCP Protocol| B
    B <-->|Tool Execution| E
    
    %% Direct connections (Remote MCP Server)
    A1 <-->|MCP Streamable HTTP<br/>POST /mcp| E
    A1 <-->|REST API<br/>POST /api/mcp/execute| I
    A2 <-->|Web Interface| J
    
    %% Internal connections
    E <-->|Jira Operations| F
    F <-->|REST API| K
    E <--> G
    E <--> H
    G <--> I
    G <--> J
    G <--> L
    
    %% Hub internal
    B --> C
    B --> D
    
    %% Styling
    classDef clientStyle fill:#e1f5fe
    classDef hubStyle fill:#f3e5f5
    classDef appStyle fill:#e8f5e8
    classDef externalStyle fill:#fff3e0
    
    class A,A1,A2 clientStyle
    class B,C,D hubStyle
    class E,F,G,H,I,J appStyle
    class K,L externalStyle
```

### 다양한 클라이언트 연결 방식

1. **MCP Hub를 통한 연결**
   - Chat Client → Flava MCP Hub → CQA Test App MCP Server
   - 표준 MCP 프로토콜 사용
   - Hub에서 도구 관리 및 라우팅

2. **Remote MCP Server 연결 (Claude Code)**
   - HTTP Client → `/mcp` 엔드포인트 (MCP Streamable HTTP)
   - 표준 MCP 프로토콜을 HTTP로 구현
   - Docker 컨테이너로 배포

3. **REST API 연결**
   - HTTP Client → `/api/mcp/execute` 엔드포인트
   - REST API 형태로 MCP 도구 실행
   - `curl`, Postman 등으로 테스트 가능

4. **웹 UI 연결**
   - Web Browser → `/jira_test_ui/` 페이지
   - 사용자 친화적인 테스트 인터페이스
   - 실시간 결과 확인 가능

## MCP 서버 구현 구조

```mermaid
graph LR
    subgraph "MCP Protocol Layer"
        A[streamable_http.py]
        B[JSON-RPC 2.0 Handler]
        C[Tool Registry]
    end
    
    subgraph "Business Logic Layer"
        D[jira_client.py]
        E[API Functions]
        F[PAT Authentication]
    end
    
    subgraph "Integration Layer"
        G[Flask Blueprints]
        H[HTTP Endpoints]
        I[Web UI]
    end
    
    A --> B
    B --> C
    C --> D
    D --> E
    E --> F
    
    A --> G
    G --> H
    H --> I
```

## Jira Tools 실행 플로우

```mermaid
sequenceDiagram
    participant Chat as Chat Interface
    participant Hub as Flava MCP Hub
    participant MCP as MCP Server
    participant Jira as Jira Client
    participant API as Jira API
    
    Chat->>Hub: "Jira에서 최근 이슈 검색해줘"
    Hub->>MCP: call_tool("jira_search_issues", {"jql": "..."})
    MCP->>Jira: search_issues(jql, max_results)
    Jira->>API: GET /search?jql=...
    API-->>Jira: JSON Response
    Jira-->>MCP: Parsed Issues List
    MCP-->>Hub: Tool Result (JSON)
    Hub-->>Chat: Formatted Response
```

## 배포 아키텍처

```mermaid
graph TB
    subgraph "Development Environment"
        A[Local Flask App]
        B[MCP Streamable HTTP]
        C[Local Jira Access]
    end
    
    subgraph "Claude Code Environment"
        D[Docker Container]
        E[MCP Client]
        F[Tool Execution]
    end
    
    subgraph "Production Environment"
        G[Containerized MCP Server]
        H[Environment Variables]
        I[Monitoring & Logs]
    end
    
    A -->|Development Testing| E
    B --> D
    G -->|Production Deployment| E
    H --> G
    I --> G
    
    E --> F
    D --> B
```

## MCP Tools 매핑

```mermaid
graph LR
    subgraph "MCP Tools"
        A[jira_list_projects]
        B[jira_search_issues]
        C[jira_get_issue]
        D[jira_get_comments]
        E[jira_create_issue]
    end
    
    subgraph "Jira Client Methods"
        F[list_projects()]
        G[search_issues()]
        H[get_issue()]
        I[get_issue_comments()]
        J[create_issue()]
    end
    
    subgraph "Jira REST API"
        K[GET /project]
        L[GET /search]
        M[GET /issue/{key}]
        N[GET /issue/{key}/comment]
        O[POST /issue]
    end
    
    A --> F --> K
    B --> G --> L
    C --> H --> M
    D --> I --> N
    E --> J --> O
```

## 연결 방식별 구조

### Flask Integration

```mermaid
graph TB
    A[run_cqa_test_app.py] --> B[Flask App]
    B --> C[MCP Streamable HTTP Blueprint]
    B --> D[MCP REST API Blueprint]
    C --> E[JSON-RPC Handler]
    D --> F[REST Endpoints]
    E --> G[Tool Execution]
    F --> G
    G --> H[Jira Client]
    H --> I[Jira API]
    
    B --> J[Web UI]
    B --> K[Other Blueprints]
```

### Remote MCP Server Integration (Claude Code)

```mermaid
graph TB
    A[Claude Code] --> B[Docker Container]
    B --> C[MCP Client]
    C --> D[HTTP Request to /mcp]
    D --> E[JSON-RPC 2.0 Handler]
    E --> F[Tool Dispatcher]
    F --> G[Jira Client]
    
    A --> H[User Interface]
    H --> I[Natural Language Processing]
    I --> J[Tool Selection]
    J --> C
```

## 에러 처리 플로우

```mermaid
graph TD
    A[Tool Execution Request] --> B{Jira Connection OK?}
    B -->|No| C[Return Connection Error]
    B -->|Yes| D[Execute Jira API Call]
    D --> E{API Call Success?}
    E -->|No| F[Return API Error]
    E -->|Yes| G[Process Response]
    G --> H{Data Valid?}
    H -->|No| I[Return Data Error]
    H -->|Yes| J[Return Success Result]
    
    C --> K[Error Response to Hub]
    F --> K
    I --> K
    J --> L[Success Response to Hub]
```