# Steam Gamepick MCP

**Steam Gamepick MCP**는 Steam 라이브러리, 플레이타임, 할인 후보, 리뷰 데이터를 활용해 사용자가 **지금 플레이할 게임**과 **구매할 만한 할인 게임**을 고르도록 돕는 개인화 게임 큐레이터 MCP 서버입니다.

이 프로젝트는 PlayMCP 제출을 고려해 모든 Tool의 `description`에 서비스명 **Steam Gamepick MCP**를 포함하고, 모든 Tool에 `annotations`를 정의한 형태로 구성되어 있습니다.

---

## 1. 서비스 개요

Steam에는 수많은 게임과 할인 정보가 있지만, 사용자는 다음과 같은 고민을 자주 하게 됩니다.

- 사놓고 플레이하지 않은 게임이 너무 많음
- 할인 게임이 많아 무엇을 사야 할지 고르기 어려움
- 이미 보유한 게임이 추천 후보에 섞임
- 리뷰나 플레이타임을 함께 보고 판단하고 싶음

**Steam Gamepick MCP**는 사용자의 Steam 라이브러리와 상점 데이터를 기반으로 다음 결정을 돕습니다.

- 내 Steam 라이브러리 분석
- 많이 플레이한 게임과 방치한 게임 확인
- 보유 게임을 제외한 할인 게임 추천
- Steam 앱 상세 정보 조회
- Steam 리뷰 원천 데이터 조회
- 경쟁작 또는 장르별 후보 검색

---

## 2. 핵심 보안 설계

이 서버는 기본적으로 **무상태(stateless) MCP 서버**입니다.

- Steam API Key를 코드에 하드코딩하지 않습니다.
- 사용자의 Steam API Key를 서버 파일, DB, `.env`에 저장하지 않습니다.
- 개인 Steam 라이브러리 접근이 필요한 Tool은 `steam_api_key`와 `player`를 입력값으로 받습니다.
- 같은 대화 안에서 반복 입력을 줄이는 흐름은 서버 저장이 아니라 `GAMEPICK_SKILL.md`의 스킬 지침으로 처리합니다.
- 서버 환경변수 `STEAM_API_KEY`는 선택적 fallback 용도이며, GitHub에는 실제 Key를 올리지 않습니다.

개인 정보가 필요한 요청에서 `steam_api_key` 또는 `player`가 누락되면 Tool은 실행을 거부하고 필요한 입력을 안내합니다.

---

## 3. PlayMCP 제출 양식 대응

모든 Tool은 다음 조건을 만족하도록 작성되어 있습니다.

| 항목 | 적용 내용 |
|---|---|
| 서비스명 | 모든 Tool `description`에 **Steam Gamepick MCP** 포함 |
| annotations | 모든 Tool에 `annotations` 정의 |
| title | Tool별 제목 정의 |
| readOnlyHint | 조회/분석 중심이므로 `True` |
| destructiveHint | 외부 데이터 삭제/수정 없음, `False` |
| idempotentHint | 동일 입력에 대해 동일 성격의 조회 결과 반환, `True` |
| openWorldHint | Steam 외부 API/상점 정보 조회, `True` |

---

## 4. Skill 기반 사용 흐름

`GAMEPICK_SKILL.md`는 Steam API Key와 Steam 사용자 식별자를 안전하게 재사용하기 위한 사용 지침입니다.

스킬의 역할은 다음과 같습니다.

1. 사용자가 같은 대화 안에서 Steam API Key를 제공했다면 이후 Steam Gamepick MCP Tool 호출에 `steam_api_key`로 함께 전달합니다.
2. 사용자가 같은 대화 안에서 SteamID64, Steam 프로필 URL, 또는 Vanity URL 이름을 제공했다면 이후 Tool 호출에 `player`로 함께 전달합니다.
3. 개인 라이브러리 접근 요청인데 `steam_api_key` 또는 `player`가 없으면 먼저 사용자에게 요청합니다.
4. Steam API Key 전체를 응답에 다시 출력하지 않습니다.
5. Steam API Key가 서버에 저장되었다고 안내하지 않습니다.

중요한 점은 **스킬이 서버 저장소 역할을 하는 것이 아니라, 같은 대화 안에서 사용자가 제공한 값을 Tool 호출 인자로 다시 전달하는 흐름을 안내한다는 것**입니다.

---

## 5. 제공 Tool 목록

