# Gemini + MCP 데모 스크립트 v4: 기술 스택 및 구현 방향

## 기술 스택 결정

### Core Dependencies

```json
{
  "dependencies": {
    "@google/genai": "^1.0.0",
    "typescript": "^5.0.0",
    "node-fetch": "^3.0.0"
  },
  "devDependencies": {
    "@types/node": "^20.0.0",
    "tsx": "^4.0.0"
  }
}
```

### 1. @google/genai
- Google 공식 Gemini SDK
- TypeScript 네이티브 지원
- Function calling 완벽 지원
- MCP 연동 가능성 명시

### 2. Node.js + TypeScript
- 타입 안전성
- 최신 ECMAScript 기능
- async/await 지원
- 디버깅 용이

### 3. Vercel MCP Server
- HTTP transport 지원
- 공개 접근 가능
- 별도 설치 불필요
- Vercel API 기능 제공

### 4. node-fetch (또는 내장 fetch)
- HTTP 요청을 위한 라이브러리
- Node.js 18+ 에서는 내장 fetch 사용 가능

## 구현 아키텍처

### 전체 플로우

```
┌─────────────────┐
│     User        │
│   (Question)    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Gemini Client  │ ◄── 우리가 작성할 메인 코드
│  (gemini-mcp-   │
│   client.ts)    │
└────┬──────┬─────┘
     │      │
     │      │ 1. Get available tools
     │      ▼
     │   ┌──────────────┐
     │   │ MCP Adapter  │ ◄── MCP ↔ Gemini 변환
     │   └──────┬───────┘
     │          │
     │          │ 2. HTTP Request
     │          ▼
     │   ┌──────────────┐
     │   │ Vercel MCP   │
     │   │   Server     │
     │   └──────┬───────┘
     │          │
     │          │ 3. Response
     │          ▼
     │   ┌──────────────┐
     │   │ MCP Adapter  │
     │   └──────┬───────┘
     │          │
     │ 4. Send │
     │ to      │
     │ Gemini  │
     ▼         ▼
┌─────────────────┐
│  Gemini Model   │
│  (generates     │
│   response)     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   Final Answer  │
└─────────────────┘
```

### 주요 컴포넌트

#### 1. MCP Adapter
MCP server와 통신하고 Gemini 형식으로 변환

```typescript
class MCPAdapter {
  // MCP server에서 사용 가능한 tools 가져오기
  async getTools(): Promise<Tool[]>

  // MCP tool schema를 Gemini FunctionDeclaration으로 변환
  convertToFunctionDeclaration(mcpTool): FunctionDeclaration

  // Gemini function call을 MCP server로 전달
  async callMCPTool(name: string, args: any): Promise<any>
}
```

#### 2. Gemini Client
Gemini 모델과 대화 관리

```typescript
class GeminiMCPClient {
  private adapter: MCPAdapter
  private model: GenerativeModel

  // 대화 초기화
  async initialize()

  // 메시지 전송 및 응답 처리
  async chat(message: string): Promise<string>

  // Function call 처리
  private async handleFunctionCalls(calls: FunctionCall[])
}
```

## 데모 시나리오

### 시나리오 1: Vercel 배포 정보 조회

```
User: "최근 Vercel 배포 상태를 알려줘"
  ↓
Gemini: get_deployments() 호출 결정
  ↓
MCP Adapter: Vercel MCP server로 요청
  ↓
Vercel MCP: 배포 정보 반환
  ↓
Gemini: 정보를 자연어로 요약
  ↓
Output: "최근 3개의 배포가 성공했습니다..."
```

### 시나리오 2: 프로젝트 정보 조회

```
User: "내 Vercel 프로젝트 목록을 보여줘"
  ↓
Gemini: get_projects() 호출 결정
  ↓
... (위와 동일한 플로우)
```

## 구현 단계

### Phase 1: MCP Adapter 구현
- [ ] Vercel MCP server HTTP endpoint 확인
- [ ] MCP protocol 이해
- [ ] Tool list 가져오기 구현
- [ ] Schema 변환 로직 구현

### Phase 2: Gemini Client 구현
- [ ] Gemini SDK 초기화
- [ ] Function declarations 설정
- [ ] Chat session 관리
- [ ] Function call 처리 로직

### Phase 3: 통합 및 테스트
- [ ] End-to-end 플로우 테스트
- [ ] 에러 처리
- [ ] 로깅 추가
- [ ] 예제 시나리오 작성

### Phase 4: 개선
- [ ] 멀티턴 대화 지원
- [ ] 캐싱 추가
- [ ] 성능 최적화

## 환경 변수

```bash
# .env
GEMINI_API_KEY=your_gemini_api_key
VERCEL_TOKEN=your_vercel_token  # Vercel MCP server 인증용
MCP_SERVER_URL=https://vercel-mcp-server-url  # Vercel MCP endpoint
```

## 디렉토리 구조

```
src/
├── index.ts                 # Entry point
├── gemini-client.ts         # Gemini 클라이언트
├── mcp-adapter.ts           # MCP 어댑터
├── types.ts                 # TypeScript 타입 정의
└── examples/
    ├── simple-chat.ts       # 기본 대화 예제
    └── deployment-check.ts  # 배포 확인 예제
```

## 기술적 고려사항

### 1. Schema 변환
MCP와 Gemini 모두 JSON Schema를 사용하지만:
- 필드명 차이 가능
- 타입 표현 방식 차이
- 주의 깊은 매핑 필요

### 2. 에러 핸들링
- 네트워크 오류
- MCP server 오류
- Gemini API 오류
- 각 레이어별 적절한 처리 필요

### 3. 인증
- Gemini API key
- Vercel token
- 환경 변수로 안전하게 관리

### 4. Rate Limiting
- Gemini API 호출 제한
- MCP server 호출 제한
- 적절한 재시도 로직

## 다음 단계

v5에서는 Vercel MCP Server의 실제 endpoint와 사용 가능한 tools를 조사하고, 연결 테스트를 진행할 것이다.

---

**작성일**: 2025-11-26
**예상 개발 시간**: 4-6시간