# ⚽🏀 SportsPulse MCP

> Claude Desktop에서 실시간 스포츠 데이터를 사용할 수 있게 해주는 MCP 서버

## 🆓 사용하는 무료 API

| API | 비용 | 데이터 |
|-----|------|--------|
| [TheSportsDB](https://www.thesportsdb.com/api.php) | 완전 무료 (key: `3`) | 팀 일정, 결과, 맞대결, 순위 |
| [balldontlie.io](https://www.balldontlie.io) | 완전 무료 (키 불필요) | NBA 경기, 선수 스탯 |
| [API-Football](https://rapidapi.com/api-sports/api/api-football) | 무료 100req/day | 🔴 라이브 스코어, 실시간 순위 |

> ⚡ TheSportsDB + balldontlie 만으로도 바로 사용 가능!  
> API-Football은 선택사항 (라이브 스코어 원할 때만 발급)

---

## 🚀 설치 방법

### 1. 의존성 설치 & 빌드

```bash
git clone <this-repo>
cd sports-mcp
npm install
npm run build
```

### 2. 환경 변수 설정

```bash
cp .env.example .env
# .env 파일에서 RAPIDAPI_KEY 값만 교체 (선택사항)
```

### 3. Claude Desktop 설정

Claude Desktop 설정 파일을 열고:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`  
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

아래 내용을 추가 (경로는 본인 환경에 맞게 수정):

```json
{
  "mcpServers": {
    "sports-pulse": {
      "command": "node",
      "args": ["/Users/yourname/sports-mcp/dist/index.js"],
      "env": {
        "SPORTSDB_API_KEY": "3",
        "RAPIDAPI_KEY": "your_rapidapi_key_here"
      }
    }
  }
}
```

### 4. Claude Desktop 재시작

설정 저장 후 Claude Desktop을 완전히 종료 후 재시작하면 tools 아이콘(🔧)에 스포츠 도구들이 나타납니다!

---

## 💬 사용 예시

Claude Desktop에서 이렇게 물어보세요:

```
"오늘 EPL 경기 있어?"
"손흥민 다음 경기 언제야?"
"맨시티 최근 5경기 결과 알려줘"
"EPL 순위 보여줘"
"맨유 vs 리버풀 역대 전적이 어때?"
"레이커스 오늘 경기 했어?"
"LeBron James 이번 시즌 스탯 어때?"
"내 관심팀 토트넘이랑 레이커스 이번 주 경기 브리핑해줘"
```

---

## 🛠️ 지원 도구 (Tools)

| Tool | 설명 | 필요 API |
|------|------|---------|
| `get_live_scores` | 🔴 라이브 스코어 | API-Football |
| `get_today_fixtures` | 오늘 경기 일정/결과 | API-Football |
| `get_upcoming_fixtures` | 팀 다음 경기 일정 | TheSportsDB |
| `get_recent_results` | 팀 최근 경기 결과 | TheSportsDB |
| `get_standings` | 리그 순위표 | 둘 다 시도 |
| `get_head_to_head` | 맞대결 기록 | TheSportsDB |
| `get_nba_today` | NBA 오늘 경기 | balldontlie |
| `get_nba_team_games` | NBA 팀 최근 경기 | balldontlie |
| `get_nba_player_stats` | NBA 선수 스탯 | balldontlie |
| `get_weekly_briefing` | 관심팀 주간 브리핑 | TheSportsDB + balldontlie |

---

## 🔧 트러블슈팅

**Q: Claude에서 tool이 안 보여요**
- `dist/index.js` 파일이 있는지 확인 (`npm run build` 재실행)
- config.json의 `args` 경로가 절대경로인지 확인
- Claude Desktop 완전 재시작 (메뉴바에서 완전 종료)

**Q: "팀을 찾을 수 없습니다" 오류**
- 영어 팀 이름으로 시도 (예: "Tottenham" 대신 "Tottenham Hotspur")
- TheSportsDB에서 팀명 검색 확인: `https://www.thesportsdb.com/api/v1/json/3/searchteams.php?t=Tottenham`

**Q: 라이브 스코어가 안 돼요**
- `.env`의 `RAPIDAPI_KEY` 확인
- 무료 100req/day 초과 여부 확인

---

## 📦 프로젝트 구조

```
sports-mcp/
├── src/
│   ├── index.ts          # MCP 서버 메인 + 모든 tool 핸들러
│   ├── types.ts           # 공통 타입 정의
│   ├── utils.ts           # 시간대 변환, 팀 이름 정규화
│   └── adapters/
│       ├── sportsdb.ts    # TheSportsDB API
│       ├── nba.ts         # balldontlie.io NBA API
│       └── apifootball.ts # API-Football (RapidAPI)
├── dist/                  # 컴파일 결과 (npm run build 후 생성)
├── .env.example
├── package.json
└── tsconfig.json
```