| Tool | 설명 | API Key 필요 |
|---|---|---:|
| `get_gamepick_skill_instructions` | Steam Gamepick MCP의 스킬 사용법과 무상태 보안 원칙을 안내합니다. | 아니오 |
| `resolve_steam_player` | SteamID64 또는 프로필명/Vanity URL 이름을 SteamID64로 확인합니다. 프로필명 변환에는 API Key가 필요합니다. | 조건부 |
| `get_owned_games` | Steam ID 또는 프로필명 기준으로 보유 게임과 플레이타임 목록을 조회합니다. | 예 |
| `analyze_library` | 라이브러리 플레이타임을 분석해 많이 한 게임, 미플레이 게임, 방치 게임을 정리합니다. | 예 |
| `get_app_details` | Steam appid로 상점 상세 정보, 가격, 할인율, 장르를 조회합니다. | 아니오 |
| `get_featured_discounted_games` | Steam featured 목록에서 할인 게임 후보를 가져옵니다. 전체 할인 목록 전수조사는 아닙니다. | 아니오 |
| `recommend_discounted_games_for_user` | 사용자의 보유 게임을 제외하고 featured 할인 후보 중 추천할 만한 게임을 반환합니다. | 예 |
| `get_game_reviews` | Steam 앱 리뷰와 리뷰 요약 통계를 가져와 장단점 요약의 원천 데이터를 제공합니다. | 아니오 |
| `search_store_games` | Steam Store 검색 결과를 가져와 경쟁작 분석이나 장르별 후보 탐색에 사용합니다. | 아니오 |

---

## 6. 개인화 Tool 입력 예시

개인 Steam 라이브러리 접근이 필요한 Tool은 다음 값을 받습니다.

```json
{
  "steam_api_key": "사용자 Steam Web API Key",
  "player": "SteamID64 또는 Steam 프로필명"
}
```

`player`에는 다음 형식을 사용할 수 있습니다.

```text
7656119xxxxxxxxxx
https://steamcommunity.com/profiles/7656119xxxxxxxxxx
https://steamcommunity.com/id/my_vanity_name
my_vanity_name
```

SteamID64는 API Key 없이 그대로 사용할 수 있습니다. 프로필명/Vanity URL을 SteamID64로 변환하려면 Steam API Key가 필요합니다.

---

## 7. 대표 대화 예시

각 질문은 PlayMCP 예시 질문으로 사용하기 쉽도록 짧게 구성할 수 있습니다.

```text
내 스팀 라이브러리 분석해줘
```

```text
지금 할인 중인 게임 추천해줘
```

```text
내가 안 한 게임 중 하나 골라줘
```

개인 라이브러리 접근이 필요한 질문의 경우, Steam Gamepick MCP는 Steam API Key와 Steam 사용자 식별자가 없으면 먼저 입력을 요청합니다.

---

## 8. 실행 방법

### Docker 실행

```bash
docker build -t steam-gamepick-mcp .
docker run --rm -p 8000:8000 steam-gamepick-mcp
```

기본 MCP 엔드포인트:

```text
http://localhost:8000/mcp
```

### 선택적 환경변수 사용

서버 운영자가 fallback용 Steam API Key를 환경변수로 제공할 수도 있습니다. 단, GitHub에는 실제 API Key를 올리지 마세요.

```bash
docker run --rm -p 8000:8000 -e STEAM_API_KEY="your_steam_web_api_key_here" steam-gamepick-mcp
```

포트 변경:

```bash
docker run --rm -p 9000:9000 -e PORT=9000 steam-gamepick-mcp
```

---

## 9. 로컬 실행

### Windows

```bash
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
python server.py
```

### macOS/Linux

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python server.py
```

---

## 10. 환경변수

| 이름 | 기본값 | 설명 |
|---|---:|---|
| `PORT` | `8000` | Streamable HTTP MCP 서버 포트 |
| `STEAM_API_KEY` | 없음 | 선택 사항. 입력값 `steam_api_key`가 없을 때만 fallback으로 사용합니다. |

---

## 11. 의존성

`requirements.txt`는 제출용 Dockerfile 형식에 맞춰 아래 3개만 사용합니다.

```text
fastmcp
uvicorn
starlette
```

---

## 12. 파일 구성

```text
gamepick_mcp/
├─ server.py
├─ requirements.txt
├─ Dockerfile
├─ README.md
├─ GAMEPICK_SKILL.md
├─ .env.example
└─ .gitignore
```

---

## 13. 주의사항

- Steam 라이브러리 조회는 사용자의 Steam 프로필 공개 설정에 영향을 받을 수 있습니다.
- 할인 정보는 Steam Store 공개 featured/store 엔드포인트 기반이므로 전체 Steam 할인 목록 전수조사를 보장하지 않습니다.
- Steam API Key는 GitHub에 올리지 마세요.
- `.env`는 커밋하지 말고, `.env.example`만 커밋하세요.
- 공개 서버에서 사용자별 API Key를 서버에 저장하지 않도록 설계했습니다.

---

## 14. 한 줄 소개

**Steam Gamepick MCP는 Steam 라이브러리와 할인 정보를 분석해 지금 할 게임과 살 게임을 추천해주는 개인화 게임 큐레이터입니다.**