Document the approved real-estate MCP skill without vendoring upstream

Issue #53 is intentionally doc-only, so this change adds the real-estate-search skill, feature guide, setup/security notes, and regression coverage around the upstream real-estate-mcp integration instead of importing server code. The new docs keep the original MCP link, cover Codex/Claude registration, and spell out the self-host + Cloudflare Tunnel + launchd path for environments where no fixed hosted endpoint is available. Constraint: Must use tae0y/real-estate-mcp without copying its source into this repository Constraint: Must include the original MCP link and a stable self-host fallback when no hosted endpoint is available Rejected: Vendor the upstream MCP source | issue explicitly requires skill docs only Rejected: Assume a public hosted MCP endpoint exists | upstream docs did not publish one Confidence: high Scope-risk: narrow Reversibility: clean Directive: Keep this integration doc-only; do not add a workspace or vendored server without revisiting issue #53 constraints Tested: node --test scripts/skill-docs.test.js Tested: npm run ci Tested: upstream bootstrap smoke (`uv sync`, `uv run real-estate-mcp --help`, HTTP initialize on 127.0.0.1:8017) Not-tested: live property data queries with a valid DATA_GO_KR_API_KEY
2026-06-24 02:04:11 +00:00 · 2026-04-05 14:10:45 +09:00 · 2026-04-05 14:10:45 +09:00 · 81c81cb5da
commit 81c81cb5da
parent 4f0dd0366c
11 changed files with 504 additions and 2 deletions
--- a/README.md
+++ b/README.md
@ -24,6 +24,7 @@ Claude Code, Codex, OpenCode, OpenClaw/ClawHub 등 각종 코딩 에이전트
 | 서울 지하철 도착정보 조회 | self-host 또는 배포 확인이 끝난 `k-skill-proxy` 경유로 역 기준 실시간 도착 예정 열차 확인 | 프록시 URL 필요 | [서울 지하철 도착정보 가이드](docs/features/seoul-subway-arrival.md) |
 | 사용자 위치 미세먼지 조회 | `k-skill-proxy` 로 현재 위치 또는 지역 fallback 기준 PM10/PM2.5 확인 | 불필요 | [사용자 위치 미세먼지 조회 가이드](docs/features/fine-dust-location.md) |
 | 한국 법령 검색 | `korean-law-mcp` 우선 + 장애 시 `법망` fallback으로 법령/조문/판례/유권해석 조회 | 로컬 CLI/MCP면 `LAW_OC` 필요, remote endpoint/법망 fallback은 불필요 | [한국 법령 검색 가이드](docs/features/korean-law-search.md) |
+| 한국 부동산 실거래가 조회 | upstream `real-estate-mcp`로 아파트/오피스텔/빌라/단독주택 실거래가·전월세·지역코드 조회, hosted endpoint가 없으면 self-host + Cloudflare Tunnel + launchd 운영 | 로컬/stdio/self-host면 `DATA_GO_KR_API_KEY` 필요 | [한국 부동산 실거래가 조회 가이드](docs/features/real-estate-search.md) |
 | 조선왕조실록 검색 | 공식 조선왕조실록 사이트에서 키워드 검색 후 왕별/연도별 필터와 기사 excerpt 조회 | 불필요 | [조선왕조실록 검색 가이드](docs/features/joseon-sillok-search.md) |
 | KBO 경기 결과 조회 | 날짜별 경기 일정, 결과, 팀별 필터링 | 불필요 | [KBO 결과 가이드](docs/features/kbo-results.md) |
 | K리그 경기 결과 조회 | 날짜별 K리그1/K리그2 경기 결과, 팀별 필터링, 현재 순위 확인 | 불필요 | [K리그 결과 가이드](docs/features/kleague-results.md) |
@ -68,6 +69,7 @@ Claude Code, Codex, OpenCode, OpenClaw/ClawHub 등 각종 코딩 에이전트
 - [서울 지하철 도착정보 조회](docs/features/seoul-subway-arrival.md)
 - [사용자 위치 미세먼지 조회](docs/features/fine-dust-location.md)
 - [한국 법령 검색 가이드](docs/features/korean-law-search.md)
+- [한국 부동산 실거래가 조회 가이드](docs/features/real-estate-search.md)
 - [조선왕조실록 검색 가이드](docs/features/joseon-sillok-search.md)
 - [KBO 경기 결과 조회](docs/features/kbo-results.md)
 - [K리그 경기 결과 조회](docs/features/kleague-results.md)
