# kofic-mcp-server

영화진흥위원회(KOFIC) 박스오피스 오픈API를 감싼 MCP 서버. Vercel에 배포해서
Claude의 커스텀 커넥터로 연결하는 것을 목표로 합니다.

## 1. 로컬 설정

```bash
npm install
cp .env.example .env.local
# .env.local 에 KOFIC_API_KEY 입력
npm run dev
```

로컬에서 `http://localhost:3000/mcp` 로 MCP 엔드포인트가 뜹니다.
[MCP Inspector](https://github.com/modelcontextprotocol/inspector)로 테스트해보세요:

```bash
npx @modelcontextprotocol/inspector@latest
```

Inspector에서 Transport를 Streamable HTTP로 두고 위 URL을 입력하면
tool 목록(`get_daily_boxoffice`, `get_weekly_boxoffice`, `search_movie`, `get_movie_info`)이 보이고,
직접 호출해서 KOFIC 응답이 제대로 오는지 확인할 수 있습니다.

## 2. Vercel 배포

```bash
npx vercel
```

배포 후 Vercel 프로젝트 Settings > Environment Variables 에서
`KOFIC_API_KEY` 를 등록하고 재배포하세요 (`npx vercel --prod`).

## 3. Claude에 연결

1. claude.ai → Settings → Connectors → Add custom connector
2. URL에 `https://<your-project>.vercel.app/mcp` 입력
3. 대화(프로젝트 포함)에서 "+" 메뉴로 커넥터를 켠 뒤 사용

## 현재 제공 tool

- `get_daily_boxoffice(targetDt, itemPerPage?)` — 일별 박스오피스 + 그 시점 누적관객수
- `get_weekly_boxoffice(targetDt, weekGb?)` — 주간/주말/주중 박스오피스
- `search_movie(movieNm)` — 영화명으로 movieCd 검색
- `get_movie_info(movieCd)` — 개봉일/감독/배우 등 상세정보

## 다음 단계 (아직 미구현)

- Day14 / Day49 누적관객수 자동 수집 (개봉일 기준 날짜 계산 + 여러 날짜 순회 조회)
- 2주차 드롭율, 뒷심 배수(Day49/Day14) 계산 로직
- 4분면 포지셔닝 분류 tool (`classify_boxoffice_pattern` 같은 이름으로 추가 예정)