> ⚠️ **서비스 종료 안내**
> 본 MCP 서버는 2026-08-23부로 fly.io 배포를 종료했습니다.
> 코드는 개발 참고용으로 저장소에 남겨둡니다.

# 서울시 개별공시지가 정보 MCP

서울 열린데이터광장의 [서울시 개별공시지가 정보(IndividuallyPostedLandPriceService)](http://data.seoul.go.kr/)를
MCP 툴로 제공하는 서버입니다. 시군구명·기준년도(+ 법정동/본번/부번/필지구분코드)로
개별 필지의 공시지가(원/㎡)를 조회합니다.

## 제공 툴

### `get_individual_land_price`
시군구명과 기준년도로 개별공시지가를 조회합니다. 법정동명/본번/부번/필지구분코드로 추가 필터링 가능.

| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
| sigungu_nm | string | 필수 | 시군구명 (예: 종로구) |
| year | string | 필수 | 기준년도 (YYYY) |
| bjdong_nm | string | 선택 | 법정동명 |
| bonbeon | string | 선택 | 본번 (0~9999) |
| bubeon | string | 선택 | 부번 (0~9999) |
| pilgi_cd | string | 선택 | 필지구분코드 (1:토지 2:임야 3:가지번 4:가지번(부분세분) 5:블럭지번 6:블럭지번(롯트세분) 7:블럭지번(지구) 8:블럭지번(지구-롯트) 9:기타지번) |
| start_index | integer | 선택 (기본 1) | 조회 시작 위치 |
| end_index | integer | 선택 (기본 100) | 조회 종료 위치 (start_index와 차이 최대 1000) |

응답 필드: 시군구명/시군구코드/법정동명/법정동코드/본번/부번/필지구분명/필지구분코드/
기준년월(`YYYY-MM-DD` 형식)/**공시지가(원/㎡)**/기준년도

⚠️ **실측으로 확인된 제약 (DEVLOG.md 참고)**:
- `bjdong_nm`/`bonbeon`/`bubeon`/`pilgi_cd`는 **넷 다 채우거나 넷 다 비워야** 합니다. 하나라도 부분적으로만 채우면 서울시 API가 `ERROR-500`(서버 오류)을 반환합니다. 이 서버는 부분 채움을 감지하면 API를 호출하기 전에 `ERROR-CLIENT-PARTIAL-PARAMS`로 안내합니다.
- **시군구명+기준년도만으로(선택 파라미터 4개를 전부 비운 채) 여러 건을 조회하는 것은 지원되지 않습니다.** 이 조합도 `ERROR-500`을 반환하는 것으로 실측되었습니다. `start_index`/`end_index`로 실제 여러 건(`list_total_count > 1`)이 반환되는 유효한 조합은 아직 확인하지 못했습니다 — 4개 파라미터를 모두 채운 유효 요청은 필지 단위로 좁혀져 통상 1건만 반환됩니다.

## Rate Limiting

이 서버는 클라이언트 IP 기준으로 다음 3단계 요청 제한을 in-memory(단일 프로세스 기준)로 적용합니다. 초과 시 MCP 툴 호출이 `429:`로 시작하는 오류 메시지와 함께 실패합니다.

1. **분당 3회 초과** → 429
2. **1시간 내 429를 5회 이상 받은 IP** → 이후 **24시간 차단**
3. **IP당 일일(rolling 24h) 누적 호출 30회 초과** → 429

⚠️ in-memory 저장이므로 fly.io가 머신을 여러 대(고가용성) 띄우면 머신별로 카운트가 분리되어 완전한 전역 제한은 아닙니다. 기본적인 남용 방지 용도로 충분한 수준입니다.

## 설치 및 로컬 실행

```bash
pip install -r requirements.txt
cp .env.example .env   # SEOUL_API_KEY 값 입력 (BOM 없이 저장할 것)
python server.py
```

## 환경변수

| 이름 | 설명 |
|---|---|
| `SEOUL_API_KEY` | 서울 열린데이터광장에서 발급받은 인증키 |
| `PORT` | 서버 포트 (기본값은 server.py 참고) |

## 배포 (fly.io)

```bash
fly launch --no-deploy
fly secrets set SEOUL_API_KEY=발급받은키
flyctl deploy
```

배포 후 Claude.ai > 설정 > 커넥터에서 연결하고, "사용 가능한 도구" 목록에 툴이 뜨는지 확인하세요.

## 라이선스 / 출처

- 원데이터: 서울특별시 (도시공간본부 토지관리과)
- 이용허락조건: **공공누리 1유형** (출처표시, 상업적 이용 및 변경 가능)
- 출처 표기 예: "본 서비스는 서울열린데이터광장의 개별공시지가 정보를 사용합니다."