--- a/docs/features/real-estate-search.md
+++ b/docs/features/real-estate-search.md
@ -0,0 +1,153 @@
+# 한국 부동산 실거래가 조회 가이드
+
+## 이 기능으로 할 수 있는 일
+
+- 아파트 매매 실거래가 조회 (`get_apartment_trades`)
+- 아파트 전월세 조회 (`get_apartment_rent`)
+- 오피스텔/연립다세대/단독주택/상업업무용 실거래가 조회
+- 지역코드 조회 (`get_region_code`) 후 행정구역 기준 검색
+- 청약홈/온비드 도구 연결
+- hosted endpoint가 없을 때 self-host + Cloudflare Tunnel + launchd 운영
+
+## 가장 중요한 규칙
+
+이 기능은 upstream **`real-estate-mcp`**(`https://github.com/tae0y/real-estate-mcp/tree/main`)를 그대로 사용한다.
+이 저장소에는 원본 MCP 서버 코드를 넣지 않고, 스킬 문서와 연결 가이드만 유지한다.
+
+2026-04-05 기준 upstream README/docs에는 고정 public MCP URL이 문서화돼 있지 않았다.
+그래서 기본 문서는 **로컬 stdio 연결 또는 self-host HTTP 운영**을 기준으로 적는다.
+
+## 먼저 필요한 것
+
+- 인터넷 연결
+- `uv`
+- 공공데이터포털 API key (`DATA_GO_KR_API_KEY`)
+- upstream clone: `git clone https://github.com/tae0y/real-estate-mcp.git`
+- shared HTTP가 필요하면 Docker + Cloudflare Tunnel
+
+`DATA_GO_KR_API_KEY` 하나만 넣어도 기본 실거래가 조회는 시작할 수 있다.
+청약홈/온비드를 더 세밀하게 나누고 싶으면 upstream 문서대로 `ODCLOUD_API_KEY`, `ODCLOUD_SERVICE_KEY`, `ONBID_API_KEY` 를 추가한다.
+
+## 가장 빠른 시작: Codex CLI stdio
+
+```bash
+git clone https://github.com/tae0y/real-estate-mcp.git
+cd real-estate-mcp
+
+codex mcp add real-estate \
+  --env DATA_GO_KR_API_KEY=your_api_key_here \
+  -- uv run --directory /path/to/real-estate-mcp \
+  python src/real_estate/mcp_server/server.py
+
+codex mcp list
+codex mcp get real-estate
+```
+
+## Claude Desktop stdio 예시
+
+```json
+{
+  "mcpServers": {
+    "real-estate": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--directory", "/path/to/real-estate-mcp",
+        "python", "src/real_estate/mcp_server/server.py"
+      ],
+      "env": {
+        "DATA_GO_KR_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+## shared HTTP / self-host 운영
+
+고정 hosted endpoint를 확인하지 못했다면 아래 흐름으로 self-host 한다.
+
+### 1. upstream Docker compose 시작
+
+```bash
+git clone https://github.com/tae0y/real-estate-mcp.git
+cd real-estate-mcp
+cp .env.example .env
+printf 'DATA_GO_KR_API_KEY=your_api_key_here\n' >> .env
+REPOSITORY_ROOT=$(pwd)
+docker compose -f "$REPOSITORY_ROOT"/docker/docker-compose.yml up -d --build
+```
+
+### 2. MCP initialize로 health check
+
+```bash
+curl -s -X POST http://localhost/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.1"}}}'
+```
+
+정상이라면 응답 JSON 안에 `protocolVersion` 이 보인다.
+
+### 3. Cloudflare Tunnel로 공유 도메인 만들기
+
+```bash
+cloudflared tunnel login
+cloudflared tunnel create real-estate-mcp
+cloudflared tunnel route dns real-estate-mcp real-estate-mcp.example.com
+cat > ~/.cloudflared/config.yml <<'EOF'
+tunnel: real-estate-mcp
+credentials-file: /Users/YOUR_USER/.cloudflared/<tunnel-id>.json
+ingress:
+  - hostname: real-estate-mcp.example.com
+    service: http://localhost:80
+  - service: http_status:404
+EOF
+cloudflared tunnel run real-estate-mcp
+```
+
+그 다음 MCP URL은 `https://real-estate-mcp.example.com/mcp` 로 잡는다.
+인터넷에 공개한다면 upstream OAuth 문서(`docs/setup-oauth.md`)대로 `AUTH_MODE=oauth` 와 Auth0/클라이언트 시크릿을 붙인다.
+
+### 4. launchd로 자동 실행
+
+macOS 기준으로는 서버와 tunnel을 분리한 launchd 항목 두 개를 만든다.
+
+- `~/Library/LaunchAgents/com.kskill.real-estate-mcp.server.plist`
+- `~/Library/LaunchAgents/com.kskill.real-estate-mcp.tunnel.plist`
+
+둘 다 `RunAtLoad` 와 `KeepAlive` 를 켜고, 서버 쪽은 `docker compose -f docker/docker-compose.yml up -d`, tunnel 쪽은 `cloudflared tunnel run real-estate-mcp` 를 실행하게 둔다.
+
+```bash
+launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.kskill.real-estate-mcp.server.plist
+launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.kskill.real-estate-mcp.tunnel.plist
+launchctl enable gui/$(id -u)/com.kskill.real-estate-mcp.server
+launchctl enable gui/$(id -u)/com.kskill.real-estate-mcp.tunnel
+```
+
+## 조회 흐름 권장 순서
+
+1. 주소/행정구역이 애매하면 `get_region_code` 부터 호출한다.
+2. 아파트 매매면 `get_apartment_trades`, 전월세면 `get_apartment_rent` 를 쓴다.
+3. 오피스텔/빌라/단독주택/상업업무용은 해당 전용 tool로 분기한다.
+4. 사용자가 연월을 안 줬으면 기준 월을 먼저 확인한다.
+5. 실거래가와 호가를 섞지 말고, 신고 기반 데이터라는 점을 짧게 명시한다.
+6. public endpoint가 미리 없다면 self-host + Cloudflare Tunnel + launchd 경로를 그대로 제시한다.
+
+## 라이브 확인 메모
+
+2026-04-05 기준 로컬 smoke verification 에서 upstream 저장소로 아래 bootstrap 명령을 실제 실행해 진입 가능 여부를 확인했다.
+
+- `uv sync`
+- `uv run real-estate-mcp --help`
+- `DATA_GO_KR_API_KEY=dummy uv run real-estate-mcp --transport http --host 127.0.0.1 --port 8017`
+- `curl -s -X POST http://127.0.0.1:8017/mcp ... initialize` → `protocolVersion: 2024-11-05`
+
+즉, upstream 프로젝트 자체는 로컬에서 실행 가능한 상태로 확인했다. 실제 거래 데이터 조회는 유효한 `DATA_GO_KR_API_KEY` 가 준비된 환경에서 바로 이어서 검증하면 된다.
+
+## 참고 링크
+
+- 원본 MCP 서버: `https://github.com/tae0y/real-estate-mcp/tree/main`
+- Codex CLI 가이드: `https://github.com/tae0y/real-estate-mcp/blob/main/docs/setup-codex-cli.md`
+- Docker 가이드: `https://github.com/tae0y/real-estate-mcp/blob/main/docs/setup-docker.md`
+- OAuth 가이드: `https://github.com/tae0y/real-estate-mcp/blob/main/docs/setup-oauth.md`
--- a/docs/install.md
+++ b/docs/install.md
@ -51,6 +51,7 @@ npx --yes skills add <owner/repo> \
  --skill lotto-results \
  --skill kakaotalk-mac \
  --skill korean-law-search \
