🎯 TOEIC Speaking MCP Server
토익 스피킹 만능문장 암기 테스트를 위한 MCP 서버입니다. Claude Desktop 앱과 연동하여 음성으로 토익 스피킹 문장을 학습하고 즉시 피드백을 받을 수 있습니다.
출처: 유튜브 시계토끼제니쌤
---
📖 목차
---
✨ 주요 특징
- 🎤 음성 학습: 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 install2. 환경 변수 설정
.env 파일 확인:
SUPABASE_URL=your_supabase_url
SUPABASE_ANON_KEY=your_supabase_anon_key3. 데이터베이스 마이그레이션
Supabase SQL Editor에서 migrate.sql 실행:
-- mastery_score, last_reviewed_at, review_count 컬럼 추가
-- 인덱스 생성4. 샘플 데이터 삽입 (선택 사항)
node seed.js5. 빌드
npm run build6. 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(선택): 파트 번호 필터
응답: ``json { "id": "uuid", "sentence_ko": "이 사진은 공원에서 찍힌 사진입니다.", "part": 2, "current_mastery": 0 } ``
2. verify_answer - 답변 검증
파라미터 (필수):
sentence_id: 문장 IDuser_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_scoreidx_part_mastery: (part, mastery_score)
---
🔧 트러블슈팅
MCP 서버가 보이지 않는 경우
- 빌드 확인:
npm run build - 파일 확인:
ls dist/main.js - 수동 실행:
node dist/main.js - Claude Desktop 로그 확인:
View > Toggle Developer Tools > Console - Claude Desktop 완전히 재시작
데이터베이스 연결 오류
claude_desktop_config.json의env섹션 확인- stdio 환경에서는
.env파일 대신 설정 파일에 환경 변수 필수 - Supabase 프로젝트 활성 상태 확인
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---
🎓 학습 팁
- 매일 10-15분 꾸준히 연습
- weak_first 모드 활용으로 취약 문장 집중 공략
- 키워드 중심 학습 (전체 문장보다 핵심 키워드 먼저 암기)
- 음성 입력 사용으로 발음 연습 병행
- 점수 80점 이상 되면 자동으로 다른 문장 출제
---
🚀 향후 계획
- [ ] 187개 전체 문장 데이터 추가
- [ ] Part 3, 4, 5 지원
- [ ] 학습 통계 대시보드
- [ ] 사용자별 학습 기록
- [ ] 발음 평가 API 연동
---
📚 참고 자료
---
📄 라이선스
ISC
---
Version: 1.0.0 | Last Updated: 2026-03-15
