Beast ⚾ — 사회인야구 전력분석 (게임원 × Claude)

게임원(gameone.kr) 의 우리 리그 데이터를 자동 수집해서, Claude Desktop에서 자연어로 팀 분석·라인업·상대 전략을 받아보는 도구입니다.

예) Claude Desktop에 "리드오프 상대 전략 짜줘" / "우리 팀 라인업 추천해줘" / "최신 데이터로 B조 순위 보여줘" 라고 말하면, Claude가 알아서 데이터를 불러와 분석합니다.

• 리그: 사이언스리그 B조 (lig_idx=85)

• 우리 팀: The Beasts (club_idx=22098)

🧠 어떻게 동작하나

게임원(로그인) ──크롤링──▶ 파싱 ──▶ SQLite 저장
                                      │
                          MCP 서버(데이터 도구 9개)
                                      │  stdio
                              Claude Desktop  ← 여기서 자연어로 분석 요청

• 데이터 수집/정리는 이 프로그램이, 분석(라인업·전략)은 Claude Desktop이 직접 합니다.

• 그래서 별도 API 키가 필요 없습니다 (Claude Desktop 구독으로 동작).

Related MCP server: Database Tools for Claude AI

✅ 사전 요구사항

1. macOS (Windows도 가능, 경로만 다름) + Claude Desktop 설치

2. Python 3.10 이상 (아래 설치 단계에서 uv로 3.12 자동 설치 가능)

3. 본인의 게임원 계정 — 우리 리그(사이언스리그)에 리그 회원으로 가입되어 있어야 함 (기록/일정은 비회원에겐 안 보입니다. 각자 자기 계정을 씁니다.)

📦 설치

1) 클론

git clone <이 저장소 URL>
cd Beast_dev   # (클론된 폴더명)

2) 가상환경 + 의존성 ― uv 권장 (빠름)

# uv 없으면 먼저 설치:  curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python -r requirements.txt

python3.12 -m venv .venv          # 또는 python3.11
.venv/bin/pip install -r requirements.txt

3) 게임원 계정 입력 (.env)

cp .env.example .env

.env 파일을 열어 본인 게임원 아이디/비밀번호를 채웁니다:

GAMEONE_USER_ID=본인_아이디
GAMEONE_PASSWD=본인_비밀번호

🔒 .env 는 깃에 올라가지 않습니다(.gitignore). 절대 공유하지 마세요. 각자 자기 계정.

4) 로그인 확인

.venv/bin/python -m beast.cli login-test
# → ✓ 로그인 성공 ... 이 나오면 OK

5) Claude Desktop 연동 (자동)

.venv/bin/python -m beast.cli setup-desktop

이 명령이 본인 PC 경로에 맞게 Claude Desktop 설정을 자동 등록합니다. 그 다음 Claude Desktop을 완전히 종료 후 다시 실행하세요.

Windows는 .venv\Scripts\python.exe -m beast.cli ... 형태로 실행하세요. setup-desktop이 OS별 설정 경로(%APPDATA%\Claude\...)도 자동 처리합니다.

🚀 사용법 (Claude Desktop)

재시작 후, Claude Desktop 채팅에 자연어로:

• "B조 순위 보여줘"

• "우리 팀(The Beasts) 타자·투수 기록 정리해줘"

• "대전 리드오프 상대 전략이랑 라인업 짜줘"

• "중앙 비글스 야구단 명단 가져와"

• "최신 데이터로 새로고침해줘" (경기 후 기록 갱신)

Claude가 아래 도구들을 알아서 호출합니다.

MCP 도구 9개

🛠 (선택) CLI 직접 사용

.venv/bin/python -m beast.cli crawl --save                 # 수집+저장
.venv/bin/python -m beast.cli export --opponent "대전 리드오프"  # 분석용 Markdown 리포트 생성

🧯 트러블슈팅

• Claude Desktop에 beast가 안 보임 → 완전 종료 후 재실행. 그래도 안 되면 setup-desktop 다시 실행 + login-test로 계정 확인. Claude Desktop > Settings > Developer에서 서버 상태 확인.

• DH_KEY_TOO_SMALL SSL 오류 → 게임원 서버의 약한 암호 설정 때문. 코드에 우회 어댑터가 포함돼 있으니 최신 코드인지 확인(git pull).

• mcp 설치 실패 / 버전 오류 → Python이 3.10 미만입니다. 3.12로 venv를 다시 만드세요(설치 2단계).

• 로그인 실패 → 아이디/비번 확인, 그리고 그 계정이 사이언스리그 리그 회원인지 확인.

🗂 프로젝트 구조

beast/
  config.py          설정(.env, 리그/팀 식별자, 조 bujo_idx)
  crawler/           로그인·수집·파싱 (session/endpoints/crawl/parse)
  storage/db.py      SQLite 적재(스냅샷 시계열)
  analysis/          지표·리포트 (stats, report)
  mcp_server.py      ★ MCP 서버 (Claude Desktop 연동)
  desktop.py         Claude Desktop 설정 자동 구성
  cli.py             CLI
data/                수집 데이터(.gitignore)

⚙️ 다른 팀/리그로 바꾸려면

.env 에서 식별자를 덮어쓰면 됩니다(우리 팀원은 그대로 두세요): LIG_IDX, CLUB_IDX, OUR_JO(A/B), OUR_BUJO_IDX(조 코드), CURRENT_SEASON.

🔒 보안: .env(계정)와 *.bak, 수집 데이터는 커밋되지 않습니다. 계정은 절대 공유 금지. 🤖 Generated with Claude Code