mcp-ps-store

PlayStation Network 계정의 게임 기록(플레이 시간, 트로피 진행 상황, 구매 라이브러리)을 노출하는 MCP 서버로, AI 어시스턴트가 추측 대신 실제 데이터를 기반으로 게임을 추천할 수 있게 해줍니다.

러시아어 버전: README.ru.md.

소개

PSN에는 공개 API가 없습니다. 이 서버는 PlayStation 모바일 앱에서 사용하는 것과 동일한 내부 API와 통신하며, 브라우저 세션에서 가져온 NPSSO 쿠키로 인증합니다. 모든 요청은 읽기 전용이며, 계정에 아무것도 기록되지 않습니다.

구조는 계층형 아키텍처를 따릅니다: API 레이어(MCP 도구), 코어 레이어(서비스, 리포지토리, DTO), DI 컨테이너, 인프라 레이어로 구성됩니다.

핵심 기술

• 언어: Python 3.11+

• 프로토콜: Model Context Protocol (mcp)

• HTTP 클라이언트: httpx (비동기)

• DI 컨테이너: dependency-injector

• 설정: pydantic-settings

• 의존성 관리: Poetry

• 테스트: Pytest, pytest-asyncio

Related MCP server: PersonalizationMCP

노출되는 기능

그리고 recommend_games 프롬프트 — "내 프로필을 작성하고 게임을 추천해줘" 시나리오를 바로 실행할 수 있으며, "짧은 게임" 또는 "2인 협동" 같은 추가 지시를 선택적으로 줄 수 있습니다.

빠른 시작

Python 3.11+가 필요합니다.

1. 설치

Poetry 사용:

poetry install

또는 일반 virtualenv 사용:

python3.11 -m venv .venv && .venv/bin/pip install -e .

2. PSN 로그인

1. 브라우저에서 https://www.playstation.com에 로그인합니다.

2. https://ca.account.sony.com/api/v1/ssocookie를 열면 {"npsso":"..."}가 반환됩니다.

3. 64자 npsso 값을 복사하고 실행:

poetry run psn-login PASTE_NPSSO_HERE

토큰은 ~/.mcp-ps-store/tokens.json에 0600 권한으로 저장됩니다.

세션 수명 정보. 액세스 토큰은 1시간, 리프레시 토큰은 10일, NPSSO 자체는 약 2개월 동안 유효합니다. 따라서 NPSSO는 토큰과 함께 저장되며, 리프레시 토큰이 만료되면 서버가 자동으로 재인증합니다. 실제로 psn-login 한 번으로 약 60일 동안 사용할 수 있습니다.

3. 작동 확인

poetry run psn-doctor

계정 이름, 표시되는 게임 수, 시간 기준 상위 5개 게임이 출력됩니다.

클라이언트 연결

Claude Code

claude mcp add ps-store -- /path/to/mcp-ps-store/.venv/bin/python -m app.main

Claude Desktop

claude_desktop_config.json에 추가:

{
  "mcpServers": {
    "ps-store": {
      "command": "/path/to/mcp-ps-store/.venv/bin/python",
      "args": ["-m", "app.main"],
      "cwd": "/path/to/mcp-ps-store"
    }
  }
}

Codex CLI

Codex는 로컬 MCP 서버와 stdio로 통신하므로 동일하게 작동합니다. codex mcp add를 실행하거나 ~/.codex/config.toml에 다음을 추가하세요:

[mcp_servers.ps-store]
command = "/path/to/mcp-ps-store/.venv/bin/python"
args = ["-m", "app.main"]
cwd = "/path/to/mcp-ps-store"

Codex 세션에서 /mcp로 확인하세요.

ChatGPT

ChatGPT는 로컬 프로세스를 실행할 수 없습니다. 사용자 정의 커넥터는 개발자 모드(설정 → 앱 → 고급)에서 추가하며, 공개 HTTPS 엔드포인트여야 하며 SSE 또는 Streamable HTTP를 사용해야 합니다. 따라서 서버를 HTTP 전송으로 전환하고 게시해야 합니다:

PSN_MCP_TRANSPORT=streamable-http PSN_MCP_PORT=8000 poetry run mcp-ps-store

그런 다음 http://127.0.0.1:8000/mcp를 HTTPS로 노출합니다(OpenAI의 Secure MCP Tunnel, 또는 cloudflared/ngrok 같은 터널 사용). 결과 URL을 사용자 정의 커넥터로 추가하세요.

이렇게 하면 PSN 기록이 URL을 찾는 모든 사람에게 공개됩니다. 서버에는 자체 인증이 없으므로 터널을 인증 뒤에 배치하고, 필요한 동안만 실행하며, 로컬 클라이언트로 충분하다면 Codex CLI를 선호하세요.

설정

모든 설정은 환경 변수 또는 .env 파일에서 읽습니다(.env.example 참조).

제한 사항

• 플레이 시간은 PS4/PS5/PC 버전에만 존재합니다. PSN은 PS3 및 Vita 게임에 대해 트로피만 보고하므로 해당 게임은 hours: null로 표시됩니다.

• 여기에는 PS Store 카탈로그가 없습니다. 스토어는 전적으로 클라이언트 측이며, GraphQL API는 Sony가 배포할 때마다 해시를 변경하는 지속 쿼리만 허용합니다. 이를 유지하는 것은 현실적이지 않습니다. 추천 후보는 모델 자체의 게임 지식에서 오며, psn_owned_games는 이미 구매한 게임을 추천하지 않도록 차단합니다.

• 구매 라이브러리는 PSN의 비공개 GraphQL API를 통해 접근합니다. Sony가 쿼리를 변경하면 해당 도구 하나만 작동이 중단되며, 다른 모든 기능은 계속 작동하고 다이제스트에 backlog_unavailable 메모가 추가됩니다.

• 플레이 시간과 트로피는 제목으로 결합되므로, 트로피 세트를 공유하는 리마스터는 원본과 병합될 수 있습니다. 에디션, 플랫폼 접미사, 로마 숫자는 의도적으로 정규화됩니다 — Alan Wake II와 Alan Wake 2는 하나의 게임으로 처리됩니다.

• 이 API는 비공식적입니다: Sony는 언제든지 변경할 수 있습니다.

프로젝트 구조

.
├── app/
│   ├── api/              # MCP layer: tools, prompts, serialisers, tool errors
│   │   ├── games/
│   │   ├── profile/
│   │   └── taste/
│   ├── core/             # Business logic: services, repositories, DTOs
│   │   ├── auth/         # NPSSO -> tokens, refresh, re-login
│   │   ├── games/        # Library, playtime/trophy merge, name normalisation
│   │   ├── profile/      # Account profile and trophy summary
│   │   └── taste/        # Taste digest aggregation
│   ├── di/               # DI containers and providers
│   ├── infra/adapters/   # HTTP client, token storage, TTL cache
│   ├── cli.py            # psn-login, psn-doctor
│   └── main.py           # MCP server entry point
├── settings/             # pydantic-settings configuration
├── tests/
│   ├── core/             # Merge and aggregation tests
│   └── factories/        # Builders for test data
└── pyproject.toml

개발

poetry run pytest        # unit tests; no network and no account needed
poetry run psn-doctor    # live check against the signed-in account