# 청약 도우미 — Claude·Codex용 MCP 서버

Claude와 Codex에서 내 청약 조건에 맞는 공고를 비교하고, 주거비·대출·자금 계획을 계산하고 저장하는 도구입니다. 같은 서비스 계정으로 연결하면 두 AI에서 같은 개인 자료를 이어서 사용할 수 있습니다.

**Node.js만으로 실행할 수 있습니다. Docker는 선택 사항입니다.** 이 저장소는 직접 운영하는 서버 프로그램이며, 다운로드만으로 공용 온라인 서버가 생기지는 않습니다.

[최신 배포 ZIP 다운로드](https://github.com/ANNJUNGCHAN/housing-mcp/releases/latest/download/housing-mcp.zip) · [전체 릴리스](https://github.com/ANNJUNGCHAN/housing-mcp/releases) · [운영·배포 안내](docs/operations.md)

## 빠르게 시작하기

준비물은 **Node.js 22.14 이상**과 로컬 도구 연결을 지원하는 Codex 또는 Claude Code입니다. [Node.js 다운로드](https://nodejs.org/en/download)에서 지원되는 LTS 버전을 설치하고 `node --version`으로 확인하세요. Node 22에서는 SQLite 실험 기능 경고가 나올 수 있습니다.

1. 위 ZIP을 다운로드해 압축을 풀고, **`package.json`이 있는 폴더**에서 터미널을 엽니다. Git을 사용한다면 다음으로 내려받습니다.

   ```sh
   git clone https://github.com/ANNJUNGCHAN/housing-mcp.git
   cd housing-mcp
   ```

2. Windows PowerShell, macOS 또는 Linux 터미널에서 실행합니다.

   ```sh
   npm ci
   npm run setup
   npm start
   ```

3. 초기 설정에서 사용할 이메일을 입력합니다. 설정 도구가 로컬 실행용 `.env`와 **한 번만 사용하는 가입 링크**를 준비합니다. 이미 있는 `.env`는 덮어쓰지 않습니다.
4. 서버가 실행된 상태에서 출력된 가입 링크를 브라우저로 열고 비밀번호를 정합니다. 이메일을 발송하는 기능은 없으며, 가입 링크는 24시간 동안 유효합니다.
5. 아래 방법으로 AI에 연결합니다. 로컬로 사용할 때는 이 터미널의 서버를 계속 실행해 둡니다.

여기서 만드는 계정은 **이 청약 도우미 서버의 계정**입니다. Claude·OpenAI 계정 비밀번호나 AI API 키를 입력하지 않습니다.

| 로컬 주소 | 용도 |
|---|---|
| `http://127.0.0.1:8787/account` | 로그인, AI 연결 권한 철회 |
| `http://127.0.0.1:8787/mcp` | Claude Code·Codex에 등록할 MCP 주소 |
| `http://127.0.0.1:8787/healthz` | 서버 동작 확인 |

## AI에 연결하기

### Codex

Codex CLI가 설치된 터미널에서 실행합니다.

```sh
codex mcp add housing --url http://127.0.0.1:8787/mcp
codex mcp login housing --scopes housing --oauth-client-registration dcr
```

열리는 브라우저에서 청약 도우미 계정으로 로그인하고 **연결 허용**을 선택합니다. Codex 앱에서는 MCP 서버 설정에 같은 URL을 추가하고 인증할 수 있습니다.

### Claude Code

```sh
claude mcp add --transport http --scope user housing http://127.0.0.1:8787/mcp
```

Claude Code 대화에서 `/mcp`를 열어 `housing`의 인증을 시작하고, 청약 도우미 계정으로 로그인해 연결을 허용합니다.

### 일반 Claude 웹·데스크톱·모바일

일반 Claude의 **원격 연결은 인터넷에서 접근할 수 있는 HTTPS 서버**가 필요합니다. 위의 `127.0.0.1` 주소는 같은 컴퓨터에서 쓰는 Codex·Claude Code용입니다.

운영자가 제공한 `https://실제-서버-주소/mcp`를 Claude의 사용자 지정 연결에 등록하세요. OAuth 등록 방법을 선택할 수 있으면 **자동 등록 / Register automatically**를 사용합니다. 별도 클라이언트 비밀키는 필요하지 않습니다. 조직 계정은 관리자의 연결 정책을 따릅니다.

서버를 직접 공개하려면 [HTTPS 배포 안내](docs/operations.md#외부-https-서버로-운영하기)를 따릅니다. 직접 Node.js를 실행하는 방법과 선택 사항인 Docker 구성을 제공합니다.

## 연결 후 이렇게 요청하세요

- “내 청약통장과 관심 지역을 등록해 줘. 모르는 조건은 미확인으로 남겨 줘.”
- “현재 공고를 찾고 내 조건과 비교해 줘. 원문 확인이 필요한 항목도 알려 줘.”
- “대출 3억 원, 연 4%, 30년이라는 가정으로 월별 상환액을 계산해 줘.”
- “이 후보와 자금 계획을 저장하고 다음에 다시 보여 줘.”

기능은 **청약·통근 조건 저장, 청약홈·LH 공고 조회, 입력한 원문 조건 비교, 주거비 비교, 대출·완납기간·상환여력 계산, 후보·자금 계획 저장**입니다. AI가 사용할 17개 도구와 입력 형식은 연결 시 자동으로 전달됩니다.

### 공공데이터 API 키는 선택 사항입니다

비용·대출 계산과 개인 조건·후보·계획 저장은 키 없이 사용할 수 있습니다. 청약홈·LH의 **API 공고 목록 조회**에는 공공데이터포털 일반 인증키와 해당 서비스 활용신청이 필요합니다.

키가 있다면 서버의 `.env`에 저장하고 재시작합니다.

```dotenv
DATA_GOV_API_KEY=발급받은_공공데이터포털_일반_인증키
```

키는 AI 대화나 도구 입력에 붙여넣지 않습니다. 키가 없거나 API가 실패하면 서버는 조회 불가·불완전 상태를 표시합니다. 연결한 AI가 웹 검색을 지원하면 공식 웹 공고를 별도로 확인하도록 요청할 수 있습니다. 이 서버 자체에 별도 AI 호출 비용이 발생하는 코드는 없습니다.

공고 목록은 최종 자격 확인이 아닙니다. 원문·정정 공고와 복합 자격은 별도로 확인하며 계산 결과는 입력한 가정에 따른 산술 결과입니다. 기존 시세 연구 DB, 가격 예측 모델, 청약 신청 제출, 자동 알림 발송은 포함하지 않습니다.

## 여러 사람이 함께 쓰기

사용 방법은 두 가지입니다.

| 방법 | 데이터가 저장되는 곳 | 접속 방법 |
|---|---|---|
| 각자 내려받아 자기 PC에서 실행 | 각자 PC의 데이터 폴더 | 같은 PC의 Codex·Claude Code로 연결 |
| 한 운영자가 HTTPS 서버를 운영 | 그 서버의 사용자별 저장소 | 각자 초대받아 가입한 후 자신의 Claude·Codex에서 연결 |

공유 서버에서는 운영자가 `npm run admin -- invite person@example.com`으로 초대 링크를 만듭니다. 각 사용자는 자신의 계정으로 로그인하며 다른 사용자의 프로필·후보·계획에 접근할 수 없습니다. 같은 사람이 같은 서버 계정으로 연결한 Claude와 Codex는 저장 자료를 공유하지만 **AI 대화 기록 자체가 동기화되지는 않습니다.**

기본 데이터는 `var/`의 SQLite에 저장됩니다. 다른 서버로 옮길 때는 백업·복구가 필요합니다. 운영자는 서버 파일에 접근할 수 있으므로, 공유 서버 이용자는 운영 주체를 확인하고 사용하는 것이 좋습니다. [.env·데이터 관리 및 백업](docs/operations.md#데이터와-백업)에 자세한 내용을 정리했습니다.

## 업데이트와 문제 해결

Git으로 설치했다면 서버를 멈추고 `git pull`, `npm ci`를 실행한 뒤 다시 `npm start`로 시작합니다. ZIP으로 설치했다면 새 버전으로 교체하기 전에 `.env`와 데이터 폴더를 따로 백업하고 새 버전에 복원합니다. 업데이트할 때 개인 데이터 폴더를 덮어쓰거나 삭제하지 않습니다.

| 증상 | 확인할 것 |
|---|---|
| `node` 또는 `npm`을 찾을 수 없음 | Node.js 설치 후 터미널을 다시 열기 |
| Node/SQLite 기능 오류 | `node --version`이 22.14 이상인지 확인 |
| 로컬 서버가 시작되지 않음 | `npm run setup` 실행 여부와 8787 포트 사용 여부 |
| API 공고가 비어 있거나 조회 불가 | `DATA_GOV_API_KEY`와 서비스별 활용신청 상태, 반환된 오류·조회 범위 |
| Claude 웹에서 로컬 주소에 연결되지 않음 | 외부에서 접근 가능한 HTTPS 주소 사용 |
| 비밀번호를 잊음 | 운영자가 `npm run admin -- reset 이메일`로 재설정 링크 발급 |

문제를 올릴 때는 비밀번호, 초대·재설정 링크, API 키, 개인 조건과 데이터 파일을 제외해 주세요.

## 개발·검증

```sh
npm run check
npm test
```

테스트는 임시 DB와 합성 입력·모의 API를 사용합니다. GitHub Actions는 Windows·Ubuntu의 Node.js 22.14와 24에서 검사하도록 구성되어 있습니다. [Actions 실행 결과](https://github.com/ANNJUNGCHAN/housing-mcp/actions)와 [검증 범위](VERIFICATION.md)를 확인할 수 있습니다. 실제 Claude·Codex 계정 연결과 공개 HTTPS 운영은 배포 환경에서 별도 확인해야 합니다.

소프트웨어는 [MIT 라이선스](LICENSE)입니다. 외부 라이브러리와 공공데이터 이용 조건은 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)를 참고하세요.