🎯 TOEIC Speaking MCP Server

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

출처: 유튜브 시계토끼제니쌤

---

📖 목차

• 주요 특징
• 기술 스택
• 설치 및 설정
• 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. 의존성 설치

npm install

2. 환경 변수 설정

.env 파일 확인:

SUPABASE_URL=your_supabase_url
SUPABASE_ANON_KEY=your_supabase_anon_key

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

Supabase SQL Editor에서 migrate.sql 실행:

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

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

node seed.js

5. 빌드

npm run build

6. Claude Desktop 설정

~/Library/Application Support/Claude/claude_desktop_config.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 (선택): 파트 번호 필터

응답:

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

2. verify_answer - 답변 검증

파라미터 (필수):

• sentence_id: 문장 ID
• user_answer: 사용자 답변 (영어 문장)

응답:

{
  "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 실행 확인

타입 에러

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

---

🛠️ 개발 명령어

# 빌드
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 공식 문서
• NestJS 공식 문서
• Supabase 문서

---

📄 라이선스

ISC

---

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