# 공모전 정보 검색 MCP 서버

**Agentic Player 10 (카카오 PlayMCP 공모전)** 참가용으로 만든 MCP 서버입니다. 국내 공모전 정보를 검색/조회하는 4개의 도구(Tool)를 제공합니다.

## 제공 도구

| 도구 | 설명 |
|---|---|
| `search_contests(query, category)` | 키워드/분야로 공모전 검색 |
| `get_contest_detail(contest_id)` | 특정 공모전 상세 정보 조회 |
| `list_categories()` | 등록된 분야(카테고리) 목록 조회 |
| `list_deadline_soon(days)` | N일 이내 마감되는 공모전 조회 |

데이터는 `data/contests.json`에 있으며(2026-07-11 기준, 28건), 링커리어(linkareer.com) 등 공개 공모전 정보 사이트를 참고해 정리한 샘플 데이터입니다. 실제 서비스로 확장하려면 이 파일을 최신 데이터로 교체하거나, 크롤러/API 연동으로 대체하면 됩니다.

## 기술 스택

- Python 3.11 + [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) (`FastMCP`)
- Transport: **Streamable HTTP** (PlayMCP in KC는 원격 MCP 서버만 지원하며 Streamable HTTP가 표준입니다 — [참고](https://tech.kakao.com/posts/734))
- 엔드포인트: `POST /mcp` (FastMCP 기본 경로)

## 로컬 실행

```bash
pip install -r requirements.txt
python server.py
# http://localhost:8080/mcp 에서 Streamable HTTP MCP 서버가 뜹니다.
```

포트는 `PORT` 환경변수로 바꿀 수 있습니다 (기본 8080).

### 테스트 방법

**1) MCP Inspector 사용 (권장)**

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

Inspector UI에서 Transport를 `Streamable HTTP`로 선택하고 URL에 `http://localhost:8080/mcp` 입력 후 연결 → Tools 탭에서 4개 도구 확인 및 호출 테스트.

**2) Python 클라이언트로 직접 테스트**

```python
import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    async with streamablehttp_client("http://localhost:8080/mcp") as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            print(await session.list_tools())
            print(await session.call_tool("search_contests", {"query": "AI"}))

asyncio.run(main())
```

이 저장소는 위 방식으로 이미 로컬에서 initialize → tools/list → tools/call 전체 플로우를 검증했습니다.

## Docker 빌드/실행 (선택)

```bash
docker build --platform linux/amd64 -t contest-mcp .
docker run --rm -p 8080:8080 contest-mcp
```

`--platform linux/amd64`는 Apple Silicon 등 arm64 환경에서 빌드할 때 필요합니다. (PlayMCP in KC는 컨테이너 이미지 등록 시 linux/amd64만 지원합니다.)

## PlayMCP in KC 배포 (Git 소스 빌드 방식, 권장)

1. 이 프로젝트를 GitHub 저장소로 push합니다 (루트에 `Dockerfile` 필수 — 이미 포함되어 있음).
2. https://playmcp.kakaocloud.io 접속 → 카카오 계정 로그인 (PlayMCP 가입 계정이어야 함).
3. "+ 새 MCP 서버 등록" → "Git 소스 빌드" 선택.
   - MCP 서버 이름 / 설명 입력
   - Git URL: 저장소 주소
   - 브랜치: `main`
   - Dockerfile 경로: `Dockerfile` (기본값)
   - PAT: 저장소가 private이면 GitHub PAT 입력, public이면 비워둠
4. 등록 후 Status가 `Active`가 될 때까지 대기 → 상세 정보에서 **Endpoint URL** 복사.

## PlayMCP 등록 및 공모전 접수

1. https://playmcp.kakao.com 가입/로그인.
2. 개발자 콘솔 → "새로운 MCP 서버 등록" → MCP Endpoint에 위에서 복사한 URL 입력 → "정보 불러오기" (성공해야 함).
3. **"임시 등록"** 클릭 (등록 및 심사요청은 아직 누르지 않음).
4. "MCP 상세 미리보기" → "도구함에 추가" → AI 채팅으로 충분히 테스트.
5. 테스트 완료 후 "심사 요청" 클릭 → 승인되면 공개 상태를 "전체 공개"로 전환.
6. 공개된 MCP 상세페이지 URL 복사.
7. Agentic Player 10 공모전 페이지 → "Player 예선 참여" 버튼 → 비즈폼 접수 (MCP 서버 최대 2개 등록 가능).

**예선 접수 기간: 2026년 6월 15일 ~ 7월 14일** — PlayMCP in KC의 MCP 서버 발급도 이 기간에만 가능하므로 여유 있게 진행하세요.

## 데이터 갱신

`data/contests.json`을 편집한 뒤 다시 배포(Git push → PlayMCP in KC가 재빌드, 또는 기존 서버 삭제 후 동일 이름으로 재등록 → PlayMCP에서 "정보 수정"으로 재조회)하면 됩니다.

## 프로젝트 구조

```
contest-mcp-server/
├── server.py           # MCP 서버 (FastMCP, Streamable HTTP)
├── data/
│   └── contests.json   # 공모전 데이터
├── requirements.txt
├── Dockerfile
└── README.md
```