+  --skill real-estate-search \
  --skill joseon-sillok-search \
  --skill fine-dust-location \
  --skill daiso-product-search \
@ -71,6 +72,7 @@ npx --yes skills add <owner/repo> \
  --skill srt-booking \
  --skill ktx-booking \
  --skill korean-law-search \
+  --skill real-estate-search \
  --skill joseon-sillok-search \
  --skill seoul-subway-arrival \
  --skill fine-dust-location
@ -90,6 +92,24 @@ korean-law list

 로컬 설치가 막히면 `https://korean-law-mcp.fly.dev/mcp` remote endpoint를 MCP 클라이언트에 등록한다. 그 경로도 응답하지 않거나 서비스 장애가 나면 `https://api.beopmang.org/mcp` 또는 `https://api.beopmang.org/api/v4/law?action=search` 를 fallback으로 사용한다.

+`real-estate-search` 는 skill 설치 후 upstream `real-estate-mcp` (`https://github.com/tae0y/real-estate-mcp/tree/main`) 를 따로 clone 해서 붙인다.
+
+- 로컬 stdio/HTTP/self-host 경로는 `DATA_GO_KR_API_KEY` 를 채운다.
+- 2026-04-05 기준 upstream 문서에는 고정 public MCP URL이 없어서, shared HTTP가 필요하면 self-host를 기본으로 본다.
+- Codex CLI 에 붙일 때는 `uv run` 기반 stdio 등록을 먼저 시도한다.
+- self-host는 upstream Docker 문서 + `cloudflared tunnel`(Cloudflare Tunnel) + `launchd` 조합을 권장한다.
+
+```bash
+git clone https://github.com/tae0y/real-estate-mcp.git
+cd real-estate-mcp
+codex mcp add real-estate \
+  --env DATA_GO_KR_API_KEY=your-api-key \
+  -- uv run --directory /path/to/real-estate-mcp \
+  python src/real_estate/mcp_server/server.py
+```
+
+shared HTTP가 필요하면 upstream Docker guide 대로 띄운 뒤 Cloudflare Tunnel 도메인(`https://real-estate-mcp.example.com/mcp`)을 붙이고, macOS에서는 `launchd` 로 서버/터널을 자동 실행한다. 자세한 흐름은 [한국 부동산 실거래가 조회 가이드](features/real-estate-search.md)를 본다.
+
 로컬 저장소에서 바로 전체 설치 테스트:

 ```bash
@ -175,6 +195,7 @@ python3 scripts/korean_spell_check.py --text "아버지가방에들어가신다.
 - `seoul-subway-arrival`
 - `fine-dust-location`
 - `korean-law-search`
+- `real-estate-search`

 관련 문서:

--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@ -13,6 +13,7 @@
 - 서울 지하철 도착 정보
 - 사용자 위치 미세먼지 조회 스킬 출시
 - 한국 법령 검색 스킬 출시
+- 한국 부동산 실거래가 조회 스킬 출시
 - 조선왕조실록 검색 스킬 출시
 - 우편번호 검색
 - 근처 블루리본 맛집 스킬 출시
--- a/docs/security-and-secrets.md
+++ b/docs/security-and-secrets.md
@ -25,6 +25,7 @@ KSKILL_SRT_PASSWORD=replace-me
 KSKILL_KTX_ID=replace-me
 KSKILL_KTX_PASSWORD=replace-me
 LAW_OC=replace-me
+DATA_GO_KR_API_KEY=replace-me
 AIR_KOREA_OPEN_API_KEY=replace-me
 KSKILL_PROXY_BASE_URL=https://your-proxy.example.com
 ```
