内容
# 韩国生活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` → 有效 |
| `validate_rrn` | 주민등록번호 형식/체크섬 + 生年月日·性别 추출 | 仅格式验证（不查询） |
| `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. 安装 & 本地运行
```bash
# 依赖安装
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 模式启动：
```powershell
$env:MCP_TRANSPORT="http"; python server.py
```
### 环境变量
| 变量 | 默认值 | 说明 |
|------|--------|------|
| `MCP_TRANSPORT` | `stdio` | `stdio` / `http`（streamable）/ `sse` |
| `HOST` | `0.0.0.0` | HTTP 绑定地址 |
| `PORT` | `8000` | HTTP 端口 |
---
## 2. 自身测试
```bash
python test_tools.py # 纯逻辑 21 个案例验证（21/21 PASS）
```
---
## 3. 使用 MCP Inspector 验证（PlayMCP 注册前必备）
Inspector 无需单独安装，通过 `npx` 运行。
**HTTP（远程）模式验证** — 与 PlayMCP 注册形式相同，推荐：
```bash
# 终端 1: 服务器运行
MCP_TRANSPORT=http python server.py
# 终端 2: 运行 Inspector 后在浏览器中访问
npx @modelcontextprotocol/inspector
# → Transport: "Streamable HTTP"
# → URL: http://localhost:8000/mcp
# → Connect → Tools 标签页中调用 11 个工具测试
```
**stdio 模式验证**:
```bash
npx @modelcontextprotocol/inspector python server.py
```
---
## 4. 카카오 云部署（创建远程端点）
PlayMCP 注册 **具有公开 URL 的远程 MCP 服务器**。使用附带的 `Dockerfile` 构建容器镜像并部署到 카카오 云。
```bash
# 镜像构建
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`](deploy/DEPLOY.md)
>
> 根据 공모전 规定，提交物必须是 **카카오 云 MCP 服务器端点**，方可获得参赛资格。
---
## 5. PlayMCP 注册流程
1. 使用 카카오 账户登录 [playmcp.kakao.com](https://playmcp.kakao.com/)
2. 开发人员控制台 → **注册新的 MCP 服务器**
3. 输入步骤 4 中创建的 **카카오 云端点 URL** (`.../mcp`)
4. 根据提供的模板填写服务器信息（名称·说明·工具列表）
5. 完成 Inspector 验证后 **公开** 服务器
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
```
