korea-life-mcp 🇰🇷

한국 생활 특화 유틸리티 MCP 서버 — 카카오 PlayMCP 공모전(MCP Player 10) 제출용.

외부 API 키·네트워크·개인정보 조회 없이 완전히 자기완결형으로 동작하므로, MCP Inspector 검증과 심사가 간단하고 안정적입니다.

---

제공 도구 (15종)

도구	설명	예시
decompose_hangul	한글을 초/중/종성으로 분해	값 → ㄱ, ㅏ, ㅄ
chosung	초성 검색용 문자열 생성	한국어 → ㅎㄱㅇ
compose_hangul	자모를 완성형 한글로 조합	ㅎ,ㅏ,ㄴ → 한
romanize	로마자 표기(자음동화 반영)	종로 → jongno
number_to_korean	숫자 → 한글 (읽기/금액 정자체)	12345 → 일만이천삼백사십오
korean_to_number	한글 금액 → 숫자	일만이천삼백사십오 → 12345
validate_business_number	사업자등록번호 체크섬 검증	220-81-62517 → valid
validate_rrn	주민등록번호 형식/체크섬 + 생년월일·성별 추출	형식 검증만 (조회 X)
korean_holidays	연도별 공휴일 목록	2026 → 신정, 설날 …
business_days_between	두 날짜 사이 영업일(주말·공휴일 제외) 수
d_day	기준일→목표일 D-day 계산	D-6
format_phone_number	전화번호 포맷 + 종류/지역 판별	0212345678 → 서울, 02-1234-5678
area_convert	면적 평↔㎡ 변환	34평 → 112.4㎡
korean_age	만 나이·연 나이·세는나이 계산	생년월일+기준일
won_format	원화 천 단위 포맷	1234567 → ₩1,234,567

⚠️ 개인정보 안전: validate_rrn은 어떤 외부 조회도 하지 않으며, 입력된 번호의 형식·체크섬만 계산합니다.

---

1. 설치 & 로컬 실행

# 의존성 설치
pip install -r requirements.txt        # 또는: pip install mcp

# (a) 로컬 개발용 stdio 모드 — Claude Desktop 등에서 직접 실행
python server.py

# (b) 원격(Streamable HTTP) 모드 — PlayMCP 배포와 동일한 형태
#     엔드포인트: http://0.0.0.0:8000/mcp
MCP_TRANSPORT=http python server.py

Windows PowerShell에서 HTTP 모드로 띄우려면:

$env:MCP_TRANSPORT="http"; python server.py

환경변수

변수	기본값	설명
MCP_TRANSPORT	stdio	stdio / http(streamable) / sse
HOST	0.0.0.0	HTTP 바인드 주소
PORT	8000	HTTP 포트

---

2. 자체 테스트

python test_tools.py       # 순수 로직 21개 케이스 검증 (21/21 PASS)

---

3. MCP Inspector로 검증 (PlayMCP 등록 전 필수)

Inspector는 별도 설치 없이 npx로 실행됩니다.

HTTP(원격) 모드 검증 — PlayMCP 등록 형태와 동일하므로 권장:

# 터미널 1: 서버 실행
MCP_TRANSPORT=http python server.py

# 터미널 2: Inspector 실행 후 브라우저에서 접속
npx @modelcontextprotocol/inspector
#  → Transport: "Streamable HTTP"
#  → URL: http://localhost:8000/mcp
#  → Connect → Tools 탭에서 11개 도구 호출 테스트

stdio 모드 검증:

npx @modelcontextprotocol/inspector python server.py

---

4. 카카오 클라우드 배포 (원격 엔드포인트 만들기)

PlayMCP는 공개 URL을 가진 원격 MCP 서버를 등록합니다. 포함된 Dockerfile로 컨테이너 이미지를 만들어 카카오 클라우드에 배포하세요.

# 이미지 빌드
docker build -t korea-life-mcp .

# 로컬에서 컨테이너 동작 확인 (http://localhost:8000/mcp)
docker run -p 8000:8000 korea-life-mcp

카카오 클라우드에 배포하면 https://<발급받은-도메인>/mcp 형태의 공개 엔드포인트가 생성됩니다. 이 URL을 다음 단계에서 등록합니다.

📄 가장 쉬운 배포(VM + Docker + 자동 HTTPS) 단계별 가이드: deploy/DEPLOY.md

공모전 규정상 제출물은 카카오 클라우드 MCP 서버 엔드포인트여야 참가 자격이 인정됩니다.

---

5. PlayMCP 등록 절차

1. playmcp.kakao.com 에 카카오 계정으로 로그인
2. 개발자 콘솔 → 새 MCP 서버 등록
3. 위 4단계에서 만든 카카오 클라우드 엔드포인트 URL(.../mcp) 입력
4. 제공된 템플릿에 맞춰 서버 정보(이름·설명·도구 목록) 작성
5. Inspector 검증 완료 후 공개(Public) 전환
6. 공모전 페이지에서 제출 → 심사 대기

---

알려진 한계

• romanize: 자모 매핑 + 연음 + 자음동화(유음화·비음화) 주요 규칙을 반영합니다(종로→jongno, 신라→silla, 협력→hyeomnyeok). 다만 겹받침 연음·구개음화·ㅎ축약 등 일부 음운 변동은 단순화되어 있습니다.
• korean_holidays / business_days_between: 양력 고정 공휴일은 모든 연도 계산 가능하지만, 음력 기반(설날·추석·부처님오신날) 및 대체공휴일은 korea_tools.py의 _LUNAR_TABLE에 등록된 연도(현재 2025·2026)만 정확합니다. 다른 연도는 결과의 note 필드로 안내되며, 표를 갱신하면 확장됩니다.

---

프로젝트 구조

korea-life-mcp/
├── server.py          # FastMCP 서버 (도구 11종 노출, stdio/http 전환)
├── korea_tools.py     # 순수 로직 함수 (테스트 가능, 네트워크 미사용)
├── test_tools.py      # 자체 검증 스크립트
├── requirements.txt   # 의존성 (mcp)
├── pyproject.toml     # 패키지 메타데이터
├── Dockerfile         # 카카오 클라우드 배포용 컨테이너
└── README.md