@ -61,9 +62,10 @@ KSKILL_PROXY_BASE_URL=https://your-proxy.example.com
 - `KSKILL_KTX_ID`
 - `KSKILL_KTX_PASSWORD`
 - `LAW_OC`
+- `DATA_GO_KR_API_KEY`
 - `AIR_KOREA_OPEN_API_KEY`
 - `KSKILL_PROXY_BASE_URL`

-`LAW_OC` 는 `korean-law-mcp` 가 법제처 Open API 를 호출할 때 쓰는 표준 변수명이다. 이 값은 로컬 CLI/로컬 MCP server 경로에서만 사용자 쪽에 필요하고, upstream remote MCP endpoint 예시는 사용자 `LAW_OC` 없이 `url`만 등록한다. 프록시 운영자 문맥에서는 upstream 환경변수 `SEOUL_OPEN_API_KEY` 도 사용할 수 있다. 다만 일반 사용자/client 쪽 기본 secrets 파일에는 넣지 않는다. `KSKILL_PROXY_BASE_URL` 도 서울 지하철 route가 실제 배포된 proxy URL 로만 넣는다.
+`LAW_OC` 는 `korean-law-mcp` 가 법제처 Open API 를 호출할 때 쓰는 표준 변수명이다. 이 값은 로컬 CLI/로컬 MCP server 경로에서만 사용자 쪽에 필요하고, upstream remote MCP endpoint 예시는 사용자 `LAW_OC` 없이 `url`만 등록한다. `DATA_GO_KR_API_KEY` 는 upstream `real-estate-mcp` 의 로컬/stdio/self-host 경로에서 쓰는 표준 변수명이다. public 공유용 Cloudflare Tunnel/Auth0/operator secret은 사용자 기본 secrets 파일에 넣지 않는다. 프록시 운영자 문맥에서는 upstream 환경변수 `SEOUL_OPEN_API_KEY` 도 사용할 수 있다. 다만 일반 사용자/client 쪽 기본 secrets 파일에는 넣지 않는다. `KSKILL_PROXY_BASE_URL` 도 서울 지하철 route가 실제 배포된 proxy URL 로만 넣는다.

 이 레포의 credential-bearing skill은 전부 이 정책을 전제로 작성한다. 자세한 공통 설치 절차는 [공통 설정 가이드](setup.md)를 본다.
--- a/docs/setup.md
+++ b/docs/setup.md
@ -1,6 +1,6 @@
 # 공통 설정 가이드

-`k-skill` 전체 스킬을 설치한 뒤, 인증 정보가 필요한 기능(SRT 예매, KTX 예매, 한국 법령 검색의 로컬 CLI/MCP 경로용 `LAW_OC`, self-host 프록시 운영용 서울 지하철/미세먼지 upstream key, 또는 배포 확인이 끝난 proxy URL 공유)이 있으면 이 절차를 진행하면 된다.
+`k-skill` 전체 스킬을 설치한 뒤, 인증 정보가 필요한 기능(SRT 예매, KTX 예매, 한국 법령 검색의 로컬 CLI/MCP 경로용 `LAW_OC`, 한국 부동산 실거래가 조회의 로컬/self-host 경로용 `DATA_GO_KR_API_KEY`, self-host 프록시 운영용 서울 지하철/미세먼지 upstream key, 또는 배포 확인이 끝난 proxy URL 공유)이 있으면 이 절차를 진행하면 된다.

 ## Credential resolution order

@ -25,6 +25,7 @@ KSKILL_SRT_PASSWORD=replace-me
 KSKILL_KTX_ID=replace-me
 KSKILL_KTX_PASSWORD=replace-me
 LAW_OC=replace-me
+DATA_GO_KR_API_KEY=replace-me
 AIR_KOREA_OPEN_API_KEY=replace-me
 KSKILL_PROXY_BASE_URL=https://your-proxy.example.com
 EOF
@ -39,6 +40,8 @@ chmod 0600 ~/.config/k-skill/secrets.env

 remote MCP endpoint는 사용자 `LAW_OC` 없이 `url`만으로 연결한다. 다만 기존 `korean-law-mcp` 경로가 서비스 장애로 막히면 `법망`(`https://api.beopmang.org`) MCP/REST를 fallback으로 사용할 수 있다.

