GameDrop MCP Server (gamedrop-mcp)

GameDrop MCP 서버는 스팀(Steam), 에픽게임즈 스토어(Epic Games Store), GOG, 험블 번들(Humble Store) 등 다양한 플랫폼의 무료 배포 게임, 할인율 순 게임 할인 정보 검색, 플랫폼별 가격 실시간 비교 및 최저가 조회, 그리고 상세 게임 정보를 인공지능 에이전트(Kakao PlayMCP, Claude Desktop, ChatGPT MCP 등)에게 실시간으로 제공하는 모델 컨텍스트 프로토콜(MCP) 서버입니다.

주요 기능 및 MCP 도구 (Tools)

본 서버는 다음 5가지 핵심 MCP 도구(Tool)를 노출합니다:

1. gameDropFreeGames: 현재 주요 플랫폼에서 무료로 배포되고 있는 게임 정보 및 구매/다운로드 링크 목록을 실시간으로 가져옵니다. (에픽게임즈 스토어 포함)
   • 파라미터: platform (all | steam | epic | gog)
2. gameDropDiscounts: 플랫폼별 현재 할인 중인 게임의 정상가, 할인가, 할인율 및 다이렉트 구매 링크 목록을 정렬해 반환합니다.
   • 파라미터: platform (all | steam | epic | gog), minDiscount (최소 할인율 %, 기본값: 50), limit (조회 개수, 기본값: 20)
3. gameDropSearch: 게임명(영문/한글 키워드)으로 게임의 ID 및 스토어별 최저가 정보를 빠르게 검색합니다.
   • 파라미터: keyword (검색어)
4. gameDropComparePrice: 입력받은 게임 타이틀에 대해 지원되는 모든 온라인 스토어(Steam, GOG, Epic, Humble 등)의 판매 가격을 실시간으로 비교하여 원화(KRW)로 정렬하고, 가장 저렴한 최저가 스토어 정보를 반환합니다.
   • 파라미터: title (게임 타이틀)
5. gameDropGameInfo: 스팀 API 데이터를 실시간으로 파싱하여 게임의 상세 소개 설명(한글화 우선 제공), 개발사, 퍼블리셔, 출시일, 장르(태그), 가격을 포괄적으로 반환합니다.
   • 파라미터: title (게임 타이틀)

---

환경 변수 설정 (.env)

프로젝트 루트에 .env 파일을 생성하고 아래 형식을 참고하여 설정합니다:

# HTTP 서버 포트 (Streamable HTTP 모드일 때만 적용됨, 기본값: 3000)
PORT=3000

# 트랜스포트 기본 모드 (sse 또는 stdio)
TRANSPORT=sse

# (선택 사항) 캐싱 성능 향상을 위한 Redis 서버 설정
# REDIS_URL=redis://localhost:6379

# (선택 사항) IsThereAnyDeal API 연동 시 필요한 API Key
ITAD_API_KEY=

---

로컬 개발 및 실행

1. 의존성 패키지 설치

npm install

2. 개발 모드로 실행 (핫 리로드)

npm run dev

3. TypeScript 컴파일 빌드

npm run build

4. 빌드된 프로덕션 서버 시작

npm run start

---

Docker 컨테이너 실행 및 빌드

이 프로젝트는 Docker 컨테이너 환경을 완벽하게 지원합니다.

Docker 단독 빌드 및 실행

# 1. Docker 이미지 빌드
docker build -t gamedrop-mcp .

# 2. 컨테이너 백그라운드 기동 (3000번 포트 연결)
docker run -d -p 3000:3000 --name gamedrop-mcp-server --env PORT=3000 gamedrop-mcp

Docker Compose 환경 실행 (Redis 캐시 포함)

docker-compose up -d --build

실행 후 http://localhost:3000/health 에 접속하여 정상 동작(Health Check) 여부를 확인할 수 있습니다.

---

MCP 플랫폼별 등록 및 사용법

1. Kakao PlayMCP (Streamable HTTP 기반 등록)

PlayMCP는 최신 MCP SDK의 Streamable HTTP 프로토콜을 사용해 MCP 서버를 등록할 수 있습니다.

• MCP Endpoint URL: http://<서버-도메인-또는-IP>:3000/mcp
• HTTP Method: GET/POST/DELETE (단일 /mcp 엔드포인트에서 모두 처리)

2. Claude Desktop (stdio 기반 등록)

Claude Desktop App의 MCP 설정 파일(claude_desktop_config.json)을 다음과 같이 편집하여 추가합니다:

• Windows 경로: %APPDATA%\Claude\claude_desktop_config.json
• macOS 경로: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "gamedrop-mcp": {
      "command": "node",
      "args": ["C:/absolute/path/to/gamedrop-mcp/build/src/index.js", "--transport=stdio"],
      "env": {
        "ITAD_API_KEY": ""
      }
    }
  }
}

3. ChatGPT MCP (stdio/Streamable HTTP 기반 등록)

사용하시는 ChatGPT MCP 커넥터 클라이언트의 지침에 따라 stdio 명령을 추가하거나, 실행 중인 Streamable HTTP 서비스 URL(http://<서버-도메인-또는-IP>:3000/mcp)을 기입하여 연동합니다.

---

아키텍처 및 복구력 (Resilience) 설계

• 안전한 로깅: stdio 모드로 구동될 때 stdout으로 로그가 유출되면 JSON-RPC 직렬화 규격이 손상됩니다. GameDrop MCP는 실행 모드를 감지하여 stdio 모드에서는 모든 시스템 로그를 stderr로 안전하게 우회 출력을 적용했습니다.
• 예외 복구력: Zod 스키마로 들어오는 인풋을 사전에 엄격히 검증하며, 외부 API 연동 에러가 발생해도 전체 서버의 다운타임으로 이어지지 않고 상세한 에러 원인을 JSON 결과 구조에 녹여 반환합니다.
• 이중 캐싱 시스템: ioredis를 지원하여 분산 서버나 컨테이너 환경에서는 Redis를 사용하여 부하를 덜고, Redis가 감지되지 않거나 연결 에러가 발생할 시 로컬 메모리-TTL 캐시 방식으로 자동 대체되어 무중단 구동됩니다.
• 환율 동적 변환: CheapShark API의 모든 달러($) 가격은 오픈 환율 API를 통해 원화(KRW)로 실시간 환산하여 한눈에 쉽게 딜을 파악할 수 있게 가공합니다.