Metadata-Version: 2.5
Name: kre-mcp
Version: 0.1.0
Summary: Korean apartment transaction and presale right trade MCP server
Project-URL: Repository, https://github.com/jaypakdevkr/KRE-MCP
Project-URL: Issues, https://github.com/jaypakdevkr/KRE-MCP/issues
Author: jaypakdevkr
License-Expression: MIT
License-File: LICENSE
Keywords: apartment,korea,mcp,real-estate
Requires-Python: >=3.10
Requires-Dist: defusedxml<1,>=0.7.1
Requires-Dist: httpx<1,>=0.27
Requires-Dist: mcp<2,>=1.26
Description-Content-Type: text/markdown

# KRE-MCP

jaypakdevkr가 만드는 한국 아파트 실거래가 MCP 서버입니다. Python 3.10 이상에서 실행되며,
공식 MCP Python SDK의 stdio 전송을 사용합니다.

데이터 출처는 **국토교통부 공공데이터포털 API**입니다. 한국부동산원 R-ONE 통계 API는
포함하지 않습니다. `korea-realestate-mcp`와 별개의 독립 패키지입니다.

## 제공 도구

| 도구 | 기능 |
| --- | --- |
| `realestate_search_apt_trade` | 아파트 매매 실거래가 조회 |
| `realestate_search_presale_trade` | 아파트 분양권·입주권 전매 실거래가 조회 |

두 도구는 동일한 입력을 받습니다.

| 입력 | 설명 | 예시 |
| --- | --- | --- |
| `region_code` | 법정동 코드 앞 5자리 (문자열) | `"11110"` (서울 종로구), `"11680"` (서울 강남구) |
| `deal_ym` | 계약년월 YYYYMM (문자열) | `"202601"` |
| `page` | 페이지, 기본 1 | `1` |
| `page_size` | 페이지당 1~100건, 기본 100 | `100` |

지역코드는 [행정표준코드관리시스템](https://www.code.go.kr/)에서 확인합니다.
이 버전에는 지역명 검색, 전월세 조회, 시세 분석 기능은 포함하지 않습니다.

## API 준비

[공공데이터포털](https://www.data.go.kr/)에서 아래 **두 API 각각** 활용신청 후 승인 상태를 확인하세요.

- [국토교통부_아파트 매매 실거래가 자료](https://www.data.go.kr/data/15126469/openapi.do)
- [국토교통부_아파트 분양권전매 실거래가 자료](https://www.data.go.kr/data/15126471/openapi.do)

일반 인증키(Decoding)를 `PUBLIC_DATA_API_KEY` 환경변수에 설정합니다.
Encoding 키도 1회 디코딩하여 처리합니다. 키는 도구 입력에 넣지 않습니다.
서버는 `.env`를 자동으로 읽지 않으므로 클라이언트 `env` 또는 셸에 설정하세요.

## 설치 및 실행

PyPI 릴리스가 게시된 후:

```sh
uvx kre-mcp
```

또는:

```sh
pip install kre-mcp
kre-mcp
```

`kre-mcp --version`으로 설치를 확인합니다. 서버 실행 시 화면에 대화형 프롬프트가
나오지 않는 것이 정상입니다. MCP 클라이언트가 표준입출력으로 연결합니다.

## MCP 클라이언트 설정

Claude Desktop 등 stdio MCP 클라이언트의 서버 설정에 추가하세요.
`uvx`를 찾지 못하면 `command`에 설치된 `uvx`의 절대 경로를 넣으세요.

```json
{
  "mcpServers": {
    "kre-mcp": {
      "command": "uvx",
      "args": ["kre-mcp==0.1.0"],
      "env": {
        "PUBLIC_DATA_API_KEY": "본인의 공공데이터포털 인증키"
      }
    }
  }
}
```

교육 실습에서는 수강생마다 본인의 API 키를 사용하세요.

### 실습 질문

- “지역코드 11680, 2026년 1월 아파트 매매 거래 10건을 조회해줘.”
- “같은 지역·월의 분양권 전매 거래도 조회해줘.”
- “다음 페이지가 있으면 이어서 조회하고 취소 거래를 구분해줘.”

### 결과 해석

`items`는 API 원본 필드를 공백 정리한 문자열로 반환합니다.
`dealAmount`는 **만원**, `excluUseAr`는 **㎡**입니다.
`total_count`는 API 전체 건수, `returned_count`는 현재 페이지 건수입니다.
`has_next=true`이면 `page`를 1 늘려 추가 조회하세요.
필터링하지 않으므로 `cdealType`, `cdealDay`로 취소 거래를 확인해야 합니다.
한 페이지로 전체 평균·시세를 계산하지 마세요. 신고 지연, 취소, 정정으로 결과가 바뀔 수 있습니다.

## 로컬 개발

```sh
uv sync --locked
uv run pytest -q
uv run ruff check .
uv run python -m kre_mcp
uv build
uv run twine check dist/*
```

테스트는 실제 API 키 없이 mock HTTP와 실제 stdio MCP 연결을 검증합니다.
네트워크 오류에는 인증키가 포함된 요청 URL을 출력하지 않습니다.

## PyPI 배포 (관리자)

GitHub Actions의 `publish.yml`은 테스트·빌드 후 PyPI Trusted Publishing(OIDC)으로 배포합니다.
PyPI 토큰을 저장소에 저장하지 않습니다.

최초 1회 [PyPI Publishing 설정](https://pypi.org/manage/account/publishing/)의
새 pending publisher에 다음 값을 등록하세요.

| 항목 | 값 |
| --- | --- |
| PyPI Project Name | `kre-mcp` |
| Owner | `jaypakdevkr` |
| Repository name | `KRE-MCP` |
| Workflow name | `publish.yml` |
| Environment name | `pypi` |

그다음 GitHub Actions에서 **Publish to PyPI** 워크플로를 `main` 브랜치로 수동 실행합니다.
후속 배포는 `pyproject.toml`의 버전을 올리고 `uv lock` 후 `main`에 반영하여 실행하세요.
이미 배포한 버전은 재업로드할 수 없습니다.

## 라이선스

MIT. 데이터 이용 조건은 각 공공데이터포털 API 안내를 따릅니다.