+한국 부동산 실거래가 조회의 로컬/self-host 경로는 upstream `real-estate-mcp` 가 읽는 `DATA_GO_KR_API_KEY` 를 채운다. 2026-04-05 기준 upstream 문서에는 고정 public endpoint가 없어 self-host를 기본으로 보고, Cloudflare Tunnel/operator secret은 운영자별 값이라 기본 client secrets 파일에는 넣지 않는다.
+
 ## 확인

 ```bash
@ -60,6 +63,8 @@ bash scripts/check-setup.sh
 | KTX 예매 | `KSKILL_KTX_ID`, `KSKILL_KTX_PASSWORD` |
 | 한국 법령 검색 (로컬 CLI/MCP) | `LAW_OC` |
 | 한국 법령 검색 (remote MCP endpoint) | 사용자 시크릿 불필요 (`url`만 등록, 장애 시 `법망` fallback 가능) |
+| 한국 부동산 실거래가 조회 (로컬/stdio/self-host) | `DATA_GO_KR_API_KEY` |
+| 한국 부동산 실거래가 조회 (공유 URL) | 사용자 시크릿 불필요, 대신 운영자가 self-host + Cloudflare Tunnel + launchd/systemd 를 준비 |
 | 서울 지하철 도착정보 조회 | self-host 또는 배포 확인이 끝난 `KSKILL_PROXY_BASE_URL` |
 | 사용자 위치 미세먼지 조회 | `KSKILL_PROXY_BASE_URL` 또는 `AIR_KOREA_OPEN_API_KEY` |

@ -70,6 +75,7 @@ bash scripts/check-setup.sh
 - [서울 지하철 도착정보 가이드](features/seoul-subway-arrival.md)
 - [사용자 위치 미세먼지 조회 가이드](features/fine-dust-location.md)
 - [한국 법령 검색 가이드](features/korean-law-search.md)
+- [한국 부동산 실거래가 조회 가이드](features/real-estate-search.md)
 - [보안/시크릿 정책](security-and-secrets.md)

 설치 기본 흐름은 "전체 스킬 설치 → 개별 기능 사용" 이다.
--- a/docs/sources.md
+++ b/docs/sources.md
@ -13,6 +13,10 @@
 - `@ohah/hwpjs`: https://github.com/ohah/hwpjs
 - `hwp-mcp`: https://github.com/jkf87/hwp-mcp
 - korean-law-mcp: https://github.com/chrisryugj/korean-law-mcp
+- real-estate-mcp: https://github.com/tae0y/real-estate-mcp/tree/main
+- real-estate-mcp Codex guide: https://github.com/tae0y/real-estate-mcp/blob/main/docs/setup-codex-cli.md
+- real-estate-mcp Docker guide: https://github.com/tae0y/real-estate-mcp/blob/main/docs/setup-docker.md
+- real-estate-mcp OAuth guide: https://github.com/tae0y/real-estate-mcp/blob/main/docs/setup-oauth.md
 - beopmang: https://api.beopmang.org
 - `silver-flight-group/kakaocli`: https://github.com/silver-flight-group/kakaocli
 - KakaoTalk Mac 설치 참고(`mas`): https://velog.io/@bonjugi/%EB%A7%A5%EB%B6%81-M1%EC%97%90-homebrew%EB%A1%9C-node-vscode-%EC%B9%B4%EC%B9%B4%EC%98%A4%ED%86%A1-%EC%84%A4%EC%B9%98%ED%95%98%EA%B8%B0
--- a/examples/secrets.env.example
+++ b/examples/secrets.env.example
@ -3,5 +3,6 @@ KSKILL_SRT_PASSWORD=replace-me
 KSKILL_KTX_ID=replace-me
 KSKILL_KTX_PASSWORD=replace-me
 LAW_OC=replace-me
+DATA_GO_KR_API_KEY=replace-me
 AIR_KOREA_OPEN_API_KEY=replace-me
 KSKILL_PROXY_BASE_URL=https://your-proxy.example.com
--- a/k-skill-setup/SKILL.md
+++ b/k-skill-setup/SKILL.md
@ -68,6 +68,7 @@ KSKILL_SRT_PASSWORD=replace-me
 KSKILL_KTX_ID=replace-me
 KSKILL_KTX_PASSWORD=replace-me
 LAW_OC=replace-me
+DATA_GO_KR_API_KEY=replace-me
 AIR_KOREA_OPEN_API_KEY=replace-me
 KSKILL_PROXY_BASE_URL=https://your-proxy.example.com
 EOF
@ -80,6 +81,8 @@ chmod 0600 ~/.config/k-skill/secrets.env

 한국 법령 검색은 로컬 `korean-law-mcp` 경로를 쓸 때만 `LAW_OC` 를 채운다. remote endpoint는 사용자 `LAW_OC` 없이 `url`만 등록하면 되고, 기존 경로 장애 시에는 `법망`(`https://api.beopmang.org`)을 fallback으로 안내한다.

+한국 부동산 실거래가 조회는 upstream `real-estate-mcp` 의 로컬/stdio/self-host 경로를 쓸 때 `DATA_GO_KR_API_KEY` 를 채운다. 2026-04-05 기준 고정 public endpoint는 확인하지 못했으므로 shared URL이 필요하면 self-host + Cloudflare Tunnel + launchd(systemd) 운영을 먼저 설명한다.
+
 ### Missing secret response template

 인증 스킬에서 값이 빠졌을 때는 credential resolution order에 따라 확보한다.
@ -90,6 +93,8 @@ chmod 0600 ~/.config/k-skill/secrets.env
 - KTX: `KSKILL_KTX_ID`, `KSKILL_KTX_PASSWORD`
 - 로컬 한국 법령 검색: `LAW_OC` + `korean-law-mcp`
 - 한국 법령 검색 remote endpoint: 사용자 `LAW_OC` 없이 `url`만 등록, 장애 시 `법망` fallback
