korea-life-mcp 🇰🇷

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

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

제공 도구 (15종)

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

Related MCP server: brasil-mcp-essentials

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

환경변수

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