# unified-school-mcp

학교알리미(schoolinfo-mcp) + 국토교통부 실거래가(realestate-mcp) + 학구도(통학구역) 조회를 하나의 MCP 서버로 합친 것.

## 도구

- **schoolinfo-mcp 도구 13종** — 학교 검색, 공시정보(급식·학생수·동아리 등), 급식식단, 학사일정, 수행평가 계획 자동조회 등
- **realestate-mcp 도구 7종** — 아파트/토지/상가/단독주택 실거래가 조회, 지역 시세 통계
- **학구도 도구 2종**
  - `find_school_zone(address, level?)` — 주소 → 배정 학구(초/중/고) 조회
  - `get_school_zone_boundary(address, level)` — 학구 경계 폴리곤(GeoJSON)

## 아키텍처

```
unified-school-mcp (이 서버)
 ├─ schoolinfo-mcp ──── 로컬 자식 프로세스(stdio)로 실행, 도구를 그대로 전달(proxy)
 ├─ realestate-mcp ──── 이미 배포된 원격 서버를 그대로 프록시 (별도 키 불필요)
 └─ 학구도(schoolzone) ── 이 서버에서 직접 구현
     주소 → 좌표: 브이월드(VWorld) 주소 API
     좌표 → 학구: schoolgis.emac.kr ArcGIS REST (인증키 불필요, 공개 엔드포인트)
```

## 환경변수

| 변수 | 용도 | 발급처 |
|------|------|--------|
| `SCHOOLINFO_API_KEY` | 학교알리미 공시정보 조회 | https://www.schoolinfo.go.kr (네이버/카카오 로그인, 무료 즉시발급) |
| `NEIS_API_KEY` | 급식식단·학사일정 조회 (선택) | https://open.neis.go.kr (무료 즉시발급) |
| `VWORLD_KEY` | 학구도 주소→좌표 변환 | https://www.vworld.kr (무료 가입) |
| `SCHOOLINFO_MCP_PATH` | schoolinfo-mcp의 `dist/mcp.js` 경로 (선택, 기본값은 `../schoolinfo-mcp/dist/mcp.js`) | — |
| `REALESTATE_REMOTE_URL` | 실거래가 원격 MCP URL (선택, 기본값 있음) | — |

## 실행

### 로컬(stdio) — Claude Code/Desktop MCP로 등록

```json
{
  "mcpServers": {
    "unified-school": {
      "command": "node",
      "args": ["/path/to/unified-school-mcp/server.js"],
      "env": {
        "SCHOOLINFO_API_KEY": "...",
        "NEIS_API_KEY": "...",
        "VWORLD_KEY": "..."
      }
    }
  }
}
```

### 원격(HTTP) — 한 번 배포하면 설치자는 키 없이 URL만으로 사용

```bash
PORT=3000 node server.js
```

Render/Fly 등에 배포 시 위 환경변수를 서버 쪽에만 설정하면, 이 서버에 연결하는 사람은 키 발급 없이 `https://<배포주소>/mcp` 한 줄로 세 기능을 모두 쓸 수 있다.

```json
{
  "mcpServers": {
    "unified-school": {
      "type": "streamable-http",
      "url": "https://<배포주소>/mcp"
    }
  }
}
```

## 주의

- 학구도 조회 결과는 단순 참고용이며 법적 효력이 없습니다. 정확한 배정 학교는 관할 교육(지원)청에 확인하세요.
- 인증키는 코드에 넣지 말고 항상 환경변수/호스팅 서비스의 시크릿으로 주입하세요.