+- 로컬/stdio 한국 부동산 실거래가 조회: `DATA_GO_KR_API_KEY` + `real-estate-mcp`
+- 공유형 한국 부동산 실거래가 조회: 운영자가 self-host + Cloudflare Tunnel + launchd/systemd 준비
 - 서울 지하철: self-host 또는 배포 확인이 끝난 `KSKILL_PROXY_BASE_URL`
 - 사용자 위치 미세먼지 조회: `KSKILL_PROXY_BASE_URL` 또는 `AIR_KOREA_OPEN_API_KEY`

--- a/real-estate-search/SKILL.md
+++ b/real-estate-search/SKILL.md
@ -0,0 +1,245 @@
+---
+name: real-estate-search
+description: Use tae0y's real-estate-mcp for Korean apartment/officetel/villa/single-house real transaction price and rent lookups. If no hosted endpoint is available, self-host the upstream server with Cloudflare Tunnel and launchd.
+license: MIT
+metadata:
+  category: real-estate
+  locale: ko-KR
+  phase: v1
+---
+
+# Korean Real Estate Search
+
+## What this skill does
+
+한국 부동산 실거래가/전월세 조회가 필요할 때 **upstream `real-estate-mcp`**(`https://github.com/tae0y/real-estate-mcp/tree/main`)를 그대로 사용한다.
+이 저장소는 upstream 소스 코드를 vendoring 하지 않고, 연결/운영 가이드만 제공한다.
+
+대표 도구:
+
+- 아파트 매매 실거래가: `get_apartment_trades`
+- 아파트 전월세: `get_apartment_rent`
+- 오피스텔 매매/전월세: `get_officetel_trades`, `get_officetel_rent`
+- 연립다세대 매매/전월세: `get_villa_trades`, `get_villa_rent`
+- 단독/다가구 매매/전월세: `get_single_house_trades`, `get_single_house_rent`
+- 상업업무용 매매: `get_commercial_trade`
+- 청약홈 분양/당첨: `get_apt_subscription_info`, `get_apt_subscription_results`
+- 공공경매/온비드: `get_public_auction_items`, `get_public_auction_item_detail`
+- 지역코드 조회: `get_region_code`
+
+## When to use
+
+- "잠실 리센츠 2024년 매매 실거래가 찾아줘"
+- "마포구 아파트 전세 실거래가 보여줘"
+- "성수동 오피스텔 월세 실거래 데이터 볼래"
+- "세종시 청약 결과 찾아줘"
+- "실거래가 조회용 한국 부동산 MCP 붙여줘"
+
+## When not to use
+
+- 해외 부동산 시세/거래 조회
+- 실거래가가 아닌 민간 호가/매물 비교만 필요한 경우
+- 세금/등기/중개 법률자문처럼 판단이 필요한 경우
+- 이 저장소 안에 부동산 데이터 수집기나 새 서버 코드를 추가하려는 경우
+
+## Prerequisites
+
+- 인터넷 연결
+- `uv`
+- MCP 클라이언트(Codex CLI, Claude Desktop 등)
+- 공공데이터포털 API key (`DATA_GO_KR_API_KEY`)
+- upstream clone: `https://github.com/tae0y/real-estate-mcp/tree/main`
+
+`DATA_GO_KR_API_KEY` 하나만 넣어도 기본 부동산 조회는 시작할 수 있다.
+청약홈/온비드 키를 분리하고 싶으면 upstream 문서대로 `ODCLOUD_API_KEY`, `ODCLOUD_SERVICE_KEY`, `ONBID_API_KEY` 를 추가한다.
+
+## Codex CLI setup (stdio)
+
+로컬에서 가장 빠른 기본 경로는 Codex CLI stdio 연결이다.
+
+```bash
+git clone https://github.com/tae0y/real-estate-mcp.git
+cd real-estate-mcp
+
+codex mcp add real-estate \
+  --env DATA_GO_KR_API_KEY=your_api_key_here \
+  -- uv run --directory /path/to/real-estate-mcp \
+  python src/real_estate/mcp_server/server.py
+
+codex mcp list
+codex mcp get real-estate
+```
+
+## Claude Desktop setup (stdio)
+
+```json
+{
+  "mcpServers": {
+    "real-estate": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--directory", "/path/to/real-estate-mcp",
+        "python", "src/real_estate/mcp_server/server.py"
+      ],
+      "env": {
+        "DATA_GO_KR_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+## Shared HTTP setup
+
+여러 클라이언트가 같이 붙어야 하면 upstream HTTP 모드를 사용한다.
+
+```bash
+git clone https://github.com/tae0y/real-estate-mcp.git
+cd real-estate-mcp
+cp .env.example .env
+printf 'DATA_GO_KR_API_KEY=your_api_key_here\n' >> .env
+uv run real-estate-mcp --transport http --host 127.0.0.1 --port 8000
+```
+
+Codex CLI/Claude Desktop 에는 HTTP URL을 등록한다.
+
+```bash
+codex mcp add real-estate --url http://127.0.0.1:8000/mcp
+```
+
+```json
+{
+  "mcpServers": {
+    "real-estate": {
+      "url": "http://127.0.0.1:8000/mcp"
+    }
+  }
+}
+```
+
+## Self-host fallback when no hosted endpoint is available
+
+2026-04-05 기준, upstream README/docs에는 고정 public MCP URL이 문서화돼 있지 않았다. 그래서 인터넷에서 공유 가능한 endpoint가 미리 준비돼 있지 않다고 보고 **self-host를 기본 운영 경로**로 잡는다.
+
+### 1. Upstream Docker + Caddy로 로컬 HTTP 서버 띄우기
+
+```bash
+git clone https://github.com/tae0y/real-estate-mcp.git
+cd real-estate-mcp
+cp .env.example .env
+printf 'DATA_GO_KR_API_KEY=your_api_key_here\n' >> .env
+REPOSITORY_ROOT=$(pwd)
+docker compose -f "$REPOSITORY_ROOT"/docker/docker-compose.yml up -d --build
+```
+
+헬스 체크는 upstream 문서의 MCP initialize 예시로 확인한다.
+
+```bash
+curl -s -X POST http://localhost/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.1"}}}'
+```
+
+### 2. Cloudflare Tunnel로 적합한 도메인 붙이기
+
+```bash
+cloudflared tunnel login
+cloudflared tunnel create real-estate-mcp
+cloudflared tunnel route dns real-estate-mcp real-estate-mcp.example.com
+cat > ~/.cloudflared/config.yml <<'EOF'
+tunnel: real-estate-mcp
+credentials-file: /Users/YOUR_USER/.cloudflared/<tunnel-id>.json
+ingress:
+  - hostname: real-estate-mcp.example.com
+    service: http://localhost:80
+  - service: http_status:404
+EOF
+cloudflared tunnel run real-estate-mcp
+```
+
+공유용 HTTPS URL은 `https://real-estate-mcp.example.com/mcp` 형식으로 잡는다.
+public 인터넷에 노출한다면 upstream `docs/setup-oauth.md` 대로 `AUTH_MODE=oauth` 를 켜고 OAuth/Auth0를 붙인다.
+
+### 3. macOS launchd 자동 실행
+
+부팅 후 안정적으로 다시 뜨게 하려면 upstream 서버와 tunnel을 각각 launchd 로 올린다.
+
+`~/Library/LaunchAgents/com.kskill.real-estate-mcp.server.plist`
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+  <dict>
+    <key>Label</key><string>com.kskill.real-estate-mcp.server</string>
+    <key>ProgramArguments</key>
+    <array>
+      <string>/bin/zsh</string>
+      <string>-lc</string>
+      <string>cd $HOME/src/real-estate-mcp && docker compose -f docker/docker-compose.yml up -d</string>
+    </array>
+    <key>RunAtLoad</key><true/>
+    <key>KeepAlive</key><true/>
+  </dict>
+</plist>
+```
+
+`~/Library/LaunchAgents/com.kskill.real-estate-mcp.tunnel.plist`
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+  <dict>
+    <key>Label</key><string>com.kskill.real-estate-mcp.tunnel</string>
+    <key>ProgramArguments</key>
+    <array>
+      <string>/opt/homebrew/bin/cloudflared</string>
+      <string>tunnel</string>
+      <string>run</string>
+      <string>real-estate-mcp</string>
+    </array>
+    <key>RunAtLoad</key><true/>
+    <key>KeepAlive</key><true/>
+  </dict>
+</plist>
+```
+
+```bash
+launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.kskill.real-estate-mcp.server.plist
+launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.kskill.real-estate-mcp.tunnel.plist
+launchctl enable gui/$(id -u)/com.kskill.real-estate-mcp.server
+launchctl enable gui/$(id -u)/com.kskill.real-estate-mcp.tunnel
+```
+
+위 예시는 macOS 기준이다. Linux/Windows에서는 systemd 또는 서비스 관리자로 같은 역할을 분리해서 등록한다.
+
+## Response policy
+
+- 실거래가/전월세 요청이면 `get_region_code` 로 행정구역 코드를 먼저 확인한 뒤 자산 타입별 tool로 조회한다.
+- 아파트 매매는 `get_apartment_trades`, 아파트 전월세는 `get_apartment_rent` 를 우선 사용한다.
+- 오피스텔/빌라/단독주택/상업업무용은 자산 타입에 맞는 전용 tool로 라우팅한다.
+- 사용자가 동/건물명/연월을 덜 줬으면 지역, 단지명, 기준 월을 먼저 보강한다.
+- 실거래가와 호가를 섞어 말하지 않는다. 이 스킬은 국토교통부 기반 실거래/전월세 신고 데이터를 우선 다룬다.
+- 인터넷 공유용 endpoint가 미리 없다면 self-host + Cloudflare Tunnel + launchd 운영 경로를 안내한다.
+- upstream 소스는 이 저장소에 복사하지 않는다.
+
+## Done when
+
+- 요청 자산 타입에 맞는 `real-estate-mcp` tool이 선택되었다.
+- 필요한 경우 `get_region_code` 로 지역코드를 먼저 확인했다.
+- 실거래가/전월세/청약/경매 중 적절한 결과를 조회했다.
+- 로컬 stdio/HTTP 경로면 `DATA_GO_KR_API_KEY` 준비 여부를 확인했다.
+- hosted endpoint가 없으면 self-host + Cloudflare Tunnel + launchd 운영 경로를 제시했다.
+- 원본 MCP 링크(`https://github.com/tae0y/real-estate-mcp/tree/main`)를 함께 남겼다.
+
+## Notes
+
+- upstream: `https://github.com/tae0y/real-estate-mcp/tree/main`
+- upstream Codex guide: `https://github.com/tae0y/real-estate-mcp/blob/main/docs/setup-codex-cli.md`
+- upstream Docker guide: `https://github.com/tae0y/real-estate-mcp/blob/main/docs/setup-docker.md`
+- upstream OAuth guide: `https://github.com/tae0y/real-estate-mcp/blob/main/docs/setup-oauth.md`
+- official data source: 공공데이터포털 (`https://www.data.go.kr`)
+- 이 저장소에는 별도 workspace/package를 추가하지 않고 스킬 문서만 유지한다.
--- a/scripts/skill-docs.test.js
+++ b/scripts/skill-docs.test.js
@ -1195,6 +1195,68 @@ test("joseon-sillok-search install payload includes the documented helper comman
  }
 });

