Content
# Tool List
**Specialized Utility MCP Server for Korean Life** — Submission for Kakao **PlayMCP** Contest (MCP Player 10).
No external API keys, network, or personal information inquiries are required, making it **completely self-contained**. This simplifies MCP Inspector verification and review.
## Provided Tools (15 types)
| Tool | Description | Example |
|------|------|------|
| `decompose_hangul` | Decompose Hangul into initial/consonant/final consonant | `값` → ㄱ, ㅏ, ㅄ |
| `chosung` | Generate string for initial consonant search | `한국어` → `ㅎㄱㅇ` |
| `compose_hangul` | Combine jamo into complete Hangul | ㅎ,ㅏ,ㄴ → `한` |
| `romanize` | Romanization (reflecting assimilation) | `종로` → `jongno` |
| `number_to_korean` | Number → Hangul (reading/amount in regular font) | `12345` → `일만이천삼백사십오` |
| `korean_to_number` | Hangul amount → Number | `일만이천삼백사십오` → `12345` |
| `validate_business_number` | Business registration number checksum verification | `220-81-62517` → valid |
| `validate_rrn` | Resident registration number format/checksum + birthdate/gender extraction | Only format verification (no inquiry) |
| `korean_holidays` | Annual holiday list | `2026` → New Year's Day, Seollal … |
| `business_days_between` | Number of business days between two dates (excluding weekends/holidays) | |
| `d_day` | Calculate D-day from reference date to target date | `D-6` |
| `format_phone_number` | Phone number formatting + type/location identification | `0212345678` → Seoul, `02-1234-5678` |
| `area_convert` | Area conversion between pyeong and ㎡ | `34평` → `112.4㎡` |
| `korean_age` | Calculation of age in Korean counting systems | Birthdate + reference date |
| `won_format` | KRW formatting with thousand separators | `1234567` → `₩1,234,567` |
> ⚠️ **Personal Information Safety**: `validate_rrn` does not perform any external inquiries and only calculates the **format and checksum** of the input number.
## 1. Installation & Local Execution
```bash
# Install dependencies
pip install -r requirements.txt # or: pip install mcp
# (a) Local development mode — run directly in Claude Desktop, etc.
python server.py
# (b) Remote (Streamable HTTP) mode — same form as PlayMCP deployment
# Endpoint: http://0.0.0.0:8000/mcp
MCP_TRANSPORT=http python server.py
```
To run in HTTP mode on Windows PowerShell:
```powershell
$env:MCP_TRANSPORT="http"; python server.py
```
### Environment Variables
| Variable | Default Value | Description |
|------|--------|------|
| `MCP_TRANSPORT` | `stdio` | `stdio` / `http`(streamable) / `sse` |
| `HOST` | `0.0.0.0` | HTTP bind address |
| `PORT` | `8000` | HTTP port |
## 2. Self-Testing
```bash
python test_tools.py # Verify 21 pure logic cases (21/21 PASS)
```
## 3. Verification with MCP Inspector (required before PlayMCP registration)
The Inspector can be run without separate installation using `npx`.
**HTTP (remote) mode verification** — recommended as it matches the PlayMCP registration form:
```bash
# Terminal 1: Run server
MCP_TRANSPORT=http python server.py
# Terminal 2: Run Inspector and connect via browser
npx @modelcontextprotocol/inspector
# → Transport: "Streamable HTTP"
# → URL: http://localhost:8000/mcp
# → Connect → Tools tab to test 11 tool calls
```
**stdio mode verification**:
```bash
npx @modelcontextprotocol/inspector python server.py
```
## 4. Kakao Cloud Deployment (create remote endpoint)
PlayMCP registers a **public URL-enabled remote MCP server**. Use the included `Dockerfile` to build a container image and deploy it to Kakao Cloud.
```bash
# Build image
docker build -t korea-life-mcp .
# Verify container operation on localhost (http://localhost:8000/mcp)
docker run -p 8000:8000 korea-life-mcp
```
Deploying to Kakao Cloud generates a **public endpoint** in the form of `https://<issued-domain>/mcp`. Register this URL in the next step.
> 📄 **Simplest deployment (VM + Docker + automatic HTTPS) step-by-step guide**: [`deploy/DEPLOY.md`](deploy/DEPLOY.md)
>
> According to contest regulations, the submission must be a **Kakao Cloud MCP server endpoint** to qualify for participation.
## 5. PlayMCP Registration Procedure
1. Log in to [playmcp.kakao.com](https://playmcp.kakao.com/) with a Kakao account
2. Developer console → **Register new MCP server**
3. Enter the **Kakao Cloud endpoint URL** (`.../mcp`) created in step 4
4. Fill in server information (name, description, tool list) using the provided template
5. Complete Inspector verification and **make public**
6. Submit on the contest page → wait for review
## Known Limitations
- `romanize`: Reflects jamo mapping + liaison + **major assimilation rules** (`종로`→`jongno`, `신라`→`silla`, `협력`→`hyeomnyeok`). However, some phonological variations like **double final consonant liaison, palatalization, and ㅎ reduction** are simplified.
- `korean_holidays` / `business_days_between`: **Solar term-fixed holidays** can be calculated for all years, but **lunar-based holidays (Seollal, Chuseok, Buddha's Birthday) and substitute holidays** are accurate only for years registered in `korea_tools.py`'s `_LUNAR_TABLE` (currently 2025·2026). Other years are guided by the `note` field in the result and can be extended by updating the table.
## Project Structure
```
korea-life-mcp/
├── server.py # FastMCP server (exposes 11 tools, stdio/http switch)
├── korea_tools.py # Pure logic functions (testable, no network usage)
├── test_tools.py # Self-verification script
├── requirements.txt # Dependencies (mcp)
├── pyproject.toml # Package metadata
├── Dockerfile # Container for Kakao Cloud deployment
└── README.md
```
