# 🎯 TOEIC Speaking MCP Server

토익 스피킹 만능문장 암기 테스트를 위한 MCP 서버입니다. Claude Desktop 앱과 연동하여 음성으로 토익 스피킹 문장을 학습하고 즉시 피드백을 받을 수 있습니다.

**출처**: [유튜브 시계토끼제니쌤](https://youtu.be/A14nJjAGqbY?si=T-7GGcWc9rilQd0G)

---

## 📖 목차

- [주요 특징](#-주요-특징)
- [기술 스택](#️-기술-스택)
- [설치 및 설정](#-설치-및-설정)
- [MCP 도구](#️-mcp-도구)
- [사용 예시](#-사용-예시)
- [프로젝트 구조](#-프로젝트-구조)
- [트러블슈팅](#-트러블슈팅)

---

## ✨ 주요 특징

- 🎤 **음성 학습**: Claude Desktop 음성 인식으로 자연스러운 학습
- 🧠 **적응형 출제**: mastery_score 기반 취약 문장 우선 출제
- ⚡ **즉시 피드백**: 키워드 매칭 분석으로 실시간 학습 효과 확인
- 📊 **자동 점수 관리**: 답변 정확도에 따른 자동 점수 업데이트 (0-100)
- 🔒 **타입 안정성**: TypeScript strict 모드 + Zod 스키마 검증

## 🏗️ 기술 스택

- **Framework**: NestJS 11 + TypeScript 5 (strict mode)
- **Protocol**: Model Context Protocol (MCP) SDK
- **Database**: Supabase PostgreSQL
- **Validation**: Zod schema validation
- **Architecture**: Domain-driven layered architecture

## 🚀 설치 및 설정

### 1. 의존성 설치

```bash
npm install
```

### 2. 환경 변수 설정

`.env` 파일 확인:

```env
SUPABASE_URL=your_supabase_url
SUPABASE_ANON_KEY=your_supabase_anon_key
```

### 3. 데이터베이스 마이그레이션

Supabase SQL Editor에서 `migrate.sql` 실행:

```sql
-- mastery_score, last_reviewed_at, review_count 컬럼 추가
-- 인덱스 생성
```

### 4. 샘플 데이터 삽입 (선택 사항)

```bash
node seed.js
```

### 5. 빌드

```bash
npm run build
```

### 6. Claude Desktop 설정

`~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "toeic-speaking": {
      "command": "node",
      "args": ["/절대/경로/dist/main.js"],
      "env": {
        "SUPABASE_URL": "your_url",
        "SUPABASE_ANON_KEY": "your_key"
      }
    }
  }
}
```

⚠️ 경로를 실제 프로젝트 경로로 수정 후 Claude Desktop 재시작

---

## 🛠️ MCP 도구

### 1. `get_quiz_sentence` - 문제 출제

**파라미터**:
- `mode` (선택): `'weak_first'` | `'random'` (기본: `'weak_first'`)
- `part` (선택): 파트 번호 필터

**응답**:
```json
{
  "id": "uuid",
  "sentence_ko": "이 사진은 공원에서 찍힌 사진입니다.",
  "part": 2,
  "current_mastery": 0
}
```

### 2. `verify_answer` - 답변 검증

**파라미터** (필수):
- `sentence_id`: 문장 ID
- `user_answer`: 사용자 답변 (영어 문장)

**응답**:
```json
{
  "success": true,
  "original_sentence": "This is a picture taken at a park.",
  "matched_keywords": ["picture", "taken", "park"],
  "missing_keywords": [],
  "match_rate": "100.0%",
  "score_change": 10,
  "feedback": "Perfect! All keywords matched. Score increased by 10 points."
}
```

**점수 규칙**:
| 매칭률 | 점수 변화 |
|--------|-----------|
| 100% | +10 |
| 70-99% | +5 |
| 50-69% | 0 |
| 0-49% | -5 |

---

## 💬 사용 예시

```
👤 "토익 스피킹 연습 시작할게요"

🤖 [get_quiz_sentence 호출]
   문제: "이 사진은 공원에서 찍힌 사진입니다."
   (현재 숙련도: 0점)

👤 [음성] "This is a picture taken at a park"

🤖 [verify_answer 호출]
   ✅ 완벽합니다!
   - 포함된 키워드: picture, taken, park (3/3)
   - 매칭률: 100.0%
   - 점수 변화: +10점
```

---

## 📁 프로젝트 구조

```
src/
├── main.ts                    # MCP 서버 엔트리포인트
├── app.module.ts              # 루트 모듈
├── config/
│   └── supabase.config.ts     # Supabase DI Provider
├── types/
│   └── sentence.interface.ts  # TypeScript 인터페이스
├── mcp/
│   ├── mcp.module.ts
│   └── mcp.service.ts         # MCP 도구 정의 + Zod 검증
├── quiz/                      # Quiz 도메인
│   ├── quiz.module.ts
│   ├── quiz.service.ts        # 문제 출제 로직
│   └── quiz.repository.ts     # DB 쿼리
└── answer/                    # Answer 도메인
    ├── answer.module.ts
    ├── answer.service.ts      # 키워드 매칭 알고리즘
    └── answer.repository.ts   # 점수 업데이트
```

**아키텍처**:
```
Claude Desktop (stdio)
    ↓
MCP Layer (Zod 검증)
    ↓
Domain Layer (Quiz/Answer)
    ↓
Supabase PostgreSQL
```

---

## 🗄️ 데이터베이스 스키마

| 컬럼 | 타입 | 설명 |
|------|------|------|
| `id` | uuid | PK |
| `part` | integer | TOEIC 파트 번호 |
| `sentence_en` | text | 영어 원문 (정답) |
| `sentence_ko` | text | 한국어 번역 (문제) |
| `keywords` | text[] | 핵심 키워드 배열 |
| `mastery_score` | integer | 학습 숙련도 (0-100) |
| `last_reviewed_at` | timestamptz | 마지막 복습 시각 |
| `review_count` | integer | 총 복습 횟수 |

**인덱스**:
- `idx_mastery_score`: mastery_score
- `idx_part_mastery`: (part, mastery_score)

---

## 🔧 트러블슈팅

### MCP 서버가 보이지 않는 경우

1. 빌드 확인: `npm run build`
2. 파일 확인: `ls dist/main.js`
3. 수동 실행: `node dist/main.js`
4. Claude Desktop 로그 확인: `View > Toggle Developer Tools > Console`
5. Claude Desktop 완전히 재시작

### 데이터베이스 연결 오류

1. `claude_desktop_config.json`의 `env` 섹션 확인
2. stdio 환경에서는 `.env` 파일 대신 설정 파일에 환경 변수 필수
3. Supabase 프로젝트 활성 상태 확인
4. `migrate.sql` 실행 확인

### 타입 에러

```bash
rm -rf node_modules package-lock.json
npm install
npm run build
```

---

## 🛠️ 개발 명령어

```bash
# 빌드
npm run build

# 개발 모드
npm run start:dev

# 실행
npm start

# 샘플 데이터
node seed.js

# 타입 체크
npx tsc --noEmit
```

---

## 🎓 학습 팁

1. **매일 10-15분** 꾸준히 연습
2. **weak_first 모드** 활용으로 취약 문장 집중 공략
3. **키워드 중심** 학습 (전체 문장보다 핵심 키워드 먼저 암기)
4. **음성 입력** 사용으로 발음 연습 병행
5. 점수 80점 이상 되면 자동으로 다른 문장 출제

---

## 🚀 향후 계획

- [ ] 187개 전체 문장 데이터 추가
- [ ] Part 3, 4, 5 지원
- [ ] 학습 통계 대시보드
- [ ] 사용자별 학습 기록
- [ ] 발음 평가 API 연동

---

## 📚 참고 자료

- [MCP 공식 문서](https://modelcontextprotocol.io/)
- [NestJS 공식 문서](https://docs.nestjs.com/)
- [Supabase 문서](https://supabase.com/docs)

---

## 📄 라이선스

ISC

---

**Version**: 1.0.0 | **Last Updated**: 2026-03-15