+test("repository docs advertise the real-estate-search skill and upstream self-host guidance", () => {
+  const readme = read("README.md");
+  const install = read(path.join("docs", "install.md"));
+  const setup = read(path.join("docs", "setup.md"));
+  const security = read(path.join("docs", "security-and-secrets.md"));
+  const setupSkill = read(path.join("k-skill-setup", "SKILL.md"));
+  const examplesSecrets = read(path.join("examples", "secrets.env.example"));
+  const featureDocPath = path.join(repoRoot, "docs", "features", "real-estate-search.md");
+  const featureDoc = read(path.join("docs", "features", "real-estate-search.md"));
+  const skillPath = path.join(repoRoot, "real-estate-search", "SKILL.md");
+  const skill = read(path.join("real-estate-search", "SKILL.md"));
+  const sources = read(path.join("docs", "sources.md"));
+  const roadmap = read(path.join("docs", "roadmap.md"));
+  const packageJson = readJson("package.json");
+
+  assert.ok(fs.existsSync(featureDocPath), "expected docs/features/real-estate-search.md to exist");
+  assert.ok(fs.existsSync(skillPath), "expected real-estate-search/SKILL.md to exist");
+
+  assert.match(readme, /\| 한국 부동산 실거래가 조회 \|/);
+  assert.match(readme, /\[한국 부동산 실거래가 조회 가이드\]\(docs\/features\/real-estate-search\.md\)/);
+  assert.match(install, /--skill real-estate-search/);
+
+  for (const doc of [skill, featureDoc]) {
+    assert.match(doc, /https:\/\/github\.com\/tae0y\/real-estate-mcp\/tree\/main/);
+    assert.match(doc, /DATA_GO_KR_API_KEY/);
+    assert.match(doc, /get_apartment_trades/);
+    assert.match(doc, /get_apartment_rent/);
+    assert.match(doc, /get_region_code/);
+    assert.match(doc, /Codex CLI|Claude Desktop/);
+    assert.match(doc, /Cloudflare Tunnel/i);
+    assert.match(doc, /launchd/i);
+    assert.match(doc, /uv run/);
+    assert.match(doc, /cloudflared tunnel/i);
+    assert.doesNotMatch(doc, /packages\/real-estate-search/);
+    assert.doesNotMatch(doc, /python-packages\/real-estate-search/);
+  }
+
+  for (const doc of [install]) {
+    assert.match(doc, /https:\/\/github\.com\/tae0y\/real-estate-mcp\/tree\/main/);
+    assert.match(doc, /DATA_GO_KR_API_KEY/);
+    assert.match(doc, /Codex CLI/);
+    assert.match(doc, /Cloudflare Tunnel/i);
+    assert.match(doc, /launchd/i);
+    assert.match(doc, /uv run/);
+    assert.match(doc, /cloudflared tunnel/i);
+  }
+
+  for (const doc of [setup, security, setupSkill]) {
+    assert.match(doc, /DATA_GO_KR_API_KEY/);
+    assert.match(doc, /real-estate-mcp/);
+  }
+
+  assert.match(examplesSecrets, /^DATA_GO_KR_API_KEY=replace-me$/m);
+  assert.match(sources, /real-estate-mcp: https:\/\/github\.com\/tae0y\/real-estate-mcp\/tree\/main/);
+  assert.match(roadmap, /한국 부동산 실거래가 조회 스킬 출시/);
+  assert.ok(
+    !packageJson.workspaces.some((workspace) => workspace.includes("real-estate-search")),
+    "expected no repo workspace to be added for real-estate-search",
+  );
+  assert.equal(fs.existsSync(path.join(repoRoot, "packages", "real-estate-search")), false);
+});
+
 test("repository docs advertise the shipped korean-spell-check helper assets", () => {
  const readme = read("README.md");
  const install = read(path.join("docs", "install.md"));